From b994800061608b2ae656f142d3bb7b26d0bd3eff Mon Sep 17 00:00:00 2001
From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com>
Date: Fri, 23 Oct 2026 11:06:37 -0400
Subject: [PATCH 1/6] perf(pr-pipeline): wait for the rate-limit reset in
 ci-status instead of failing

ci-status failed closed whenever a GitHub API read hit the repository
GITHUB_TOKEN rate limit and asked for a re-run that landed in the same
empty window. The aggregate-results composite needed 399 to 523 s waits
against a 60 s ceiling in the 05:26Z and 09:24Z runs.

- Set RATE_LIMIT_WAIT_SECONDS: 600 on the job and pass it to the
  check-contract and aggregate-results composites, whose gh-api.sh already
  waits for the reset.
- Add a first step that writes gh_read, the same wait for the inline
  steps: on a rate limit it reads the reset from GET /rate_limit, waits
  until five seconds past it (60 s for a secondary limit) and reads again,
  under a job-wide ceiling; past it the read fails closed naming the reset.
  Every fail-closed read in the six hold and review steps goes through it.
- Raise timeout-minutes from 9 to 20 to hold one reset wait.
- Test the helper in scripts/ci-gh-read.test.sh and the recover, past the
  ceiling and non-rate-limit cases in ci-hold-human-gated.test.sh.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/pr-require-checks.yml | 118 ++++++++++++---
 scripts/ci-broker-pin.test.sh           |   5 +
 scripts/ci-gh-read.test.sh              | 191 ++++++++++++++++++++++++
 scripts/ci-hold-cost-decision.test.sh   |   5 +
 scripts/ci-hold-human-gated.test.sh     |  56 ++++++-
 scripts/ci-hold-lifted-by.test.sh       |   5 +
 scripts/ci-hold-merge-group.test.sh     |   5 +
 scripts/ci-review-lanes.test.sh         |   5 +
 scripts/lib/ci-gh-read.sh               |  20 +++
 9 files changed, 384 insertions(+), 26 deletions(-)
 create mode 100755 scripts/ci-gh-read.test.sh
 create mode 100644 scripts/lib/ci-gh-read.sh

diff --git a/.github/workflows/pr-require-checks.yml b/.github/workflows/pr-require-checks.yml
index b553872360..4d3e90bd5a 100644
--- a/.github/workflows/pr-require-checks.yml
+++ b/.github/workflows/pr-require-checks.yml
@@ -3104,17 +3104,24 @@ jobs:
     # `ci-lanes` commit status the last full run recorded on this SHA.
     if: ${{ !cancelled() }}
     runs-on: ubuntu-24.04
-    # 9 s p95 and 42 s max in full mode, about 10 s contract-only. The cap is
-    # the worst case of the pinned composites' waits: two 60 s rate-limit waits
-    # (`rate-limit-wait-seconds` on check-contract and aggregate-results), 45 s
-    # of own-gate retries, 7 s of status-write retries and the 90 s
-    # `rerun-wait-seconds` wait, about four and a half minutes, plus up to
-    # 15 s of retry sleeps for each of the hold-lift step's three reads and
-    # the review-lane step's four, under two minutes, plus the cost-hold step's
-    # reads: three for most pull requests, which stop at the label events; for a
-    # lane-labeled one whose body cites a decision, about ten, and two more per
-    # review run since the window opened.
-    timeout-minutes: 9
+    # 9 s p95 and 42 s max in full mode, about 10 s contract-only. The cap
+    # covers one wait for the primary rate limit's reset of up to
+    # RATE_LIMIT_WAIT_SECONDS (10 minutes), plus the pinned composites' other
+    # waits: 45 s of own-gate retries, 7 s of status-write retries and the 90 s
+    # `rerun-wait-seconds` wait, plus up to 15 s of retry sleeps for each of
+    # the hold-lift step's three reads and the review-lane step's four, plus
+    # the cost-hold step's reads: three for most pull requests, which stop at
+    # the label events; for a lane-labeled one whose body cites a decision,
+    # about ten, and two more per review run since the window opened. Only
+    # one wait in a run can reach a reset: the next one is an hour later, past
+    # the cap, so a read limited again fails at once; any other wait is 60 s
+    # for a secondary limit.
+    timeout-minutes: 20
+    env:
+      # The ceiling on rate-limit waits, for check-contract, aggregate-results
+      # and the gh_read steps below together. The limit-events rows that set it
+      # needed 399 to 523 s.
+      RATE_LIMIT_WAIT_SECONDS: 600
     permissions:
       # `yield-to-full-run` lists this workflow's runs on the head SHA, and
       # `rerun-contract-only-siblings` re-runs the red contract-only ones once
@@ -3132,10 +3139,70 @@ jobs:
       pull-requests: write
       statuses: write
     steps:
+      # A RATE-LIMITED READ WAITS FOR THE RESET. The steps below read through
+      # gh_read, which runs `gh api` and, when it fails on a rate limit, waits
+      # and reads again, as the pinned composites' gh-api.sh does: until five
+      # seconds past the reset when GET /rate_limit (which no limit counts)
+      # shows the resource (core, or graphql for a graphql call) at 0, else
+      # 60 s. It is a rate limit when gh's error names one, or is an HTTP 403
+      # or 429 while that resource is at 0. The waits of every step sum to at
+      # most RATE_LIMIT_WAIT_SECONDS; a wait that does not fit fails the read
+      # with an error naming the reset, and later reads before the reset fail
+      # without a call. Any other failure returns gh's status at once, so each
+      # caller's own retries and fail-closed exit stay as they were. This step
+      # writes the function for the others to source. Pinned by
+      # scripts/ci-gh-read.test.sh, which runs this body.
+      - name: Write the rate-limit-aware read helper
+        run: |
+          gh_read() {
+            local state="$RUNNER_TEMP/gh-read.state" cap=${RATE_LIMIT_WAIT_SECONDS:-600}
+            local resource=core spent=0 until=0 arg err out now limit remaining reset wait at
+            for arg; do [ "$arg" != graphql ] || resource=graphql; done
+            err=$(mktemp)
+            while :; do
+              [ ! -s "$state" ] || read -r spent until <"$state"
+              now=$(date +%s)
+              [ "$until" -le "$now" ] || { rm -f "$err"; return 1; }
+              if out=$(gh api "$@" 2>"$err"); then
+                cat "$err" >&2
+                rm -f "$err"
+                [ -z "$out" ] || printf '%s\n' "$out"
+                return 0
+              fi
+              cat "$err" >&2
+              grep -qiE 'rate limit|HTTP (403|429)' "$err" || { rm -f "$err"; return 1; }
+              limit=$(gh api rate_limit --jq ".resources.$resource | \"\(.remaining) \(.reset)\"" 2>/dev/null) || limit=
+              read -r remaining reset <<<"$limit"
+              if [ "$remaining" = 0 ] && [[ $reset =~ ^[0-9]{1,10}$ ]]; then
+                wait=$((reset - now + 5))
+                [ "$wait" -ge 5 ] || wait=5
+              elif grep -qi 'rate limit' "$err"; then
+                wait=60 reset=$((now + 60))
+              else
+                rm -f "$err"
+                return 1
+              fi
+              if [ $((spent + wait)) -gt "$cap" ]; then
+                at=$(jq -rn --argjson t "$reset" '$t | todate')
+                echo "::error::GitHub's $resource API rate limit blocks 'gh api $*' until $at, past the ${cap}s ci-status waits for a reset (${spent}s spent); re-run this run after $at." >&9
+                echo "$spent $reset" >"$state"
+                rm -f "$err"
+                return 1
+              fi
+              echo "::notice::'gh api $*' is rate limited ($resource); waiting ${wait}s for the reset, then reading again." >&9
+              sleep "$wait"
+              spent=$((spent + wait))
+              echo "$spent 0" >"$state"
+            done
+          }
+          # fd 9 is each sourcing step's stderr, so the notices reach the log
+          # when a caller captures or redirects gh_read's own stderr.
+          { echo 'exec 9>&2'; declare -f gh_read; } >"$RUNNER_TEMP/gh-read.sh"
       - name: Check the pull-request contract
         uses: melodic-software/ci-workflows/.github/actions/pr-require-checks/check-contract@5e18f3d6cebd6fa5e66b0941ee0f7ed6ba288d6c # v0.58.0
         with:
           token: ${{ github.token }}
+          rate-limit-wait-seconds: ${{ env.RATE_LIMIT_WAIT_SECONDS }}
           # Carried over verbatim from `pr-issue-linkage.yml`, the caller this
           # step replaces: dependabot PR bodies cannot carry the closing keyword
           # and the four contract sections, so its login is exempt from the
@@ -3160,10 +3227,11 @@ jobs:
           PR_BODY: ${{ github.event.pull_request.body }}
           PR_NUMBER: ${{ github.event.pull_request.number }}
         run: |
+          . "$RUNNER_TEMP/gh-read.sh"
           BROKER_PATHS='.github/actions/resolve-config/package.json
           .github/actions/resolve-config/package-lock.json'
           for attempt in 1 2 3; do
-            if files=$(gh api "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER/files?per_page=100" --paginate --jq '.[] | .filename, (.previous_filename // empty)'); then
+            if files=$(gh_read "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER/files?per_page=100" --paginate --jq '.[] | .filename, (.previous_filename // empty)'); then
               break
             fi
             [ "$attempt" -lt 3 ] || { echo "::error::could not read the files of #$PR_NUMBER; re-run this run."; exit 1; }
@@ -3295,6 +3363,7 @@ jobs:
           HEAD_SHA: ${{ github.event.pull_request.head.sha }}
           LANES_APP_ID: ${{ vars.AUTOMATION_LANES_APP_SENDER_ID }}
         run: |
