codagent:wait-ci

Poll CI check status for the current branch's PR and report the result, enriching failures with log output and checking for blocking reviews.

Use the bundled scripts for all API calls — they encode the correct field names, jq patterns, and GraphQL queries. Do not rewrite API calls inline.

NEVER pause to ask the user for permission to wait. Always run the full polling duration silently. Asking mid-execution breaks automation and is never needed — the caller already decided to invoke this skill.

How polling works

check-ci.sh is a single-invocation script. It polls every 10 seconds for up to 90 seconds, then exits. Claude calls it in a loop to cover the full max wait time. This keeps each Bash call bounded to ~2 minutes rather than blocking the agent for the full duration.

Each Bash call to check-ci.sh must use timeout: 120000 (2 minutes).

Steps

1. Run the polling loop

Compute max_runs = ceil(max_minutes * 60 / 90), defaulting to max_minutes = 15 → 10 runs.

The skill accepts an optional --max-minutes N argument; pass it through to adjust max_runs.

Track ever_had_checks = false, run = 0, and the overall deadline across iterations. The deadline is max_minutes after polling starts and also bounds any review-bot waiting in Step 3.

For each run:

bash skills/wait-ci/scripts/check-ci.sh

Use timeout: 120000 on the Bash call. Check the exit code:

Exit code	Meaning	Action
0	Terminal (passed or failed)	Break out of loop, proceed to Step 2
2	Not yet terminal (pending or no_checks)	If run < max_runs, re-run; else preserve the result and proceed to Step 3
1	Fatal error	Report error and stop

After each exit-2 result, set ever_had_checks = ever_had_checks OR result.had_checks.

Timeout handling: When all runs are exhausted (exit code 2 on the last run):

• If ever_had_checks is false → treat CI as non-blocking, then still run Step 3 before reporting a final status
• Otherwise → preserve pending and the list of still-running checks, then run Step 3 before classifying the final status

The script outputs a JSON object with these fields:

Field	Type	Description
status	string	passed, failed, pending, no_checks, or comments (set by caller; may coexist with pending-check evidence)
pr_url	string	PR URL
pr_number	number	PR number
head_sha	string	PR head commit queried for this invocation; preserve it when upgrading the status to comments
owner / repo	string	Repo coordinates for subsequent calls
had_checks	bool	Whether any checks were seen on this invocation
failed_checks	array	Checks with bucket == "fail"
passed_checks	array	Checks with bucket == "pass"
pending_checks	array	Checks still running
blocking_reviews	array	Reviews with CHANGES_REQUESTED (latest per reviewer)
failed_run_ids	array	GitHub Actions run IDs extracted from failed check links
mergeable	string	GraphQL mergeable: MERGEABLE, CONFLICTING, or UNKNOWN
mergeStateStatus	string	GraphQL merge state (DIRTY when conflicting)
conflicting_files	array	Paths that conflict with the PR base when git merge-tree can see both commits

CONFLICTING is terminal failed even when checks are green. Keep polling while mergeable is UNKNOWN; do not emit passed. Include conflicting_files in the JSON when the PR base is available locally.

2. Fetch failure logs (if status == "failed")

For each run ID in failed_run_ids:

gh run view <run-id> --log-failed

Keep the last 100 lines if output is longer. External checks (no run ID) get no logs.

3. Gather PR comments

Run this step after checks are terminal, checks time out as pending, or no checks exist:

bash skills/wait-ci/scripts/get-pr-comments.sh <owner> <repo> <pr-number> [<pr-author-login>]

Uses GraphQL to check isResolved on review threads directly — no jq != workarounds needed.

Output fields:

Field	Type	Description
has_comments	bool	True if any actionable comments exist
unresolved_threads	array	{file, line, author, body} per actionable unresolved review thread
deferred_threads	array	{file, line, author, body} per unresolved thread deferred by the PR author or fix-pr session
issue_comments	array	{author, body} blocking top-level human comments (excluding PR creator)
informational_bot_comments	array	{author, body} non-blocking top-level bot comments retained as evidence

