@openhands/extensions 0.24.0 → 0.25.0

package/skills/github-delivery-watchdog/scripts/github_client.py

@@ -165,6 +165,122 @@ class GitHubRepository:
             result.setdefault(item["context"], item["state"])
         return result
 
+    def check_runs(self, sha):
+        """Return every check run GitHub reported for one commit SHA.
+
+        Reading check runs needs no branch-protection or ruleset access, so this
+        is the head-eligibility signal the automation's own token can always
+        see. The endpoint answers with an object rather than a list, so it
+        paginates through ``gh`` instead of ``gh_pages``.
+        """
+        runs = []
+        for page in range(1, 101):
+            data = self.gh(
+                "GET", f"/commits/{sha}/check-runs?per_page=100&page={page}"
+            )
+            batch = data.get("check_runs") or []
+            runs.extend(batch)
+            if len(runs) >= int(data.get("total_count") or 0) or not batch:
+                return runs
+        raise RuntimeError("GitHub check-run pagination exceeded limit")
+
+    def required_check_contexts(self, number):
+        """Return the status contexts GitHub marks required on one pull request.
+
+        `isRequired` is the merge-policy source of truth and is PR-scoped, so it
+        is correct for a stacked PR whose symbolic base branch carries no branch
+        rules of its own. It is a field on each context in the head's status
+        check rollup and takes the pull request number, so a single GraphQL query
+        answers with the required check runs and any required commit statuses,
+        each already attributed to the exact head. Only contexts GitHub itself
+        reports as required are returned, so an optional workflow that fails
+        before creating any check run is not present.
+        """
+        owner, name = self.repository.split("/", 1)
+        query = (
+            "query($owner:String!,$name:String!,$number:Int!){"
+            "repository(owner:$owner,name:$name){"
+            "pullRequest(number:$number){"
+            "commits(last:1){"
+            "nodes{"
+            "commit{"
+            "statusCheckRollup{"
+            "contexts(first:100){"
+            "pageInfo{hasNextPage}"
+            "nodes{"
+            "__typename"
+            " ... on CheckRun{name isRequired(pullRequestNumber:$number)}"
+            " ... on StatusContext{context isRequired(pullRequestNumber:$number)}"
+            "}"
+            "}"
+            "}"
+            "}"
+            "}"
+            "}"
+            "}"
+            "}"
+            "}"
+        )
+        data = self.api(
+            "POST",
+            "/graphql",
+            body={
+                "query": query,
+                "variables": {"owner": owner, "name": name, "number": number},
+            },
+        )
+        if data.get("errors"):
+            raise RuntimeError(
+                f"GitHub required-check query failed: {data['errors'][0].get('message')}"
+            )
+        nodes = (
+            (((data.get("data") or {}).get("repository") or {}).get("pullRequest") or {})
+            .get("commits", {})
+            .get("nodes")
+        ) or []
+        contexts = (
+            ((nodes[0].get("commit") or {}).get("statusCheckRollup") or {}).get(
+                "contexts", {}
+            )
+            if nodes
+            else {}
+        )
+        if (contexts.get("pageInfo") or {}).get("hasNextPage"):
+            raise RuntimeError(
+                "GitHub required-check rollup exceeds one page; the required "
+                "set may be incomplete"
+            )
+        return [
+            {
+                "name": node.get("name") or node.get("context"),
+                "kind": node.get("__typename"),
+            }
+            for node in (contexts.get("nodes") or [])
+            if node.get("isRequired") and (node.get("name") or node.get("context"))
+        ]
+
+    def workflow_runs(self, sha):
+        """Return every Actions workflow run GitHub reported for one commit SHA.
+
+        A workflow that fails before any job starts - a workflow-level error, or
+        a `pull_request` run whose jobs never materialize - still records a
+        failed check suite, but it contributes no check runs, so the commit's
+        check-run rollup and `gh pr checks` both report success. Reading the
+        workflow runs directly is the only way the gate can see that failure.
+        Like the check-run endpoint this answers with an object, so it paginates
+        manually.
+        """
+        runs = []
+        for page in range(1, 101):
+            data = self.gh(
+                "GET", f"/actions/runs?head_sha={sha}&per_page=100&page={page}"
+            )
+            batch = data.get("workflow_runs") or []
+            runs.extend(batch)
+            if len(runs) >= int(data.get("total_count") or 0) or not batch:
+                return runs
+        raise RuntimeError("GitHub workflow-run pagination exceeded limit")
+
     def completed_dependency(self, number):
         if number in self._completed_dependencies:
             return self._completed_dependencies[number]

