@olegkoval/agent-skills 1.51.0 → 1.51.2

package/.kiro/steering/qodoloop.md

@@ -23,10 +23,31 @@ Qodo runs as `qodo-code-review[bot]` and posts **two independent things** per re
 
 **Use the inline threads as the source of truth.** They carry `isResolved` state natively (fetch via GraphQL, see `references/graphql-queries.md`), so "done" is answerable directly instead of re-parsing the rollup's HTML on every iteration. Each thread's body contains a `<details><summary>Agent Prompt</summary>` (or `**Agent Prompt**`) section with a ready-made fix spec, and a severity badge image whose `alt` text is `Remediation recommended` or `Informational` (recommended ↔ "Review recommended", informational ↔ "Optional").
 
-Qodo has **no check run to poll**: there is nothing in `gh pr checks` to wait on. Completion means a new `qodo-code-review[bot]` comment/review appears after your push; poll comments, not checks.
+Qodo has **no check run to poll**: there is nothing in `gh pr checks` to wait on. Completion means a new `qodo-code-review[bot]` comment/review appears after your push; `scripts/pr-review-state.sh` detects it.
 
 **Rate limit is a real terminal state, not a bug.** A completed-looking comment reading "Qodo reviews are paused" / "you've reached your PR review limit" means Qodo will not review again this cycle: stop and report it, don't loop waiting for something that isn't coming.
 
+## Review state comes from the PR, not from memory
+
+`scripts/pr-review-state.sh` reads the PR and prints one JSON object: the current head, whether
+Qodo has acted on that head (a review of it, or any comment after it was pushed), and every
+unresolved review thread with its author. Every "is there work / are we done" decision in this
+loop comes from its exit code, never from what you remember resolving. The script lives in this
+skill's directory, `SKILL_ROOT`: the directory holding this `SKILL.md` (Claude Code prints it as the
+skill's base directory when the skill loads; in Codex, derive it from the selected `SKILL.md` path).
+
+| Exit | `verdict`  | Meaning                                                             | Do                                   |
+|------|------------|---------------------------------------------------------------------|--------------------------------------|
+| 0    | `clean`    | Qodo acted on the current head and no bot thread is unresolved    | exit check: done                     |
+| 10   | `findings` | unresolved threads from Qodo **or any other review bot**          | run an iteration                     |
+| 20   | `pending`  | Qodo has not acted on the current head yet                        | trigger if needed, then wait         |
+| 30   | `limited`  | a rate-limit or paused notice from Qodo after the current head    | stop, report `blocked: rate-limited` |
+
+Resolving the last thread does not make a PR clean: Qodo has not reviewed your push yet. Earlier
+versions of this loop exited at exactly that moment, while the next round of comments was still on
+its way. Human threads are listed in `.unresolved` (`is_bot: false`) and counted in `.counts.humans`;
+they never block `clean`, and this loop never resolves them.
+
 ## Instructions
 
 ### 1. Identify the PR
@@ -51,33 +72,48 @@ narrower.
 
 ### 2. Loop (max 5 iterations)
 