has_comments is true only for actionable unresolved threads plus blocking issue comments. A thread is deferred (non-actionable) when fix-pr replied without resolving: the latest significant comment after stripping trailing reviewer-bot acks is from the PR author or from a different bot than the original finding bot (factory session identity). Later bot acknowledgments do not re-block; a later human reviewer reply is actionable again. Green CI with only deferred threads is passed. Keep deferred threads visible under their own heading. Do not add a fourth CI status marker.

When checks are terminal, time out as pending, or do not exist, inspect informational_bot_comments. If a bot explicitly reports that its review is pending or in progress, or asks the caller to check back, wait 10 seconds and call get-pr-comments.sh again while time remains before the overall deadline. Re-evaluate the latest evidence on every poll. Do not hard-code bot vendors or exact phrases; use the comment's meaning. A terminal current-head check from that bot supersedes an older progress notice. Completed summaries and ordinary status notices remain informational and do not delay completion.

At the overall deadline, use this precedence:

1. failed for failed checks, CONFLICTING merge state, or blocking reviews.
2. comments when actionable unresolved feedback exists, even if a review bot is still unfinished.
3. pending when checks or a review bot remain unfinished and no actionable feedback exists.
4. passed when CI is green or explicitly absent, no actionable feedback exists, and no review bot remains unfinished.

Preserve unfinished bot notices in the report even when actionable feedback makes the status comments. Never extend the overall deadline while waiting for review bots.

Status upgrade: If checks returned passed, timed out as pending, or were absent, but get-pr-comments.sh returns has_comments: true, report the final status as comments unless failed checks or blocking reviews require failed. Preserve the check result, including pending_checks, when upgrading the status.

No-checks handling: If polling timed out with no checks ever observed, run get-pr-comments.sh before reporting success. Report comments when has_comments is true, pending when a review bot remains explicitly unfinished at the deadline or mergeable is UNKNOWN, and otherwise passed.

Output Format

## CI Status: <passed | failed | pending | comments>

**PR:** <url>
**Elapsed:** ~<N> minutes

### Failed Checks
- **<check-name>** (FAILURE)
  Link: <details-url>
  Logs:

Merge Conflicts

• <conflicting-path>

Blocking Reviews

• :

PR Comments

• on <file> line :
• (issue comment):

Deferred Threads

• on <file> line :

Informational Bot Comments

• :

Passing Checks

• (SUCCESS)

Still Running

• (PENDING/IN_PROGRESS)

Status meanings:
- `passed` — CI green, mergeable, no blocking reviews or actionable comments, and no bot review still in progress. Deferred threads may still be listed.
- `failed` — CI failures, `CONFLICTING` merge state, or `CHANGES_REQUESTED` reviews (with logs and conflicting paths when available)
- `comments` — actionable PR comments need addressing; known actionable feedback takes precedence
  over unfinished checks or review automation, whose pending evidence remains in the report
- `pending` — checks, unknown mergeability, or an explicitly unfinished bot review remain after max wait, with no actionable feedback available

## Notes

- Can be invoked standalone without prior workflow state
- Default: 10 runs × 90 seconds = ~15 minutes max wait; pass `--max-minutes N` to override
- **Never ask the user for permission mid-execution** — always run the full duration
- `CHANGES_REQUESTED` is a hard block; `APPROVED` and `COMMENTED` alone do not block
- `CONFLICTING` is a hard block; `UNKNOWN` mergeability is not `passed`
- Comment gathering runs after polling ends, including pending-check timeouts and the no-checks path
- Log enrichment only works for GitHub Actions checks (not external status checks)

## Scripts Reference

| Script | Purpose |
|---|---|
| `scripts/check-ci.sh` | Single-invocation poller (90s, 10s interval) — call in a loop from the skill |
| `scripts/get-pr-comments.sh` | GraphQL comment fetcher — returns actionable review feedback, deferred threads, and informational bot comments |