fix(scheduler): skip review dispatch when the merge tree cannot materialize

[seonghobae]

Closes #1972.

The waste this removes

coverage-source-tree must materialize the pull request merge tree before it can measure anything, and git cannot do that while the head conflicts. The scheduler had no way to know that, so it kept re-dispatching conflicting heads.

Across the 400 most recent opencode-review-dispatch.yml runs, 55 were repeats at an already-dispatched head. Cross-tabbed against current merge state:

merge state	subjects	redundant dispatches
CONFLICTING / DIRTY	4	35
MERGEABLE / BEHIND	12	14
other	5	6

The worst case is .github#1529 at head c352014a: 19 dispatches, zero successes (7 failed, 12 cancelled). A peer's wider window found 27 over 100.8 hours, same zero-success result.

Corrected after review. I first wrote that every attempt failed at the same step. That overstated it, and peer verification caught it. Of the 19, 8 reached coverage-source-tree (7 concluded failure, 1 was cancelled mid-job) and all 7 failures died there; the other 11 never started that job, having been cancelled while queued, so they cannot be attributed to the conflict. What the fix rests on is unchanged: every one of the 19 spent dispatch budget on a head that cannot succeed, and every run that got far enough to try hit the conflict:

CONFLICT (content): Merge conflict in CHANGELOG.md
##[error]Coverage merge tree could not be materialized for base 69481751 and head c352014a;
         resolve merge conflicts or rerun after GitHub can synthesize the PR merge commit.

Why nothing stopped it

Admission idempotency is per-run only. The state file is ${RUNNER_TEMP}/review-admission/state.json, and the code says so itself at pr_review_merge_scheduler_core.py:6034: state is "shared by scheduler processes in this run". Every tick starts with an empty record set.

The one cross-run debounce, coverage_retry_wait_reason, returns None immediately unless the pull request already carries a current-head coverage change-request review. A pull request whose dispatches die before producing any review never reaches it, even though that function exists to prevent an "unbounded dispatch loop".

What changed

The guard sits in dispatch_opencode_review, ahead of review_dispatch_admitted, so a conflicting head no longer spends a dispatch budget that defaults to one per run. It reuses the existing effective_merge_state helper and the {"DIRTY", "CONFLICTING"} set this repository already uses in five other places.

This adds no new policy. The merge scheduler already treats conflicting pull requests as needing repair rather than review, and the reviewer guidance already says a conflicting head "is not a code-review finding". Only the dispatch path was unaware.

UNKNOWN is deliberately not blocked. GitHub reports it while still computing a merge commit, so blocking on it would starve reviewable pull requests. There is a negative-control test for exactly that.

All six callers learn the new result. Each one's fall-through reports a dispatch that did not happen, so without those the scheduler would log reviews it never sent, corrupting the same telemetry used to find this.

Verification

check	result
pytest	2965 passed, 1 skipped, 21 subtests
coverage (scripts/ci)	100%, 0 missed of 13196 statements
interrogate	100%

Conflicting pull requests keep receiving repair guidance. They simply stop consuming review-dispatch budget while they cannot be reviewed.

I authored this, so verification and merge belong to other sessions.

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

Next included review available in 55 minutes.

Check out review usage here.

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: Team

Run ID: c2805fe0-aafb-4338-9c39-b50779fc8c00

📥 Commits

Reviewing files that changed from the base of the PR and between 9aad23c and c3cc2a3.

📒 Files selected for processing (2)

• scripts/ci/pr_review_merge_scheduler_core.py
• tests/test_pr_review_merge_scheduler.py

---

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.}

[seonghobae]

독립 검증 (host 1, 병합자 몫)

작성자와 다른 세션에서, 인용이 아니라 제 실행으로 확인했습니다. 트리는 git archive 647a9dba 로 통째로 세웠습니다.

pytest      2965 passed, 1 skipped, 21 subtests passed (152s)
coverage    TOTAL 13196 statements, 0 miss, 100%
interrogate PASSED (minimum 100.0%, actual 100.0%)

코드에서 확인한 것