package/skills/github-issue-to-pr/scripts/github_client.py

@@ -165,6 +165,122 @@ class GitHubRepository:
             result.setdefault(item["context"], item["state"])
         return result
 
+    def check_runs(self, sha):
+        """Return every check run GitHub reported for one commit SHA.
+
+        Reading check runs needs no branch-protection or ruleset access, so this
+        is the head-eligibility signal the automation's own token can always
+        see. The endpoint answers with an object rather than a list, so it
+        paginates through ``gh`` instead of ``gh_pages``.
+        """
+        runs = []
+        for page in range(1, 101):
+            data = self.gh(
+                "GET", f"/commits/{sha}/check-runs?per_page=100&page={page}"
+            )
+            batch = data.get("check_runs") or []
+            runs.extend(batch)
+            if len(runs) >= int(data.get("total_count") or 0) or not batch:
+                return runs
+        raise RuntimeError("GitHub check-run pagination exceeded limit")
+
+    def required_check_contexts(self, number):
+        """Return the status contexts GitHub marks required on one pull request.
+
+        `isRequired` is the merge-policy source of truth and is PR-scoped, so it
+        is correct for a stacked PR whose symbolic base branch carries no branch
+        rules of its own. It is a field on each context in the head's status
+        check rollup and takes the pull request number, so a single GraphQL query
+        answers with the required check runs and any required commit statuses,
+        each already attributed to the exact head. Only contexts GitHub itself
+        reports as required are returned, so an optional workflow that fails
+        before creating any check run is not present.
+        """
+        owner, name = self.repository.split("/", 1)
+        query = (
+            "query($owner:String!,$name:String!,$number:Int!){"
+            "repository(owner:$owner,name:$name){"
+            "pullRequest(number:$number){"
+            "commits(last:1){"
+            "nodes{"
+            "commit{"
+            "statusCheckRollup{"
+            "contexts(first:100){"
+            "pageInfo{hasNextPage}"
+            "nodes{"
+            "__typename"
+            " ... on CheckRun{name isRequired(pullRequestNumber:$number)}"
+            " ... on StatusContext{context isRequired(pullRequestNumber:$number)}"
+            "}"
+            "}"
+            "}"
+            "}"
+            "}"
+            "}"
+            "}"
+            "}"
+            "}"
+        )
+        data = self.api(
+            "POST",
+            "/graphql",
+            body={
+                "query": query,
+                "variables": {"owner": owner, "name": name, "number": number},
+            },
+        )
+        if data.get("errors"):
+            raise RuntimeError(
+                f"GitHub required-check query failed: {data['errors'][0].get('message')}"
+            )
+        nodes = (
+            (((data.get("data") or {}).get("repository") or {}).get("pullRequest") or {})
+            .get("commits", {})
+            .get("nodes")
+        ) or []
+        contexts = (
+            ((nodes[0].get("commit") or {}).get("statusCheckRollup") or {}).get(
+                "contexts", {}
+            )
+            if nodes
+            else {}
+        )
+        if (contexts.get("pageInfo") or {}).get("hasNextPage"):
+            raise RuntimeError(
+                "GitHub required-check rollup exceeds one page; the required "
+                "set may be incomplete"
+            )
+        return [
+            {
+                "name": node.get("name") or node.get("context"),
+                "kind": node.get("__typename"),
+            }
+            for node in (contexts.get("nodes") or [])
+            if node.get("isRequired") and (node.get("name") or node.get("context"))
+        ]
+
+    def workflow_runs(self, sha):
+        """Return every Actions workflow run GitHub reported for one commit SHA.
+
+        A workflow that fails before any job starts - a workflow-level error, or
+        a `pull_request` run whose jobs never materialize - still records a
+        failed check suite, but it contributes no check runs, so the commit's
+        check-run rollup and `gh pr checks` both report success. Reading the
+        workflow runs directly is the only way the gate can see that failure.
+        Like the check-run endpoint this answers with an object, so it paginates
+        manually.
+        """
+        runs = []
+        for page in range(1, 101):
+            data = self.gh(
+                "GET", f"/actions/runs?head_sha={sha}&per_page=100&page={page}"
+            )
+            batch = data.get("workflow_runs") or []
+            runs.extend(batch)
+            if len(runs) >= int(data.get("total_count") or 0) or not batch:
+                return runs
+        raise RuntimeError("GitHub workflow-run pagination exceeded limit")
+
     def completed_dependency(self, number):
         if number in self._completed_dependencies:
             return self._completed_dependencies[number]

