Add CI watch script, API budget rules and /code-review note for agents

[Mikola Lysenko (mikolalysenko)]

What

• scripts/ci-watch.sh: a quiet event stream of a PR's CI, for Claude Code's Monitor tool (it also works in a terminal). It prints a start summary, fail: <check> for each failed check, progress: counts, queue: position changes, and a final DONE ... line. Exit status is 0 for pass/merged and 1 for fail/closed/dequeued. --merge follows the PR through the merge queue.
  • Cheap to run: each poll (every 2 minutes) is one small GraphQL query for the PR's rollup state. The full check list, several pages for a PR here, is fetched only when that state changes or every 5th poll. A rate-limited poll pauses 10 minutes.
• AGENTS.md:
  • Wait on CI by running the script under Monitor, not with sleep + gh pr checks loops or /loop.
  • Run /code-review high (and --fix) before a PR leaves draft or enters the merge queue. Use --comment when reviewing someone else's PR.
  • New section, Share the GitHub API budget: check x-ratelimit-remaining before bulk reads, cap pagination and parallelism, stop on rate-limit errors, and keep at most one re-check reminder per PR.

Why

Every agent and routine calls GitHub as one account and shares one 5,000/hour budget. On 2026-10-08 a bulk Actions fetch by the new CI profiler, plus ~18 concurrent agent sessions, ran that budget to zero twice in one evening, and every agent stalled. The cloud routines' prompts got the same budget rules separately; this PR puts them where every agent reading this repo will see them.

Testing

• shellcheck clean.
• First version run against live PRs: Fix npm wrapper running the glibc binary on musl (#974) #976 (merged) and Remove apply.lock when a lock-holding run is interrupted (#808) #1030 (merged during the test) each printed a summary and DONE merged. Fix Poetry/PDM vendored re-vendor to superseding patch (#1136) #1137 (in the queue, --merge) printed queue: entered at 1 awaiting_checks, then stayed silent.
• The rollup-gated polling and the rate-limit pause were added after that and have not been run live. Neither have the pending-check and fail: paths: no PR had pending checks during testing.

🤖 Generated with Claude Code

---

Note

Low Risk
Documentation and a local gh helper script only; no changes to application runtime, auth, or data paths.

Overview
Adds scripts/ci-watch.sh, a quiet CI/merge-queue event stream for Monitor (or a terminal): rollup-gated GraphQL polls, full gh pr checks only when status changes or every 5th poll, fail:/progress:/queue: lines, 10-minute pause on rate limits, and exit codes for pass/fail/merged/dequeued.

AGENTS.md now tells agents to use that script instead of sleep/gh pr checks loops, run /code-review high (and --fix / --comment) before leaving draft or entering the merge queue, and follow shared GitHub API budget rules (check x-ratelimit-remaining, cap pagination/parallelism, stop on 403/429, one re-check reminder per PR).

^{Reviewed by Cursor Bugbot for commit fd1987d. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Watch script can exit too early
  • Added check for terminal statusCheckRollup.state (SUCCESS/FAILURE/ERROR) before exiting to prevent premature exit when checks are expected but not yet created or when draft jobs are skipped.

Or push these changes by commenting:

@cursor push cd1fb43bf9

Preview (cd1fb43bf9)

diff --git a/scripts/ci-watch.sh b/scripts/ci-watch.sh
--- a/scripts/ci-watch.sh
+++ b/scripts/ci-watch.sh
@@ -101,8 +101,12 @@
 
   if [ "$merge" = 0 ]; then
     if [ "$total" -gt 0 ] && [ "$pending" = 0 ]; then
-      if [ "$fail" = 0 ]; then echo "DONE checks pass ($total checks)"; exit 0; fi
-      echo "DONE checks fail ($fail of $total failed)"; exit 1
+      case "$rollup" in
+        SUCCESS|FAILURE|ERROR)
+          if [ "$fail" = 0 ]; then echo "DONE checks pass ($total checks)"; exit 0; fi
+          echo "DONE checks fail ($fail of $total failed)"; exit 1
+          ;;
+      esac
     fi
   fi
   sleep "$interval"

_{You can send follow-ups to the cloud agent here.}

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit fd1987d. Configure here.}