[kyle-sexton]

No related issue: efficiency register E5 (owner directive 2026-10-23)

Summary

ci-status failed closed as soon as a GitHub API read hit the repository's GITHUB_TOKEN rate limit, then told people to re-run. The re-run landed in the same exhausted window. In the 05:26Z and 09:24Z runs (39905801496, 39931677333, 39931558895) the reset was 399 to 523 s away.

With this change, ci-status's inline reads wait for the reset when it falls inside the job's existing timeout. Otherwise they fail red at once, naming the reset time and saying a re-run after it is needed. The owner's decision (Q10) was the most time-efficient option that adds no spam: no timeout raise, and no new re-run loop.

Fix

gh_read. A new first step writes gh_read to $RUNNER_TEMP, and later steps source it. On a rate limit it waits once and reads again.

• Detection. gh's error names a rate limit, or a 403/429 comes back while the probe below reads remaining 0 or retry-after.
• Length of the wait. It reads the x-ratelimit-* and retry-after headers of one gh api -i probe to the same resource (core, or graphql for a graphql call).
  • retry-after seconds when that header is present.
  • Otherwise, 5 s past x-ratelimit-reset while remaining is 0.
  • 1 s when the probe shows the limit has already cleared.
  • Otherwise, 60 s.
• Why a probe. This PR's first live run showed that GET /rate_limit does not report the installation limit. It read core remaining > 0 while every read failed, and the failing responses' own headers said remaining=0, reset 15:35:06.
• Wait budget. A wait is taken only when it ends inside the job's existing 11-minute timeout, less a 300 s margin for the job's setup and the steps after the wait. The deadline is measured from when the helper step starts: GH_READ_JOB_SECONDS: 660 minus GH_READ_MARGIN_SECONDS: 300, so 360 s. The margin covers aggregate-results' 202 s of waits (60 s rate limit, 45 s own-gate, 7 s status writes, 90 s rerun wait) plus retry sleeps.
• Past the budget. A reset after the deadline fails the read at once with ::error::, which turns the check red, never neutral. The error names the reset and says a re-run after it is needed. Later reads of that resource before the reset fail without a call. Any other error returns at once, so each step's existing retries and fail-closed messages are unchanged.
• What the budget covers. A wait is taken only for a reset about 6 minutes or less away. The cited resets were 399 to 523 s away, past the 360 s budget, so those cases still fail red as before. The change is that the error now names the reset time and says a re-run is needed after it, so the re-run does not land in the same window. The composites' 60 s rate-limit-wait-seconds matches main; this PR does not change it.
• No new re-run mechanism. The next review lane's rerun-ci-status, or the rate-limit wait from E10 in perf(pr-pipeline): re-run ci-status once per head after the review lanes finish #9429, picks the PR up after the reset.

Which reads use it. The API reads that remain after #9433:

• the PR file list in the broker step, and in the review-lane fallback
• the label reads in the human-gated and merge-group steps
• the comment and event reads in hold-lifted-by
• the read_api helpers in the review-lane and lanes-hold steps

Two reads keep plain gh api. The cost-hold step keeps it because a wait there would act on reads taken before a newer hold. The best-effort hold-reason read keeps it too. Both are marked gh-read-exempt, and a test fails on any new unmarked read.

What does not change. ci-status keeps its timeout-minutes: 11. The composites keep their 60 s rate-limit-wait-seconds default. rerun-ci-status and the pr-pipeline README are unchanged from main.

Verification

• scripts/ci-gh-read.test.sh (new, 33 checks).
  • The budget env equals timeout-minutes in seconds, and the margin leaves room for the steps after a wait.
  • The step sets the deadline at its start plus the timeout, less the margin.
  • No composite gets a rate-limit-wait-seconds override.
  • Waits are taken for a primary limit, a graphql limit, retry-after, a secondary limit, and a cleared limit.
  • A second limit after the wait fails the read.
  • A reset past the deadline fails at once, and later reads of that resource make no call while graphql reads are still sent.
  • A later wait that would end past the deadline is not taken.
  • A 403 or 404 that is not a rate limit returns at once.
  • The helper is the first step, every caller sources it, and every other gh api read is a write or marked exempt.
• scripts/ci-hold-human-gated.test.sh, end to end.
  • A rate-limited label read sleeps 125 s and passes.
  • A reset past the deadline fails closed, naming 2026-10-24T00:50:00Z.
  • A 403 that is not a rate limit fails closed with only the step's own 5 s and 10 s retries.
• Mutation. Dropping the margin from the deadline fails the suite.
• Full suite and checks. Every scripts/ci-*.test.sh passes, as do actionlint, shellcheck, shfmt, and check-affected.sh --tests on the merged head.
• Left out. A live run against a real exhausted rate limit, because one cannot be produced on demand.

Related

• Efficiency register row E5.
• perf(pr-pipeline): cut ci-status's GITHUB_TOKEN reads #9433: base-config checkout replacing the contents reads.
• perf(pr-pipeline): re-run ci-status once per head after the review lanes finish #9429: E10's rate-limit wait.
• The wait rules gh_read follows: melodic-software/ci-workflows .github/actions/pr-require-checks/gh-api.sh at v0.58.0.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-23T15:30:37.757030Z	64b6bb4	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[melodic-automation-lanes]

The pr-unblock lane stopped on this pull request and needs a person: a conflicted path is a workflow, submodule config or a settings file, which the lane does not resolve.

• Reason: protected-path-conflict
• Resume key: 64b6bb4744bd0f888752b28e59a1d59f24f9326b (the head the lane stopped on)

