Skip to content

feat(scripts): add pr_watch.py PR waiter with optional review-bot gate (12.1.0) - #110

Merged
lklimek merged 7 commits into
mainfrom
feat/pr-watch
Nov 10, 2026
Merged

lklimek merged 7 commits into
mainfrom
feat/pr-watch

Conversation

@lklimek

@lklimek lklimek commented Nov 6, 2026 •

Copy link
Copy Markdown
Owner

TL;DR: Adds a ready-made way to wait for pull requests to change and to check, before pushing, whether a review bot is still working on a pull request.

User story

As a developer driving several pull requests with an AI agent, I can have the agent wait in the background until something on a pull request changes (a new review comment, a failed check, a finished bot review) and check that a review bot is not in the middle of a review before it pushes, to avoid wasted reviews and constant manual polling.

Scenario

Base flow

  1. An agent pushes changes to a pull request that a review bot will review.
  2. The agent wants to know when the review lands or CI fails, and must not push again while the bot is reviewing.

Actual behavior

The plugin only offers one-off GitHub lookups. Waiting for changes and detecting a running bot review relied on scripts kept outside the plugin, tied to one bot and one repository.

Expected behavior

The plugin ships a waiter that works in any repository. It prints a line when a watched pull request changes and can be told which bot to treat as a reviewer. Before a push, it answers "reviewing" / "not reviewing" / "could not tell" through its exit code.

Detailed discussion

What was done

  • scripts/pr_watch.py (Python, stdlib only), two subcommands:
    • watch <pr>... — takes a full reading every --interval (default 120 s, env PR_WATCH_INTERVAL) and prints one line per PR whose reading changed: state, review decision, draft flag, unresolved review threads (GraphQL with pagination, body in the same query), and non-passing checks (gh pr checks --json name,bucket, judged by output since gh exits non-zero for failing/pending checks). Options: --checks regex, --ignore-pending, --quiet-init, --oneshot. A failed fetch, or a pr-hygiene block that describes an older head, skips the PR for that pass. The failure is reported on stderr once per outage; --oneshot exits 2 after 5 passes in which every fetch failed.
    • Between full readings, every --probe-interval (default 30 s, env PR_WATCH_PROBE_INTERVAL, 0 disables) it sends conditional REST requests (If-None-Match) for the PR's issue record (not pulls/{n}, whose ETag changes on any push to the repository), the last-read head's check runs and commit statuses, and with a gate bot the first page of comments. A 304 costs no rate limit; any change triggers a full reading at once. The notifications API would be cheaper still, but fine-grained tokens cannot use it. An endpoint that fails (for example no permission) is skipped until the PR's next good full reading. Changes the probes cannot see, such as a resolved review thread, show at the next full reading.
    • gate <pr> — for a bot that edits one status comment in place. The comment is selected by marker (default <login>-gate) and newest updated_at. An optional JSON feed (live.active / live.queued, data_as_of) can be cross-checked. A busy comment always holds. A feed ACTIVE entry holds unless the comment was edited later. Exit codes: 3 = reviewing, 0 = not reviewing, 2 = fetch failure or bad usage. Unexpected errors also map to 2, never to an implicit "go".
    • Both adapters are optional: no --gate-bot/GATE_BOT means no gate, and no hygiene block in the body means no hygiene segment. REPO/GATE_BOT/GATE_MARKER/GATE_FEED_URL supply defaults.
  • git-and-github § Before Every Push ("Wait for bots") points to the script. references/gh-cli.md § PR waiter documents usage: background run with --quiet-init --oneshot, relaunch after each event, and the exit-code caveats.
  • Version 12.1.0 (new script, minor).

