@openhands/extensions 0.24.0 → 0.25.0

package/automations/catalog/github-pr-reviewer/manifest.json

@@ -1,9 +1,9 @@
 {
   "id": "github-pr-reviewer",
-  "version": "1.5.0",
+  "version": "1.8.0",
   "name": "GitHub code review",
   "category": "Code review",
-  "description": "Review requested pull-request heads, record exact-head decisions, stop early on out-of-scope changes, and optionally request a code-aware human maintainer after approval or a maintainer-decision scope stop.",
+  "description": "Review requested pull-request heads, resume an outstanding reviewer request on a schedule once its checks are green, review a bounded rotating window of open non-draft pull requests that nobody requested once their current head is green and unreviewed, drain the backlog oldest-first under a small per-scan new-conversation bound, record exact-head decisions, stop early on out-of-scope changes, and optionally request a code-aware human maintainer after approval or a maintainer-decision scope stop.",
   "requires": {
     "integrations": {},
     "features": [
@@ -13,7 +13,7 @@
   },
   "popularityRank": 100,
   "estimatedSetupMinutes": 4,
-  "exampleImplementation": "A scheduled label scan or GitHub reviewer-request event selects a PR head and submits an idempotent subject turn. The profile-backed agent clones that exact head in its runtime, applies an early repository-ownership and product/architecture scope gate, then reuses the established review workflow, runs appropriate tests, and publishes a readable native review. A native approval, or a maintainer-decision scope stop, can then be handed to a code-aware human maintainer.",
+  "exampleImplementation": "A scheduled scan of the trigger label, of open non-draft PRs holding an outstanding reviewer request, and of a bounded rotating window of open non-draft PRs nobody requested whose current head is green and unreviewed, or a GitHub reviewer-request event, selects a PR head and submits an idempotent subject turn. The unrequested window resumes from a per-repository position kept in the Automation KV store, so each scan reads a bounded number of pull requests while still covering the backlog over time, and explicit requests are always examined. The scheduled scan orders eligible heads with explicit requests first and then oldest-first, and starts at most a small configurable number of new conversations per scan across every repository. The profile-backed agent clones that exact head in its runtime, applies an early repository-ownership and product/architecture scope gate, then reuses the established review workflow, runs appropriate tests, and publishes a readable native review. A native approval, or a maintainer-decision scope stop, can then be handed to a code-aware human maintainer.",
   "impact": {
     "basis": "completed-runs",
     "one": "1 PR review sweep completed",
@@ -28,8 +28,8 @@
           "schedule": {
             "type": "cron",
             "label": "Check frequency",
-            "help": "How often to look for newly labelled pull requests.",
-            "default": "*/15 * * * *",
+            "help": "How often to look for newly labelled pull requests, outstanding reviewer requests whose checks have not yet finished, and open non-draft pull requests nobody requested that still need a review.",
+            "default": "*/5 * * * *",
             "required": true
           },
           "timezone": {
@@ -68,7 +68,7 @@
         "triggerLabel": {
           "type": "text",
           "label": "Trigger label",
-          "help": "Only pull requests carrying this label are reviewed.",
+          "help": "Pull requests carrying this label are reviewed. An open, non-draft pull request that nobody requested is also reviewed once its current head is green and carries no review yet, examined a bounded rotating window at a time so one scan reads only a slice of the backlog.",
           "default": "openhands-review",
           "required": true,
           "constraints": {
@@ -87,6 +87,16 @@
             "maxLength": 39
           }
         },
+        "maxNewPerRun": {
+          "type": "number",
+          "label": "New reviews per scan",
+          "help": "Most new review conversations one scheduled scan may start, counted across every repository. Keeps a first scan over a large backlog from starting an agent for every eligible pull request at once. Reviews that are already running are resumed without counting against it.",
+          "default": 2,
+          "required": true,
+          "constraints": {
+            "min": 1
+          }
+        },
         "reviewTone": {
           "type": "select",
           "label": "Review tone",
@@ -125,7 +135,7 @@
       }
     },
     "bundle": {
-      "version": "1.5.0",
+      "version": "1.8.0",
       "entrypoint": "python3 worker.py",
       "timeout": 300,
       "files": {
@@ -139,12 +149,13 @@
         "repos": "{{form.repositories}}",
         "trigger_label": "{{form.triggerLabel}}",
         "trigger_reviewer": "{{form.triggerReviewer}}",
+        "max_new_per_run": "{{form.maxNewPerRun}}",
         "review_tone": "{{form.reviewTone}}",
         "maintainers": "{{form.maintainers}}",
         "github_token_secret": "{{form.githubTokenSecret}}"
       }
     },
     "filter": "contains({{form.repositories}}, repository.full_name) && contains(keys(@), 'pull_request') && ((action == 'review_requested' && requested_reviewer.login == '{{form.triggerReviewer}}') || (action == 'submitted' && contains(keys(@), 'review') && review.user.login == '{{form.triggerReviewer}}'))",
-    "message": "Configure the repositories, trigger, review tone, optional maintainer roster, credential name, and agent profile."
+    "message": "Configure the repositories, trigger, review tone, optional maintainer roster, credential name, per-scan new-review bound, and agent profile."
   }
 }

package/automations/catalog/github-stale-ci-pr-closer/manifest.json

@@ -0,0 +1,71 @@
+{
+  "id": "github-stale-ci-pr-closer",
+  "version": "1.0.0",
+  "name": "GitHub stale CI cleanup",
+  "category": "Code review",
+  "description": "Warn and close abandoned pull requests whose required CI remains failing.",
+  "requires": {
+    "integrations": {},
+    "features": [
+      "customTarball"
+    ]
+  },
+  "estimatedSetupMinutes": 3,
+  "exampleImplementation": "A deterministic scheduled scan reads the required checks that apply to each pull request's base branch. It warns after seven days of observed failure and closes after seven more days only when the author has neither pushed nor commented.",
+  "setup": {
+    "version": "1.0",
+    "mode": "direct",
+    "form": {
+      "triggers": {
+        "cron": {
+          "schedule": {
+            "type": "cron",
+            "label": "Check frequency",
+            "help": "How often to reconcile failing pull requests.",
+            "default": "0 * * * *",
+            "required": true
+          },
+          "timezone": {
+            "type": "timezone",
+            "label": "Timezone",
+            "help": "Timezone for the schedule.",
+            "default": "UTC",
+            "required": true
+          }
+        }
+      },
+      "args": {
+        "repositories": {
+          "type": "repo-picker",
+          "provider": "github",
+          "multiple": true,
+          "label": "Repositories",
+          "help": "Repositories whose open pull requests should be maintained.",
+          "required": true
+        },
+        "githubTokenSecret": {
+          "type": "text",
+          "label": "GitHub token secret",
+          "help": "Name of a saved GitHub token with rules and CI read access plus issue and pull-request write access.",
+          "default": "GITHUB_TOKEN_REVIEW",
+          "required": true
+        }
+      }
+    },
+    "bundle": {
+      "version": "1.0.0",
+      "entrypoint": "python3 worker.py",
+      "timeout": 300,
+      "files": {
+        "worker.py": "skills/github-stale-ci-pr-closer/scripts/worker.py",
+        "github_client.py": "skills/github/scripts/github_client.py"
+      },
+      "config": {
+        "repos": "{{form.repositories}}",
+        "github_token_secret": "{{form.githubTokenSecret}}"
+      }
+    },
+    "message": "Configure the repositories, credential name, and schedule."
+  },
+  "popularityRank": 77
+}

package/automations/catalog-index.js

@@ -24,6 +24,7 @@ import entry18 from "./catalog/github-issue-triage/manifest.json" with { type: "
 import entry19 from "./catalog/upstream-fork-sync/manifest.json" with { type: "json" };
 import entry20 from "./catalog/incident-retrospective-drafter/manifest.json" with { type: "json" };
 import entry21 from "./catalog/news-digest/manifest.json" with { type: "json" };
+import entry22 from "./catalog/github-stale-ci-pr-closer/manifest.json" with { type: "json" };
 
 export const AUTOMATION_CATALOG_ENTRIES = [
   entry0,
@@ -48,4 +49,5 @@ export const AUTOMATION_CATALOG_ENTRIES = [
   entry19,
   entry20,
   entry21,
+  entry22,
 ];

package/marketplaces/openhands-extensions.json

@@ -890,6 +890,12 @@
       "source": "./skills/github-delivery-watchdog",
       "description": "Periodically check pull requests and merge only current heads with independent review, tests, and passing CI.",
       "category": "automations"
+    },
+    {
+      "name": "github-stale-ci-pr-closer",
+      "source": "./skills/github-stale-ci-pr-closer",
+      "description": "Warn and close abandoned pull requests whose required CI remains failing.",
+      "category": "automations"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openhands/extensions",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Public OpenHands extension catalogs for skills, plugins, integrations, and automation templates.",
   "license": "MIT",
   "type": "module",

package/plugins/openhands/skills/openhands-sdk/SKILL.md

@@ -201,6 +201,7 @@ Source: [`examples/`](https://github.com/OpenHands/software-agent-sdk/tree/main/
 - [`56_structured_output.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/56_structured_output.py)
 - [`57_prompt_hooks`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/01_standalone_sdk/57_prompt_hooks)
 - [`58_ask_oracle_tool`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/01_standalone_sdk/58_ask_oracle_tool)
+- [`59_route_task_to_model.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/59_route_task_to_model.py)
 
 ### [`02_remote_agent_server/`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/02_remote_agent_server)
 

package/plugins/pr-review/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/plugins/qa-changes/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/plugins/vulnerability-remediation/skills/github/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/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "openhands-extensions"
-version = "0.24.0"
+version = "0.25.0"
 description = "OpenHands extensions, plugins, and skills (Python bindings for the integration catalog)"
 requires-python = ">=3.12"
 dependencies = [

package/python/openhands_extensions/_version.py

@@ -18,7 +18,7 @@ from importlib.metadata import PackageNotFoundError, version
 #: Kept in lock-step with pyproject.toml/package.json by the version test.
 #: release-please only rewrites a semver found on the annotated line itself, so
 #: the annotation must stay on the assignment; on its own line it is a no-op.
-_FALLBACK_VERSION = "0.24.0"  # x-release-please-version
+_FALLBACK_VERSION = "0.25.0"  # x-release-please-version
 
 try:
     __version__: str = version("openhands-extensions")

package/skills/github/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-agents-md-maintainer/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]