The CI traffic-controller (priority-based runner orchestration) currently lives as a large inline bash script in .github/workflows/ci.yml — the traffic-control job's "Apply runner priority" step (~L76–210), a two-pass (preemption + hold-back) shell script with extensive inline comments. It is complex and effectively untestable in YAML. Split it into its own Python file checked into the repo and rewrite it in Python for developer ergonomics + unit-testability.
Order of operations (the desired behavior — implement exactly this)
Priority label sets order: effective priority = the lowest-numbered P0–P9 label present (P0 = highest), default P5 if none. broken and draft PRs are effectively P10 (bottom, below P9).
No higher-priority PR may bump (cancel) a lower-priority PR that is already in the middle of status checks — EXCEPT P0. A P0 (emergency) preempts strictly-lower in-progress/queued runs to reclaim runners; P1–P9 never bump a lower run mid-flight.
Within the same priority level, order by: (a) PRs already running status checks first, then (b) the oldest PR in that priority group.
Requirements
New Python module checked into the repo (e.g. .github/scripts/traffic_control.py — follow any existing convention). Pure, testable core: given the open PRs (number, priority label, draft?, broken?, run status = running/queued/none, created-at) + THIS PR, decide (i) which other runs to cancel (only when THIS PR is P0 — strictly-lower in-progress/queued runs), and (ii) whether THIS PR proceeds now or waits (yield to any strictly-higher-priority PR with an active/queued run; among equal priority, order running-first then oldest).
Preserve the existing safety invariants (read them from the current step): never cancel a run on main/push events, never cancel THIS PR's own run, never cancel an equal-or-higher-priority PR's run.
ci.yml's traffic-control job invokes the Python module (pass PR/label/state data via gh/env; the module emits the decisions). Keep the job's permissions (actions: write, pull-requests: read) and the downstream needs: traffic-control wiring intact. Behavior-preserving except where the order-of-operations above refines it (notably: drafts now count as P10, and the same-level running-first/oldest tiebreaker is explicit).
Unit tests for the algorithm (the whole point): priority resolution incl. broken/draft=P10; P0 preempts lower / P1–P9 never bump; same-level ordering (running-first, then oldest); self/main/equal-or-higher never cancelled.
Repo Python conventions: stdlib-first, SPDX header on the new .py. Use PowerShell/Python (not Git Bash) for any local scripting.
Priority
P2 — must clear ahead of the in-flight P3 logging PRs.
## Goal
The CI **traffic-controller** (priority-based runner orchestration) currently lives as a large **inline bash script** in `.github/workflows/ci.yml` — the `traffic-control` job's "Apply runner priority" step (~L76–210), a two-pass (preemption + hold-back) shell script with extensive inline comments. It is complex and effectively untestable in YAML. **Split it into its own Python file checked into the repo and rewrite it in Python** for developer ergonomics + **unit-testability**.
## Order of operations (the desired behavior — implement exactly this)
1. **Priority label** sets order: effective priority = the lowest-numbered `P0`–`P9` label present (P0 = highest), default `P5` if none. **`broken` and `draft` PRs are effectively P10** (bottom, below P9).
2. **No higher-priority PR may bump (cancel) a lower-priority PR that is already in the middle of status checks — EXCEPT `P0`.** A P0 (emergency) preempts strictly-lower in-progress/queued runs to reclaim runners; P1–P9 never bump a lower run mid-flight.
3. **Within the same priority level**, order by: (a) PRs **already running** status checks first, then (b) the **oldest** PR in that priority group.
## Requirements
- New Python module checked into the repo (e.g. `.github/scripts/traffic_control.py` — follow any existing convention). **Pure, testable core:** given the open PRs (number, priority label, draft?, broken?, run status = running/queued/none, created-at) + THIS PR, decide (i) which other runs to cancel (only when THIS PR is P0 — strictly-lower in-progress/queued runs), and (ii) whether THIS PR proceeds now or waits (yield to any strictly-higher-priority PR with an active/queued run; among equal priority, order running-first then oldest).
- **Preserve the existing safety invariants** (read them from the current step): never cancel a run on `main`/push events, never cancel THIS PR's own run, never cancel an equal-or-higher-priority PR's run.
- `ci.yml`'s `traffic-control` job invokes the Python module (pass PR/label/state data via `gh`/env; the module emits the decisions). Keep the job's permissions (`actions: write`, `pull-requests: read`) and the downstream `needs: traffic-control` wiring intact. Behavior-preserving except where the order-of-operations above refines it (notably: **drafts now count as P10**, and the same-level running-first/oldest tiebreaker is explicit).
- **Unit tests** for the algorithm (the whole point): priority resolution incl. `broken`/`draft`=P10; P0 preempts lower / P1–P9 never bump; same-level ordering (running-first, then oldest); self/main/equal-or-higher never cancelled.
- Repo Python conventions: stdlib-first, SPDX header on the new `.py`. Use PowerShell/Python (not Git Bash) for any local scripting.
## Priority
**P2** — must clear ahead of the in-flight P3 logging PRs.
Clarification (maintainer) on same-priority ordering — order-of-operations rule 3: within a priority group, (a) a PR already running its status checks keeps running (a same-level peer does not preempt or reorder it), and (b) among the PRs waiting to start, the oldest PR (earliest created_at) runs first — older PRs go ahead of newer ones. So the queue within a level is: in-flight run continues, then oldest-waiting → newest-waiting.
Clarification (maintainer) on same-priority ordering — order-of-operations rule 3: within a priority group, (a) a PR already running its status checks keeps running (a same-level peer does not preempt or reorder it), and (b) among the PRs waiting to start, the **oldest PR (earliest created_at) runs first — older PRs go ahead of newer ones**. So the queue within a level is: in-flight run continues, then oldest-waiting → newest-waiting.
Requirement update (maintainer) — restore the behavior the refactor removed: any strictly-higher-priority PR may preempt (cancel the active/queued runs of) a broken OR draft PR (effective priority 10) — not only P0.
runs_to_cancel(this_pr, all_prs) cancels an OTHER PR's active/queued runs when EITHER:
(a) THIS PR is P0 and that PR is strictly-lower (prio > 0) — unchanged; OR
(b) that PR is broken/draft (effective priority == 10) and THIS PR is strictly-higher than it (THIS prio < 10).
Unchanged: P1–P9 still NEVER preempt a normal (non-broken/draft) lower run — only P0 does. A broken/draft PR preempts nothing. All invariants stay (never self, never main/push, never equal-or-higher — so a P10 never preempts another P10).
Requirement update (maintainer) — restore the behavior the refactor removed: **any strictly-higher-priority PR may preempt (cancel the active/queued runs of) a `broken` OR `draft` PR (effective priority 10)** — not only P0.
`runs_to_cancel(this_pr, all_prs)` cancels an OTHER PR's active/queued runs when EITHER:
- (a) THIS PR is P0 and that PR is strictly-lower (prio > 0) — unchanged; OR
- (b) that PR is broken/draft (effective priority == 10) and THIS PR is strictly-higher than it (THIS prio < 10).
Unchanged: P1–P9 still NEVER preempt a *normal* (non-broken/draft) lower run — only P0 does. A broken/draft PR preempts nothing. All invariants stay (never self, never main/push, never equal-or-higher — so a P10 never preempts another P10).
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Goal
The CI traffic-controller (priority-based runner orchestration) currently lives as a large inline bash script in
.github/workflows/ci.yml— thetraffic-controljob's "Apply runner priority" step (~L76–210), a two-pass (preemption + hold-back) shell script with extensive inline comments. It is complex and effectively untestable in YAML. Split it into its own Python file checked into the repo and rewrite it in Python for developer ergonomics + unit-testability.Order of operations (the desired behavior — implement exactly this)
P0–P9label present (P0 = highest), defaultP5if none.brokenanddraftPRs are effectively P10 (bottom, below P9).P0. A P0 (emergency) preempts strictly-lower in-progress/queued runs to reclaim runners; P1–P9 never bump a lower run mid-flight.Requirements
.github/scripts/traffic_control.py— follow any existing convention). Pure, testable core: given the open PRs (number, priority label, draft?, broken?, run status = running/queued/none, created-at) + THIS PR, decide (i) which other runs to cancel (only when THIS PR is P0 — strictly-lower in-progress/queued runs), and (ii) whether THIS PR proceeds now or waits (yield to any strictly-higher-priority PR with an active/queued run; among equal priority, order running-first then oldest).main/push events, never cancel THIS PR's own run, never cancel an equal-or-higher-priority PR's run.ci.yml'straffic-controljob invokes the Python module (pass PR/label/state data viagh/env; the module emits the decisions). Keep the job's permissions (actions: write,pull-requests: read) and the downstreamneeds: traffic-controlwiring intact. Behavior-preserving except where the order-of-operations above refines it (notably: drafts now count as P10, and the same-level running-first/oldest tiebreaker is explicit).broken/draft=P10; P0 preempts lower / P1–P9 never bump; same-level ordering (running-first, then oldest); self/main/equal-or-higher never cancelled..py. Use PowerShell/Python (not Git Bash) for any local scripting.Priority
P2 — must clear ahead of the in-flight P3 logging PRs.
Clarification (maintainer) on same-priority ordering — order-of-operations rule 3: within a priority group, (a) a PR already running its status checks keeps running (a same-level peer does not preempt or reorder it), and (b) among the PRs waiting to start, the oldest PR (earliest created_at) runs first — older PRs go ahead of newer ones. So the queue within a level is: in-flight run continues, then oldest-waiting → newest-waiting.
Requirement update (maintainer) — restore the behavior the refactor removed: any strictly-higher-priority PR may preempt (cancel the active/queued runs of) a
brokenORdraftPR (effective priority 10) — not only P0.runs_to_cancel(this_pr, all_prs)cancels an OTHER PR's active/queued runs when EITHER:Unchanged: P1–P9 still NEVER preempt a normal (non-broken/draft) lower run — only P0 does. A broken/draft PR preempts nothing. All invariants stay (never self, never main/push, never equal-or-higher — so a P10 never preempts another P10).