Testing

  • tests/test_pr_watch.py: 60 tests on recorded, trimmed real responses in tests/fixtures/pr-watch/ (PR body with hygiene block, GraphQL PR node, gate comments, review-system feed). Covered: multi-line and CRLF gate comments, emoji-prefixed status lines, case-insensitive repo, bot names and default gate marker, review threads past the first page, conditional probes (baseline, 304, change, failing endpoint backoff) and their scheduling against full readings, a U+0085 inside a comment body, stale feed ACTIVE vs a newer gate edit, a stale hygiene head, failed/malformed fetches, failing checks with non-zero exit, "no checks reported", quiet-init/oneshot (including giving up on persistent failure), exit codes, regex validation, and isolation from exported env vars and the network.
  • Full suite: python3 -m pytest -q tests passes. Shell tests pass, except tests/test_cargo_cached.sh. That one fails on this host because cargo metadata times out, and it touches no file in this PR.
  • Smoke-tested against live PRs (perf(wallet): stop re-copying wallet funding state for Max quotes and snapshots dashpay/dash-evo-tool#1167, feat!: fold push skill into git-and-github, wait for bots before pushing (12.0.0) #109, a nonexistent PR number).
  • Independent basic review (one reviewer, complete coverage): 4 low-severity findings, all fixed in this PR.

Breaking changes

None.

Checklist

  • Version bumped (12.1.0)
  • Tests added
  • Docs updated

Prior work

Ported from a user-level script pair (pr-watch.sh, bot-gate.sh), generalized to be repository- and bot-agnostic.

Attribution

🤖 Co-authored by Claudius the Magnificent AI Agent

🤖 Generated with Claude Code

…e (12.1.0)

`watch` polls PRs and prints one line per state change (state, decision,
unresolved threads, non-passing checks, optional pr-hygiene block and gate
line); `gate` is a push check for a bot that edits one status comment in
place, optionally cross-checked against a JSON feed of its running reviews.
Ported from a user-level pr-fleet-loop script pair; documented in
git-and-github's "Wait for bots" rule.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… tests

- Fetch failures go to stderr once per PR per distinct error; a malformed
  response is a failed reading in watch and exit 2 in gate.
- Feed: HTTP protocol errors, malformed entries and naive timestamps are
  handled; --gate-feed-url/--gate-busy move to gate, the only consumer.
- Regex options are validated by argparse.
- The PR body comes from the same GraphQL query; an empty description is
  a PR without a Hygiene block.
- Tests clear REPO/GATE_* and forbid network fetches.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… match

Both tests fail on 2592b1d and pass once fixed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…p on persistent failure

- Match the feed repo and gate-bot login case-insensitively, as GitHub does;
  a differently cased --repo or --gate-bot could read a running review as idle.
- Split gh --jq comment rows on "\n" only: a raw U+0085 inside a body is valid
  JSON and splitlines() broke every gate read on that PR.
- watch: re-report a fetch failure after each recovery, and --oneshot exits 2
  after 5 passes in which every fetch failed instead of waiting forever.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Case-sensitive gate-marker matching can falsely report success for a busy gate, while missing pagination can hide unresolved review threads beyond the first 100.

2 open issues
What changed in this PR

Adds a reusable PR watcher and optional review-bot push gate to Claudius, replacing ad hoc polling scripts with a repository-independent helper.

Changes:

  • Adds pr_watch.py with change monitoring, configurable bot detection, and gate exit codes.
  • Documents background waiting and pre-push gate usage.
  • Adds fixture-based tests and bumps the plugin version to 12.1.0.
File Description
scripts/​pr_watch.py Implements PR monitoring and the optional review-bot gate.
tests/​test_pr_watch.py Tests parsing, polling, failures, and CLI behavior.
tests/​fixtures/​pr-watch/​graphql-1167.json Supplies PR state and review-thread data.
tests/​fixtures/​pr-watch/​feed.json Supplies active and queued review-feed examples.
tests/​fixtures/​pr-watch/​comments.jsonl Supplies bot status and unrelated comment examples.
tests/​fixtures/​pr-watch/​body-hygiene.md Supplies a PR hygiene block for parser tests.
skills/​git-and-github/​SKILL.md Links pre-push guidance to the new helper.
skills/​git-and-github/​references/​gh-cli.md Documents commands, options, and exit-code caveats.
.claude-plugin/​plugin.json Bumps the plugin version to 12.1.0.

Review effort: Balanced

Comment thread scripts/pr_watch.py Resolved
Comment thread scripts/pr_watch.py Resolved
…eview threads

- watch: every --probe-interval (default 30 s) send conditional REST requests
  for the PR, its head's check runs and statuses, and the first comments page
  with a gate bot. A 304 costs no rate limit; any change triggers a full
  reading at once. Full readings still run every --interval (default 120 s).
  Both intervals also take PR_WATCH_INTERVAL / PR_WATCH_PROBE_INTERVAL.
  An endpoint that fails is skipped until the PR's next good full reading.
- Follow reviewThreads pagination, so threads past the first 100 count.
- The default gate marker <bot>-gate matches in any case, like the login;
  an explicit --gate-marker still matches exactly.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…be churn

Both marked xfail(strict) until fixed: full readings drift past --interval
when the probe interval does not divide it, and the pulls ETag changes on any
push to the repository (embedded base.repo.pushed_at).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ever drift past --interval

- pulls/{n} embeds the repository's pushed_at, so a push to any branch changed
  its ETag and turned every probe into a counted 200 plus a full reading on a
  busy repository. Probe issues/{n} instead and take the head for the
  check-run and status probes from the last full reading.
- Count probes per full reading with floor division, so full readings are at
  most --interval apart for any probe interval.
- Reject --interval 0, which made the watcher read in a tight loop.
- gh-cli.md: --oneshot gives up after 5 failed full readings in a row.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@lklimek
lklimek merged commit d31993a into main Nov 10, 2026
2 checks passed
@lklimek
lklimek deleted the feat/pr-watch branch November 10, 2026 16:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants