[ptr727]

Summary

A pull request into a non-default branch is "held": an attested local pass covers its head, and pr_review.py wait polls the head's checks instead of a Copilot round. Run right after a push, that poll exited 0 while CI was still running. A job behind needs: enters the rollup only once its dependencies finish, so the merge read CLEAN and every registered check was green while most of a run's jobs had not been created yet. A caller trusting the exit judged the pull request ready.

The held poll now holds while any workflow run on the head has not completed:

• runs_open(pr) in scripts/pr_review_checks.py names every workflow run whose suite is not COMPLETED. It reads the head commit's own suites and each rollup check run's suite, so a fresh head's run counts before most of its jobs exist. A suite with no workflow run, such as another app's that never reports, holds nothing.
• held_checks_open reads its conditions in this order:
  • a pull request no longer open releases
  • a merge reading UNKNOWN holds
  • a BLOCKED merge with a required check stuck in a shape waiting does not clear ends the poll at 44
  • an open run holds
  • only then does a CLEAN, UNSTABLE, or HAS_HOOKS merge release
• A check run WAITING past --check-grace is its own GATED shape. It gets a CHECK WAITING ON ITS ENVIRONMENT line saying to approve the job or let its timer pass, since a re-run meets the same rule. WAITING leaves NOT_STARTED.
• Where workflowRun is unreadable, an Actions suite stands in, named suite <id>, through unkeyed_actions_suite, which check_nodes shares. The head's suites query now selects app{ slug } for this.
• The status=CHECKS_PENDING line names the open runs. The wait help and the scripts/README.md held-wait and exit-44 paragraphs describe the new reading, in the code's order.

Closes on promotion: #3451

Decisions

• Every open run holds, with no exception. Earlier revisions released a run waiting on an environment, then one with a starved job. Review showed each release reopened the early exit 0: a job pending behind a concurrency group, a busy runner pool, or a dependent not yet registered. The cost is that a run waiting on an approval that never comes, or on a job no runner takes, polls to the timeout. It then exits 30, with the digest's GATED or CHECK NOT PICKED UP line naming what holds it.
• A gated or long-running required check does not end a BLOCKED poll at 44. A timer clears by itself and an approval may land, so on a held head these hold to 30. On the Copilot path a required gated check still exits 44, as a long-running one already did.
• A required starved check under BLOCKED still exits 44 at once, as before.
• No shared walker with check_nodes. Its suite walk is threaded through per-node normalization, so runs_open reads the suites itself. The one condition the two share, whether a suite is an Actions suite left unkeyed, is one predicate.
• A job-less Actions suite may hold in degraded mode. With workflowRun unreadable, an unfinished Actions suite holds even when it has no job yet, since right after a push it looks the same as one that never gets a job. I measured the check suites on the 8 most recent pull request heads here: every Actions suite carried jobs, and none sat unfinished. The suites left queued with no jobs belonged to other apps (azure-pipelines, claude, coderabbitai), which the predicate excludes and a test pins.

Remaining Local-Review Findings

Each push had recorded frontier-tier passes, and every introduced finding they raised is fixed in the commits above, apart from these:

• introduced, fixed in 8acf0511: the wait help's exit-30 line read as a complete list of holds. It now points to the holds status=CHECKS_PENDING names.
• introduced, deferred to A Held Wait Exits 0 Under a DIRTY or BEHIND Merge Whose Required Checks Never Ran #3471: the exit-0 help's completed-runs clause now names coverage, the condition the code reads (3545ba46). One path still falls outside it: when the rollup's commit is not the head, wait deliberately exits 0 with CHECKS UNREADABLE, and no run is read. That predates this change and a test pins it, but the help's new clause now overclaims there. It joins A Held Wait Exits 0 Under a DIRTY or BEHIND Merge Whose Required Checks Never Ran #3471, which tracks exit 0 where the required checks were never read.
• pre-existing: the help's claim that exit 0 means the head's required checks settled is false under a DIRTY or BEHIND merge whose required checks never ran. GitHub runs no pull_request workflow on a conflicted pull request, and held_checks_open holds an unregistered required context only under BLOCKED. These paths predate this change, so they are left to an issue of their own.
• introduced, conditional: the degraded-mode decision above. If GitHub ever leaves a job-less Actions suite queued on a head, the held wait would poll to 30 in that mode alone. The measurement above found none.
• style: one help string and two help-text lines are wrapped short. Declined, since no gate reads them and the file already carries longer lines.
• pre-existing: a head read before any check suite exists, on a base requiring no check, can still exit 0 under CLEAN. Nothing on the head exists yet for any reader to see. Every develop ruleset in this fleet requires the aggregator, so there the merge reads BLOCKED and required_unmet holds.
• pre-existing: sentences over 25 words that this change only rewrapped or left in place: three at scripts/README.md line 233, scripts/pr_review.py lines 120 and 123, and the 49 = help sentence.