-#### A. Wait for a review of the current head
-
-On **iteration 1**, if there is nothing to push yet (you haven't fixed anything in this loop), don't wait for a brand-new review: use whatever Qodo has already posted as your starting point and go straight to step B. Otherwise:
-
-```bash
-SINCE=$(date -u +%Y-%m-%dT%H:%M:%SZ)
-git push
-```
+#### A. Read the PR state; wait for Qodo's review of the current head
 
-Poll (every ~10s, timeout ~5min), fetching **every page** of comments, not just the first:
+One read answers both "is there work?" and "has Qodo seen my last push?". `SINCE` is the
+timestamp you took right before your last push (step E); leave it empty on iteration 1. Right
+after a push, add `--wait 600` straight away: the wait ends only once the bot has acted on the new
+head, so threads left open on purpose cannot make the push look reviewed.
 
 ```bash
-gh api --paginate "repos/{owner}/{repo}/issues/<PR_NUMBER>/comments?per_page=100" | jq -s '
-  add | map(select(.user.login == "qodo-code-review[bot]")) | sort_by(.created_at)'
+"$SKILL_ROOT/scripts/pr-review-state.sh" --repo OWNER/REPO --pr <PR> --bot qodo-code-review --since "$SINCE"
 ```
 
-From the comments created **after `$SINCE`** (ignore anything older: that's leftover from a prior push, not this one):
-- Any of them contains "review limit" or "paused" → **stop the loop now**, go to Report with `blocked: rate-limited`.
-- The latest one starts with `<h3>Code Review by Qodo</h3>` → proceed to step B.
-- Otherwise (nothing yet, or only "Qodo is busy working") → sleep 10s and poll again, up to the 5-minute timeout.
+- Exit `10` (`findings`): go to B. On iteration 1 this is whatever Qodo (or another bot)
+  already posted.
+- Exit `20` (`pending`): Qodo reviews new pushes on its own, so there is nothing to post. Then wait with the same command plus `--wait 600`. Run the
+  wait in the background where the host allows it (Claude Code: Bash `run_in_background`; you are
+  re-invoked when it exits) so ten minutes of polling never sits in the conversation. Still `20`
+  after the wait: say so out loud, check the PR for a Qodo notice explaining the silence, and wait once more. Still `20` after that: stop and
+  report the timeout honestly; never claim success.
+- Exit `0` (`clean`): go to the exit check. A `--wait` call returns `clean` only after a settle
+  re-read 60 seconds later, so a comment landing right behind the review is still caught. A bare
+  read (no `--wait`) that says `clean` is good enough only when you have not pushed since Qodo's
+  last review.
+- Exit `30` (`limited`): stop now and report `blocked: rate-limited`; nothing more is coming.
+- Exit `1`: the read itself failed (often a transient GitHub 502). Retry once; if it fails again,
+  stop and report it. An unknown state is not a clean one.
 
 #### B. Fetch unresolved findings
 
-Run the paginated GraphQL query in `references/graphql-queries.md` (`unresolvedQodoThreads`): **follow `pageInfo.hasNextPage`/`endCursor` until it's exhausted**; a PR with more than 100 Qodo threads silently loses every finding past the first page otherwise. For each unresolved thread from `qodo-code-review[bot]`: parse the finding title, severity (recommended/optional), file/line, and the **Agent Prompt** block.
+The working set is every unresolved thread in the state JSON with `is_bot: true`: Qodo's
+own (`is_target: true`) **and any other review bot's** (Greptile, for example). A
+fix for one bot often draws a comment from another, and leaving those open is how a "finished" loop
+leaves a PR that is not clean. Never act on a human's thread (`is_bot: false`); list it in the report.
+
+Qodo's threads are `.unresolved[] | select(.is_target)` in step A's state JSON (the script already follows pagination). For each, read the full comment (`gh api repos/{owner}/{repo}/pulls/comments/<comment_id>`) and parse the finding title, severity (recommended/optional), file/line, and the **Agent Prompt** block.
 
 Build the working set: all `recommended` threads, plus `optional` ones too if `--include-optional`.
 
+Threads from other bots come from the state JSON (`.unresolved[] | select(.is_bot and (.is_target | not))`).
+They carry no ready-made fix prompt: read the full comment
+(`gh api repos/{owner}/{repo}/pulls/comments/<comment_id>`), verify its claim against the real
+code, and handle it like any Qodo finding: fix it, or reply with the evidence for not fixing it.
+
 Mark each thread as seen with an 👀 reaction on its first comment (`databaseId` from the query), so
 the bot and a watching human can tell it is being worked. GitHub's reaction set is fixed; `eyes` is
 the only "looking at it" value:
@@ -88,7 +124,15 @@ gh api --method POST repos/{owner}/{repo}/pulls/comments/<DATABASE_ID>/reactions
 
 #### C. Check exit conditions
 
-Stop if the working set is empty, or max iterations reached.
+Stop when step A's read exited `0` (`clean`) after your last push (a `--wait` read, which settles),
+or exited `30` (`limited`), or the iteration cap is reached. An empty working set on its own is not
+done: with no review of the current head yet, it only means Qodo has not answered your push.
+
+Two kinds of thread stay open by design, so for Qodo `findings` can still mean done: a finding you
+**blocked** (replied, deliberately left unresolved) and, without `--include-optional`, an
+**Optional** finding outside the working set. Stop as done when Qodo has acted on the current head
+(`.bots[0].acted_on_head` is `true` in a `--wait` read) and every open bot thread is one of those
+two. Never re-work a thread already in your blocked ledger.
 
 #### D. Fix each finding
 
@@ -101,6 +145,7 @@ If **fixed** is empty, skip straight to F (nothing to commit). Otherwise, stage
 ```bash
 git add <files touched by this iteration's fixes>
 git commit -m "address Qodo review feedback (qodoloop iteration N)"
+SINCE=$(date -u +%Y-%m-%dT%H:%M:%SZ)   # step A reads bot activity after this
 git push
 ```
 
@@ -134,6 +179,18 @@ gh api --method POST repos/{owner}/{repo}/pulls/comments/<DATABASE_ID>/reactions
 
 Go back to step A.
 
+### Keep the context small; resume instead of restarting
+
+- Carry only three things between iterations: the iteration counter, the latest state JSON, and a
+  ledger of each thread you handled (fixed with its commit, rebutted, or blocked). Re-read files
+  fresh each iteration; do not re-paste earlier rounds' comment bodies.
+- All loop state lives on the PR, so the loop is resumable. If the session has grown long or slow,
+  or a bot commented after the loop ended, run this skill again in a fresh session: step A picks up
+  from the PR as it is now. Starting fresh is cheaper than dragging a long session through more
+  rounds.
+- After reporting done, if the host can schedule a follow-up (Claude Code: `/loop` or a scheduled
+  wakeup), offer one re-check about 20 minutes later for bots that comment late.
+
 ### 3. Report
 
 | Field              | Value |
@@ -142,7 +199,8 @@ Go back to step A.
 | Findings resolved  | N     |
 | Findings blocked   | N (with reasons, left unresolved) |
 | Remaining          | N (if any) |
-| Blocked            | rate-limited / human-intervention / max-iterations / none |
+| Human threads      | N (open, listed; never resolved by this loop) |
+| Blocked            | rate-limited / timeout / human-intervention / max-iterations / none |
 
 ```text
 Qodoloop complete.
@@ -154,4 +212,4 @@ Qodoloop complete.
 
 ## References
 
-- `references/graphql-queries.md`: the exact `unresolvedQodoThreads` query and the `resolveReviewThread` / `addPullRequestReviewThreadReply` mutations, with field notes.
+- `references/graphql-queries.md`: the `resolveReviewThread` / `addPullRequestReviewThreadReply` mutations, with field notes. Its `unresolvedQodoThreads` query is superseded by `scripts/pr-review-state.sh` for finding threads.

package/.windsurf/rules/coderabbitloop.md

@@ -28,6 +28,27 @@ CodeRabbit has slash commands (official, `docs.coderabbit.ai/reference/review-co
 
 **Rate limit is a real terminal state, not a bug.** A comment reading "you've reached your PR review limit" (confirmed live wording) means CodeRabbit will not review again this cycle: stop and report it, don't loop waiting for something that isn't coming.
 
+## Review state comes from the PR, not from memory
+
+`scripts/pr-review-state.sh` reads the PR and prints one JSON object: the current head, whether
+CodeRabbit has acted on that head (a review of it, or any comment after it was pushed), and every
+unresolved review thread with its author. Every "is there work / are we done" decision in this
+loop comes from its exit code, never from what you remember resolving. The script lives in this
+skill's directory, `SKILL_ROOT`: the directory holding this `SKILL.md` (Claude Code prints it as the
+skill's base directory when the skill loads; in Codex, derive it from the selected `SKILL.md` path).
+
+| Exit | `verdict`  | Meaning                                                             | Do                                   |
+|------|------------|---------------------------------------------------------------------|--------------------------------------|
+| 0    | `clean`    | CodeRabbit acted on the current head and no bot thread is unresolved    | exit check: done                     |
+| 10   | `findings` | unresolved threads from CodeRabbit **or any other review bot**          | run an iteration                     |
+| 20   | `pending`  | CodeRabbit has not acted on the current head yet                        | trigger if needed, then wait         |
+| 30   | `limited`  | a rate-limit or paused notice from CodeRabbit after the current head    | stop, report `blocked: rate-limited` |
+
+Resolving the last thread does not make a PR clean: CodeRabbit has not reviewed your push yet. Earlier
+versions of this loop exited at exactly that moment, while the next round of comments was still on
+its way. Human threads are listed in `.unresolved` (`is_bot: false`) and counted in `.counts.humans`;
+they never block `clean`, and this loop never resolves them.
+
 ## Instructions
 
 ### 1. Identify the PR
@@ -52,38 +73,50 @@ gets those edits swept into the fix commit right along with it.
 Keep an explicit iteration counter and stop at 5: the cap is a real bound to enforce, not a figure
 of speech. Each pass through A–F is one iteration; on hitting the cap, go straight to the report.
 
-#### A. Wait for a review of the current head
-
-On **iteration 1**, if there is nothing to push yet (you haven't fixed anything in this loop), don't
-wait for a brand-new review: use whatever CodeRabbit has already posted as your starting point and
-go straight to step B. Otherwise:
-
-```bash
-SINCE=$(date -u +%Y-%m-%dT%H:%M:%SZ)
-git push
-```
+#### A. Read the PR state; wait for CodeRabbit's review of the current head
 
-If this repo doesn't auto-review on push, nudge it:
+One read answers both "is there work?" and "has CodeRabbit seen my last push?". `SINCE` is the
+timestamp you took right before your last push (step E); leave it empty on iteration 1. Right
+after a push, add `--wait 600` straight away: the wait ends only once the bot has acted on the new
+head, so threads left open on purpose cannot make the push look reviewed.
 
 ```bash
-gh pr comment <PR_NUMBER> --body "@coderabbitai review"
+"$SKILL_ROOT/scripts/pr-review-state.sh" --repo OWNER/REPO --pr <PR> --bot coderabbitai --since "$SINCE"
 ```
 
-Poll (every ~10s, timeout ~5min) for CodeRabbit's next formal review to land: a new entry in
-`gh api --paginate repos/{owner}/{repo}/pulls/<PR_NUMBER>/reviews` from `coderabbitai[bot]`
-(REST spelling carries the `[bot]` suffix) created after `$SINCE`. Follow pagination so a review
-that lands on page two is not missed. If you instead see a rate-limit comment ("review limit"),
-**stop the loop now** and go to Report with `blocked: rate-limited`. If no review arrives within
-the timeout after one retry, stop and report the timeout honestly; do not claim success.
+- Exit `10` (`findings`): go to B. On iteration 1 this is whatever CodeRabbit (or another bot)
+  already posted.
+- Exit `20` (`pending`): post `@coderabbitai review` if this repo does not review pushes automatically (`gh pr comment <PR_NUMBER> --body "@coderabbitai review"`). Then wait with the same command plus `--wait 600`. Run the
+  wait in the background where the host allows it (Claude Code: Bash `run_in_background`; you are
+  re-invoked when it exits) so ten minutes of polling never sits in the conversation. Still `20`
+  after the wait: say so out loud, post `@coderabbitai review` once more, and wait once more. Still `20` after that: stop and
+  report the timeout honestly; never claim success.
+- Exit `0` (`clean`): go to the exit check. A `--wait` call returns `clean` only after a settle
+  re-read 60 seconds later, so a comment landing right behind the review is still caught. A bare
+  read (no `--wait`) that says `clean` is good enough only when you have not pushed since CodeRabbit's
+  last review.
+- Exit `30` (`limited`): stop now and report `blocked: rate-limited`; nothing more is coming.
+- Exit `1`: the read itself failed (often a transient GitHub 502). Retry once; if it fails again,
+  stop and report it. An unknown state is not a clean one.
 
 #### B. Fetch unresolved findings
 
-Run the `unresolvedQodoThreads`-shaped query in `references/graphql-queries.md` (filter `author.login`
-on GraphQL's bare `coderabbitai`, **not** REST's `coderabbitai[bot]`: see the reference's login-spelling
-note, and follow `pageInfo.hasNextPage`/`endCursor` until exhausted). For each unresolved thread,
-parse the finding text, its `databaseId`, and the **Prompt for AI Agents** block (heading text is
+The working set is every unresolved thread in the state JSON with `is_bot: true`: CodeRabbit's
+own (`is_target: true`) **and any other review bot's** (Greptile, for example). A
+fix for one bot often draws a comment from another, and leaving those open is how a "finished" loop
+leaves a PR that is not clean. Never act on a human's thread (`is_bot: false`); list it in the report.
+
+CodeRabbit's threads are `.unresolved[] | select(.is_target)` in step A's state JSON (the script
+already follows pagination). For each, read the full comment
+(`gh api repos/{owner}/{repo}/pulls/comments/<comment_id>`) and parse the finding text and the
+**Prompt for AI Agents** block (heading text is
 `🤖 Prompt for AI Agents`, not `Agent Prompt`: match case/emoji-insensitively).
 
+Threads from other bots come from the state JSON (`.unresolved[] | select(.is_bot and (.is_target | not))`).
+They carry no ready-made fix prompt: read the full comment
+(`gh api repos/{owner}/{repo}/pulls/comments/<comment_id>`), verify its claim against the real
+code, and handle it like any CodeRabbit finding: fix it, or reply with the evidence for not fixing it.
+
 Mark each thread as seen with an 👀 reaction on its first comment (`databaseId` from the query), so
 the bot and a watching human can tell it is being worked:
 
@@ -93,7 +126,9 @@ gh api --method POST repos/{owner}/{repo}/pulls/comments/<DATABASE_ID>/reactions
 
 #### C. Check exit conditions
 
-Stop if there are zero unresolved CodeRabbit threads, or max iterations reached.
+Stop when step A's read exited `0` (`clean`) after your last push (a `--wait` read, which settles),
+or exited `30` (`limited`), or the iteration cap is reached. An empty working set on its own is not
+done: with no review of the current head yet, it only means CodeRabbit has not answered your push.
 
 #### D. Fix each finding
 
@@ -113,6 +148,7 @@ If step D changed code:
 git status --short                     # look before you stage
 git add <path> [<path>...]             # the files named in the findings you fixed
 git commit -m "address CodeRabbit review feedback (coderabbitloop iteration N)"
+SINCE=$(date -u +%Y-%m-%dT%H:%M:%SZ)   # step A reads bot activity after this
 git push
 ```
 
@@ -161,6 +197,18 @@ the reply, and a resolved thread with no reply loses the reasoning.
 
 Go back to step A.
 
+### Keep the context small; resume instead of restarting
+
+- Carry only three things between iterations: the iteration counter, the latest state JSON, and a
+  ledger of each thread you handled (fixed with its commit, rebutted, or blocked). Re-read files
+  fresh each iteration; do not re-paste earlier rounds' comment bodies.
+- All loop state lives on the PR, so the loop is resumable. If the session has grown long or slow,
+  or a bot commented after the loop ended, run this skill again in a fresh session: step A picks up
+  from the PR as it is now. Starting fresh is cheaper than dragging a long session through more
+  rounds.
+- After reporting done, if the host can schedule a follow-up (Claude Code: `/loop` or a scheduled
+  wakeup), offer one re-check about 20 minutes later for bots that comment late.
+
 ### 3. Report
 
 | Field              | Value |
@@ -169,6 +217,7 @@ Go back to step A.
 | Findings resolved  | N     |
 | Findings skipped   | N (with reasons) |
 | Remaining          | N (if any) |
+| Human threads      | N (open, listed; never resolved by this loop) |
 | Blocked            | rate-limited / timeout / max-iterations / none |
 
 ```

package/.windsurf/rules/codexloop.md

@@ -14,7 +14,8 @@ suggestion applied is worse than the comment itself.
 
 - **No check-run, no score.** Codex does not publish an `X/5` confidence or a named check. It posts
   a **PR review** (state `COMMENTED`) plus inline review comments. Detection is by polling the
-  *reviews* endpoint. "Satisfied" = zero unresolved comments (each either fixed or rebutted).
+  *reviews* endpoint. "Satisfied" = Codex has reviewed the latest push and no bot comment is left unresolved (each
+  either fixed or rebutted).
 - **Trigger phrase is `@codex review`.** Codex reviews automatically when a PR opens or gets new
   commits if auto-review is enabled on the repo; the mention forces a fresh pass. Other useful
   mentions: `@codex review focus on <area>` for a scoped re-review.
@@ -46,11 +47,32 @@ Pick the login matching `*codex*` (commonly `chatgpt-codex-connector[bot]`, some
 
 **Finding nothing here is NOT a stop condition.** On a PR Codex has never reviewed there is no bot
 login to find yet: that is the normal starting state, not a missing app. When the probe comes back
-empty, fall through to step 2A, post `@codex review`, and re-run this probe once a review lands;
+empty, fall through to step A, post `@codex review`, and re-run this probe once a review lands;
 until then match any login containing `codex` when polling. Only conclude the app is absent after
-step 2A's bounded wait has expired with no review and no codex-like login anywhere on the PR, and
+step A's bounded wait has expired with no review and no codex-like login anywhere on the PR, and
 then say so and stop, rather than looping against nothing.
 
+## Review state comes from the PR, not from memory
+
+`scripts/pr-review-state.sh` reads the PR and prints one JSON object: the current head, whether
+Codex has acted on that head (a review of it, or any comment after it was pushed), and every
+unresolved review thread with its author. Every "is there work / are we done" decision in this
+loop comes from its exit code, never from what you remember resolving. The script lives in this
+skill's directory, `SKILL_ROOT`: the directory holding this `SKILL.md` (Claude Code prints it as the
+skill's base directory when the skill loads; in Codex, derive it from the selected `SKILL.md` path).
+
+| Exit | `verdict`  | Meaning                                                             | Do                                   |
+|------|------------|---------------------------------------------------------------------|--------------------------------------|
+| 0    | `clean`    | Codex acted on the current head and no bot thread is unresolved    | exit check: done                     |
+| 10   | `findings` | unresolved threads from Codex **or any other review bot**          | run an iteration                     |
+| 20   | `pending`  | Codex has not acted on the current head yet                        | trigger if needed, then wait         |
+| 30   | `limited`  | a rate-limit or paused notice from Codex after the current head    | stop, report `blocked: rate-limited` |
+
+Resolving the last thread does not make a PR clean: Codex has not reviewed your push yet. Earlier
+versions of this loop exited at exactly that moment, while the next round of comments was still on
+its way. Human threads are listed in `.unresolved` (`is_bot: false`) and counted in `.counts.humans`;
+they never block `clean`, and this loop never resolves them.
+
 ## 1. Identify the PR
 
 ```bash
@@ -71,66 +93,50 @@ Keep an explicit iteration counter and stop at 5: the cap is a real bound to enf
 figure of speech. Each pass through A–G is one iteration; on hitting the cap, go straight to the
 report and list what is still unresolved rather than starting a sixth.
 
-### A. Ensure a fresh Codex review on the current head
-
-```bash
-HEAD_SHA=$(gh pr view <PR> --json headRefOid -q .headRefOid)
-# Only trigger if no Codex review already exists for this exact SHA.
-# gh cannot combine --slurp with --jq, so pipe to `jq -s`: it folds every page
-# into one array. Without it the filter runs once per page and HAVE becomes a
-# multi-line count that never equals "0", silently skipping the trigger.
-HAVE=$(gh api repos/{owner}/{repo}/pulls/<PR>/reviews --paginate |
-  jq -s --arg bot "$BOT" --arg head "$HEAD_SHA" \
-    '[.[][] | select(.user.login==$bot and .commit_id==$head)] | length')
-if [ "$HAVE" = "0" ]; then gh pr comment <PR> --body "@codex review"; fi
-```
+### A. Read the PR state; wait for Codex's review of the current head
 
-Poll for the review of THIS head to land. No check-run exists, so poll the reviews endpoint, and
-poll it on a **deadline**, never `while true`: a review that never arrives must end the skill with
-an honest timeout, not hang it.
+One read answers both "is there work?" and "has Codex seen my last push?". `SINCE` is the
+timestamp you took right before your last push (step E); leave it empty on iteration 1. Right
+after a push, add `--wait 600` straight away: the wait ends only once the bot has acted on the new
+head, so threads left open on purpose cannot make the push look reviewed.
 
 ```bash
-# 10-minute deadline, one retry, then give up. DEADLINE/RETRIES are the
-# enforcement of the bounds this skill claims: do not drop them.
-wait_for_review() {                       # $1 = attempt label
-  local deadline=$(( SECONDS + 600 ))
-  while [ "$SECONDS" -lt "$deadline" ]; do
-    R=$(gh api repos/{owner}/{repo}/pulls/<PR>/reviews --paginate |
-      jq -s --arg bot "$BOT" --arg head "$HEAD_SHA" \
-        '[.[][] | select(.user.login==$bot and .commit_id==$head)] | sort_by(.submitted_at, .id) | last')
-    if [ -n "$R" ] && [ "$R" != "null" ]; then return 0; fi
-    echo "waiting for Codex review of $HEAD_SHA ($1)..."; sleep 15
-  done
-  return 1
-}
-
-if ! wait_for_review "first wait"; then
-  echo "no Codex review after 10m, retrying once"     # say the retry out loud
-  gh pr comment <PR> --body "@codex review"
-  if ! wait_for_review "after retry"; then
-    echo "Codex did not review $HEAD_SHA after a retry; stopping and reporting."
-    exit 1                                # honest timeout, never a success claim
-  fi
-fi
+"$SKILL_ROOT/scripts/pr-review-state.sh" --repo OWNER/REPO --pr <PR> --bot codex --since "$SINCE"
 ```
 
-Codex can take several minutes on a large diff, which is why the deadline is generous. Report the
-retry in the final summary; two silent timeouts are the failure mode this guard exists to prevent.
+- Exit `10` (`findings`): go to B. On iteration 1 this is whatever Codex (or another bot)
+  already posted.
+- Exit `20` (`pending`): post `@codex review` (`gh pr comment <PR> --body "@codex review"`). Then wait with the same command plus `--wait 600`. Run the
+  wait in the background where the host allows it (Claude Code: Bash `run_in_background`; you are
+  re-invoked when it exits) so ten minutes of polling never sits in the conversation. Still `20`
+  after the wait: say so out loud, post `@codex review` once more, and wait once more. Still `20` after that: stop and
+  report the timeout honestly; never claim success.
+- Exit `0` (`clean`): go to the exit check. A `--wait` call returns `clean` only after a settle
+  re-read 60 seconds later, so a comment landing right behind the review is still caught. A bare
+  read (no `--wait`) that says `clean` is good enough only when you have not pushed since Codex's
+  last review.
+- Exit `30` (`limited`): stop now and report `blocked: rate-limited`; nothing more is coming.
+- Exit `1`: the read itself failed (often a transient GitHub 502). Retry once; if it fails again,
+  stop and report it. An unknown state is not a clean one.
 
 ### B. Fetch the findings
 
-- **Summary**: the review `.body` from the object above: read the overall take and the priority
+The working set is every unresolved thread in the state JSON with `is_bot: true`: Codex's
+own (`is_target: true`) **and any other review bot's** (Greptile, for example). A
+fix for one bot often draws a comment from another, and leaving those open is how a "finished" loop
+leaves a PR that is not clean. Treat another bot's thread with exactly the same verify-first rules
+below. Never act on a human's thread (`is_bot: false`); list it in the report.
+
+- **Summary**: the latest review `.body` from this bot (`gh pr view <PR> --json reviews`): read the overall take and the priority
   spread.
-- **Unresolved inline comments** on the current head:
+- **Unresolved inline comments**: `.unresolved[] | select(.is_bot)` in step A's state JSON lists
+  each thread's `thread_id`, `comment_id`, `path`, `line` and a short excerpt, across every page of
+  threads. Read the full comment before judging it:
 
 ```bash
-gh api repos/{owner}/{repo}/pulls/<PR>/comments --paginate \
-  --jq ".[] | select(.user.login==\"$BOT\") | {id, path, line, body}"
+gh api repos/{owner}/{repo}/pulls/comments/<COMMENT_ID> --jq '{user: .user.login, path, line, body}'
 ```
 
-Also pull the review threads + their resolved state via GraphQL (see step F) so you only act on
-unresolved ones.
-
 Mark each unresolved comment as seen, so the bot and a watching human can tell it is being handled.
 GitHub's reaction set is fixed; `eyes` is the only "looking at it" value:
 
@@ -187,6 +193,7 @@ If step D changed code:
 git status --short                     # look before you stage
 git add <path> [<path>...]             # the files named in the findings you fixed
 git commit -m "address codex review feedback (codexloop iteration N)"
+SINCE=$(date -u +%Y-%m-%dT%H:%M:%SZ)   # step A reads bot activity after this
 git push
 ```
 
@@ -206,31 +213,8 @@ to and resolved without a push.
 
 ### F. Reply to and resolve every addressed thread
 
-Only now, with the fixes pushed, reply and resolve. Fetch unresolved threads, **following
-pagination**: a PR with more than 100 threads will otherwise look clean while unresolved findings
-sit on page two:
-
-```bash
-# Loop until hasNextPage is false, passing endCursor back in as $cursor.
-CURSOR=null
-while : ; do
-  PAGE=$(gh api graphql -F cursor="$CURSOR" -f query='
-  query($cursor: String) {
-    repository(owner: "OWNER", name: "REPO") {
-      pullRequest(number: PR_NUMBER) {
-        reviewThreads(first: 100, after: $cursor) {
-          pageInfo { hasNextPage endCursor }
-          nodes { id isResolved comments(first: 1) { nodes { databaseId author { login } path body } } }
-        }
-      }
-    }
-  }')
-  echo "$PAGE"          # collect nodes from every page before deciding the PR is clean
-  PI='.data.repository.pullRequest.reviewThreads.pageInfo'
-  [ "$(echo "$PAGE" | jq -r "$PI.hasNextPage")" = "true" ] || break
-  CURSOR=$(echo "$PAGE" | jq -r "$PI.endCursor")
-done
-```
+Only now, with the fixes pushed, reply and resolve. Take thread and comment ids from step A's state
+JSON (`.unresolved[]`): the script already follows pagination, so do not hand-roll a threads query.
 
 Reply on a thread's comment via `gh api repos/{owner}/{repo}/pulls/<PR>/comments -f body="..." -F in_reply_to=<comment_id>`,
 then resolve:
@@ -254,7 +238,8 @@ gh api --method POST repos/{owner}/{repo}/pulls/comments/<COMMENT_ID>/reactions
 Reply first, then react, then resolve: the reaction is not a substitute for the reply, and a
 resolved thread with no reply loses the reasoning.
 
-Resolve a thread only for comments authored by `$BOT` that you have fixed or rebutted: never
+Resolve a thread only for a bot comment in your working set (this bot's or another
+review bot's) that you have fixed or rebutted: never
 blanket-resolve, and never resolve a human reviewer's thread. For each fixed comment, verify the
 push first, reply with the change made, then resolve the thread and verify `isResolved: true`.
 For each rebutted comment, reply with the evidence and verify resolution. Do not report a comment
@@ -263,19 +248,34 @@ as fixed or rebutted until its thread is confirmed resolved.
 Threads you are **rebutting** need no push, so they may be replied to and resolved regardless of
 whether step D changed code.
 
-### G. Re-review
+### G. Back to A
 
-Pushing re-triggers Codex when auto-review is on; otherwise post `@codex review`. Go back to **A**
-with the new head SHA. If step D changed nothing (all comments were rebutted), skip the push,
-ensure all threads are resolved, and exit.
+Go back to **A**. After a push, A waits for Codex's review of the new head (pushing re-triggers
+it when auto-review is on; otherwise A triggers it). If this iteration changed no code (every finding
+rebutted), there is no new head to wait for: A's fresh read says `clean` or shows what is still open.
 
 ## 3. Exit conditions
 
+Decide from a fresh state read, never from what you remember resolving.
+
 Stop when **any** is true:
-- Zero unresolved `$BOT` comments remain, and every comment this round was fixed or
-  rebutted+resolved. (There is no score to hit: this is "done".)
-- Max iterations (5) reached: report what remains.
-- Codex never responded after one retry: report the timeout honestly; do not claim success.
+- **Done**: the latest `pr-review-state.sh --wait 600` call, made after your last push, exited `0`
+  (`clean`); with no push since the bot's last review, a bare read that exits `0` is enough. Open human threads do not block this; list them in the report.
+- **Max iterations (5)** reached: report what remains.
+- **Timeout**: still `pending` after the retry in step A. Report it honestly; do not claim success.
+- **Rate limited**: exit `30`. Report `blocked: rate-limited`.
+
+## Keep the context small; resume instead of restarting
+
+- Carry only three things between iterations: the iteration counter, the latest state JSON, and a
+  ledger of each thread you handled (fixed with its commit, rebutted, or blocked). Re-read files
+  fresh each iteration; do not re-paste earlier rounds' comment bodies.
+- All loop state lives on the PR, so the loop is resumable. If the session has grown long or slow,
+  or a bot commented after the loop ended, run this skill again in a fresh session: step A picks up
+  from the PR as it is now. Starting fresh is cheaper than dragging a long session through more
+  rounds.
+- After reporting done, if the host can schedule a follow-up (Claude Code: `/loop` or a scheduled
+  wakeup), offer one re-check about 20 minutes later for bots that comment late.
 
 ## 4. Report
 
@@ -286,7 +286,9 @@ Codexloop complete.
   Iterations:         N
   Comments fixed:     N   (genuinely-correct findings)
   Comments rebutted:  N   (false positives / nits, resolved with rationale)
-  Remaining:          0
+  Remaining:          N   (bot threads still open)
+  Human threads:      N   (open, listed below; this loop never resolves them)
+  Final state:        clean | timeout | rate-limited | iteration cap
 ```
 
 If it stopped at max iterations, list the remaining threads with your current assessment