package/skills/github-issue-triage/scripts/github_client.py

@@ -165,6 +165,122 @@ class GitHubRepository:
             result.setdefault(item["context"], item["state"])
         return result
 
+    def check_runs(self, sha):
+        """Return every check run GitHub reported for one commit SHA.
+
+        Reading check runs needs no branch-protection or ruleset access, so this
+        is the head-eligibility signal the automation's own token can always
+        see. The endpoint answers with an object rather than a list, so it
+        paginates through ``gh`` instead of ``gh_pages``.
+        """
+        runs = []
+        for page in range(1, 101):
+            data = self.gh(
+                "GET", f"/commits/{sha}/check-runs?per_page=100&page={page}"
+            )
+            batch = data.get("check_runs") or []
+            runs.extend(batch)
+            if len(runs) >= int(data.get("total_count") or 0) or not batch:
+                return runs
+        raise RuntimeError("GitHub check-run pagination exceeded limit")
+
+    def required_check_contexts(self, number):
+        """Return the status contexts GitHub marks required on one pull request.
+
+        `isRequired` is the merge-policy source of truth and is PR-scoped, so it
+        is correct for a stacked PR whose symbolic base branch carries no branch
+        rules of its own. It is a field on each context in the head's status
+        check rollup and takes the pull request number, so a single GraphQL query
+        answers with the required check runs and any required commit statuses,
+        each already attributed to the exact head. Only contexts GitHub itself
+        reports as required are returned, so an optional workflow that fails
+        before creating any check run is not present.
+        """
+        owner, name = self.repository.split("/", 1)
+        query = (
+            "query($owner:String!,$name:String!,$number:Int!){"
+            "repository(owner:$owner,name:$name){"
+            "pullRequest(number:$number){"
+            "commits(last:1){"
+            "nodes{"
+            "commit{"
+            "statusCheckRollup{"
+            "contexts(first:100){"
+            "pageInfo{hasNextPage}"
+            "nodes{"
+            "__typename"
+            " ... on CheckRun{name isRequired(pullRequestNumber:$number)}"
+            " ... on StatusContext{context isRequired(pullRequestNumber:$number)}"
+            "}"
+            "}"
+            "}"
+            "}"
+            "}"
+            "}"
+            "}"
+            "}"
+            "}"
+        )
+        data = self.api(
+            "POST",
+            "/graphql",
+            body={
+                "query": query,
+                "variables": {"owner": owner, "name": name, "number": number},
+            },
+        )
+        if data.get("errors"):
+            raise RuntimeError(
+                f"GitHub required-check query failed: {data['errors'][0].get('message')}"
+            )
+        nodes = (
+            (((data.get("data") or {}).get("repository") or {}).get("pullRequest") or {})
+            .get("commits", {})
+            .get("nodes")
+        ) or []
+        contexts = (
+            ((nodes[0].get("commit") or {}).get("statusCheckRollup") or {}).get(
+                "contexts", {}
+            )
+            if nodes
+            else {}
+        )
+        if (contexts.get("pageInfo") or {}).get("hasNextPage"):
+            raise RuntimeError(
+                "GitHub required-check rollup exceeds one page; the required "
+                "set may be incomplete"
+            )
+        return [
+            {
+                "name": node.get("name") or node.get("context"),
+                "kind": node.get("__typename"),
+            }
+            for node in (contexts.get("nodes") or [])
+            if node.get("isRequired") and (node.get("name") or node.get("context"))
+        ]
+
+    def workflow_runs(self, sha):
+        """Return every Actions workflow run GitHub reported for one commit SHA.
+
+        A workflow that fails before any job starts - a workflow-level error, or
+        a `pull_request` run whose jobs never materialize - still records a
+        failed check suite, but it contributes no check runs, so the commit's
+        check-run rollup and `gh pr checks` both report success. Reading the
+        workflow runs directly is the only way the gate can see that failure.
+        Like the check-run endpoint this answers with an object, so it paginates
+        manually.
+        """
+        runs = []
+        for page in range(1, 101):
+            data = self.gh(
+                "GET", f"/actions/runs?head_sha={sha}&per_page=100&page={page}"
+            )
+            batch = data.get("workflow_runs") or []
+            runs.extend(batch)
+            if len(runs) >= int(data.get("total_count") or 0) or not batch:
+                return runs
+        raise RuntimeError("GitHub workflow-run pagination exceeded limit")
+
     def completed_dependency(self, number):
         if number in self._completed_dependencies:
             return self._completed_dependencies[number]