+          . "$RUNNER_TEMP/gh-read.sh"
           keep() {
             echo "The cost hold stays for a person: $1."
             exit 0
@@ -3302,7 +3371,7 @@ jobs:
           read_api() {
             local attempt out
             for attempt in 1 2 3; do
-              if out=$(gh api "$@" 2>"$RUNNER_TEMP/cost-hold.err"); then
+              if out=$(gh_read "$@" 2>"$RUNNER_TEMP/cost-hold.err"); then
                 printf '%s\n' "$out"
                 return 0
               fi
@@ -3459,12 +3528,13 @@ jobs:
           PR_NUMBER: ${{ github.event.pull_request.number }}
           BASE_SHA: ${{ github.event.pull_request.base.sha }}
         run: |
+          . "$RUNNER_TEMP/gh-read.sh"
           if [[ ! $BASE_SHA =~ ^[0-9a-f]{40}$ ]]; then
             echo "::error::the base commit '$BASE_SHA' is not a commit SHA."
             exit 1
           fi
           for attempt in 1 2 3; do
-            if tracker=$(gh api -H 'Accept: application/vnd.github.raw+json' "repos/$GITHUB_REPOSITORY/contents/.work-item-tracker.json?ref=$BASE_SHA" 2>"$RUNNER_TEMP/tracker.err"); then
+            if tracker=$(gh_read -H 'Accept: application/vnd.github.raw+json' "repos/$GITHUB_REPOSITORY/contents/.work-item-tracker.json?ref=$BASE_SHA" 2>"$RUNNER_TEMP/tracker.err"); then
               break
             elif grep -q 'HTTP 404' "$RUNNER_TEMP/tracker.err"; then
               tracker=
@@ -3484,7 +3554,7 @@ jobs:
           fi
           echo "label=$human_gated" >>"$GITHUB_OUTPUT"
           for attempt in 1 2 3; do
-            if labels=$(gh api "repos/$GITHUB_REPOSITORY/issues/$PR_NUMBER/labels?per_page=100" --paginate --jq '.[].name'); then
+            if labels=$(gh_read "repos/$GITHUB_REPOSITORY/issues/$PR_NUMBER/labels?per_page=100" --paginate --jq '.[].name'); then
               break
             fi
             [ "$attempt" -lt 3 ] || { echo "::error::could not read the labels of #$PR_NUMBER; re-run this run."; exit 1; }
@@ -3534,13 +3604,14 @@ jobs:
           BASE_SHA: ${{ github.event.pull_request.base.sha }}
           HUMAN_GATED: ${{ steps.human_gated.outputs.label }}
         run: |
+          . "$RUNNER_TEMP/gh-read.sh"
           if [[ ! $BASE_SHA =~ ^[0-9a-f]{40}$ ]]; then
             echo "::error::the base commit '$BASE_SHA' is not a commit SHA."
             exit 1
           fi
           # shellcheck disable=SC2016 # the $ in the --jq filter is a regex anchor
           for attempt in 1 2 3; do
-            if held_at=$(gh api "repos/$GITHUB_REPOSITORY/issues/$PR_NUMBER/comments?per_page=100" --paginate \
+            if held_at=$(gh_read "repos/$GITHUB_REPOSITORY/issues/$PR_NUMBER/comments?per_page=100" --paginate \
               --jq '.[] | select(.user.type == "Bot" and (.body | test("(^|\n)<!-- claude-lane-hold lane="))
                 and (.user.login == "claude[bot]" or (.user.login == "github-actions[bot]"
                   and ([.body | splits("\r?\n") | gsub("^\\s+|\\s+$"; "") | select(. != "")] | last // ""
@@ -3552,7 +3623,7 @@ jobs:
             sleep $((attempt * 5))
           done
           for attempt in 1 2 3; do
-            if events=$(gh api "repos/$GITHUB_REPOSITORY/issues/$PR_NUMBER/events?per_page=100" --paginate); then
+            if events=$(gh_read "repos/$GITHUB_REPOSITORY/issues/$PR_NUMBER/events?per_page=100" --paginate); then
               break
             fi
             [ "$attempt" -lt 3 ] || { echo "::error::could not read the events of #$PR_NUMBER; re-run this run."; exit 1; }
@@ -3569,7 +3640,7 @@ jobs:
             exit 0
           fi
           for attempt in 1 2 3; do
-            if actors=$(gh api -H 'Accept: application/vnd.github.raw+json' "repos/$GITHUB_REPOSITORY/contents/.github/standards/trusted-actors/trusted-actors.json?ref=$BASE_SHA"); then
+            if actors=$(gh_read -H 'Accept: application/vnd.github.raw+json' "repos/$GITHUB_REPOSITORY/contents/.github/standards/trusted-actors/trusted-actors.json?ref=$BASE_SHA"); then
               break
             fi
             [ "$attempt" -lt 3 ] || { echo "::error::could not read the trusted-actor list at $BASE_SHA; re-run this run."; exit 1; }
@@ -3627,6 +3698,7 @@ jobs:
           AUTHOR_ID: ${{ github.event.pull_request.user.id }}
           PR_NUMBER: ${{ github.event.pull_request.number }}
         run: |
+          . "$RUNNER_TEMP/gh-read.sh"
           # dependabot[bot], melodic-plugin-release[bot] and
           # melodic-standards-sync[bot], as
           # .github/standards/trusted-actors/trusted-actors.json lists them.
@@ -3640,7 +3712,7 @@ jobs:
           read_api() {
             local attempt body
             for attempt in 1 2 3; do
-              if body=$(gh api "$2"); then
+              if body=$(gh_read "$2"); then
                 printf '%s\n' "$body"
                 return 0
               fi
@@ -3657,7 +3729,7 @@ jobs:
             fi
             pr=$(read_api "#$PR_NUMBER" "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER") || exit 1
             for attempt in 1 2 3; do
-              if files=$(gh api "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER/files?per_page=100" --paginate --jq '.[] | [.filename, (.previous_filename // "")] | @tsv'); then
+              if files=$(gh_read "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER/files?per_page=100" --paginate --jq '.[] | [.filename, (.previous_filename // "")] | @tsv'); then
                 break
               fi
               [ "$attempt" -lt 3 ] || { echo "::error::could not read the files of #$PR_NUMBER; re-run this run."; exit 1; }
@@ -3749,6 +3821,7 @@ jobs:
           GH_TOKEN: ${{ github.token }}
           BASE_SHA: ${{ github.event.merge_group.base_sha }}
         run: |
+          . "$RUNNER_TEMP/gh-read.sh"
           pr=$(sed -nE 's#^(refs/heads/)?gh-readonly-queue/.+/pr-([0-9]+)-[0-9a-f]{40}$#\2#p' <<<"$GITHUB_REF")
           if [ -z "$pr" ]; then
             echo "::error::cannot read a pull request number from the merge-group ref '$GITHUB_REF'."
@@ -3759,7 +3832,7 @@ jobs:
             exit 1
           fi
           for attempt in 1 2 3; do
-            if tracker=$(gh api -H 'Accept: application/vnd.github.raw+json' "repos/$GITHUB_REPOSITORY/contents/.work-item-tracker.json?ref=$BASE_SHA" 2>"$RUNNER_TEMP/tracker.err"); then
+            if tracker=$(gh_read -H 'Accept: application/vnd.github.raw+json' "repos/$GITHUB_REPOSITORY/contents/.work-item-tracker.json?ref=$BASE_SHA" 2>"$RUNNER_TEMP/tracker.err"); then
               break
             elif grep -q 'HTTP 404' "$RUNNER_TEMP/tracker.err"; then
               tracker=
@@ -3778,7 +3851,7 @@ jobs:
             }
           fi
           for attempt in 1 2 3; do
-            if labels=$(gh api "repos/$GITHUB_REPOSITORY/issues/$pr/labels?per_page=100" --paginate --jq '.[].name'); then
+            if labels=$(gh_read "repos/$GITHUB_REPOSITORY/issues/$pr/labels?per_page=100" --paginate --jq '.[].name'); then
               break
             fi
             [ "$attempt" -lt 3 ] || { echo "::error::could not read the labels of #$pr; re-run this run."; exit 1; }
@@ -3856,3 +3929,4 @@ jobs:
           # how many steps of the job are in progress.
           step-name: Aggregate lane results
           token: ${{ github.token }}
+          rate-limit-wait-seconds: ${{ env.RATE_LIMIT_WAIT_SECONDS }}
diff --git a/scripts/ci-broker-pin.test.sh b/scripts/ci-broker-pin.test.sh
index daa9829a10..8060095a97 100755
--- a/scripts/ci-broker-pin.test.sh
+++ b/scripts/ci-broker-pin.test.sh
@@ -22,6 +22,11 @@ WORKFLOW="$ROOT/.github/workflows/pr-require-checks.yml"
 TMP_ROOT="$(mktemp -d)"
 trap 'rm -rf "$TMP_ROOT"' EXIT
 
+# shellcheck source=lib/ci-gh-read.sh
+. "$ROOT/scripts/lib/ci-gh-read.sh"
+export RUNNER_TEMP="$TMP_ROOT"
+ci_gh_read::install "$WORKFLOW" "$TMP_ROOT" || fail "the ci-status gh_read helper step is missing or fails"
+
 NAME='Require a broker deploy PR for a resolve-config dependency change'
 step="$(awk -v name="      - name: $NAME" '$0 == name { on = 1; print; next }
   on && /^      - / { exit }
diff --git a/scripts/ci-gh-read.test.sh b/scripts/ci-gh-read.test.sh
new file mode 100755
index 0000000000..a3a08defde
--- /dev/null
+++ b/scripts/ci-gh-read.test.sh
@@ -0,0 +1,191 @@
+#!/usr/bin/env bash
+# Runs the `Write the rate-limit-aware read helper` step body of
+# .github/workflows/pr-require-checks.yml's ci-status, then calls the gh_read
+# function it writes, under bash -e, against stub `gh`, `sleep` and `date`.
+#
+# gh_read runs `gh api`. On a rate limit it waits until five seconds past the
+# reset GET /rate_limit reports (60 s when that resource is not at 0) and
+# reads again; the waits of the whole job sum to at most
+# RATE_LIMIT_WAIT_SECONDS, and a wait past that fails the read naming the
+# reset. Any other failure returns at once.
+# test-scope: .github/workflows/pr-require-checks.yml
+# shellcheck disable=SC2016 # the step snippets and the env expression are literal
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+WORKFLOW="$ROOT/.github/workflows/pr-require-checks.yml"
+
+# shellcheck source=lib/test-harness.sh
+. "$ROOT/scripts/lib/test-harness.sh"
+# shellcheck source=lib/ci-gh-read.sh
+. "$ROOT/scripts/lib/ci-gh-read.sh"
+
+TMP_ROOT="$(mktemp -d)"
+trap 'rm -rf "$TMP_ROOT"' EXIT
+
+if ! ci_gh_read::install "$WORKFLOW" "$TMP_ROOT"; then
+  fail "no working 'Write the rate-limit-aware read helper' step in $WORKFLOW"
+  test_harness::report
+  exit 1
+fi
+
+job="$(awk '/^  ci-status:$/ { on = 1 } on && /^  [a-z-]+:$/ && !/ci-status/ { exit } on { print }' "$WORKFLOW")"
+first="$(grep -m1 '^      - name: ' <<<"$job")"
+if [[ "$first" == "      - name: Write the rate-limit-aware read helper" ]]; then
+  ok "the helper is ci-status's first step, so no failure before it skips it"
+else
+  fail "ci-status's first step is '$first', not the helper"
+fi
+# Every step that reads through gh_read sources it first.
+while IFS= read -r name; do
+  body="$(awk -v name="      - name: $name" '$0 == name { on = 1; next } on && /^      - / { exit } on { print }' <<<"$job")"
+  if [[ "$body" == *$'        run: |\n          . "$RUNNER_TEMP/gh-read.sh"\n'* ]]; then
+    ok "'$name' sources gh_read before its reads"
+  else
+    fail "'$name' calls gh_read without sourcing it first"
+  fi
+done < <(awk '/^      - name: / { name = substr($0, 15) } /gh_read [-"]/ && name != "Write the rate-limit-aware read helper" { print name }' <<<"$job" | sort -u)
+cap="$(sed -nE 's/^      RATE_LIMIT_WAIT_SECONDS: ([0-9]+)$/\1/p' <<<"$job")"
+timeout="$(sed -nE 's/^    timeout-minutes: ([0-9]+)$/\1/p' <<<"$job")"
+if [[ -n "$cap" && -n "$timeout" && $((cap / 60 + 9)) -le "$timeout" ]]; then
+  ok "the job timeout ($timeout min) holds one ${cap}s reset wait plus the 9 min the other waits need"
+else
+  fail "the job timeout '$timeout' does not hold a '${cap}'s reset wait plus 9 minutes"
+fi
+if [[ "$(grep -c 'rate-limit-wait-seconds: \${{ env.RATE_LIMIT_WAIT_SECONDS }}' <<<"$job")" -eq 2 ]]; then
+  ok "check-contract and aggregate-results wait under the same ceiling"
+else
+  fail "check-contract and aggregate-results do not both take rate-limit-wait-seconds from RATE_LIMIT_WAIT_SECONDS"
+fi
+
+# The stub logs its arguments. GET /rate_limit prints STUB_LIMIT_<resource>
+# ("<remaining> <reset>") or fails when that is unset. Any other call takes the
+# next line of STUB_SCRIPT: `ok <stdout>`, or `fail <stderr>`.
+mkdir -p "$TMP_ROOT/bin"
+cat >"$TMP_ROOT/bin/gh" <<'EOF'
+#!/usr/bin/env bash
+printf '%s\n' "$*" >>"$STUB_LOG"
+if [[ "$2" == rate_limit ]]; then
+  [[ "$4" == .resources.core* ]] && v=${STUB_LIMIT_core:-} || v=${STUB_LIMIT_graphql:-}
+  [[ -n "$v" ]] || exit 1
+  printf '%s\n' "$v"
+  exit 0
+fi
+n=$(grep -vc '^api rate_limit ' "$STUB_LOG")
+line=$(sed -n "${n}p" <<<"$STUB_SCRIPT")
+case $line in
+ok\ *) printf '%s\n' "${line#ok }" ;;
+fail\ *) printf '%s\n' "${line#fail }" >&2; exit 1 ;;
+*) echo "unscripted call $n" >&2; exit 1 ;;
+esac
+EOF
+cat >"$TMP_ROOT/bin/sleep" <<'EOF'
+#!/usr/bin/env bash
+printf '%s\n' "$*" >>"$STUB_SLEEPS"
+EOF
+cat >"$TMP_ROOT/bin/date" <<'EOF'
+#!/usr/bin/env bash
+printf '%s\n' "$STUB_NOW"
+EOF
+chmod +x "$TMP_ROOT/bin/gh" "$TMP_ROOT/bin/sleep" "$TMP_ROOT/bin/date"
+
+LIMITED='fail gh: API rate limit exceeded for installation. (HTTP 403)'
+NOW=1792800000
+
+# run <calls...>: runs `. gh-read.sh` and then each argument as a command in
+# one bash -e step, with the job state kept from earlier runs unless reset.
+run() {
+  : >"$TMP_ROOT/log"
+  : >"$TMP_ROOT/sleeps"
+  out="$(PATH="$TMP_ROOT/bin:$PATH" RUNNER_TEMP="$TMP_ROOT" STUB_LOG="$TMP_ROOT/log" STUB_SLEEPS="$TMP_ROOT/sleeps" \
+    STUB_NOW="${STUB_NOW:-$NOW}" RATE_LIMIT_WAIT_SECONDS="${CAP:-600}" \
+    bash -ec ". \"\$RUNNER_TEMP/gh-read.sh\"; $1" 2>&1)" && rc=0 || rc=$?
+  calls=$(grep -vc '^api rate_limit ' "$TMP_ROOT/log")
+  sleeps=$(paste -sd' ' "$TMP_ROOT/sleeps")
+}
+fresh() { rm -f "$TMP_ROOT/gh-read.state"; }
+# check <label> <want-rc> <want-calls> <want-sleeps> [want-out] [refuse-out]
+check() {
+  if [[ "$rc" -ne "$2" ]]; then
+    fail "$1: expected rc=$2 got rc=$rc out='$out'"
+  elif [[ "$calls" -ne "$3" ]]; then
+    fail "$1: expected $3 read(s) got $calls: '$(cat "$TMP_ROOT/log")'"
+  elif [[ "$sleeps" != "$4" ]]; then
+    fail "$1: expected sleeps '$4' got '$sleeps'"
+  elif [[ -n "${5:-}" && "$out" != *"$5"* ]]; then
+    fail "$1: output lacks '$5': '$out'"
+  elif [[ -n "${6:-}" && "$out" == *"$6"* ]]; then
+    fail "$1: output has '$6': '$out'"
+  else
+    ok "$1"
+  fi
+}
+
+fresh
+STUB_SCRIPT='ok hello' run 'x=$(gh_read repos/o/r/pulls/1); echo "got $x"'
+check "a read that succeeds prints its output once" 0 1 "" "got hello"
+if [[ "$(cat "$TMP_ROOT/log")" == "api repos/o/r/pulls/1" ]]; then
+  ok "gh_read passes its arguments to gh api unchanged and reads no rate limit"
+else
+  fail "gh_read called '$(cat "$TMP_ROOT/log")'"
+fi
+
+fresh
+STUB_LIMIT_core="0 $((NOW + 30))" STUB_SCRIPT="$LIMITED
+ok after" run 'x=$(gh_read repos/o/r/pulls/1); echo "got $x"'
+check "a primary rate limit waits until five seconds past the reset and reads again" 0 2 "35" "got after" "got API"
+if [[ "$out" == *"::notice::'gh api repos/o/r/pulls/1' is rate limited (core); waiting 35s for the reset, then reading again."* ]]; then
+  ok "the wait is announced on the step's stderr even inside a capture"
+else
+  fail "the wait notice is missing: '$out'"
+fi
+
+fresh
+STUB_LIMIT_graphql="0 $((NOW + 50))" STUB_LIMIT_core="4999 $((NOW + 9))" STUB_SCRIPT='fail gh: GraphQL: API rate limit already exceeded for installation ID 1.
+ok {}' run 'gh_read graphql -f query=x >/dev/null'
+check "a graphql read waits for the graphql reset, not the core one" 0 2 "55"
+
+fresh
+STUB_LIMIT_core="4999 $((NOW + 9))" STUB_SCRIPT='fail gh: You have exceeded a secondary rate limit. (HTTP 403)
+ok fine' run 'gh_read repos/o/r/pulls/1 >/dev/null'
+check "a secondary rate limit waits 60 s" 0 2 "60"
+
+fresh
+STUB_SCRIPT="$LIMITED
+ok fine" run 'gh_read repos/o/r/pulls/1 >/dev/null'
+check "a rate limit whose reset is unreadable waits 60 s" 0 2 "60"
+
+fresh
+STUB_LIMIT_core="0 $((NOW + 30))" STUB_SCRIPT='fail gh: Forbidden (HTTP 403)
+ok fine' run 'gh_read repos/o/r/pulls/1 >/dev/null'
+check "a 403 while the core limit is at 0 is a rate limit" 0 2 "35"
+
+fresh
+STUB_LIMIT_core="0 $((NOW + 3000))" STUB_SCRIPT="$LIMITED" run 'gh_read repos/o/r/pulls/1 || echo "rc=$?"'
+check "a reset past the ceiling fails the read at once" 0 1 "" \
+  "::error::GitHub's core API rate limit blocks 'gh api repos/o/r/pulls/1' until 2026-10-24T00:50:00Z, past the 600s ci-status waits for a reset (0s spent); re-run this run after 2026-10-24T00:50:00Z."
+STUB_SCRIPT='ok never' run 'gh_read repos/o/r/pulls/2 || echo "rc=$?"'
+check "a later read, in a later step, before that reset fails without a call" 0 0 "" "rc=1" "::error::"
+STUB_NOW=$((NOW + 3000)) STUB_SCRIPT='ok again' run 'gh_read repos/o/r/pulls/2'
+check "a read after that reset is sent" 0 1 "" "again"
+
+fresh
+STUB_LIMIT_core="0 $((NOW + 400))" STUB_SCRIPT="$LIMITED
+ok one" run 'gh_read repos/o/r/pulls/1 >/dev/null'
+check "a first 405 s wait fits the 600 s ceiling" 0 2 "405"
+STUB_LIMIT_core="0 $((NOW + 300))" STUB_SCRIPT="$LIMITED" run 'gh_read repos/o/r/pulls/2 || echo "rc=$?"'
+check "a later step's wait counts what earlier steps spent" 0 1 "" "(405s spent)"
+
+fresh
+STUB_SCRIPT='fail gh: Not Found (HTTP 404)' run 'gh_read repos/o/r/contents/x 2>"$RUNNER_TEMP/err" || echo "rc=$?"; grep -c "HTTP 404" "$RUNNER_TEMP/err"'
+check "any other error returns at once, its text on the caller's stderr" 0 1 "" $'rc=1\n1'
+if grep -q '^api rate_limit ' "$TMP_ROOT/log"; then
+  fail "a 404 read the rate limit"
+else
+  ok "a 404 reads no rate limit"
+fi
+fresh
+STUB_LIMIT_core="4999 $((NOW + 30))" STUB_SCRIPT='fail gh: Resource not accessible by integration (HTTP 403)' run 'gh_read repos/o/r/pulls/1 || echo "rc=$?"'
+check "a 403 that is not a rate limit returns at once" 0 1 "" "rc=1" "::error::"
+
+test_harness::report
diff --git a/scripts/ci-hold-cost-decision.test.sh b/scripts/ci-hold-cost-decision.test.sh
index 57f3effc32..8512968745 100755
--- a/scripts/ci-hold-cost-decision.test.sh
+++ b/scripts/ci-hold-cost-decision.test.sh
@@ -24,6 +24,11 @@ WORKFLOW="$ROOT/.github/workflows/pr-require-checks.yml"
 TMP_ROOT="$(mktemp -d)"
 trap 'rm -rf "$TMP_ROOT"' EXIT
 
+# shellcheck source=lib/ci-gh-read.sh
+. "$ROOT/scripts/lib/ci-gh-read.sh"
+export RUNNER_TEMP="$TMP_ROOT"
+ci_gh_read::install "$WORKFLOW" "$TMP_ROOT" || fail "the ci-status gh_read helper step is missing or fails"
+
 NAME='Clear a cost-only review hold the owner decided'
 step="$(awk -v name="      - name: $NAME" '$0 == name { on = 1; print; next }
   on && /^      - / { exit }
diff --git a/scripts/ci-hold-human-gated.test.sh b/scripts/ci-hold-human-gated.test.sh
index acac62c00d..aa30aeb008 100755
--- a/scripts/ci-hold-human-gated.test.sh
+++ b/scripts/ci-hold-human-gated.test.sh
@@ -20,6 +20,11 @@ WORKFLOW="$ROOT/.github/workflows/pr-require-checks.yml"
 TMP_ROOT="$(mktemp -d)"
 trap 'rm -rf "$TMP_ROOT"' EXIT
 
+# shellcheck source=lib/ci-gh-read.sh
+. "$ROOT/scripts/lib/ci-gh-read.sh"
+export RUNNER_TEMP="$TMP_ROOT"
+ci_gh_read::install "$WORKFLOW" "$TMP_ROOT" || fail "the ci-status gh_read helper step is missing or fails"
+
 NAME='Fail a pull request carrying the human-gated label'
 step="$(awk -v name="      - name: $NAME" '$0 == name { on = 1; print; next }
   on && /^      - / { exit }
@@ -87,7 +92,7 @@ case "$*" in
   printf '%s\n' "$STUB_TRACKER"
   ;;
 */labels*)
-  [[ "$(grep -c '/labels' "$STUB_LOG")" -gt "${STUB_FAILS:-0}" ]] || exit 1
+  [[ "$(grep -c '/labels' "$STUB_LOG")" -gt "${STUB_FAILS:-0}" ]] || { printf '%s\n' "${STUB_FAIL_TEXT:-}" >&2; exit 1; }
   [[ -z "$STUB_LABELS" ]] || tr ',' '\n' <<<"$STUB_LABELS"
   ;;
 */comments*)
@@ -95,11 +100,23 @@ case "$*" in
   while [[ $# -gt 0 && "$1" != --jq ]]; do shift; done
   jq -r "$2" <<<"${STUB_COMMENTS:-[]}"
   ;;
+'api rate_limit '*)
+  [[ -n "${STUB_RATE_LIMIT:-}" ]] || exit 1
+  printf '%s\n' "$STUB_RATE_LIMIT"
+  ;;
 *) exit 1 ;;
 esac
 EOF
-printf '#!/usr/bin/env bash\n' >"$TMP_ROOT/bin/sleep"
-chmod +x "$TMP_ROOT/bin/gh" "$TMP_ROOT/bin/sleep"
+# sleep logs its seconds; date +%s answers STUB_NOW.
+cat >"$TMP_ROOT/bin/sleep" <<'EOF'
+#!/usr/bin/env bash
+printf '%s\n' "$*" >>"$STUB_SLEEPS"
+EOF
+cat >"$TMP_ROOT/bin/date" <<'EOF'
+#!/usr/bin/env bash
+printf '%s\n' "$STUB_NOW"
+EOF
+chmod +x "$TMP_ROOT/bin/gh" "$TMP_ROOT/bin/sleep" "$TMP_ROOT/bin/date"
 
 BASE=89abcdef0123456789abcdef0123456789abcdef
 CUSTOM='{"config":{"role_labels":{"human-gated":"owner-call"}}}'
@@ -117,8 +134,10 @@ OTHER_BOT="$(hold "$LANE" $'A comment with no hold marker.\nclaude-lane: claude-
 expect() {
   local label="$1" want_rc="$2" want_calls="$3" out rc calls
   : >"$TMP_ROOT/log"
+  : >"$TMP_ROOT/sleeps"
+  rm -f "$TMP_ROOT/gh-read.state"
   : >"$TMP_ROOT/output"
-  out="$(PATH="$TMP_ROOT/bin:$PATH" STUB_LOG="$TMP_ROOT/log" STUB_LABELS="$4" STUB_FAILS="$5" PR_NUMBER=6419 \
+  out="$(PATH="$TMP_ROOT/bin:$PATH" STUB_LOG="$TMP_ROOT/log" STUB_SLEEPS="$TMP_ROOT/sleeps" STUB_NOW=1792800000 STUB_LABELS="$4" STUB_FAILS="$5" PR_NUMBER=6419 \
     GITHUB_REPOSITORY=o/r RUNNER_TEMP="$TMP_ROOT" GITHUB_OUTPUT="$TMP_ROOT/output" BASE_SHA="${BASE_SHA-$BASE}" \
     bash -e "$TMP_ROOT/body.sh" 2>&1)" && rc=0 || rc=$?
   calls=$(grep -c '/labels' "$TMP_ROOT/log")
@@ -174,6 +193,35 @@ expect "an unreadable comment list still fails, without a reason" 1 1 "needs-hum
 unset STUB_COMMENTS STUB_COMMENTS_FAIL
 
 expect "a transient label read failure is retried" 1 2 "needs-human" 1
+
+# A rate-limited read waits until five seconds past the reset and reads again;
+# a reset past the 600 s ceiling fails closed naming it; any other error keeps
+# the caller's retries and is never waited on.
+sleeps() { paste -sd' ' "$TMP_ROOT/sleeps"; }
+export STUB_FAIL_TEXT='gh: API rate limit exceeded for installation. (HTTP 403)' STUB_RATE_LIMIT='0 1792800120'
+expect "a rate-limited label read recovers after the reset" 0 2 "enhancement" 1 \
+  "is rate limited (core); waiting 125s for the reset, then reading again."
+if [[ "$(sleeps)" == 125 ]]; then
+  ok "the rate-limited read slept until five seconds past the reset"
+else
+  fail "the rate-limited read slept '$(sleeps)', not 125"
+fi
+export STUB_RATE_LIMIT='0 1792803000'
+expect "a reset past the ceiling fails closed naming the reset" 1 1 "enhancement" 3 \
+  "::error::GitHub's core API rate limit blocks 'gh api repos/o/r/issues/6419/labels?per_page=100 --paginate --jq .[].name' until 2026-10-24T00:50:00Z, past the 600s ci-status waits for a reset (0s spent); re-run this run after 2026-10-24T00:50:00Z."
+if [[ "$(sleeps)" == "5 10" ]]; then
+  ok "a reset past the ceiling is not waited for, and the retries make no call"
+else
+  fail "a reset past the ceiling slept '$(sleeps)', not the caller's '5 10'"
+fi
+export STUB_FAIL_TEXT='gh: Resource not accessible by integration (HTTP 403)' STUB_RATE_LIMIT='4999 1792800120'
+expect "a 403 that is not a rate limit fails closed without a wait" 1 3 "" 3 "::error::could not read the labels of #6419" "rate limited"
+if [[ "$(sleeps)" == "5 10" ]]; then
+  ok "a 403 that is not a rate limit keeps the caller's retries only"
+else
+  fail "a 403 that is not a rate limit slept '$(sleeps)'"
+fi
+unset STUB_FAIL_TEXT STUB_RATE_LIMIT
 expect "an unreadable label list fails closed" 1 3 "" 3 "::error::could not read the labels of #6419"
 if grep -q '^held=' "$TMP_ROOT/output"; then
   fail "an unreadable label list output held"
diff --git a/scripts/ci-hold-lifted-by.test.sh b/scripts/ci-hold-lifted-by.test.sh
index 531900ceb0..18648302f6 100755
--- a/scripts/ci-hold-lifted-by.test.sh
+++ b/scripts/ci-hold-lifted-by.test.sh
@@ -19,6 +19,11 @@ WORKFLOW="$ROOT/.github/workflows/pr-require-checks.yml"
 TMP_ROOT="$(mktemp -d)"
 trap 'rm -rf "$TMP_ROOT"' EXIT
 
+# shellcheck source=lib/ci-gh-read.sh
+. "$ROOT/scripts/lib/ci-gh-read.sh"
+export RUNNER_TEMP="$TMP_ROOT"
+ci_gh_read::install "$WORKFLOW" "$TMP_ROOT" || fail "the ci-status gh_read helper step is missing or fails"
+
 NAME='Fail a review-lane hold an untrusted account lifted'
 step="$(awk -v name="      - name: $NAME" '$0 == name { on = 1; print; next }
   on && /^      - / { exit }
diff --git a/scripts/ci-hold-merge-group.test.sh b/scripts/ci-hold-merge-group.test.sh
index b756a105ea..eab26dad5f 100755
--- a/scripts/ci-hold-merge-group.test.sh
+++ b/scripts/ci-hold-merge-group.test.sh
@@ -19,6 +19,11 @@ WORKFLOW="$ROOT/.github/workflows/pr-require-checks.yml"
 TMP_ROOT="$(mktemp -d)"
 trap 'rm -rf "$TMP_ROOT"' EXIT
 
+# shellcheck source=lib/ci-gh-read.sh
+. "$ROOT/scripts/lib/ci-gh-read.sh"
+export RUNNER_TEMP="$TMP_ROOT"
+ci_gh_read::install "$WORKFLOW" "$TMP_ROOT" || fail "the ci-status gh_read helper step is missing or fails"
+
 NAME='Fail a queued pull request carrying a hold label'
 step="$(awk -v name="      - name: $NAME" '$0 == name { on = 1; print; next }
   on && /^      - / { exit }
diff --git a/scripts/ci-review-lanes.test.sh b/scripts/ci-review-lanes.test.sh
index 21626577ac..72531c7b07 100755
--- a/scripts/ci-review-lanes.test.sh
+++ b/scripts/ci-review-lanes.test.sh
@@ -21,6 +21,11 @@ WORKFLOW="$ROOT/.github/workflows/pr-require-checks.yml"
 TMP_ROOT="$(mktemp -d)"
 trap 'rm -rf "$TMP_ROOT"' EXIT
 
+# shellcheck source=lib/ci-gh-read.sh
+. "$ROOT/scripts/lib/ci-gh-read.sh"
+export RUNNER_TEMP="$TMP_ROOT"
+ci_gh_read::install "$WORKFLOW" "$TMP_ROOT" || fail "the ci-status gh_read helper step is missing or fails"
+
 NAME='Require both review lanes on this head'
 step="$(awk -v name="      - name: $NAME" '$0 == name { on = 1; print; next }
   on && /^      - / { exit }
diff --git a/scripts/lib/ci-gh-read.sh b/scripts/lib/ci-gh-read.sh
new file mode 100644
index 0000000000..15c4a1d249
--- /dev/null
+++ b/scripts/lib/ci-gh-read.sh
@@ -0,0 +1,20 @@
+# shellcheck shell=bash
+# Writes ci-status's gh_read helper for the step-body tests. Sourced, never
+# executed.
+#
+#   ci_gh_read::install <workflow> <dir>
+#
+# Runs the `Write the rate-limit-aware read helper` step body of <workflow>
+# with RUNNER_TEMP=<dir>, which leaves <dir>/gh-read.sh for the step bodies
+# under test to source. Returns non-zero when the step is missing or fails.
+ci_gh_read::install() {
+  local workflow="$1" dir="$2"
+  awk '$0 == "      - name: Write the rate-limit-aware read helper" { on = 1; next }
+    on && /^      - / { exit }
+    on && /^        run: \|$/ { body = 1; next }
+    body && /^          / { print substr($0, 11); next }
+    body && /^[[:blank:]]*$/ { print ""; next }
+    body { exit }' "$workflow" >"$dir/gh-read-step.sh"
+  [[ -s "$dir/gh-read-step.sh" ]] || return 1
+  RUNNER_TEMP="$dir" bash -e "$dir/gh-read-step.sh" && [[ -s "$dir/gh-read.sh" ]]
+}

From e88c48a96103a18c8b16537c3316ec9913436853 Mon Sep 17 00:00:00 2001
From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com>
Date: Fri, 23 Oct 2026 11:20:58 -0400
Subject: [PATCH 2/6] fix(pr-pipeline): bound ci-status rate-limit waits by a
 deadline per run

Review of the first commit found two gaps and a fail-open:

- gh_read's job-wide budget did not include the composites' waits, and
  core and graphql reset on separate windows, so two reset waits plus the
  other waits could pass the 20-minute timeout. gh_read now waits only
  until a deadline RATE_LIMIT_WAIT_SECONDS after the job starts, which
  check-contract's wait also spends; the timeout is 25 minutes for that
  window, aggregate-results' own and five minutes of other waits.
- A block past the deadline was stored for every resource, so a graphql
  block stopped later core reads. Blocks are now kept per resource.
- The cost-hold step reads plain gh api again: its failure keeps the
  hold, and a wait there would remove the label on reads made before a
  newer hold landed.
- gh_read waits once per call, like the composites' gh-api.sh, and reads
  again after one second when the window has already reset.
- pr-feedback-dispatch polls an in-progress ci-status for 26 minutes, past
  its new timeout, so the re-run after a review is not skipped.
- A test fails any new plain gh api read in ci-status that is neither a
  write nor marked gh-read-exempt.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/pr-feedback-dispatch.yml |   7 +-
 .github/workflows/pr-require-checks.yml    | 107 ++++++++++++---------
 docs/conventions/pr-pipeline/README.md     |   3 +-
 scripts/ci-gh-read.test.sh                 |  77 +++++++++++----
 scripts/ci-hold-cost-decision.test.sh      |   5 -
 scripts/ci-hold-human-gated.test.sh        |  12 +--
 scripts/ci-rerun-ci-status.test.sh         |   2 +-
 scripts/lib/ci-gh-read.sh                  |  10 ++
 8 files changed, 140 insertions(+), 83 deletions(-)

diff --git a/.github/workflows/pr-feedback-dispatch.yml b/.github/workflows/pr-feedback-dispatch.yml
index 7b110db041..b6e0793c32 100644
--- a/.github/workflows/pr-feedback-dispatch.yml
+++ b/.github/workflows/pr-feedback-dispatch.yml
@@ -271,7 +271,8 @@ jobs:
   # never runs, so neither starts it. A head the PR has moved past, or a
   # closed PR, is left alone. A ci-status job not started yet reads the
   # reviews when it starts, so it is left alone too; one in progress is
-  # polled every 60 s for at most 10 minutes, then re-run. No checkout, no
+  # polled every 60 s for at most 26 minutes, longer than ci-status's
+  # 25-minute timeout, then re-run. No checkout, no
   # model: the token can only read runs and the PR and re-run a job.
   # Pinned by scripts/ci-rerun-ci-status.test.sh, which runs this body.
   rerun-ci-status:
@@ -284,7 +285,7 @@ jobs:
       && github.event.workflow_run.repository.full_name == github.repository
       && github.event.workflow_run.head_repository.full_name == github.repository
     runs-on: ubuntu-24.04
-    timeout-minutes: 15
+    timeout-minutes: 30
     permissions:
       actions: write # list pr-require-checks runs and jobs; re-run the ci-status job
       pull-requests: read # the PR's state and live head
@@ -295,7 +296,7 @@ jobs:
           HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
           PR_NUMBER: ${{ github.event.workflow_run.pull_requests[0].number }}
           POLL_SECONDS: '60'
-          POLL_LIMIT_SECONDS: '600'
+          POLL_LIMIT_SECONDS: '1560'
         run: |
           if [[ ! $HEAD_SHA =~ ^[0-9a-f]{40}$ ]]; then
             echo "::error::the review run's head '$HEAD_SHA' is not a commit SHA."
diff --git a/.github/workflows/pr-require-checks.yml b/.github/workflows/pr-require-checks.yml
index 4d3e90bd5a..ed3d3cf4ab 100644
--- a/.github/workflows/pr-require-checks.yml
+++ b/.github/workflows/pr-require-checks.yml
@@ -3105,22 +3105,23 @@ jobs:
     if: ${{ !cancelled() }}
     runs-on: ubuntu-24.04
     # 9 s p95 and 42 s max in full mode, about 10 s contract-only. The cap
-    # covers one wait for the primary rate limit's reset of up to
-    # RATE_LIMIT_WAIT_SECONDS (10 minutes), plus the pinned composites' other
-    # waits: 45 s of own-gate retries, 7 s of status-write retries and the 90 s
-    # `rerun-wait-seconds` wait, plus up to 15 s of retry sleeps for each of
-    # the hold-lift step's three reads and the review-lane step's four, plus
-    # the cost-hold step's reads: three for most pull requests, which stop at
-    # the label events; for a lane-labeled one whose body cites a decision,
-    # about ten, and two more per review run since the window opened. Only
-    # one wait in a run can reach a reset: the next one is an hour later, past
-    # the cap, so a read limited again fails at once; any other wait is 60 s
-    # for a secondary limit.
-    timeout-minutes: 20
+    # holds two rate-limit windows of RATE_LIMIT_WAIT_SECONDS (10 minutes):
+    # one shared by check-contract and the gh_read steps, which wait only
+    # until RATE_LIMIT_WAIT_SECONDS past the job's start, and aggregate-results'
+    # own. Core and graphql reset on separate hourly windows, so each window
+    # can hold a reset wait. Then about five minutes of other waits: 45 s of
+    # own-gate retries, 7 s of status-write retries and the 90 s
+    # `rerun-wait-seconds` wait, up to 15 s of retry sleeps for each of the
+    # hold-lift step's three reads and the review-lane step's four, and the
+    # cost-hold step's reads: three for most pull requests, which stop at the
+    # label events; for a lane-labeled one whose body cites a decision, about
+    # ten, and two more per review run since the window opened.
+    # pr-feedback-dispatch.yml polls an in-progress ci-status for longer than
+    # this cap.
+    timeout-minutes: 25
     env:
-      # The ceiling on rate-limit waits, for check-contract, aggregate-results
-      # and the gh_read steps below together. The limit-events rows that set it
-      # needed 399 to 523 s.
+      # The rate-limit wait ceiling of each window above. The limit-events
+      # rows that set it needed 399 to 523 s.
       RATE_LIMIT_WAIT_SECONDS: 600
     permissions:
       # `yield-to-full-run` lists this workflow's runs on the head SHA, and
@@ -3139,30 +3140,35 @@ jobs:
       pull-requests: write
       statuses: write
     steps:
-      # A RATE-LIMITED READ WAITS FOR THE RESET. The steps below read through
-      # gh_read, which runs `gh api` and, when it fails on a rate limit, waits
-      # and reads again, as the pinned composites' gh-api.sh does: until five
+      # A RATE-LIMITED READ WAITS FOR THE RESET. The fail-closed steps below
+      # read through gh_read, which runs `gh api` and, when that fails on a
+      # rate limit, waits once and reads again. The wait runs until five
       # seconds past the reset when GET /rate_limit (which no limit counts)
-      # shows the resource (core, or graphql for a graphql call) at 0, else
-      # 60 s. It is a rate limit when gh's error names one, or is an HTTP 403
-      # or 429 while that resource is at 0. The waits of every step sum to at
-      # most RATE_LIMIT_WAIT_SECONDS; a wait that does not fit fails the read
-      # with an error naming the reset, and later reads before the reset fail
-      # without a call. Any other failure returns gh's status at once, so each
-      # caller's own retries and fail-closed exit stay as they were. This step
-      # writes the function for the others to source. Pinned by
+      # shows the resource (core, or graphql for a graphql call) at 0; 60 s for
+      # a secondary limit or when the reset cannot be read; one second when the
+      # window has already reset. It is a rate limit when gh's error names one,
+      # or is an HTTP 403 or 429 while that resource is at 0. A wait that would
+      # end past the deadline this step sets, RATE_LIMIT_WAIT_SECONDS after it
+      # runs, fails the read with an error naming the reset, and later reads
+      # of that resource before the reset fail without a call. Any other
+      # failure, or a second rate limit after the wait, returns gh's status at
+      # once, so each caller's own retries and fail-closed exit stay as they
+      # were. The cost-hold step keeps plain `gh api`: an unreadable input
+      # keeps its hold, and a wait there would act on reads made before it.
+      # Every other `gh api` in this job is a write or marked gh-read-exempt.
+      # This step writes the function for the others to source. Pinned by
       # scripts/ci-gh-read.test.sh, which runs this body.
       - name: Write the rate-limit-aware read helper
         run: |
           gh_read() {
-            local state="$RUNNER_TEMP/gh-read.state" cap=${RATE_LIMIT_WAIT_SECONDS:-600}
-            local resource=core spent=0 until=0 arg err out now limit remaining reset wait at
+            local resource=core until=0 deadline arg err out now limit remaining reset wait at waited=
             for arg; do [ "$arg" != graphql ] || resource=graphql; done
+            local blocked="$RUNNER_TEMP/gh-read.until-$resource"
+            deadline=$(cat "$RUNNER_TEMP/gh-read.deadline")
+            [ ! -s "$blocked" ] || until=$(cat "$blocked")
+            [ "$until" -le "$(date +%s)" ] || return 1
             err=$(mktemp)
             while :; do
-              [ ! -s "$state" ] || read -r spent until <"$state"
-              now=$(date +%s)
-              [ "$until" -le "$now" ] || { rm -f "$err"; return 1; }
               if out=$(gh api "$@" 2>"$err"); then
                 cat "$err" >&2
                 rm -f "$err"
@@ -3170,31 +3176,37 @@ jobs:
                 return 0
               fi
               cat "$err" >&2
-              grep -qiE 'rate limit|HTTP (403|429)' "$err" || { rm -f "$err"; return 1; }
-              limit=$(gh api rate_limit --jq ".resources.$resource | \"\(.remaining) \(.reset)\"" 2>/dev/null) || limit=
-              read -r remaining reset <<<"$limit"
-              if [ "$remaining" = 0 ] && [[ $reset =~ ^[0-9]{1,10}$ ]]; then
-                wait=$((reset - now + 5))
-                [ "$wait" -ge 5 ] || wait=5
-              elif grep -qi 'rate limit' "$err"; then
-                wait=60 reset=$((now + 60))
-              else
+              wait=
+              if [ -z "$waited" ] && grep -qiE 'rate limit|HTTP (403|429)' "$err"; then
+                now=$(date +%s)
+                limit=$(gh api rate_limit --jq ".resources.$resource | \"\(.remaining) \(.reset)\"" 2>/dev/null) || limit=
+                read -r remaining reset <<<"$limit"
+                if [ "$remaining" = 0 ] && [[ $reset =~ ^[0-9]{1,10}$ ]]; then
+                  wait=$((reset - now + 5))
+                  [ "$wait" -ge 5 ] || wait=5
+                elif grep -qi 'secondary rate limit' "$err" || { grep -qi 'rate limit' "$err" && [[ ! $remaining =~ ^[0-9]+$ ]]; }; then
+                  wait=60 reset=$((now + 60))
+                elif grep -qi 'rate limit' "$err"; then
+                  wait=1 reset=$((now + 1))
+                fi
+              fi
+              if [ -z "$wait" ]; then
                 rm -f "$err"
                 return 1
               fi
-              if [ $((spent + wait)) -gt "$cap" ]; then
+              if [ $((now + wait)) -gt "$deadline" ]; then
                 at=$(jq -rn --argjson t "$reset" '$t | todate')
-                echo "::error::GitHub's $resource API rate limit blocks 'gh api $*' until $at, past the ${cap}s ci-status waits for a reset (${spent}s spent); re-run this run after $at." >&9
-                echo "$spent $reset" >"$state"
+                echo "::error::GitHub's $resource API rate limit blocks 'gh api $*' until $at, after ci-status stops waiting at $(jq -rn --argjson t "$deadline" '$t | todate'); re-run this run after $at." >&9
+                echo "$reset" >"$blocked"
                 rm -f "$err"
                 return 1
               fi
               echo "::notice::'gh api $*' is rate limited ($resource); waiting ${wait}s for the reset, then reading again." >&9
               sleep "$wait"
-              spent=$((spent + wait))
-              echo "$spent 0" >"$state"
+              waited=1
             done
           }
+          echo $(($(date +%s) + RATE_LIMIT_WAIT_SECONDS)) >"$RUNNER_TEMP/gh-read.deadline"
           # fd 9 is each sourcing step's stderr, so the notices reach the log
           # when a caller captures or redirects gh_read's own stderr.
           { echo 'exec 9>&2'; declare -f gh_read; } >"$RUNNER_TEMP/gh-read.sh"
@@ -3363,7 +3375,6 @@ jobs:
           HEAD_SHA: ${{ github.event.pull_request.head.sha }}
           LANES_APP_ID: ${{ vars.AUTOMATION_LANES_APP_SENDER_ID }}
         run: |
-          . "$RUNNER_TEMP/gh-read.sh"
           keep() {
             echo "The cost hold stays for a person: $1."
             exit 0
@@ -3371,7 +3382,8 @@ jobs:
           read_api() {
             local attempt out
             for attempt in 1 2 3; do
-              if out=$(gh_read "$@" 2>"$RUNNER_TEMP/cost-hold.err"); then
+              # gh-read-exempt: an unreadable input keeps the hold, and a wait would act on stale reads.
+              if out=$(gh api "$@" 2>"$RUNNER_TEMP/cost-hold.err"); then
                 printf '%s\n' "$out"
                 return 0
               fi
@@ -3565,6 +3577,7 @@ jobs:
             echo "#$PR_NUMBER carries no '$human_gated' label."
             exit 0
           fi
+          # gh-read-exempt: the reason is best effort; the step fails either way.
           reason=$(gh api "repos/$GITHUB_REPOSITORY/issues/$PR_NUMBER/comments?per_page=100" --paginate \
             --jq '.[] | select(.user.type == "Bot" and (.body | test("(^|\n)<!-- claude-lane-hold lane="))
               and (.user.login == "claude[bot]" or (.user.login == "github-actions[bot]"
diff --git a/docs/conventions/pr-pipeline/README.md b/docs/conventions/pr-pipeline/README.md
index 6dac1ea6a9..eb908b2cda 100644
--- a/docs/conventions/pr-pipeline/README.md
+++ b/docs/conventions/pr-pipeline/README.md
@@ -1440,7 +1440,8 @@ A review usually finishes after ci-status has read it, so `pr-feedback-dispatch.
 `rerun-ci-status` job re-runs the ci-status job of the newest `pr-require-checks` run on the head
 whenever either review caller completes (not when GitHub skipped it) on an open same-repository PR
 still at that head. A ci-status not started yet is left to read the reviews itself; one in progress
-is polled every 60 seconds for at most 10 minutes first. The merge-group run re-checks the labels.
+is polled every 60 seconds first, for at most 26 minutes, past ci-status's 25-minute timeout. The
+merge-group run re-checks the labels.
 `fix-ci` keys on `ci-lanes`, so a hold or a pending review never summons it.
 
 ## Trust-root paths
diff --git a/scripts/ci-gh-read.test.sh b/scripts/ci-gh-read.test.sh
index a3a08defde..3a490c12e6 100755
--- a/scripts/ci-gh-read.test.sh
+++ b/scripts/ci-gh-read.test.sh
@@ -3,17 +3,20 @@
 # .github/workflows/pr-require-checks.yml's ci-status, then calls the gh_read
 # function it writes, under bash -e, against stub `gh`, `sleep` and `date`.
 #
-# gh_read runs `gh api`. On a rate limit it waits until five seconds past the
-# reset GET /rate_limit reports (60 s when that resource is not at 0) and
-# reads again; the waits of the whole job sum to at most
-# RATE_LIMIT_WAIT_SECONDS, and a wait past that fails the read naming the
-# reset. Any other failure returns at once.
+# gh_read runs `gh api`. On a rate limit it waits once and reads again: until
+# five seconds past the reset GET /rate_limit reports for the resource, 60 s
+# for a secondary limit or an unreadable reset, one second when the window has
+# already reset. A wait that would end past the deadline the step sets,
+# RATE_LIMIT_WAIT_SECONDS after it runs, fails the read naming the reset and
+# blocks that resource until it. Any other failure returns at once.
 # test-scope: .github/workflows/pr-require-checks.yml
+# test-scope: .github/workflows/pr-feedback-dispatch.yml
 # shellcheck disable=SC2016 # the step snippets and the env expression are literal
 set -uo pipefail
 
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 WORKFLOW="$ROOT/.github/workflows/pr-require-checks.yml"
+DISPATCH="$ROOT/.github/workflows/pr-feedback-dispatch.yml"
 
 # shellcheck source=lib/test-harness.sh
 . "$ROOT/scripts/lib/test-harness.sh"
@@ -23,11 +26,16 @@ WORKFLOW="$ROOT/.github/workflows/pr-require-checks.yml"
 TMP_ROOT="$(mktemp -d)"
 trap 'rm -rf "$TMP_ROOT"' EXIT
 
-if ! ci_gh_read::install "$WORKFLOW" "$TMP_ROOT"; then
+if ! RATE_LIMIT_WAIT_SECONDS=600 ci_gh_read::install "$WORKFLOW" "$TMP_ROOT"; then
   fail "no working 'Write the rate-limit-aware read helper' step in $WORKFLOW"
   test_harness::report
   exit 1
 fi
+if [[ "$(cat "$TMP_ROOT/gh-read.deadline")" -ge $(($(date +%s) + 590)) ]]; then
+  ok "the step sets the wait deadline RATE_LIMIT_WAIT_SECONDS after it runs"
+else
+  fail "the step set the deadline '$(cat "$TMP_ROOT/gh-read.deadline")'"
+fi
 
 job="$(awk '/^  ci-status:$/ { on = 1 } on && /^  [a-z-]+:$/ && !/ci-status/ { exit } on { print }' "$WORKFLOW")"
 first="$(grep -m1 '^      - name: ' <<<"$job")"
@@ -45,18 +53,34 @@ while IFS= read -r name; do
     fail "'$name' calls gh_read without sourcing it first"
   fi
 done < <(awk '/^      - name: / { name = substr($0, 15) } /gh_read [-"]/ && name != "Write the rate-limit-aware read helper" { print name }' <<<"$job" | sort -u)
+# Every other `gh api` in the job is a write, or marked gh-read-exempt on the
+# line above, so a new fail-closed read cannot skip the wait unnoticed.
+stray="$(awk '/^      - name: / { helper = ($0 == "      - name: Write the rate-limit-aware read helper") }
+  !helper && /gh api / && $0 !~ /^ *#/ && $0 !~ /gh api -X (POST|DELETE|PATCH|PUT) / && prev !~ /# gh-read-exempt: / { print }
+  { prev = $0 }' <<<"$job")"
+if [[ -z "$stray" ]]; then
+  ok "every other gh api in ci-status is a write or marked gh-read-exempt"
+else
+  fail "ci-status reads through plain gh api without a gh-read-exempt mark: $stray"
+fi
 cap="$(sed -nE 's/^      RATE_LIMIT_WAIT_SECONDS: ([0-9]+)$/\1/p' <<<"$job")"
 timeout="$(sed -nE 's/^    timeout-minutes: ([0-9]+)$/\1/p' <<<"$job")"
-if [[ -n "$cap" && -n "$timeout" && $((cap / 60 + 9)) -le "$timeout" ]]; then
-  ok "the job timeout ($timeout min) holds one ${cap}s reset wait plus the 9 min the other waits need"
+if [[ -n "$cap" && -n "$timeout" && $((2 * cap / 60 + 5)) -le "$timeout" ]]; then
+  ok "the job timeout ($timeout min) holds two ${cap}s wait windows plus the 5 min the other waits need"
 else
-  fail "the job timeout '$timeout' does not hold a '${cap}'s reset wait plus 9 minutes"
+  fail "the job timeout '$timeout' does not hold two '${cap}'s wait windows plus 5 minutes"
 fi
 if [[ "$(grep -c 'rate-limit-wait-seconds: \${{ env.RATE_LIMIT_WAIT_SECONDS }}' <<<"$job")" -eq 2 ]]; then
   ok "check-contract and aggregate-results wait under the same ceiling"
 else
   fail "check-contract and aggregate-results do not both take rate-limit-wait-seconds from RATE_LIMIT_WAIT_SECONDS"
 fi
+poll="$(sed -nE "s/^          POLL_LIMIT_SECONDS: '([0-9]+)'$/\1/p" "$DISPATCH")"
+if [[ -n "$poll" && -n "$timeout" && "$poll" -gt $((timeout * 60)) ]]; then
+  ok "pr-feedback-dispatch polls an in-progress ci-status longer than its ${timeout} min timeout"
+else
+  fail "pr-feedback-dispatch's POLL_LIMIT_SECONDS '$poll' does not outlast ci-status's ${timeout} min timeout"
+fi
 
 # The stub logs its arguments. GET /rate_limit prints STUB_LIMIT_<resource>
 # ("<remaining> <reset>") or fails when that is unset. Any other call takes the
@@ -92,18 +116,17 @@ chmod +x "$TMP_ROOT/bin/gh" "$TMP_ROOT/bin/sleep" "$TMP_ROOT/bin/date"
 LIMITED='fail gh: API rate limit exceeded for installation. (HTTP 403)'
 NOW=1792800000
 
-# run <calls...>: runs `. gh-read.sh` and then each argument as a command in
-# one bash -e step, with the job state kept from earlier runs unless reset.
+# run <commands>: sources gh-read.sh, then runs <commands>, in one bash -e
+# step. The blocks and deadline stay from earlier runs until fresh.
 run() {
   : >"$TMP_ROOT/log"
   : >"$TMP_ROOT/sleeps"
   out="$(PATH="$TMP_ROOT/bin:$PATH" RUNNER_TEMP="$TMP_ROOT" STUB_LOG="$TMP_ROOT/log" STUB_SLEEPS="$TMP_ROOT/sleeps" \
-    STUB_NOW="${STUB_NOW:-$NOW}" RATE_LIMIT_WAIT_SECONDS="${CAP:-600}" \
-    bash -ec ". \"\$RUNNER_TEMP/gh-read.sh\"; $1" 2>&1)" && rc=0 || rc=$?
+    STUB_NOW="${STUB_NOW:-$NOW}" bash -ec ". \"\$RUNNER_TEMP/gh-read.sh\"; $1" 2>&1)" && rc=0 || rc=$?
   calls=$(grep -vc '^api rate_limit ' "$TMP_ROOT/log")
   sleeps=$(paste -sd' ' "$TMP_ROOT/sleeps")
 }
-fresh() { rm -f "$TMP_ROOT/gh-read.state"; }
+fresh() { ci_gh_read::reset "$TMP_ROOT" $((NOW + 600)); }
 # check <label> <want-rc> <want-calls> <want-sleeps> [want-out] [refuse-out]
 check() {
   if [[ "$rc" -ne "$2" ]]; then
@@ -155,26 +178,40 @@ STUB_SCRIPT="$LIMITED
 ok fine" run 'gh_read repos/o/r/pulls/1 >/dev/null'
 check "a rate limit whose reset is unreadable waits 60 s" 0 2 "60"
 
+fresh
+STUB_LIMIT_core="4999 $((NOW + 3000))" STUB_SCRIPT="$LIMITED
+ok fine" run 'gh_read repos/o/r/pulls/1 >/dev/null'
+check "a primary limit whose window has already reset reads again after a second" 0 2 "1"
+
 fresh
 STUB_LIMIT_core="0 $((NOW + 30))" STUB_SCRIPT='fail gh: Forbidden (HTTP 403)
 ok fine' run 'gh_read repos/o/r/pulls/1 >/dev/null'
 check "a 403 while the core limit is at 0 is a rate limit" 0 2 "35"
 
+fresh
+STUB_LIMIT_core="0 $((NOW + 30))" STUB_SCRIPT="$LIMITED
+$LIMITED
+ok never" run 'gh_read repos/o/r/pulls/1 || echo "rc=$?"'
+check "a second rate limit after the wait fails the read without another wait" 0 2 "35" "rc=1"
+
 fresh
 STUB_LIMIT_core="0 $((NOW + 3000))" STUB_SCRIPT="$LIMITED" run 'gh_read repos/o/r/pulls/1 || echo "rc=$?"'
-check "a reset past the ceiling fails the read at once" 0 1 "" \
-  "::error::GitHub's core API rate limit blocks 'gh api repos/o/r/pulls/1' until 2026-10-24T00:50:00Z, past the 600s ci-status waits for a reset (0s spent); re-run this run after 2026-10-24T00:50:00Z."
+check "a reset past the deadline fails the read at once" 0 1 "" \
+  "::error::GitHub's core API rate limit blocks 'gh api repos/o/r/pulls/1' until 2026-10-24T00:50:00Z, after ci-status stops waiting at 2026-10-24T00:10:00Z; re-run this run after 2026-10-24T00:50:00Z."
 STUB_SCRIPT='ok never' run 'gh_read repos/o/r/pulls/2 || echo "rc=$?"'
-check "a later read, in a later step, before that reset fails without a call" 0 0 "" "rc=1" "::error::"
+check "a later read of that resource, in a later step, before its reset fails without a call" 0 0 "" "rc=1" "::error::"
+STUB_SCRIPT='ok graphql' run 'gh_read graphql -f query=x'
+check "a block on core does not stop a graphql read" 0 1 "" "graphql"
 STUB_NOW=$((NOW + 3000)) STUB_SCRIPT='ok again' run 'gh_read repos/o/r/pulls/2'
 check "a read after that reset is sent" 0 1 "" "again"
 
 fresh
 STUB_LIMIT_core="0 $((NOW + 400))" STUB_SCRIPT="$LIMITED
 ok one" run 'gh_read repos/o/r/pulls/1 >/dev/null'
-check "a first 405 s wait fits the 600 s ceiling" 0 2 "405"
-STUB_LIMIT_core="0 $((NOW + 300))" STUB_SCRIPT="$LIMITED" run 'gh_read repos/o/r/pulls/2 || echo "rc=$?"'
-check "a later step's wait counts what earlier steps spent" 0 1 "" "(405s spent)"
+check "a 405 s wait inside the deadline is taken" 0 2 "405"
+STUB_NOW=$((NOW + 560)) STUB_LIMIT_core="4999 $((NOW + 3600))" STUB_SCRIPT='fail gh: You have exceeded a secondary rate limit. (HTTP 403)' \
+  run 'gh_read repos/o/r/pulls/2 || echo "rc=$?"'
+check "a later step's wait that would end past the deadline is not taken" 0 1 "" "after ci-status stops waiting at 2026-10-24T00:10:00Z"
 
 fresh
 STUB_SCRIPT='fail gh: Not Found (HTTP 404)' run 'gh_read repos/o/r/contents/x 2>"$RUNNER_TEMP/err" || echo "rc=$?"; grep -c "HTTP 404" "$RUNNER_TEMP/err"'
diff --git a/scripts/ci-hold-cost-decision.test.sh b/scripts/ci-hold-cost-decision.test.sh
index 8512968745..57f3effc32 100755
--- a/scripts/ci-hold-cost-decision.test.sh
+++ b/scripts/ci-hold-cost-decision.test.sh
@@ -24,11 +24,6 @@ WORKFLOW="$ROOT/.github/workflows/pr-require-checks.yml"
 TMP_ROOT="$(mktemp -d)"
 trap 'rm -rf "$TMP_ROOT"' EXIT
 
-# shellcheck source=lib/ci-gh-read.sh
-. "$ROOT/scripts/lib/ci-gh-read.sh"
-export RUNNER_TEMP="$TMP_ROOT"
-ci_gh_read::install "$WORKFLOW" "$TMP_ROOT" || fail "the ci-status gh_read helper step is missing or fails"
-
 NAME='Clear a cost-only review hold the owner decided'
 step="$(awk -v name="      - name: $NAME" '$0 == name { on = 1; print; next }
   on && /^      - / { exit }
diff --git a/scripts/ci-hold-human-gated.test.sh b/scripts/ci-hold-human-gated.test.sh
index aa30aeb008..5bd9f022b7 100755
--- a/scripts/ci-hold-human-gated.test.sh
+++ b/scripts/ci-hold-human-gated.test.sh
@@ -135,7 +135,7 @@ expect() {
   local label="$1" want_rc="$2" want_calls="$3" out rc calls
   : >"$TMP_ROOT/log"
   : >"$TMP_ROOT/sleeps"
-  rm -f "$TMP_ROOT/gh-read.state"
+  ci_gh_read::reset "$TMP_ROOT" 1792800600
   : >"$TMP_ROOT/output"
   out="$(PATH="$TMP_ROOT/bin:$PATH" STUB_LOG="$TMP_ROOT/log" STUB_SLEEPS="$TMP_ROOT/sleeps" STUB_NOW=1792800000 STUB_LABELS="$4" STUB_FAILS="$5" PR_NUMBER=6419 \
     GITHUB_REPOSITORY=o/r RUNNER_TEMP="$TMP_ROOT" GITHUB_OUTPUT="$TMP_ROOT/output" BASE_SHA="${BASE_SHA-$BASE}" \
@@ -195,7 +195,7 @@ unset STUB_COMMENTS STUB_COMMENTS_FAIL
 expect "a transient label read failure is retried" 1 2 "needs-human" 1
 
 # A rate-limited read waits until five seconds past the reset and reads again;
-# a reset past the 600 s ceiling fails closed naming it; any other error keeps
+# a reset past the deadline fails closed naming it; any other error keeps
 # the caller's retries and is never waited on.
 sleeps() { paste -sd' ' "$TMP_ROOT/sleeps"; }
 export STUB_FAIL_TEXT='gh: API rate limit exceeded for installation. (HTTP 403)' STUB_RATE_LIMIT='0 1792800120'
@@ -207,12 +207,12 @@ else
   fail "the rate-limited read slept '$(sleeps)', not 125"
 fi
 export STUB_RATE_LIMIT='0 1792803000'
-expect "a reset past the ceiling fails closed naming the reset" 1 1 "enhancement" 3 \
-  "::error::GitHub's core API rate limit blocks 'gh api repos/o/r/issues/6419/labels?per_page=100 --paginate --jq .[].name' until 2026-10-24T00:50:00Z, past the 600s ci-status waits for a reset (0s spent); re-run this run after 2026-10-24T00:50:00Z."
+expect "a reset past the deadline fails closed naming the reset" 1 1 "enhancement" 3 \
+  "::error::GitHub's core API rate limit blocks 'gh api repos/o/r/issues/6419/labels?per_page=100 --paginate --jq .[].name' until 2026-10-24T00:50:00Z, after ci-status stops waiting at 2026-10-24T00:10:00Z; re-run this run after 2026-10-24T00:50:00Z."
 if [[ "$(sleeps)" == "5 10" ]]; then
-  ok "a reset past the ceiling is not waited for, and the retries make no call"
+  ok "a reset past the deadline is not waited for, and the retries make no call"
 else
-  fail "a reset past the ceiling slept '$(sleeps)', not the caller's '5 10'"
+  fail "a reset past the deadline slept '$(sleeps)', not the caller's '5 10'"
 fi
 export STUB_FAIL_TEXT='gh: Resource not accessible by integration (HTTP 403)' STUB_RATE_LIMIT='4999 1792800120'
 expect "a 403 that is not a rate limit fails closed without a wait" 1 3 "" 3 "::error::could not read the labels of #6419" "rate limited"
diff --git a/scripts/ci-rerun-ci-status.test.sh b/scripts/ci-rerun-ci-status.test.sh
index 9d1bfbd649..7eaf536346 100755
--- a/scripts/ci-rerun-ci-status.test.sh
+++ b/scripts/ci-rerun-ci-status.test.sh
@@ -36,7 +36,7 @@ if [[ ! -s "$TMP_ROOT/body.sh" ]]; then
   exit 1
 fi
 # shellcheck disable=SC2016 # the ${{ }} text is workflow source, not shell
-for env in 'HEAD_SHA: ${{ github.event.workflow_run.head_sha }}' 'PR_NUMBER: ${{ github.event.workflow_run.pull_requests[0].number }}' "POLL_LIMIT_SECONDS: '600'"; do
+for env in 'HEAD_SHA: ${{ github.event.workflow_run.head_sha }}' 'PR_NUMBER: ${{ github.event.workflow_run.pull_requests[0].number }}' "POLL_LIMIT_SECONDS: '1560'"; do
   if [[ "$step" == *"$env"* ]]; then ok "step env carries $env"; else fail "step env lacks $env"; fi
 done
 job="$(awk '/^  rerun-ci-status:$/ { on = 1; next } on && /^  [a-z]/ { exit } on { print }' "$WORKFLOW")"
diff --git a/scripts/lib/ci-gh-read.sh b/scripts/lib/ci-gh-read.sh
index 15c4a1d249..bbeef72003 100644
--- a/scripts/lib/ci-gh-read.sh
+++ b/scripts/lib/ci-gh-read.sh
@@ -7,6 +7,11 @@
 # Runs the `Write the rate-limit-aware read helper` step body of <workflow>
 # with RUNNER_TEMP=<dir>, which leaves <dir>/gh-read.sh for the step bodies
 # under test to source. Returns non-zero when the step is missing or fails.
+#
+#   ci_gh_read::reset <dir> <deadline>
+#
+# Clears the per-resource blocks an earlier case left in <dir> and sets the
+# wait deadline to the epoch second <deadline>, so a case runs on a stub clock.
 ci_gh_read::install() {
   local workflow="$1" dir="$2"
   awk '$0 == "      - name: Write the rate-limit-aware read helper" { on = 1; next }
@@ -18,3 +23,8 @@ ci_gh_read::install() {
   [[ -s "$dir/gh-read-step.sh" ]] || return 1
   RUNNER_TEMP="$dir" bash -e "$dir/gh-read-step.sh" && [[ -s "$dir/gh-read.sh" ]]
 }
+
+ci_gh_read::reset() {
+  rm -f "$1"/gh-read.until-*
+  echo "$2" >"$1/gh-read.deadline"
+}

From fe3d4e1fc24da5200f2efee2dc2d0039828a7e72 Mon Sep 17 00:00:00 2001
From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com>
Date: Fri, 23 Oct 2026 11:23:10 -0400
Subject: [PATCH 3/6] chore(pr-pipeline): add the changelog fragment for the
 ci-status wait

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../perf-ci-status-wait-rate-limit-reset-490ba60b.md         | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changes/pr-pipeline/perf-ci-status-wait-rate-limit-reset-490ba60b.md

diff --git a/.changes/pr-pipeline/perf-ci-status-wait-rate-limit-reset-490ba60b.md b/.changes/pr-pipeline/perf-ci-status-wait-rate-limit-reset-490ba60b.md
new file mode 100644
index 0000000000..98590ccb16
--- /dev/null
+++ b/.changes/pr-pipeline/perf-ci-status-wait-rate-limit-reset-490ba60b.md
@@ -0,0 +1,5 @@
+---
+bump: none
+---
+
+No release needed (ci): ci-status waits for a GitHub API rate-limit reset instead of failing closed at once

From a6f910874a41283555d557dc2dbb748d0d84f428 Mon Sep 17 00:00:00 2001
From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com>
Date: Fri, 23 Oct 2026 11:26:50 -0400
Subject: [PATCH 4/6] chore(pr-pipeline): rename the fragment off a typos false
 positive

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 ...0ba60b.md => perf-ci-status-wait-rate-limit-reset-7c3e41d2.md} | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename .changes/pr-pipeline/{perf-ci-status-wait-rate-limit-reset-490ba60b.md => perf-ci-status-wait-rate-limit-reset-7c3e41d2.md} (100%)

diff --git a/.changes/pr-pipeline/perf-ci-status-wait-rate-limit-reset-490ba60b.md b/.changes/pr-pipeline/perf-ci-status-wait-rate-limit-reset-7c3e41d2.md
similarity index 100%
rename from .changes/pr-pipeline/perf-ci-status-wait-rate-limit-reset-490ba60b.md
rename to .changes/pr-pipeline/perf-ci-status-wait-rate-limit-reset-7c3e41d2.md

From b52a8b5cbecd40b234679dc88cf671e2c71d0ae2 Mon Sep 17 00:00:00 2001
From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com>
Date: Fri, 23 Oct 2026 11:37:30 -0400
Subject: [PATCH 5/6] fix(pr-pipeline): read the rate-limit reset from a
 probe's headers

The first live run of this branch hit the GITHUB_TOKEN installation
limit: every read failed "API rate limit exceeded for installation" with
x-ratelimit-remaining 0 and a reset five minutes out, while GET
/rate_limit reported core remaining above 0, so gh_read waited one
second and the review-lane step failed closed.

gh_read now reads the wait from the x-ratelimit-* and retry-after
headers of one `gh api -i` probe to the same resource, the headers the
composites' gh-api.sh already uses.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/pr-require-checks.yml | 34 +++++++++++-----
 scripts/ci-gh-read.test.sh              | 53 +++++++++++++++++--------
 scripts/ci-hold-human-gated.test.sh     |  6 ++-
 3 files changed, 63 insertions(+), 30 deletions(-)

diff --git a/.github/workflows/pr-require-checks.yml b/.github/workflows/pr-require-checks.yml
index ed3d3cf4ab..0f13160aa1 100644
--- a/.github/workflows/pr-require-checks.yml
+++ b/.github/workflows/pr-require-checks.yml
@@ -3142,13 +3142,17 @@ jobs:
     steps:
       # A RATE-LIMITED READ WAITS FOR THE RESET. The fail-closed steps below
       # read through gh_read, which runs `gh api` and, when that fails on a
-      # rate limit, waits once and reads again. The wait runs until five
-      # seconds past the reset when GET /rate_limit (which no limit counts)
-      # shows the resource (core, or graphql for a graphql call) at 0; 60 s for
-      # a secondary limit or when the reset cannot be read; one second when the
-      # window has already reset. It is a rate limit when gh's error names one,
-      # or is an HTTP 403 or 429 while that resource is at 0. A wait that would
-      # end past the deadline this step sets, RATE_LIMIT_WAIT_SECONDS after it
+      # rate limit, waits once and reads again. Without -i, gh drops the failed
+      # response's headers, and GET /rate_limit does not report the
+      # GITHUB_TOKEN's installation limit (it read core 'remaining > 0' while
+      # every read failed on it), so the wait comes from the x-ratelimit-* and
+      # retry-after headers of one probe request to the same resource (core,
+      # or graphql for a graphql call): retry-after seconds when sent, else
+      # five seconds past x-ratelimit-reset while remaining is 0, one second
+      # when the probe shows the limit has cleared, else 60 s. It is a rate
+      # limit when gh's error names one, or is an HTTP 403 or 429 while the
+      # probe reads remaining 0 or retry-after. A wait that would end past the
+      # deadline this step sets, RATE_LIMIT_WAIT_SECONDS after it
       # runs, fails the read with an error naming the reset, and later reads
       # of that resource before the reset fail without a call. Any other
       # failure, or a second rate limit after the wait, returns gh's status at
@@ -3161,7 +3165,7 @@ jobs:
       - name: Write the rate-limit-aware read helper
         run: |
           gh_read() {
-            local resource=core until=0 deadline arg err out now limit remaining reset wait at waited=
+            local resource=core until=0 deadline arg err out now limit remaining reset after wait at waited=
             for arg; do [ "$arg" != graphql ] || resource=graphql; done
             local blocked="$RUNNER_TEMP/gh-read.until-$resource"
             deadline=$(cat "$RUNNER_TEMP/gh-read.deadline")
@@ -3179,9 +3183,17 @@ jobs:
               wait=
               if [ -z "$waited" ] && grep -qiE 'rate limit|HTTP (403|429)' "$err"; then
                 now=$(date +%s)
-                limit=$(gh api rate_limit --jq ".resources.$resource | \"\(.remaining) \(.reset)\"" 2>/dev/null) || limit=
-                read -r remaining reset <<<"$limit"
-                if [ "$remaining" = 0 ] && [[ $reset =~ ^[0-9]{1,10}$ ]]; then
+                if [ "$resource" = graphql ]; then
+                  limit=$(gh api -i graphql -f query='{rateLimit{remaining}}' 2>/dev/null) || true
+                else
+                  limit=$(gh api -i "repos/$GITHUB_REPOSITORY" 2>/dev/null) || true
+                fi
+                limit=$(tr -d '\r' <<<"$limit" | sed '/^$/q' | awk -F': *' '{ h[tolower($1)] = $2 }
+                  END { print h["x-ratelimit-remaining"] " " h["x-ratelimit-reset"] " " h["retry-after"] }')
+                read -r remaining reset after <<<"$limit"
+                if [[ $after =~ ^[0-9]{1,5}$ ]]; then
+                  wait=$((10#$after)) reset=$((now + 10#$after))
+                elif [ "$remaining" = 0 ] && [[ $reset =~ ^[0-9]{1,10}$ ]]; then
                   wait=$((reset - now + 5))
                   [ "$wait" -ge 5 ] || wait=5
                 elif grep -qi 'secondary rate limit' "$err" || { grep -qi 'rate limit' "$err" && [[ ! $remaining =~ ^[0-9]+$ ]]; }; then
diff --git a/scripts/ci-gh-read.test.sh b/scripts/ci-gh-read.test.sh
index 3a490c12e6..3a6fd08134 100755
--- a/scripts/ci-gh-read.test.sh
+++ b/scripts/ci-gh-read.test.sh
@@ -3,10 +3,11 @@
 # .github/workflows/pr-require-checks.yml's ci-status, then calls the gh_read
 # function it writes, under bash -e, against stub `gh`, `sleep` and `date`.
 #
-# gh_read runs `gh api`. On a rate limit it waits once and reads again: until
-# five seconds past the reset GET /rate_limit reports for the resource, 60 s
-# for a secondary limit or an unreadable reset, one second when the window has
-# already reset. A wait that would end past the deadline the step sets,
+# gh_read runs `gh api`. On a rate limit it waits once and reads again, taking
+# the wait from the headers of one `gh api -i` probe to the same resource:
+# retry-after seconds, else five seconds past x-ratelimit-reset while
+# remaining is 0, one second when the probe shows the limit cleared, else
+# 60 s. A wait that would end past the deadline the step sets,
 # RATE_LIMIT_WAIT_SECONDS after it runs, fails the read naming the reset and
 # blocks that resource until it. Any other failure returns at once.
 # test-scope: .github/workflows/pr-require-checks.yml
@@ -82,20 +83,27 @@ else
   fail "pr-feedback-dispatch's POLL_LIMIT_SECONDS '$poll' does not outlast ci-status's ${timeout} min timeout"
 fi
 
-# The stub logs its arguments. GET /rate_limit prints STUB_LIMIT_<resource>
-# ("<remaining> <reset>") or fails when that is unset. Any other call takes the
-# next line of STUB_SCRIPT: `ok <stdout>`, or `fail <stderr>`.
+# The stub logs its arguments. A `gh api -i` probe (graphql, or any other path
+# for core) prints a response whose x-ratelimit-remaining, x-ratelimit-reset
+# and optional retry-after come from STUB_LIMIT_<resource> ("<remaining>
+# <reset> [<retry-after>]"), and fails with no output when that is unset. Any
+# other call takes the next line of STUB_SCRIPT: `ok <stdout>`, or
+# `fail <stderr>`.
 mkdir -p "$TMP_ROOT/bin"
 cat >"$TMP_ROOT/bin/gh" <<'EOF'
 #!/usr/bin/env bash
 printf '%s\n' "$*" >>"$STUB_LOG"
-if [[ "$2" == rate_limit ]]; then
-  [[ "$4" == .resources.core* ]] && v=${STUB_LIMIT_core:-} || v=${STUB_LIMIT_graphql:-}
+if [[ "$2" == -i ]]; then
+  [[ "$3" == graphql ]] && v=${STUB_LIMIT_graphql:-} || v=${STUB_LIMIT_core:-}
   [[ -n "$v" ]] || exit 1
-  printf '%s\n' "$v"
+  read -r remaining reset after <<<"$v"
+  printf 'HTTP/2.0 403 Forbidden\r\nX-Ratelimit-Remaining: %s\r\nX-Ratelimit-Reset: %s\r\n' "$remaining" "$reset"
+  [[ -z "$after" ]] || printf 'Retry-After: %s\r\n' "$after"
+  printf '\r\n{"message":"x"}\n'
+  [[ "$remaining" != 0 && -z "$after" ]] || exit 1
   exit 0
 fi
-n=$(grep -vc '^api rate_limit ' "$STUB_LOG")
+n=$(grep -vc '^api -i ' "$STUB_LOG")
 line=$(sed -n "${n}p" <<<"$STUB_SCRIPT")
 case $line in
 ok\ *) printf '%s\n' "${line#ok }" ;;
@@ -121,9 +129,9 @@ NOW=1792800000
 run() {
   : >"$TMP_ROOT/log"
   : >"$TMP_ROOT/sleeps"
-  out="$(PATH="$TMP_ROOT/bin:$PATH" RUNNER_TEMP="$TMP_ROOT" STUB_LOG="$TMP_ROOT/log" STUB_SLEEPS="$TMP_ROOT/sleeps" \
+  out="$(PATH="$TMP_ROOT/bin:$PATH" RUNNER_TEMP="$TMP_ROOT" GITHUB_REPOSITORY=o/r STUB_LOG="$TMP_ROOT/log" STUB_SLEEPS="$TMP_ROOT/sleeps" \
     STUB_NOW="${STUB_NOW:-$NOW}" bash -ec ". \"\$RUNNER_TEMP/gh-read.sh\"; $1" 2>&1)" && rc=0 || rc=$?
-  calls=$(grep -vc '^api rate_limit ' "$TMP_ROOT/log")
+  calls=$(grep -vc '^api -i ' "$TMP_ROOT/log")
   sleeps=$(paste -sd' ' "$TMP_ROOT/sleeps")
 }
 fresh() { ci_gh_read::reset "$TMP_ROOT" $((NOW + 600)); }
@@ -148,7 +156,7 @@ fresh
 STUB_SCRIPT='ok hello' run 'x=$(gh_read repos/o/r/pulls/1); echo "got $x"'
 check "a read that succeeds prints its output once" 0 1 "" "got hello"
 if [[ "$(cat "$TMP_ROOT/log")" == "api repos/o/r/pulls/1" ]]; then
-  ok "gh_read passes its arguments to gh api unchanged and reads no rate limit"
+  ok "gh_read passes its arguments to gh api unchanged and sends no probe"
 else
   fail "gh_read called '$(cat "$TMP_ROOT/log")'"
 fi
@@ -163,6 +171,17 @@ else
   fail "the wait notice is missing: '$out'"
 fi
 
+if grep -qxF 'api -i repos/o/r' "$TMP_ROOT/log"; then
+  ok "a core read probes the repository with -i for the limit's headers"
+else
+  fail "a core read probed '$(grep '^api -i' "$TMP_ROOT/log")'"
+fi
+
+fresh
+STUB_LIMIT_core="0 $((NOW + 30)) 7" STUB_SCRIPT="$LIMITED
+ok after" run 'gh_read repos/o/r/pulls/1 >/dev/null'
+check "a retry-after header sets the wait" 0 2 "7"
+
 fresh
 STUB_LIMIT_graphql="0 $((NOW + 50))" STUB_LIMIT_core="4999 $((NOW + 9))" STUB_SCRIPT='fail gh: GraphQL: API rate limit already exceeded for installation ID 1.
 ok {}' run 'gh_read graphql -f query=x >/dev/null'
@@ -216,10 +235,10 @@ check "a later step's wait that would end past the deadline is not taken" 0 1 ""
 fresh
 STUB_SCRIPT='fail gh: Not Found (HTTP 404)' run 'gh_read repos/o/r/contents/x 2>"$RUNNER_TEMP/err" || echo "rc=$?"; grep -c "HTTP 404" "$RUNNER_TEMP/err"'
 check "any other error returns at once, its text on the caller's stderr" 0 1 "" $'rc=1\n1'
-if grep -q '^api rate_limit ' "$TMP_ROOT/log"; then
-  fail "a 404 read the rate limit"
+if grep -q '^api -i ' "$TMP_ROOT/log"; then
+  fail "a 404 sent a rate-limit probe"
 else
-  ok "a 404 reads no rate limit"
+  ok "a 404 sends no rate-limit probe"
 fi
 fresh
 STUB_LIMIT_core="4999 $((NOW + 30))" STUB_SCRIPT='fail gh: Resource not accessible by integration (HTTP 403)' run 'gh_read repos/o/r/pulls/1 || echo "rc=$?"'
diff --git a/scripts/ci-hold-human-gated.test.sh b/scripts/ci-hold-human-gated.test.sh
index 5bd9f022b7..08e50067a2 100755
--- a/scripts/ci-hold-human-gated.test.sh
+++ b/scripts/ci-hold-human-gated.test.sh
@@ -100,9 +100,11 @@ case "$*" in
   while [[ $# -gt 0 && "$1" != --jq ]]; do shift; done
   jq -r "$2" <<<"${STUB_COMMENTS:-[]}"
   ;;
-'api rate_limit '*)
+'api -i '*)
   [[ -n "${STUB_RATE_LIMIT:-}" ]] || exit 1
-  printf '%s\n' "$STUB_RATE_LIMIT"
+  read -r remaining reset <<<"$STUB_RATE_LIMIT"
+  printf 'HTTP/2.0 403 Forbidden\r\nX-Ratelimit-Remaining: %s\r\nX-Ratelimit-Reset: %s\r\n\r\n{}\n' "$remaining" "$reset"
+  [[ "$remaining" != 0 ]] || exit 1
   ;;
 *) exit 1 ;;
 esac

From 89f0c702e71c50bb3396234fd4bf2871a62095b4 Mon Sep 17 00:00:00 2001
From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com>
Date: Fri, 23 Oct 2026 12:49:36 -0400
Subject: [PATCH 6/6] fix(pr-pipeline): keep ci-status's timeout and wait only
 inside it

The owner chose the most time-efficient wait that adds no re-run loop
and no timeout raise. ci-status's timeout-minutes, and rerun-ci-status's
poll and job timeout, go back to main's values, and check-contract and
aggregate-results keep their 60 s rate-limit-wait-seconds default.

gh_read still waits for the reset, but only when the wait ends by the
job's timeout less a 300 s margin for the setup and the steps after it,
counted from the helper step's start (GH_READ_JOB_SECONDS 660, pinned
to timeout-minutes by the test). A reset past that fails the read red at
once, naming the reset and saying a re-run after it is needed. The next
review lane's rerun-ci-status, or a person, re-runs it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/pr-feedback-dispatch.yml |  7 +--
 .github/workflows/pr-require-checks.yml    | 58 ++++++++++---------
 docs/conventions/pr-pipeline/README.md     |  3 +-
 scripts/ci-gh-read.test.sh                 | 67 +++++++++++-----------
 scripts/ci-hold-human-gated.test.sh        |  2 +-
 scripts/ci-rerun-ci-status.test.sh         |  2 +-
 scripts/lib/ci-gh-read.sh                  | 12 +++-
 7 files changed, 80 insertions(+), 71 deletions(-)

diff --git a/.github/workflows/pr-feedback-dispatch.yml b/.github/workflows/pr-feedback-dispatch.yml
index 3489f1be25..7b110db041 100644
--- a/.github/workflows/pr-feedback-dispatch.yml
+++ b/.github/workflows/pr-feedback-dispatch.yml
@@ -271,8 +271,7 @@ jobs:
   # never runs, so neither starts it. A head the PR has moved past, or a
   # closed PR, is left alone. A ci-status job not started yet reads the
   # reviews when it starts, so it is left alone too; one in progress is
-  # polled every 60 s for at most 29 minutes, longer than ci-status's
-  # 28-minute timeout, then re-run. No checkout, no
+  # polled every 60 s for at most 10 minutes, then re-run. No checkout, no
   # model: the token can only read runs and the PR and re-run a job.
   # Pinned by scripts/ci-rerun-ci-status.test.sh, which runs this body.
   rerun-ci-status:
@@ -285,7 +284,7 @@ jobs:
       && github.event.workflow_run.repository.full_name == github.repository
       && github.event.workflow_run.head_repository.full_name == github.repository
     runs-on: ubuntu-24.04
-    timeout-minutes: 35
+    timeout-minutes: 15
     permissions:
       actions: write # list pr-require-checks runs and jobs; re-run the ci-status job
       pull-requests: read # the PR's state and live head
@@ -296,7 +295,7 @@ jobs:
           HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
           PR_NUMBER: ${{ github.event.workflow_run.pull_requests[0].number }}
           POLL_SECONDS: '60'
-          POLL_LIMIT_SECONDS: '1740'
+          POLL_LIMIT_SECONDS: '600'
         run: |
           if [[ ! $HEAD_SHA =~ ^[0-9a-f]{40}$ ]]; then
             echo "::error::the review run's head '$HEAD_SHA' is not a commit SHA."
diff --git a/.github/workflows/pr-require-checks.yml b/.github/workflows/pr-require-checks.yml
index 3eb16998b8..d2a28b5061 100644
--- a/.github/workflows/pr-require-checks.yml
+++ b/.github/workflows/pr-require-checks.yml
@@ -3104,26 +3104,28 @@ jobs:
     # `ci-lanes` commit status the last full run recorded on this SHA.
     if: ${{ !cancelled() }}
     runs-on: ubuntu-24.04
-    # 9 s p95 and 42 s max in full mode, about 10 s contract-only. The cap
-    # holds two rate-limit windows of RATE_LIMIT_WAIT_SECONDS (10 minutes):
-    # one shared by check-contract and the gh_read steps, which wait only
-    # until RATE_LIMIT_WAIT_SECONDS past the job's start, and aggregate-results'
-    # own. Core and graphql reset on separate hourly windows, so each window
-    # can hold a reset wait. Then about eight minutes of other waits: 45 s of
-    # own-gate retries, 7 s of status-write retries and the 90 s
-    # `rerun-wait-seconds` wait, up to 15 s of retry sleeps for each of the
-    # hold-lift step's two reads, the review-lane step's four and the
-    # lanes-hold step's eight, the cost-hold step's reads (one for most pull
-    # requests, which stop at the label events; for a lane-labeled one whose
-    # body cites a decision, about eight, and two more per review run since
-    # the window opened), and the base-config checkout's fetch.
-    # pr-feedback-dispatch.yml polls an in-progress ci-status for longer than
-    # this cap.
-    timeout-minutes: 28
+    # 9 s p95 and 42 s max in full mode, about 10 s contract-only. The cap is
+    # the worst case of the pinned composites' waits: two 60 s rate-limit waits
+    # (`rate-limit-wait-seconds` on check-contract and aggregate-results), 45 s
+    # of own-gate retries, 7 s of status-write retries and the 90 s
+    # `rerun-wait-seconds` wait, about four and a half minutes, plus up to
+    # 15 s of retry sleeps for each of the hold-lift step's two reads, the
+    # review-lane step's four and the lanes-hold step's eight, about four
+    # minutes, plus the cost-hold step's reads: one for most pull requests,
+    # which stop at the label events; for a lane-labeled one whose body cites a
+    # decision, about eight, and two more per review run since the window
+    # opened, plus the base-config checkout's fetch (seconds; its retries
+    # replace the contents reads' 15 s each).
+    timeout-minutes: 11
     env:
-      # The rate-limit wait ceiling of each window above. The limit-events
-      # rows that set it needed 399 to 523 s.
-      RATE_LIMIT_WAIT_SECONDS: 600
+      # gh_read's wait budget: a rate-limit wait must end by
+      # GH_READ_JOB_SECONDS (timeout-minutes in seconds) less
+      # GH_READ_MARGIN_SECONDS after the first step starts. The margin keeps
+      # five minutes for the job's setup and the steps after the wait:
+      # aggregate-results' 60 s rate-limit wait, 45 s of own-gate retries, 7 s
+      # of status writes and the 90 s rerun wait, plus retry sleeps.
+      GH_READ_JOB_SECONDS: 660
+      GH_READ_MARGIN_SECONDS: 300
     permissions:
       # `yield-to-full-run` lists this workflow's runs on the head SHA, and
       # `rerun-contract-only-siblings` re-runs the red contract-only ones once
@@ -3152,10 +3154,14 @@ jobs:
       # five seconds past x-ratelimit-reset while remaining is 0, one second
       # when the probe shows the limit has cleared, else 60 s. It is a rate
       # limit when gh's error names one, or is an HTTP 403 or 429 while the
-      # probe reads remaining 0 or retry-after. A wait that would end past the
-      # deadline this step sets, RATE_LIMIT_WAIT_SECONDS after it
-      # runs, fails the read with an error naming the reset, and later reads
-      # of that resource before the reset fail without a call. Any other
+      # probe reads remaining 0 or retry-after. The job's timeout is not raised
+      # for it: a wait is taken only when it ends inside the budget the job
+      # env sets, so the steps after it still fit. A wait past that fails the
+      # read at once, red and never neutral (a neutral required check counts
+      # as passing), with an error naming the reset and asking for a re-run
+      # after it; later reads of that resource before the reset fail without
+      # a call. Nothing here re-runs the job: the next review lane's
+      # rerun-ci-status, or a person, re-runs it after the reset. Any other
       # failure, or a second rate limit after the wait, returns gh's status at
       # once, so each caller's own retries and fail-closed exit stay as they
       # were. The cost-hold step keeps plain `gh api`: an unreadable input
@@ -3209,7 +3215,7 @@ jobs:
               fi
               if [ $((now + wait)) -gt "$deadline" ]; then
                 at=$(jq -rn --argjson t "$reset" '$t | todate')
-                echo "::error::GitHub's $resource API rate limit blocks 'gh api $*' until $at, after ci-status stops waiting at $(jq -rn --argjson t "$deadline" '$t | todate'); re-run this run after $at." >&9
+                echo "::error::GitHub's $resource API rate limit blocks 'gh api $*' until $at, past the $(jq -rn --argjson t "$deadline" '$t | todate') ci-status can wait to inside its timeout; a re-run after $at is needed." >&9
                 echo "$reset" >"$blocked"
                 rm -f "$err"
                 return 1
@@ -3219,7 +3225,7 @@ jobs:
               waited=1
             done
           }
-          echo $(($(date +%s) + RATE_LIMIT_WAIT_SECONDS)) >"$RUNNER_TEMP/gh-read.deadline"
+          echo $(($(date +%s) + GH_READ_JOB_SECONDS - GH_READ_MARGIN_SECONDS)) >"$RUNNER_TEMP/gh-read.deadline"
           # fd 9 is each sourcing step's stderr, so the notices reach the log
           # when a caller captures or redirects gh_read's own stderr.
           { echo 'exec 9>&2'; declare -f gh_read; } >"$RUNNER_TEMP/gh-read.sh"
@@ -3227,7 +3233,6 @@ jobs:
         uses: melodic-software/ci-workflows/.github/actions/pr-require-checks/check-contract@5e18f3d6cebd6fa5e66b0941ee0f7ed6ba288d6c # v0.58.0
         with:
           token: ${{ github.token }}
-          rate-limit-wait-seconds: ${{ env.RATE_LIMIT_WAIT_SECONDS }}
           # Carried over verbatim from `pr-issue-linkage.yml`, the caller this
           # step replaces: dependabot PR bodies cannot carry the closing keyword
           # and the four contract sections, so its login is exempt from the
@@ -4120,4 +4125,3 @@ jobs:
           # how many steps of the job are in progress.
           step-name: Aggregate lane results
           token: ${{ github.token }}
-          rate-limit-wait-seconds: ${{ env.RATE_LIMIT_WAIT_SECONDS }}
diff --git a/docs/conventions/pr-pipeline/README.md b/docs/conventions/pr-pipeline/README.md
index 9b55df3ff2..9c8923fc10 100644
--- a/docs/conventions/pr-pipeline/README.md
+++ b/docs/conventions/pr-pipeline/README.md
@@ -1499,8 +1499,7 @@ A review usually finishes after ci-status has read it, so `pr-feedback-dispatch.
 `rerun-ci-status` job re-runs the ci-status job of the newest `pr-require-checks` run on the head
 whenever either review caller completes (not when GitHub skipped it) on an open same-repository PR
 still at that head. A ci-status not started yet is left to read the reviews itself; one in progress
-is polled every 60 seconds first, for at most 29 minutes, past ci-status's 28-minute timeout. The
-merge-group run re-checks the labels.
+is polled every 60 seconds for at most 10 minutes first. The merge-group run re-checks the labels.
 `fix-ci` keys on `ci-lanes`, so a hold or a pending review never summons it.
 
 ## Trust-root paths
diff --git a/scripts/ci-gh-read.test.sh b/scripts/ci-gh-read.test.sh
index ae9b367bd7..de66cb3d3b 100755
--- a/scripts/ci-gh-read.test.sh
+++ b/scripts/ci-gh-read.test.sh
@@ -7,17 +7,16 @@
 # the wait from the headers of one `gh api -i` probe to the same resource:
 # retry-after seconds, else five seconds past x-ratelimit-reset while
 # remaining is 0, one second when the probe shows the limit cleared, else
-# 60 s. A wait that would end past the deadline the step sets,
-# RATE_LIMIT_WAIT_SECONDS after it runs, fails the read naming the reset and
-# blocks that resource until it. Any other failure returns at once.
+# 60 s. A wait that would end past the deadline the step sets (the job's
+# timeout less a margin, from when the step runs) fails the read at once
+# naming the reset and blocks that resource until it. Any other failure
+# returns at once.
 # test-scope: .github/workflows/pr-require-checks.yml
-# test-scope: .github/workflows/pr-feedback-dispatch.yml
-# shellcheck disable=SC2016 # the step snippets and the env expression are literal
+# shellcheck disable=SC2016 # the step snippets are literal
 set -uo pipefail
 
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 WORKFLOW="$ROOT/.github/workflows/pr-require-checks.yml"
-DISPATCH="$ROOT/.github/workflows/pr-feedback-dispatch.yml"
 
 # shellcheck source=lib/test-harness.sh
 . "$ROOT/scripts/lib/test-harness.sh"
@@ -27,18 +26,38 @@ DISPATCH="$ROOT/.github/workflows/pr-feedback-dispatch.yml"
 TMP_ROOT="$(mktemp -d)"
 trap 'rm -rf "$TMP_ROOT"' EXIT
 
-if ! RATE_LIMIT_WAIT_SECONDS=600 ci_gh_read::install "$WORKFLOW" "$TMP_ROOT"; then
-  fail "no working 'Write the rate-limit-aware read helper' step in $WORKFLOW"
+if ! ci_gh_read::install "$WORKFLOW" "$TMP_ROOT"; then
+  fail "no working 'Write the rate-limit-aware read helper' step, or no GH_READ_* env, in $WORKFLOW"
   test_harness::report
   exit 1
 fi
-if [[ "$(cat "$TMP_ROOT/gh-read.deadline")" -ge $(($(date +%s) + 590)) ]]; then
-  ok "the step sets the wait deadline RATE_LIMIT_WAIT_SECONDS after it runs"
-else
-  fail "the step set the deadline '$(cat "$TMP_ROOT/gh-read.deadline")'"
-fi
 
 job="$(awk '/^  ci-status:$/ { on = 1 } on && /^  [a-z-]+:$/ && !/ci-status/ { exit } on { print }' "$WORKFLOW")"
+timeout="$(sed -nE 's/^    timeout-minutes: ([0-9]+)$/\1/p' <<<"$job")"
+job_seconds="$(sed -nE 's/^      GH_READ_JOB_SECONDS: ([0-9]+)$/\1/p' <<<"$job")"
+margin="$(sed -nE 's/^      GH_READ_MARGIN_SECONDS: ([0-9]+)$/\1/p' <<<"$job")"
+if [[ -n "$timeout" && "$job_seconds" == $((timeout * 60)) ]]; then
+  ok "GH_READ_JOB_SECONDS ($job_seconds) is ci-status's timeout-minutes ($timeout) in seconds"
+else
+  fail "GH_READ_JOB_SECONDS '$job_seconds' is not ci-status's timeout-minutes '$timeout' in seconds"
+fi
+if [[ -n "$margin" && "$margin" -ge 240 && "$margin" -lt "${job_seconds:-0}" ]]; then
+  ok "the ${margin}s margin leaves room for aggregate-results' 202 s of waits and the setup"
+else
+  fail "the margin '$margin' does not leave room for the steps after a wait"
+fi
+want=$(($(date +%s) + job_seconds - margin))
+got="$(cat "$TMP_ROOT/gh-read.deadline")"
+if [[ "$got" -ge $((want - 5)) && "$got" -le "$want" ]]; then
+  ok "the step sets the deadline at its start plus the timeout less the margin"
+else
+  fail "the step set the deadline '$got', want about '$want'"
+fi
+if [[ "$job" != *"rate-limit-wait-seconds:"* ]]; then
+  ok "the pinned composites keep their own rate-limit-wait-seconds default"
+else
+  fail "ci-status passes rate-limit-wait-seconds to a composite, which the unchanged timeout does not hold"
+fi
 first="$(grep -m1 '^      - name: ' <<<"$job")"
 if [[ "$first" == "      - name: Write the rate-limit-aware read helper" ]]; then
   ok "the helper is ci-status's first step, so no failure before it skips it"
@@ -64,24 +83,6 @@ if [[ -z "$stray" ]]; then
 else
   fail "ci-status reads through plain gh api without a gh-read-exempt mark: $stray"
 fi
-cap="$(sed -nE 's/^      RATE_LIMIT_WAIT_SECONDS: ([0-9]+)$/\1/p' <<<"$job")"
-timeout="$(sed -nE 's/^    timeout-minutes: ([0-9]+)$/\1/p' <<<"$job")"
-if [[ -n "$cap" && -n "$timeout" && $((2 * cap / 60 + 8)) -le "$timeout" ]]; then
-  ok "the job timeout ($timeout min) holds two ${cap}s wait windows plus the 8 min the other waits need"
-else
-  fail "the job timeout '$timeout' does not hold two '${cap}'s wait windows plus 8 minutes"
-fi
-if [[ "$(grep -c 'rate-limit-wait-seconds: \${{ env.RATE_LIMIT_WAIT_SECONDS }}' <<<"$job")" -eq 2 ]]; then
-  ok "check-contract and aggregate-results wait under the same ceiling"
-else
-  fail "check-contract and aggregate-results do not both take rate-limit-wait-seconds from RATE_LIMIT_WAIT_SECONDS"
-fi
-poll="$(sed -nE "s/^          POLL_LIMIT_SECONDS: '([0-9]+)'$/\1/p" "$DISPATCH")"
-if [[ -n "$poll" && -n "$timeout" && "$poll" -gt $((timeout * 60)) ]]; then
-  ok "pr-feedback-dispatch polls an in-progress ci-status longer than its ${timeout} min timeout"
-else
-  fail "pr-feedback-dispatch's POLL_LIMIT_SECONDS '$poll' does not outlast ci-status's ${timeout} min timeout"
-fi
 
 # The stub logs its arguments. A `gh api -i` probe (graphql, or any other path
 # for core) prints a response whose x-ratelimit-remaining, x-ratelimit-reset
@@ -216,7 +217,7 @@ check "a second rate limit after the wait fails the read without another wait" 0
 fresh
 STUB_LIMIT_core="0 $((NOW + 3000))" STUB_SCRIPT="$LIMITED" run 'gh_read repos/o/r/pulls/1 || echo "rc=$?"'
 check "a reset past the deadline fails the read at once" 0 1 "" \
-  "::error::GitHub's core API rate limit blocks 'gh api repos/o/r/pulls/1' until 2026-10-24T00:50:00Z, after ci-status stops waiting at 2026-10-24T00:10:00Z; re-run this run after 2026-10-24T00:50:00Z."
+  "::error::GitHub's core API rate limit blocks 'gh api repos/o/r/pulls/1' until 2026-10-24T00:50:00Z, past the 2026-10-24T00:10:00Z ci-status can wait to inside its timeout; a re-run after 2026-10-24T00:50:00Z is needed."
 STUB_SCRIPT='ok never' run 'gh_read repos/o/r/pulls/2 || echo "rc=$?"'
 check "a later read of that resource, in a later step, before its reset fails without a call" 0 0 "" "rc=1" "::error::"
 STUB_SCRIPT='ok graphql' run 'gh_read graphql -f query=x'
@@ -230,7 +231,7 @@ ok one" run 'gh_read repos/o/r/pulls/1 >/dev/null'
 check "a 405 s wait inside the deadline is taken" 0 2 "405"
 STUB_NOW=$((NOW + 560)) STUB_LIMIT_core="4999 $((NOW + 3600))" STUB_SCRIPT='fail gh: You have exceeded a secondary rate limit. (HTTP 403)' \
   run 'gh_read repos/o/r/pulls/2 || echo "rc=$?"'
-check "a later step's wait that would end past the deadline is not taken" 0 1 "" "after ci-status stops waiting at 2026-10-24T00:10:00Z"
+check "a later step's wait that would end past the deadline is not taken" 0 1 "" "past the 2026-10-24T00:10:00Z ci-status can wait to"
 
 fresh
 STUB_SCRIPT='fail gh: Not Found (HTTP 404)' run 'gh_read repos/o/r/contents/x 2>"$RUNNER_TEMP/err" || echo "rc=$?"; grep -c "HTTP 404" "$RUNNER_TEMP/err"'
diff --git a/scripts/ci-hold-human-gated.test.sh b/scripts/ci-hold-human-gated.test.sh
index d1836c4dac..327886b1fa 100755
--- a/scripts/ci-hold-human-gated.test.sh
+++ b/scripts/ci-hold-human-gated.test.sh
@@ -231,7 +231,7 @@ else
 fi
 export STUB_RATE_LIMIT='0 1792803000'
 expect "a reset past the deadline fails closed naming the reset" 1 1 "enhancement" 3 \
-  "::error::GitHub's core API rate limit blocks 'gh api repos/o/r/issues/6419/labels?per_page=100 --paginate --jq .[].name' until 2026-10-24T00:50:00Z, after ci-status stops waiting at 2026-10-24T00:10:00Z; re-run this run after 2026-10-24T00:50:00Z."
+  "::error::GitHub's core API rate limit blocks 'gh api repos/o/r/issues/6419/labels?per_page=100 --paginate --jq .[].name' until 2026-10-24T00:50:00Z, past the 2026-10-24T00:10:00Z ci-status can wait to inside its timeout; a re-run after 2026-10-24T00:50:00Z is needed."
 if [[ "$(sleeps)" == "5 10" ]]; then
   ok "a reset past the deadline is not waited for, and the retries make no call"
 else
diff --git a/scripts/ci-rerun-ci-status.test.sh b/scripts/ci-rerun-ci-status.test.sh
index e279e8f9c2..9d1bfbd649 100755
--- a/scripts/ci-rerun-ci-status.test.sh
+++ b/scripts/ci-rerun-ci-status.test.sh
@@ -36,7 +36,7 @@ if [[ ! -s "$TMP_ROOT/body.sh" ]]; then
   exit 1
 fi
 # shellcheck disable=SC2016 # the ${{ }} text is workflow source, not shell
-for env in 'HEAD_SHA: ${{ github.event.workflow_run.head_sha }}' 'PR_NUMBER: ${{ github.event.workflow_run.pull_requests[0].number }}' "POLL_LIMIT_SECONDS: '1740'"; do
+for env in 'HEAD_SHA: ${{ github.event.workflow_run.head_sha }}' 'PR_NUMBER: ${{ github.event.workflow_run.pull_requests[0].number }}' "POLL_LIMIT_SECONDS: '600'"; do
   if [[ "$step" == *"$env"* ]]; then ok "step env carries $env"; else fail "step env lacks $env"; fi
 done
 job="$(awk '/^  rerun-ci-status:$/ { on = 1; next } on && /^  [a-z]/ { exit } on { print }' "$WORKFLOW")"
diff --git a/scripts/lib/ci-gh-read.sh b/scripts/lib/ci-gh-read.sh
index bbeef72003..03ad83dde6 100644
--- a/scripts/lib/ci-gh-read.sh
+++ b/scripts/lib/ci-gh-read.sh
@@ -5,8 +5,9 @@
 #   ci_gh_read::install <workflow> <dir>
 #
 # Runs the `Write the rate-limit-aware read helper` step body of <workflow>
-# with RUNNER_TEMP=<dir>, which leaves <dir>/gh-read.sh for the step bodies
-# under test to source. Returns non-zero when the step is missing or fails.
+# with RUNNER_TEMP=<dir> and the job's GH_READ_* env values, which leaves
+# <dir>/gh-read.sh for the step bodies under test to source. Returns non-zero
+# when the step is missing or fails.
 #
 #   ci_gh_read::reset <dir> <deadline>
 #
@@ -21,7 +22,12 @@ ci_gh_read::install() {
     body && /^[[:blank:]]*$/ { print ""; next }
     body { exit }' "$workflow" >"$dir/gh-read-step.sh"
   [[ -s "$dir/gh-read-step.sh" ]] || return 1
-  RUNNER_TEMP="$dir" bash -e "$dir/gh-read-step.sh" && [[ -s "$dir/gh-read.sh" ]]
+  local job_seconds margin
+  job_seconds=$(sed -nE 's/^      GH_READ_JOB_SECONDS: ([0-9]+)$/\1/p' "$workflow")
+  margin=$(sed -nE 's/^      GH_READ_MARGIN_SECONDS: ([0-9]+)$/\1/p' "$workflow")
+  [[ -n "$job_seconds" && -n "$margin" ]] || return 1
+  RUNNER_TEMP="$dir" GH_READ_JOB_SECONDS="$job_seconds" GH_READ_MARGIN_SECONDS="$margin" \
+    bash -e "$dir/gh-read-step.sh" && [[ -s "$dir/gh-read.sh" ]]
 }
 
 ci_gh_read::reset() {