To resume, deal with the reason above, remove the needs-human label (and do-not-merge, if set), then dispatch the pr-unblock workflow with pr-number=9430 and activity=resolve-conflicts:

gh workflow run pr-unblock.yml -R melodic-software/claude-code-plugins -f pr-number=9430 -f activity=resolve-conflicts

[github-actions]

claude-security-review reviewed 89f0c702e71c50bb3396234fd4bf2871a62095b4: 0 finding(s), 0 as inline comments.

I found no security issues in the incremental change (.github/workflows/pr-require-checks.yml, scripts/ci-gh-read.test.sh, scripts/ci-hold-human-gated.test.sh, scripts/lib/ci-gh-read.sh). I read only those four files' change and used the PR context to check what it claims to do.

• Rate-limit deadline: pr-require-checks.yml now sets the deadline to GH_READ_JOB_SECONDS - GH_READ_MARGIN_SECONDS (660 − 300 s) after the helper step starts. A wait is taken only if it ends before that deadline.
  • A reset past the deadline still fails the read at once with ::error::, and later reads of that resource before the reset make no call.
  • Callers' own retries and fail-closed exits are unchanged, so no new fail-open path appears.
• Timeout cut from 28 to 11 minutes: this shortens the job's runtime and widens nothing. A job that hits the timeout ends red, never neutral, so it can't count as a passing required check.
• Removed RATE_LIMIT_WAIT_SECONDS and the two rate-limit-wait-seconds: inputs: both composites fall back to their own 60 s default, a smaller wait than the 600 s it replaces. The composites are still pinned by SHA (@5e18f3d…, v0.58.0).
• Error message text: the new ::error:: text interpolates the same values as before (resource, $*, and timestamps computed with jq). The $* interpolation was already there and the diff adds no new injection surface.
• scripts/lib/ci-gh-read.sh: the test helper reads the two env values from the workflow with a strict digit-only sed regex. It passes them as environment to bash -e on a step body extracted from the repository's own workflow file. No untrusted input reaches it.
• Test files: scripts/ci-gh-read.test.sh and scripts/ci-hold-human-gated.test.sh only update expected strings and assertions. They also add checks that the budget equals the timeout in seconds and that the margin is at least 240 s. This tightens the guard against drifting from the timeout.
• Embedded instructions: the PR context contains no directives aimed at the review lane.
• Manifests: no plugin.json or marketplace.json is touched, so there are no manifest <field> lines.
• Instruction surfaces: no standing instruction (CLAUDE.md, skill, hook allowlist) is removed or softened.
• Trust-gate paths: none are touched, so I set no hold.

critical-findings: 0

[github-actions]

claude-review reviewed 89f0c702e71c50bb3396234fd4bf2871a62095b4: 1 finding(s), 1 as inline comments.

Incremental review of 9a1c034..89f0c70 (ci-status timeout kept at 11 min, RATE_LIMIT_WAIT_SECONDS replaced by GH_READ_JOB_SECONDS and GH_READ_MARGIN_SECONDS, composites back on their 60 s default, test and helper updates). I read the diffs only and ran nothing. The pass and fail counts in the PR description are author-claimed and I did not check them.

I found no correctness bugs in the changed lines:

• The error text matches in the workflow, ci-gh-read.test.sh and ci-hold-human-gated.test.sh.
• ci_gh_read::install now passes the same two env values the workflow job defines, and it returns non-zero when either is missing.
• The new budget checks are consistent with each other: the job seconds equal 60 × the timeout, and the deadline equals the step start plus the job seconds less the margin.

One advisory finding, anchored inline: the 360 s wait budget is smaller than the 399 to 523 s resets the PR cites as its motivation, so those cases will still fail red rather than wait (see the comment on the env lines).

There is no cost or trust-gate hold. The change lowers the composites' rate-limit waits and adds no model call, schedule or runner. The PR has no closing issue, so I checked no acceptance criteria. No plugin manifests changed.

[melodic-automation-lanes]

The pr-unblock lane escalated this pull request as protected-path-conflict, and that no longer holds at b56afc3d44580e536a7f14e38c1ad0bc468b47e0: GitHub reports no conflict with main. pr-merge removed needs-human, so the lanes run on it again. To keep a person on it, add needs-human back: a label a person adds is never removed.

[melodic-automation-lanes]

The pr-unblock lane stopped on this pull request and needs a person: a conflicted path is a workflow, submodule config or a settings file, which the lane does not resolve.

• Reason: protected-path-conflict
• Resume key: b56afc3d44580e536a7f14e38c1ad0bc468b47e0 (the head the lane stopped on)

To resume, deal with the reason above, remove the needs-human label (and do-not-merge, if set), then dispatch the pr-unblock workflow with pr-number=9430 and activity=resolve-conflicts:

gh workflow run pr-unblock.yml -R melodic-software/claude-code-plugins -f pr-number=9430 -f activity=resolve-conflicts

[melodic-automation-lanes]

The pr-unblock lane escalated this pull request as protected-path-conflict, and that no longer holds at 9a1c0343b68047bdfccc4a5456e54577749ad2c8: GitHub reports no conflict with main. pr-merge removed needs-human, so the lanes run on it again. To keep a person on it, add needs-human back: a label a person adds is never removed.

[github-actions]

claude-review: 1 inline finding(s) on 89f0c702e71c50bb3396234fd4bf2871a62095b4; the summary is in this lane's pull request comment.

claude-lane: claude-review