package/skills/github-pr-review/SKILL.md

@@ -57,12 +57,22 @@ gh api -X POST repos/{owner}/{repo}/pulls/{pr_number}/reviews --input /tmp/revie
 | Parameter | Description |
 |-----------|-------------|
 | `commit_id` | Commit SHA to comment on (use `git rev-parse HEAD`) |
-| `event` | `COMMENT`, `APPROVE`, or `REQUEST_CHANGES` |
+| `event` | `APPROVE`, `COMMENT`, or `REQUEST_CHANGES` (see below) |
 | `path` | File path as shown in the diff |
 | `line` | Line number in the NEW version (right side of diff) |
 | `side` | `RIGHT` for new/added lines, `LEFT` for deleted lines |
 | `body` | Comment text with priority label |
 
+### Choosing the `event` Value
+
+| Event | When to use |
+|-------|-------------|
+| `APPROVE` | No issues found, or only 🟡 suggestions that are non-blocking |
+| `COMMENT` | You have 🟠 Important feedback but it's not a hard blocker |
+| `REQUEST_CHANGES` | There are 🔴 Critical issues that **must** be fixed before merge |
+
+**Default to `APPROVE`** when the code is correct and merge-ready. Use `COMMENT` or `REQUEST_CHANGES` only when there are actionable issues that warrant it.
+
 ### Multi-Line Comments
 
 For comments spanning multiple lines, add `start_line` to specify the range:
@@ -184,4 +194,4 @@ curl -X POST \
 5. Do NOT post comments for code that is acceptable — only comment when action is needed
 6. Use suggestion syntax for concrete code changes, but only after verifying the resulting code matches your description (see "How Suggestions Actually Work")
 7. Keep the review body brief (details go in inline comments)
-8. If no issues: post a short approval message with no inline comments
+8. If no issues: use `"event": "APPROVE"` with a short approval message and no inline comments

package/skills/github-pr-reviewer/README.md

@@ -12,7 +12,42 @@ This skill is activated by:
 ## Features
 
 - Reviews PRs on demand from a GitHub reviewer request or label event