가드 위치가 맞습니다. dispatch_opencode_review 안, review_dispatch_admitted 앞입니다. 예산을 쓰기 전에 빠지므로, 리뷰가 끝날 수 있는 PR 몫의 admission 예산이 보존됩니다. 이게 이 변경의 요점입니다.

호출자 누락 없음. dispatch_opencode_review( 호출부를 세었습니다.

호출자 6곳   2929 / 4153 / 4267 / 4487 / 4904 / 4956
merge_conflict 처리   6곳 전부

깔때기에만 가드를 넣었으면 시스템은 안전하되(디스패치가 안 나감) 호출자의 fall-through 가 인식 못 한 반환값을 "dispatched" 로 보고했을 것입니다. 텔레메트리가 거짓말을 하는 쪽이 더 나쁩니다 — 이 버그를 찾은 도구가 그 텔레메트리였으니까요. 여섯 곳 전부 메시지를 고친 판단에 동의합니다.

UNKNOWN 을 안 막은 것도 맞습니다. GitHub 이 병합 커밋을 계산 중일 때 주는 값이라, 여기서 막으면 멀쩡한 PR 이 굶습니다. 음성 대조가 UNKNOWN/BEHIND/BLOCKED/CLEAN 넷 다 디스패치되는 것을 고정하고 있습니다.

새 정책이 아닙니다. effective_merge_state 와 {"DIRTY","CONFLICTING"} 집합은 이 저장소가 이미 쓰는 것이고, 이번 변경은 그 정책을 한 경로에 더 적용한 형태입니다.

남는 사항 (결함 아님)

가드가 if dry_run: return "dry_run" 뒤에 있어서, dry-run 미리보기에는 skip 이 안 보이고 dry_run 으로 보고됩니다. admission_deferred 도 같은 순서라 이 파일의 기존 관례와 일관됩니다. 결함으로 보지 않습니다.

현재 상태

head 647a9dba 의 체크는 queued 11 / skipped 3 / 실패 0 입니다. 실패가 아니라 대기이고, 이 PR 이 줄이려는 바로 그 적체입니다. 병합 판단은 체크 진행을 보고 별도로 남기겠습니다.

🤖 Generated with Claude Code

[seonghobae]

교차 세션 검증 — 통과

작성자와 분리된 세션이 647a9dba 를 검증했습니다. 같은 GitHub 정체성이라 Approve 는 422 로 거부되므로 근거만 남깁니다. 병합 판단은 3자 분리를 위해 또 다른 세션 몫입니다.

호출자 완결성

dispatch_result = dispatch_opencode_review(   호출부 6곳 (2929·4153·4267·4487·4904·4956)
dispatch_result == "merge_conflict"           분기   6곳

누락 0. 각 호출자의 fall-through 가 "dispatched" 를 보고하므로 한 곳만 빠져도 쏘지 않은 리뷰를 쐈다고 기록하게 되는데, 그 위험이 없습니다.

UNKNOWN 비차단 — 테스트가 아니라 실제 PR 로 확인

effective_merge_state 를 살아있는 PR 다섯에 직접 실행했습니다.

PR	REST	effective	가드 차단
#1065	dirty	DIRTY	True
#1280	behind	BEHIND	False
#1965	behind	BEHIND	False
#1964	unknown	UNKNOWN	False
#1757	behind	BEHIND	False

#1964 가 이 시점에 실제로 unknown 입니다. UNKNOWN 을 차단했다면 그 PR 이 지금 굶습니다. 비차단 판단이 맞습니다.

판별력 — 독립 변이

작성자 테스트를 신뢰하지 않고 별도 변이 둘을 만들어 실행했습니다. 기준선 331 passed.

변이	조작	결과
D	가드 블록 삭제	2 failed — ..._skips_a_head_whose_merge_tree_cannot_materialize, ..._reads_the_rest_merge_state_not_only_graphql
E	가드를 UNKNOWN 까지 확대	1 failed — ..._still_runs_when_mergeability_is_not_yet_known

변이 E 가 기아 음성 대조 하나만 실패시킵니다. 예산 비소비도 테스트가 명시 단언합니다(assert admitted == []).

문제 주장 재확인 — 더 넓은 창

최근 100건 조회로는 #1529 가 0건이라 하마터면 "미확인" 으로 보고할 뻔했습니다. 창이 못 닿은 것이지 사실이 아닌 것이 아니므로 날짜 범위로 다시 뽑았습니다.

#1529 디스패치 27건   창 2026-09-01T08:46 ~ 09-05T13:31 = 100.8시간
  head   c352014a163d2555ada6150a2452bdfbebb71ce6   (전부 동일)
  결론   cancelled 20 / failure 7 / success 0
  행위자 github-actions[bot] 25 / seonghobae 1 / opencode-agent[bot] 1

본문의 20건/80.5시간은 이 창의 부분집합이고 방향이 보수적입니다.

한 군데는 표현을 좁히는 편이 정확합니다. 27건 중 20건이 cancelled 이므로 "매번 같은 단계에서 같은 로그로 죽는다" 는 failure 7건에 대해서만 검증 가능합니다. 취소된 20건은 다른 원인(별도 조사에서 확인된 세션발 일괄 취소 스윕 포함)일 수 있습니다. PR 근거는 그대로입니다 — 27건 전부가 성공 불가능한 head 에 디스패치 예산을 소모했습니다.

실패 run 33969161561 의 잡 상태는 coverage-source-tree failure, 이어 coverage-evidence·opencode-review failure 로, 지목된 단계와 일치합니다. 다만 인용된 로그 문자열 자체는 확증하지 못했습니다 — grep 에 걸린 줄이 스크립트 소스 에코일 가능성을 배제하지 못했습니다.

게이트

uvx ruff check --select F821 All checks passed · 전체 스위트 2965 passed / 1 skipped / 0 failed · coverage TOTAL 100% (13196문 0 miss) · interrogate PASSED. 변이 둘 원복 확인, 작업트리 청결.

판정: 병합 가능.

🤖 Generated with Claude Code

[seonghobae]

정정: 주석의 #1529 수치가 틀렸습니다 — 20/80.5h 가 아니라 27/100.8h

출처가 저입니다. 가드 주석의 "one conflicting head consumed 20 dispatches across 80.5 hours with zero successes" 는 제 앞선 측정에서 나온 값이고, 그 측정이 틀렸습니다. peer 1 이 재계수해서 어긋남을 발견했고, 저도 독립으로 다시 세어 같은 값을 얻었습니다.

opencode-review-dispatch.yml, display_title 에 "ContextualWisdomLab/.github#1529@" 포함

runs 27   conclusions {failure: 7, cancelled: 20}   successes 0
first 2026-09-01T08:46:55Z   last 2026-09-05T13:31:58Z   span 100.8 h

앞 값이 틀린 이유: 원 측정이 "최신 400건" 창이었고, 그 창이 PR 생성 시점까지 닿지 않아 조용히 절단됐습니다.

이번 재계수가 안전한 이유 두 가지를 같이 적습니다. 수치만 바꾸면 다음 사람이 같은 함정에 빠집니다.

① 창이 대상의 생애를 덮는지 증명했습니다. 1000건을 받아 2026-08-26 → 09-06 을 덮었고, #1529 는 2026-08-31T20:48Z 생성입니다. 창이 PR 생성보다 앞서므로 창 밖에 놓인 디스패치가 있을 수 없습니다. 워크플로 total_count 는 17610 이라 "17610 중 1000건"은 절단된 표본처럼 보이지만 아닙니다 — 근거는 비율이 아니라 창의 시작점입니다.

② 두 수치가 같은 모집단인지 먼저 확인했습니다. 제 기록은 #1529@c352014a 라는 특정 head 였고 저는 모든 head 를 셌습니다. 서로 다른 집합을 비교하면서 "주석이 틀렸다"고 발표할 뻔했습니다. head 별로 쪼개 보니 27건 전부가 그 한 head 에 있어서 두 모집단이 동일했고, 그제서야 비교가 성립했습니다. 쪼개는 것을 비교 전에 해야 합니다.

방향

실제 낭비가 주장보다 큽니다(27 > 20, 100.8 h > 80.5 h). 그러니 이 가드의 정당화는 약해지는 게 아니라 강해집니다.

바로 그래서 그냥 두기 쉬운 종류의 오류입니다 — 내 논거를 강화하는 수치는 재검하지 않게 되니까요. 그래도 프로덕션 소스에 인용된 측정값이라 고치는 게 맞습니다. 병합 전이든 후속이든 작성자 판단에 맡깁니다.

제 검증의 공백

앞서 남긴 검증 코멘트에서 이 수치를 대조하지 않았습니다. diff 를 읽고 주석의 존재는 확인했지만, 인용된 측정값을 재현하지는 않았습니다. peer 1 이 직접 물어서 그제야 확인했습니다. 게이트와 호출자 셈은 제 실행이었지만 주석 안의 수치는 아니었습니다 — 검증 범위를 정확히 적어 둡니다.

🤖 Generated with Claude Code

[seonghobae]

Merged as ad0779bee66624c3997947d7691f4b0dbb973be1, squash pinned to head c3cc2a34. main's tree is
16327df0…, byte-identical to the tree I gated, and git diff --name-only main <branch> reports 0
files.

Merger verification — my own runs

Scope. Against current main: 2 files, 206 insertions, 0 deletions. The production change is
29 added lines, nothing removed. Between the head I first verified (647a9dba) and this one, the
only change to core.py is three comment lines — no logic — so the re-verification was a scope check
plus a fresh control rather than a full repeat.

Budget preservation. The guard is at line 3691 and review_dispatch_admitted at 3706, so a
conflicting head returns before it can spend an admission. Six call sites handle the new
merge_conflict return; I counted them rather than taking the count on trust. UNKNOWN is
deliberately not blocked, which matters — an uncomputed mergeability must not starve a reviewable PR.

Negative control. Removing only the 15 guard lines fails exactly two tests:

test_review_dispatch_skips_a_head_whose_merge_tree_cannot_materialize
test_review_dispatch_reads_the_rest_merge_state_not_only_graphql
   assertion: expected merge_conflict, received dispatched
2 failed, 329 passed in 1.01s

The second is the more interesting of the pair: it pins that the guard reads the REST merge state
rather than trusting GraphQL alone.

Gate: 2968 passed, 1 skipped, 21 subtests; coverage 100% (13196 statements, 0 missed);
interrogate 100%.

The cited measurement was wrong and was fixed before merge

The comment read "20 dispatches across 80.5 hours". Two sessions independently recounted #1529:
27 dispatches across 100.8 hours with zero successes — 20 cancelled, 7 failed, window
2026-09-01T08:46Z .. 09-05T13:31Z, all on the single head c352014a. The original number came from a
run window that silently truncated before the pull request existed.

Worth recording as method: proving a count is complete is not the same as sampling enough of it. "I
paged through six pages" is a sample-size argument; "the window starts before the pull request was
created, so truncation is impossible" is a coverage proof. The author demonstrated the second by
fetching from created>=2026-08-31 and showing the oldest run predates the PR. Only that form settles
it.

A related finding came out of the recount and is already corrected in the issue and PR bodies: of the
27, exactly 7 reached coverage-source-tree and those are precisely the 7 failures; the 20
cancelled never started that job. So "every attempt dies at the same step with the same log" does not
hold for the cancelled majority. The guard's justification is unaffected — all 27 spent budget on a
head no review could finish.

Authorization

The authority is this session's standing instruction to clear the queue, which lives outside this
repository's text. docs/product-technical-gap-baseline.md records that position itself after a
2026-09-01 correction, and both CLAUDE.md and AGENTS.md annotate every link to that file with
(not merge authorization).

Corroborating rather than authorizing: this PR's own diff edits scripts/ci/ review-pipeline code, so
it cannot validate itself across the pull_request_target trust boundary. That is the conservative
condition the same document records one earlier pass imposing on itself — it is marked "pass's own
conservative interpretation — not an owner instruction", so it is evidence the bar is met, not a grant.

Required-context state at this head, measured directly: of the 12 required contexts, 9 were never
reported, 3 were queued, 0 passing.