claw-refresh: one merge can queue 750 workflow runs; budget refreshes by the Actions queue #10588

What

claw-refresh (gate-topology.yml, decision in specs/claw/refresh.t27) calls update-branch on up to REFRESH_CAP = 30 behind, conflict-free pull requests after every push to master. Each moved head starts about 25 workflow runs (23 to 27 measured per branch on 2026-10-18).

So one merge can add up to 750 runs to the Actions queue.

Evidence (2026-10-18, about 18:07 UTC)

• actions/runs?status=queued: 886 queued, 17 in progress.
• By event: 743 pull_request, 61 pull_request_target, 34 push, 26 issues, 18 workflow_run.
• By branch: about 35 branches with 22 to 29 queued runs each.
• The four required checks (validate, check-linked-issue, parse-ratchet, own-language) wait in the same queue, behind non-required workflows.
• The master ruleset is not strict (strict_required_status_checks_policy: false). A behind PR merges without a refresh, so a refresh only buys freshness.

Today claw-refresh is red on every push (the GraphQL page timeout, #10576), so it updates nothing. #10585 fixes that listing. Merged alone, #10585 would turn the flood on. Auto-merge on #10585 is off until this lands in the same PR.

The rule (in .t27, refresh_plan_queued)

• The job passes the queued-run count, read from actions/runs?status=queued total_count.
• With QUEUE_ROOM = 100 or more queued runs, nothing is refreshed.
• Below that, at most (QUEUE_ROOM - queued) / RUNS_PER_REFRESH, which is 4 at most, and never more than REFRESH_CAP.
• An unread count refreshes nothing: fail closed.
• The step summary says which case applied.

Prior art

Merge queues throttle CI on purpose:

• Mergify's queue rules cap how many checks run in parallel.
• Trunk Merge Queue has a concurrency setting.
• GitHub's merge queue caps the number of groups it builds at once.

None of them refresh every behind PR on every merge.

Checklist

• refresh_budget and refresh_plan_queued in specs/claw/refresh.t27, with tests and a negative control; reseal; regenerate gen/c/claw/refresh.c.
• claw-refresh reads the queue count and passes it to the harness (in claw: claw-t27f/suggest/refresh pass with a note when the App token cannot be minted; claw-refresh can read the queue (#10576) #10585).
• Re-arm auto-merge on claw: claw-t27f/suggest/refresh pass with a note when the App token cannot be minted; claw-refresh can read the queue (#10576) #10585.
• Follow-up: measure the queue after merge, and lower QUEUE_ROOM if needed.

Refs #10576, #10397, #10393.

🤖 Generated with Claude Code

Superseded (2026-10-18)

#10559 (Closes #10545) landed the same gate first: a cap of 5, nothing when more than 150 runs are queued or the count is unread, and a retried listing. #10585 now takes master's refresh spec unchanged and only adds actions: read so the queue read cannot silently fall to -1. Closing as a duplicate of #10545.