+- Gates each scheduled review on the current head's GitHub-required checks
+  before starting an agent, read through the `isRequired` signal, so an optional
+  workflow that fails cannot block a mergeable head: a completed `failure`,
+  `cancelled`, or `timed_out` required check blocks the review, and a `queued`,
+  `in_progress`, or not-yet-reported required check exits with a clear
+  waiting-on-checks outcome instead of holding a slot. If the required-check
+  signal is unavailable the gate falls back to every current-head check run and
+  workflow run, including a workflow that fails before creating any check run
+- Dispatches an explicit `all-hands-bot` review request even when required CI is
+  red or pending; the CI gate applies to scheduled discovery
+- Ignores checks and workflow runs recorded for an obsolete head, so a stale
+  failure cannot block the push that fixed it
+- Resumes an outstanding reviewer request on the next scheduled scan once the
+  requested head's checks are green, so a request that arrives during CI is not
+  lost; the explicit-request event path is kept for event-only deployments
+- Reviews open, non-draft PRs that nobody requested on a scheduled scan once
+  their current head is green and carries no review yet, keyed by
+  repository/PR/head so a repeat scan never duplicates a conversation or review
+  and a changed head becomes eligible again
+- Examines a bounded, rotating window of that unrequested backlog per scan
+  (10 PRs per repository), remembering its position in the Automation KV store so
+  the next scan resumes past it; explicit requests and trigger labels are always
+  examined, never skipped behind the window
+- Posts no managed gate comment for an unrequested PR that is merely red or
+  pending - the comment answers an explicit request, so a scan over a large
+  backlog cannot storm the PRs with comments
+- Names the retry the deployment actually has in the waiting comment: a
+  scheduled scan where a cron trigger exists, and removing and re-requesting the
+  bot where only the event trigger does
+- Rewrites its own managed gate comment in place when the retry wording changes,
+  so switching a deployment from the event trigger to a cron scan updates the
+  outstanding-request explanation instead of leaving the old instruction
 - Watches several repositories from a single automation, each with its own state