Verification

• python -m unittest discover -s tests (under uvx --with-requirements tests/requirements.txt): 2,940 tests OK, 7 skipped, at e4295145. The commits after it change only the wait help text, and the test_pr_review and test_cli_usage suites pass on each.
• Each rule was mutation-tested, and dropping it fails a named test:
  • the run hold, and its place ahead of CLEAN
  • the closed-PR release
  • the stuck-required release ahead of the hold
  • the gated exemption from 44
  • the COMPLETED skip
  • the no-workflow-run exclusion
  • the rollup-suite read
  • the Actions fallback for a rollup suite, for a job-less head suite, and its other-app exclusion
  • the GATED shape
• On a live pull request, Split pr_review.py's Check and Round Readers Into Leaf Modules #3462, a wait using an earlier revision of this change (f6837bd9) held for 781 seconds until every run on the head completed, then exited 0. The same wait without it had returned while two checks were still running.
• The extended suites query was read live with status against this repository.
• ruff check, ruff format --check, mypy ., and prose_lint.py --diff: clean.

🤖 Generated with Claude Code

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

Run configuration

• Source mode: Auto
• Repository: ptr727/ProjectTemplate
• Branch: feature/3451-held-wait-runs
• File: .coderabbit.yaml
• Commit: 3545ba4
• Layers: Repository YAML
• Review profile: CHILL
• Plan: Advanced
• Run ID: f82d1785-10d6-4c77-bdea-3f9d30cd9045

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

[ptr727]

A recorded local strict-review pass covers head c8a94811f5fa8bc75d3066dd1ea53f05bb98f96f, the content this pull request carries at that commit against develop, and it recorded 7 findings.

[Copilot]

🟡 Changes recommended

Unresolved findings could allow active workflow work to be released or missed, including active jobs in waiting suites and suites beyond the query limit.

4 open issues

• Do not release waiting suites with active sibling jobs · New
• Handle truncated suite queries before releasing clean waits · New
• Document the head-suite fallback source · New
• Test exclusion of non-Actions suites in degraded mode · New

What changed in this PR

This pull request updates held pull-request waits to remain pending while workflow runs on the head commit are incomplete, including runs whose jobs have not yet entered the check rollup.

Changes:

• Detects open workflow runs from head and rollup check suites.
• Adds degraded-mode fallback for unreadable workflow-run data.
• Updates wait status reporting, documentation, and regression coverage.

File	Description
tests/​test_pr_review.py	Adds regression coverage for incomplete, completed, waiting, degraded, and duplicate workflow runs.
scripts/​README.md	Documents the updated wait behavior, status output, and exit conditions.
scripts/​pr_review.py	Extends suite queries and reports open workflow runs during waits.
scripts/​pr_review_checks.py	Detects open workflow runs and applies degraded-mode suite handling.

_{Review effort: Lite}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (develop@c75a730). Learn more about missing BASE report.

Additional details and impacted files

@@            Coverage Diff             @@
##             develop    #3470   +/-   ##
==========================================
  Coverage           ?   80.98%           
==========================================
  Files              ?       25           
  Lines              ?     8895           
  Branches           ?        0           
==========================================
  Hits               ?     7204           
  Misses             ?     1691           
  Partials           ?        0           

Flag	Coverage Δ
python-3.13	80.98% <100.00%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[ptr727]

A recorded local strict-review pass covers head 702f7035ad6192e937f92412106af6d680887322, the content this pull request carries at that commit against develop, and it recorded 8 findings.

[ptr727]

A recorded local strict-review pass covers head d1dbc640b1805a851b9e73ab9171d2a17b12abaf, the content this pull request carries at that commit against develop, and it recorded 7 findings.

[ptr727]

A recorded local strict-review pass covers head 3545ba4654c451b213e623ad970763c2fbd22d2c, the content this pull request carries at that commit against develop, and it recorded 7 findings.