The GitHub commands behind the pull-request skill's
monitor phase. The phase owns the loop, its
cadence, and every rule and gate; this file holds the commands and the GitHub and gh facts behind
them.
<checkout> is the checkout of the PR's repository the session works on, as
ready-for-review 2.5.3
defines it (absolute, or . when the shell sits in it), so neither the repository nor the branch
depends on the shell's directory:
OWNER_REPO=$(bash "<skill-dir>/scripts/target-repo.sh" --dir "<checkout>") || exit 1
OWNER=${OWNER_REPO%%/*} REPO=${OWNER_REPO#*/}
PR_NUMBER=$(gh pr view "$(git -C "<checkout>" branch --show-current)" -R "$OWNER_REPO" --json number -q '.number' | tr -d '\r')
[ -n "$PR_NUMBER" ] || exit 1On a triangular flow (the branch pushed to a fork, the PR opened on its upstream base), the base
repository takes target-repo.sh's place, named explicitly, since the script resolves the
checkout to the fork, and the head is namespaced <fork-owner>:<branch>, as in
create's triangular flow:
FORK=$(bash "<skill-dir>/scripts/target-repo.sh" --dir "<checkout>") || exit 1
OWNER_REPO="<base-owner>/<repo>" # the PR's target, not the push destination
OWNER=${OWNER_REPO%%/*} REPO=${OWNER_REPO#*/}
PR_NUMBER=$(gh pr view "${FORK%%/*}:$(git -C "<checkout>" branch --show-current)" -R "$OWNER_REPO" --json number -q '.number' | tr -d '\r')
[ -n "$PR_NUMBER" ] || exit 1The commands below write that repository as <owner>/<repo>: put the resolved value in its place.
gh pr view <pr_number> -R <owner>/<repo> --json state -q '.state'The Monitor watch's command is the bundled poll script, run by path; no script body goes inline:
bash "<skill-dir>/scripts/monitor-poll.sh" --pr <N> --checkout "<checkout>"The script resolves OWNER and REPO from --checkout as
Resolve PR identity does, and exits 1 when target-repo.sh refuses. On a
triangular flow, add --repo <base-owner>/<repo>, the PR's base repository named explicitly, which
wins over --checkout. Raise --interval <seconds> (default 60) to poll less often with several
watchers (API budget). --once exits 0 after the first poll that emits
a line, for a background Bash run where the Monitor tool is unavailable. The first arming passes no --baseline; a re-arm
passes --baseline <file>, the file this same script wrote in a snapshot run (--snapshot <file>:
one state check and checks read, the cur_checks lines written under a marker line, then exit 0,
or exit 1 with nothing written when the read failed). A baseline file without that marker line is
refused with BASELINE-UNREADABLE, so only this script's serializer produces a baseline. A usage
error exits 3.
Keep the script free of rm: an auto-mode session's safety check denied the inline command
while it ran rm on a stderr temp file (issue #16201). The reads' stderr collects in errs. The
same check later refused the inline script with no rm in it (issue #16353), so the watch runs it
from the file, and the REST read of a PR's checks lives only there. For a one-off read, run the
script once with --snapshot <file> and read the lines after the file's marker line: one
name: bucket line per finished check, none for a pending one. The bucket mapping and the
latest-per-name/workflow/event dedupe follow gh's pkg/cmd/pr/checks/aggregate.go.
gh pr checks (including --watch) and gh pr view --json query GraphQL (GH_DEBUG=api shows
POST /graphql for gh pr checks and for gh pr view --json state), and
concurrent workers under one token have hit GraphQL secondary rate limits. GraphQL and REST draw on
separate per-minute point budgets (2,000 and 900 points per minute) and separate primary limits
(5,000 points per hour for GraphQL, 5,000 requests per hour for REST), and a REST GET costs 1
point, so moving the polling to REST leaves the GraphQL budget for the calls that have no REST
equivalent, such as review-thread resolution. The 100-concurrent-request ceiling is shared by
both APIs, so REST polling does not raise it. Verified 2026-09-25, and 2026-09-26 with gh 2.97.0 for the gh behavior, against
List check runs for a Git reference,
Get the combined status for a specific reference,
Rate limits for the REST API,
and Rate limits for the GraphQL API.
Recheck when either rate-limits page changes its secondary-limit figures, or when a gh release
note says pr checks or pr view moved off GraphQL or changes the pr checks bucket mapping.
gh pr list -R <owner>/<repo> --state open --json number,title,headRefName,statusCheckRollup \
--jq '.[] | "\(.number) \(.headRefName) \(.title)"'gh pr view <N> -R <owner>/<repo> --json mergeable,mergeStateStatusgh pr checks --watch re-runs its GraphQL query every --interval seconds (default 10) until every
check settles.
gh api --paginate "repos/$OWNER/$REPO/actions/runs?head_sha=$head_sha&per_page=100" \
--jq '.workflow_runs[] | select(.status != "completed") | .id' | tr -d '\r' |
while read -r run_id; do
gh api --paginate "repos/$OWNER/$REPO/actions/runs/$run_id/jobs?per_page=100" \
--jq '.jobs[] | select(.status != "completed") | "\(.name) | \(.status) | \(.labels | join(",")) | created \(.created_at)"'
done | tr -d '\r'Claim: a long CI wait must poll REST on a fixed schedule and must not use gh pr checks --watch; a pending check is reported as queued or running before the wait starts; a queued job
is routed as stuck only when no online runner matches its label, or when occupancy is unreadable
or shows a free matching runner past the threshold, never on age alone while the pool is busy.
Basis: gh pr checks --help (--interval default 10) on gh 2.99.0; Workflow
jobs (status, labels, runner_name);
Self-hosted runners (busy,
status, labels; admin access); Check runs
(six status values); Best practices for using the REST
API
("poll only as often as you need to, on a fixed schedule"). Probe on this marketplace's repo the
same day: jobs read succeeded; both runner-list endpoints returned 403 to a non-admin token.
Issue #3955 evidence: --watch exhausted GraphQL while a self-hosted test job was still queued.
As of: 2026-09-28. Recheck: when a gh release changes --watch's transport or default
interval, or when either runners endpoint changes its permission requirement.
gh run view --log-failed is the last resort: it truncates at the CLI display layer
(cli/cli #11059, #10551, #7771, #7642), while the bundled scripts' REST path returns complete logs.
fetch-annotations.sh and fetch-failed-logs.sh take --dir "<checkout>" and resolve the
repository with target-repo.sh, as Resolve PR identity does. On a
triangular flow, name the PR's base repository in GH_REPO, or in FETCH_ANNOT_REPO and
FETCH_LOGS_REPO, which win over --dir, since the script resolves the checkout to the fork.
The last-resort eyeball:
gh run view <run-id> -R <owner>/<repo> --log-failed 2>&1 | grep '##\[error\]'gh api repos/<owner>/<repo>/pulls/<pr_number>/comments/{comment_id}/replies -f body='...'Writing the body to a file first is safer; see the provider reference.
gh api "repos/<owner>/<repo>/commits/<head-sha>/check-runs"gh pr view --json comments,reviews misses inline review comments, so the bundled
fetch-all-pr-comments.sh reads all three surfaces instead. Like the log scripts, it takes
--dir "<checkout>"; on a triangular flow, name the PR's base repository in GH_REPO, or in
FETCH_COMMENTS_OWNER and FETCH_COMMENTS_REPO, which win over --dir.