+- Bounds a scheduled scan to a small, configurable number of new review
+  conversations across all repositories (default 2), draining the oldest
+  outstanding reviewer requests first and reaching the rest on later scans
 - Processes each review request or label application idempotently
 - Supports re-review by requesting the bot again or re-applying the label. Each
   explicit request refreshes mutable GitHub state (head, PR body, reviews,

package/skills/github-pr-reviewer/SKILL.md

@@ -25,9 +25,110 @@ once per label event, and publishes the AI review to GitHub.
 Windows PowerShell equivalents for the setup, packaging, upload, and API-check shell snippets are in `references/windows.md`.
 
 The automation script is deterministic: PR discovery, label-event tracking,
-state persistence, stale-result suppression, the repository checkout, and its
-removal are all handled in Python. The LLM is invoked only for the review
-itself.
+head eligibility, state persistence, stale-result suppression, the repository
+checkout, and its removal are all handled in Python. The LLM is invoked only for
+the review itself.
+
+Before any review conversation is created, a scheduled scan evaluates the
+current head's GitHub-required checks, read through the GraphQL `isRequired`
+signal for the pull request. That signal is the merge policy's own source of
+truth and is pull-request-scoped, so it stays correct for a stacked PR whose
+symbolic base branch carries no branch rules of its own:
+
+- Only checks GitHub reports as required decide the scheduled gate. An optional
+  workflow that fails - including one that fails before creating any check run -
+  does not block a head whose required checks pass.
+- A completed required run on the exact head whose conclusion is `failure`,
+  `cancelled`, or `timed_out` blocks the review. Any other unrecognized
+  conclusion fails closed as a block rather than silently approving.
+- A completed required run whose conclusion is `success`, `neutral`, or
+  `skipped` does not block. A required `commit status` context is classified
+  alongside required check runs.
+- A `queued` or `in_progress` required run on the exact head, and a required
+  context that has not reported a current-head check run at all, make the run
+  exit with a **waiting on checks** outcome. Unfulfilled is never approval. The
+  worker does not hold a slot polling; the next scheduled scan or explicit
+  review request retries.
+- When the required-check signal cannot be read or is empty, the gate falls back
+  to every current-head check run and workflow run, so a red head still blocks.
+  In that fallback, workflow runs are read as well as check runs, because a
+  workflow can fail before creating any check run - a workflow-level error, or a
+  `pull_request` run whose jobs never start. Such a run leaves a failed check
+  suite with no check runs under it, so the commit's check-run rollup and
+  `gh pr checks` both report success and only the workflow run reveals the red
+  CI. A workflow run whose check suite already reported check runs is left to
+  those runs, so a workflow is never counted twice.
+- A scheduled scan considers the trigger label **and** every open, non-draft PR
+  that still holds an outstanding `all-hands-bot` review request. That is what
+  resumes a request made while CI was running: the request is keyed by its own
+  `review_requested` event, so repeated scans reuse one conversation and one
+  review instead of creating duplicates, and a PR whose request was answered or
+  withdrawn simply drops out of `requested_reviewers`.
+- The scheduled scan also reviews open, non-draft PRs that **nobody requested**
+  and that carry no trigger label, once their current head has no completed
+  review by this account. That is what keeps reviewing PRs after the outstanding
+  requests are exhausted. The delivery key is the stable
+  `scan:{repository}:{number}:{head}`, so repeated scans reuse one conversation
+  and one native review, and a changed head becomes eligible again under its new
+  SHA.
+- The unrequested part of a scan is a **bounded, rotating window**, not the whole
+  backlog. Classifying one unrequested head costs a review read plus the
+  exact-head check and workflow reads, so examining every open PR in one scan
+  spent the run's API budget in the largest repository and announced every red or
+  pending head. A scan examines at most `SCAN_WINDOW` (10) unrequested PRs per
+  repository and stores where the window ended in the automation service's own
+  KV store, under a per-repository `review-scan:{owner}__{repo}` key, so the next
+  scan resumes past that point and the backlog is covered fairly over several
+  scans. The window wraps at the end of the backlog. When the KV store is not
+  available (a local run) the position is kept in memory, so the scan still
+  rotates within the run.
+- An explicit `all-hands-bot` review request or a trigger label is **never**
+  subject to the window: every explicit candidate is examined on every scan,
+  whatever the stored position is, so a request is not delayed behind the
+  rotation.
+- A gate stop on an **unrequested** head posts no managed comment. A PR nobody
+  asked about that is merely red or pending is simply skipped without starting an
+  agent, which is what keeps a scan over a large backlog from posting a gate
+  comment on every PR. The managed comment is the answer to an explicit request,
+  so a requested or labeled head that is red or pending still gets its
+  explanation.
+- Workflow runs are read as well as check runs, because a workflow can fail
+  before creating any check run - a workflow-level error, or a `pull_request`
+  run whose jobs never start. Such a run leaves a failed check suite with no
+  check runs under it, so the commit's check-run rollup and `gh pr checks` both
+  report success and only the workflow run reveals the red CI. A workflow run
+  whose check suite already reported check runs is left to those runs, so a
+  workflow is never counted twice.
+- Runs attributed to any other (obsolete) head SHA are ignored, so a stale
+  failure cannot block the push that fixed it. This applies to workflow runs
+  too.
+- Only the latest run of each logical check or workflow counts. A logical check
+  is its name plus the reporting app identity, and a logical workflow is its
+  name plus workflow ID. The latest is chosen by the run ID (the reliable
+  creation sequence) with the start time as a tie-break, so a re-run that fixed
+  a check supersedes its earlier failure on the same SHA while a newer queued or
+  in-progress re-run supersedes an earlier success and makes the head wait.
+  Ordering by the run ID keeps a run whose start time is still absent in its
+  true creation position in both directions.
+
+An explicit `all-hands-bot` review request is the intake-policy exception: the
+caller asked for that head by name, so the request dispatches even when required
+CI is red or pending, and the gate leaves no explanatory comment. Draft, scope,
+exact-head, and delivery-deduplication safeguards still apply. A blocked or
+waiting scheduled stop consumes no trigger: once the head's required checks are
+non-blocking, the scheduled scan, or a new `all-hands-bot` review request,
+starts the normal review.
+
+The gate needs no configured list of check names. When it stops a review it
+leaves one concise explanation on the PR, identified by a hidden marker carrying
+the head SHA and gate category, so a later run for a different head updates that
+comment instead of posting another. Only a marker this reviewer account authored
+counts as its own comment; every other PR comment is untrusted and can neither
+suppress the explanation nor be edited. If the repository's own workflow already
+posted a deterministic remediation comment that names the same current-head
+checks, the gate adds nothing; a disclosure about some other check does not
+suppress it. The gate applies to scheduled label scans; an explicit
+`all-hands-bot` review request bypasses it by design.
 
 Each explicit review request - a re-applied trigger label, or a new reviewer
 request in event mode - is a fresh review. The conversation for a PR is reused,
@@ -39,6 +140,52 @@ verdict, or label/priority claim that state no longer supports. Repository
 analysis the conversation already did, such as reading `AGENTS.md`, stays
 useful and is not repeated.
 
+The waiting and blocked explanations name the retry the deployment actually has.
+A scheduled run proves a scan is configured, so it says the next scan will
+retry. An event-only run does not, so it tells the reader to remove the
+outstanding `all-hands-bot` request and request `all-hands-bot` again instead of
+promising a scan that does not exist: GitHub will not accept a second request
+while the first is still outstanding.
+
+The gate leaves only one explanation per head. When the same head keeps the same
+hidden marker but the retry wording changes -- an event-only comment on a head
+whose automation is later switched to a cron scan -- the scheduled run rewrites
+that managed comment in place, so the comment always names the retry that is
+actually deployed, and an unchanged body is left untouched.
+
+## Bounded intake per scheduled scan
+
+A scheduled scan drains outstanding reviewer requests fairly, but starting an
+agent for every eligible pull request at once would overload the deployment, so
+the scan starts at most `MAX_NEW_PER_RUN` new review conversations, counted
+**across every configured repository** rather than per repository. The default
+is `2`, and the rendered `config.json` overrides it through the
+`max_new_per_run` key that `github-issue-to-pr` and `gitlab-issue-to-mr` already
+use.
+
+- Eligible candidates are ordered deterministically: an explicit `all-hands-bot`
+  request (or a trigger label) is ordered before an unrequested PR, then by the
+  oldest `all-hands-bot` `review_requested` event for a requested PR or the PR's
+  own creation time (oldest first) for an unrequested one, then by repository,
+  then by pull-request number, so the oldest work drains first and a later scan
+  reaches the remainder.
+- The bound counts the conversations a scan **starts**. A delivery that only
+  deduplicates or reports an already-running conversation reuses a runtime and
+  consumes no slot, so repeated scans make progress on the backlog instead of
+  re-spending the bound on work already in flight.
+- Reaching the bound never cuts the scan short. The scan still evaluates the
+  exact-head checks of the remaining candidates, reconciles completed reviews,
+  and runs the maintainer handoff. A candidate whose checks are pending or
+  failing starts no conversation and consumes no slot, so it cannot block a later
+  green candidate. Only an explicit request or a trigger label gets a waiting or
+  blocked gate comment; an unrequested head that is merely red or pending is
+  skipped silently.
+- A dispatch that raises is reported and does not consume a slot or abort the
+  scan, so the candidates behind it are still considered.
+- The explicit `review_requested` event path and the trigger-label scan are
+  unchanged: an explicit request still starts its conversation immediately, and
+  only the scheduled scan's new conversations are bounded.
+
 The review prompt starts with a scope gate: using the repository's own guidance
 (its scope categories and ownership boundaries, not a list of individual PR
 numbers), the reviewer decides whether the change belongs in this repository
@@ -176,7 +323,7 @@ Record as `CRON_SCHEDULE`.
 
 ### Step 6 - Generate the automation script
 
-Read `scripts/main.py` from this skill's directory. Apply exactly six constant
+Read `scripts/main.py` from this skill's directory. Apply exactly seven constant
 substitutions near the top of the file:
 
 > The script also reads a `config.json` shipped beside it, if there is one, over
@@ -192,6 +339,7 @@ substitutions near the top of the file:
 | `REVIEW_TONE = "thorough"` | `REVIEW_TONE = "{review_tone}"` |
 | `REVIEW_STYLE_INSTRUCTIONS = ""` | `REVIEW_STYLE_INSTRUCTIONS = "{style_instructions}"` |
 | `REPO_REVIEW_GUIDE_PATH = ".agents/skills/custom-codereview-guide.md"` | leave unchanged to auto-load a repo review guide at this path, or set to `""` to disable |
+| `MAX_NEW_PER_RUN = 2` | leave unchanged to bound a scheduled scan to two new review conversations across all repositories, or raise it if the deployment can hold more agents at once |
 | `DEFAULT_OPENHANDS_URL = "http://localhost:8000"` | leave unchanged unless the user has a preference |
 
 Use a safe string writer such as `json.dumps(value)` when inserting user-provided
@@ -348,6 +496,10 @@ The completion callback fires once for the whole run.
 | 404 on repo access | Repo name wrong or no access | Re-check the entry in `REPOS` and the token's permissions |
 | One repository is skipped, others work | That repository failed its access check | Read the `=== owner/repo ===` block in the run log |
 | Same PR not reviewed after new commits | Label event was already processed | Remove and re-apply the trigger label |
+| Review paused with a failing-check comment | A current-head required check reported `failure`, `cancelled`, or `timed_out` | Fix the named checks and push; the review starts on the new head, or request `all-hands-bot` to review immediately |
+| Review reported waiting on checks | A current-head required check is `queued` or `in_progress`, or has not reported yet | No action; a later scan or a new review request retries |
+| Optional workflow failed but no review was paused | The failed workflow is not required, so the required-only scheduled gate ignored it | No action; only GitHub-required checks gate scheduled discovery |
+| Only a few reviews start on a large backlog | The per-scan `max_new_per_run` bound (default 2) reached | No action; later scans drain the remaining oldest requests and the bounded rotating window of unrequested PRs, or raise `max_new_per_run` if the deployment can hold more agents |
 | Review result never posts | Conversation still running or stuck | Open the conversation link from the acknowledgement comment |
 | Stale review suppressed | PR head SHA changed while the agent was reviewing | Re-apply the trigger label after the latest commit |
 | Review arrives as a plain comment, not a review | Publishing failed, so the script posted the text as a fallback | Check that the token has Pull requests: Read and Write |

package/skills/github-pr-reviewer/references/state-schema.md

@@ -18,6 +18,21 @@ store under the key `state:{owner}__{repo}` — for example
 `AUTOMATION_KV_TOKEN` is injected into the run environment. Each automation has
 its own isolated namespace.
 
+The scheduled worker (`worker.py`) uses the same store for one more document, the
+**unrequested-scan cursor**, under the key `review-scan:{owner}__{repo}`:
+
+```json
+{ "cursor": 20 }
+```
+
+`cursor` is the position in the repository's unrequested-PR backlog at which the
+next scheduled scan's bounded window starts. Each scan examines at most
+`SCAN_WINDOW` (10) unrequested PRs from that position, then writes the position
+after the window, so successive scans rotate through the whole backlog instead of
+reading one pull request per open PR. A cursor past the end wraps to the start.
+This document is separate from `main.py`'s per-repository review state; a missing
+or unreadable cursor simply starts the window at the beginning.
+
 **Fallback (local/dev):** When the KV store is not available, the state is
 written to a local JSON file at: