ctrlrelay 0.16.3__tar.gz → 0.17.0__tar.gz

{ctrlrelay-0.16.3 → ctrlrelay-0.17.0}/CHANGELOG.md

@@ -7,6 +7,66 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.17.0] - 2026-11-01
+
+Polling costs one GitHub search instead of one call per repo. **No config
+edit is required.** Check one thing if you use `include_labels`: a trigger
+label now starts a run only when the configured user added it.
+
+### Changed
+
+- Each poll asks GitHub's search once for open issues assigned to the user
+  across all configured repos, plus once per distinct `include_labels`
+  label, instead of one `gh issue list` per repo and one "is it archived"
+  probe per repo. Measured on 87 repos: 1 call per poll, down from about
+  174. A repo is probed for "archived" only when it has an issue not yet
+  handled, and a "not archived" answer is kept for 6 hours (#283, closes
+  #282)
+- A search GitHub marks incomplete, or that returns fewer rows than its
+  total, fails the poll as "could not look": nothing is marked seen or
+  treated as new. A startup seed that could not look is finished before
+  the next poll, so issues already there are never read as new (#283)
+- A trigger label (`include_labels`) starts a run only when the configured
+  user added it, whatever `accept_foreign_assignments` says; the issue is
+  still taken if the user also assigned it to themselves. Before, anyone
+  who could label an issue could start a run (#283)
+- The post-merge PR watcher and the status page's GitHub check
+  (`web.github_check_seconds`) default to 300 s, from 60 s (#283)
+- GitHub logins compare without regard to case in the assignment and label
+  checks (#283)
+
+## [0.16.4] - 2026-11-01
+
+Fixes for runs whose work could not be published. **No config edit is
+required.** `poller_state.json` gains a `publish_failures` count, added
+automatically.
+
+### Fixed
+
+- A failed publish no longer strands the issue. `poll()` marks an issue seen
+  before handing it to the handler, so a run whose agent finished but whose
+  branch the relay could not publish stayed in `seen_issues` forever: the
+  claim was retracted, the automation label was still on it, and the relay
+  never came back. The issue is now un-marked for the next poll, up to 3
+  runs, counted in `publish_failures` in `poller_state.json` (saved together
+  with the un-mark) so a restart does not reset the limit. After the third
+  the relay says on the issue that it has stopped, with the error scrubbed,
+  and says so in chat if that comment cannot be posted. A *refused* push is
+  not retried at all: the relay reaches the same refusal every time (#278,
+  closes #268)
+- The retraction comment no longer advises a retry that cannot work. It said
+  to re-assign the issue or re-apply its automation label, but the skip
+  decision reads the issue number alone, so neither did anything. It now
+  says that while the poller is running the relay tries again a limited
+  number of times and says so if it stops, and otherwise names the one route
+  that works (#278, closes #268)
+- A failed push says why. The rejected ref and git's reason (a stale lease,
+  a non-fast-forward, a protection rule) lead the error, the remote's own
+  `remote:` lines follow, and the reason reaches `dev.publish.failed` as its
+  own `push_rejection` field. Before, only git's summary line naming the URL
+  survived. Every failing git command now reports both of its output
+  streams, scrubbed of credential shapes (#277, closes #269)
+
 ## [0.16.3] - 2026-11-01
 
 A security fix: **upgrade every machine.** No config edit is required.
@@ -2016,7 +2076,9 @@ pipeline).
   per-phase implementation plans (Phase 0 through Phase 4).
 - `docs/Claude_Code_Project_Guide.md` — project development guide.
 
-[Unreleased]: https://github.com/AInvirion/ctrlrelay/compare/v0.16.3...HEAD
+[Unreleased]: https://github.com/AInvirion/ctrlrelay/compare/v0.17.0...HEAD
+[0.17.0]: https://github.com/AInvirion/ctrlrelay/compare/v0.16.4...v0.17.0
+[0.16.4]: https://github.com/AInvirion/ctrlrelay/compare/v0.16.3...v0.16.4
 [0.16.3]: https://github.com/AInvirion/ctrlrelay/compare/v0.16.2...v0.16.3
 [0.16.2]: https://github.com/AInvirion/ctrlrelay/compare/v0.16.1...v0.16.2
 [0.16.1]: https://github.com/AInvirion/ctrlrelay/compare/v0.16.0...v0.16.1

{ctrlrelay-0.16.3 → ctrlrelay-0.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ctrlrelay
-Version: 0.16.3
+Version: 0.17.0
 Summary: Local-first orchestrator for headless coding agents across multiple GitHub repos
 Project-URL: Homepage, https://github.com/AInvirion/ctrlrelay
 Project-URL: Documentation, https://ainvirion.github.io/ctrlrelay/

{ctrlrelay-0.16.3 → ctrlrelay-0.17.0}/docs/configuration.md

@@ -133,7 +133,21 @@ private git dir with hooks off and only ctrlrelay's own git config, pushes the
 commit it checked rather than the ref name, and uses `--force-with-lease`
 against the head this session last pushed (recorded in the state DB). An
 open PR found for the branch is reused only if its head repo is this repo and
-its base is the default branch. Text the agent wrote is posted with `@`-mentions and
+its base is the default branch.
+
+A push git rejects for a ref is a different thing, logged as
+`publish.push.rejected` with the per-ref reason git gave. Some are decided by
+git itself before the remote is asked (a stale lease, a non-fast-forward:
+`[rejected]`), others by the remote (a branch-protection or repository-rule
+refusal: `[remote rejected]`). That reason
+comes from the `!` line of `git push --porcelain`, which git writes to
+**stdout**; stderr carries only `error: failed to push some refs to '<url>'`.
+Both streams of any failing git command now reach the error it raises (stderr
+whole, stdout capped, both scrubbed of credential shapes), and the reason
+reaches `dev.publish.failed` as its own `push_rejection` field, so a
+rejection is not reported as a URL and nothing else.
+
+Text the agent wrote is posted with `@`-mentions and
 issue-closing keywords disabled and its length capped (20,000 characters);
 the PR's own `Closes #N` is added by ctrlrelay.
 
@@ -390,7 +404,7 @@ web:
   port: 8787
   history_days: 7
   refresh_seconds: 5
-  github_check_seconds: 60
+  github_check_seconds: 300
   stale_after_minutes: 15
   allowed_hosts: []          # e.g. ["mybox", "mybox.lan"]
 ```
@@ -401,7 +415,7 @@ web:
 | `port` | int (1-65535) | `8787` | Port to listen on. |
 | `history_days` | int (>= 1) | `7` | Days of feed the page shows, and what `/api/events` returns without `?since=`. |
 | `refresh_seconds` | int (>= 1) | `5` | How often the page asks `/api/status` again. |
-| `github_check_seconds` | int (>= 15) | `60` | How often the waiting line asks GitHub (one search, plus one query per `include_labels` label). |
+| `github_check_seconds` | int (>= 15) | `300` | How often the waiting line asks GitHub (one search, plus one query per `include_labels` label). Every check spends from the GitHub account's budget, which machines on the account share. |
 | `stale_after_minutes` | int (>= 1) | `15` | A running card is marked "looks stuck" after this long with no new agent step, unless ctrlrelay itself has a CI wait or review open for it. |
 | `allowed_hosts` | list of strings | `[]` | Extra names the page may be opened by. A request is served only when its `Host` header is `localhost`, `127.0.0.1`, `[::1]`, `host` (unless it is `0.0.0.0`/`::`), this machine's hostname, the hostname plus `.local`, or one of these, alone or followed by `:port`. Anything else, or no `Host`, gets `421`. Matching ignores case and a trailing dot. This stops a web page on another site from pointing its own name at this server (DNS rebinding) and reading it. |
 
@@ -609,21 +623,25 @@ repos:
 - An issue is accepted when **either** (a) it's assigned to the configured
   user (subject to the self-assignment filter from #79 and
   `accept_foreign_assignments`) **or** (b) it carries any label in
-  `include_labels`. A label match **skips** the self-assignment check — the
-  operator's config choice is the trust boundary.
+  `include_labels` **that the configured user added** (the latest
+  `labeled` event for that label names that account; `accept_foreign_assignments`
+  does not widen this). A label someone else added does not start a run;
+  the issue is still taken if the user also assigned it to themselves.
 - Dedup: an issue that is **both** labeled and assigned is picked up exactly
   once per poll cycle — no duplicate entries in `seen_issues` and no double
   pipeline spawn.
 - `exclude_labels` always wins over `include_labels` on the same issue: an
   explicit "not for the agent" opt-OUT beats the generic label opt-IN.
-- When a repo configures `include_labels`, the poller runs **targeted**
-  queries per cycle: the existing `gh issue list --assignee <user>` plus
-  one `gh issue list --label <L>` call per configured label. Results merge
-  by issue number. This keeps the label path scale-safe on busy repos
-  where an unfiltered fetch would silently cap at gh's `--limit` and miss
-  labeled issues on later pages. Repos without `include_labels` run only
-  the cheap `--assignee` query, so enabling the feature on one repo does
-  not add API calls on the others.
+- Each poll asks GitHub's search **once** for open issues assigned to the
+  user across all configured repos, plus **once per distinct
+  `include_labels` label** across the repos using it, whatever the number
+  of repos (split by owner only if the owner list is too long for one
+  query). A search GitHub marks incomplete, or that returns fewer rows
+  than its total, fails the poll as "could not look": nothing is marked
+  seen and nothing is treated as new. After that, only issues not yet
+  handled cost a call each (who assigned it, or who added the label), and
+  a repo is asked whether it is archived only when it has such an issue,
+  at most once every 6 hours.
 - The event log entry for a label-triggered acceptance is
   `poll.issue.included_by_label`, alongside the existing
   `poll.issue.excluded_by_label` for exclusions.

{ctrlrelay-0.16.3 → ctrlrelay-0.17.0}/docs/operations.md

@@ -727,6 +727,30 @@ file, so a restart does not reset it. Each retry posts a fresh claim
 comment and, when it fails, a fresh "nothing is working on this" comment
 on the issue.
 
+A run whose **agent finished but whose branch the relay could not
+publish** is retried the same way, for the same reason: the issue is
+already in `seen_issues`, so without this nothing would ever bring it
+back. Up to 3 runs in all, counted in `publish_failures` in the same
+file, and the retraction comment on the issue says the relay will
+return rather than asking you to re-assign it. After the third run the
+issue stays in `seen_issues` and the relay says so **on the issue** —
+the commits are still on the run branch in the local checkout (on
+GitHub too, if only opening the pull request failed), and the fix is to
+clear the cause and delete the number as above. If that comment cannot
+be posted, the chat line says so.
+
+A push the relay **refuses** (a protected or default branch, a base it
+did not expect, somebody else's commits on the branch) is not retried
+at all: the relay reaches the same refusal every time, so another run
+would spend a whole agent to arrive at it. The issue stays in
+`seen_issues` and the comment names what to do.
+
+Re-assigning an issue, or re-applying its automation label, does **not**
+make the poller look at it again. The skip decision reads the issue
+number only — no assignee and no labels — so the number has to leave
+`seen_issues` (and the relay has to be restarted, since the running
+poller holds the set in memory and rewrites the file from it).
+
 ### A repo whose history was replaced
 
 If the local copy's default branch can no longer fast-forward to GitHub's

{ctrlrelay-0.16.3 → ctrlrelay-0.17.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ctrlrelay"
-version = "0.16.3"
+version = "0.17.0"
 description = "Local-first orchestrator for headless coding agents across multiple GitHub repos"
 readme = "README.md"
 requires-python = ">=3.12"

{ctrlrelay-0.16.3 → ctrlrelay-0.17.0}/src/ctrlrelay/cli.py

@@ -1183,6 +1183,123 @@ def settle_pre_dispatch_failure(poller, repo: str, issue_number: int, result):
     )
 
 
+# Runs of one issue whose branch the relay may fail to publish before
+# the poller stops retrying it (#268). Same shape and same reason as
+# PRE_DISPATCH_ATTEMPTS: a blip deserves another poll, a permanent cause
+# must not spend one full agent run per poll forever.
+PUBLISH_ATTEMPTS = 3
+
+
+def publish_failure_message(
+    repo: str, issue_number: int, error: str, *, attempts: int, retrying: bool,
+) -> str:
+    """The chat line for a run whose branch the relay could not publish."""
+    why = (error.strip().splitlines() or ["no error recorded"])[0][:200]
+    if retrying:
+        return (
+            f"\u23f3 #{issue_number} in {repo}: the agent finished but the "
+            f"relay could not publish the branch (try {attempts} of "
+            f"{PUBLISH_ATTEMPTS}): {why}. Will retry on the next poll."
+        )
+    return (
+        f"\u274c #{issue_number} in {repo}: could not publish the branch "
+        f"{attempts} times; not retrying. Last error: {why}. The commits "
+        "are on the run branch locally; fix the cause, then remove the "
+        "issue number from seen_issues in poller_state.json to try again."
+    )
+
+
+async def settle_publish_failure(
+    github, poller, repo: str, issue_number: int, result,
+):
+    """Decide what a failed publish means for retrying its issue (#268).
+
+    `poll()` marks an issue seen BEFORE handing it to the handler, so a
+    publish failure nobody un-marks drops the issue forever: the claim
+    is retracted, the automation label is still on it, and the relay
+    never comes back. Nothing in the logs says why, because from the
+    relay's own point of view nothing is wrong.
+
+    So: the agent finished and only the publish failed, and the push was
+    not refused -> count it, and below ``PUBLISH_ATTEMPTS`` un-mark the
+    issue so the next poll runs it again. At the limit the issue stays
+    seen, the count is dropped, and the relay says on the ISSUE that it
+    has stopped — the retraction already there promised a retry, and a
+    promise silently abandoned is the original defect one step on.
+
+    A refused push is not retried at all: the relay re-reaches that
+    refusal every time, so another attempt costs a whole agent run to
+    arrive at the same answer. Returns the chat line, or ``None`` for
+    any result this is not about.
+
+    Writing the issue comment is best-effort: this runs after a run that
+    has already failed, and a `gh` error here must not replace the run's
+    real failure with a different one.
+    """
+    from ctrlrelay.pipelines.dev import (
+        publish_failure_is_retryable,
+        publish_retries_exhausted_comment,
+    )
+
+    outputs = result.outputs or {}
+    if result.success or result.blocked or not outputs.get("publish_failed"):
+        poller.clear_publish_failures(repo, issue_number)
+        return None
+    if not publish_failure_is_retryable(result):
+        # Refused, not failed. Left seen deliberately; the pipeline's
+        # retraction on the issue already names the operator action.
+        poller.clear_publish_failures(repo, issue_number)
+        log_event(
+            _logger, "publish.refused_not_retried", repo=repo,
+            issue_number=issue_number, error=(result.error or "")[:200],
+        )
+        return (
+            f"\u26d4 #{issue_number} in {repo}: the relay refused to push "
+            f"the branch, so it is not retrying. {result.error or ''}".strip()
+        )
+
+    # The count and the un-mark are saved together, in one write.
+    attempts = poller.publish_failure_count(repo, issue_number) + 1
+    retrying = attempts < PUBLISH_ATTEMPTS
+    poller.count_publish_failure(repo, issue_number, unmark=retrying)
+    notice_failed = False
+    if not retrying:
+        poller.clear_publish_failures(repo, issue_number)
+        try:
+            await github.comment_on_issue(
+                repo=repo,
+                issue_number=issue_number,
+                body=publish_retries_exhausted_comment(
+                    result.session_id,
+                    repo=repo,
+                    issue_number=issue_number,
+                    attempts=attempts,
+                    error=result.error or "",
+                ),
+            )
+        except asyncio.CancelledError:
+            raise
+        except Exception as e:
+            log_event(
+                _logger, "publish.exhausted_notice_failed", repo=repo,
+                issue_number=issue_number,
+                error=f"{type(e).__name__}: {str(e)[:200]}",
+            )
+            notice_failed = True
+    message = publish_failure_message(
+        repo, issue_number, result.error or "",
+        attempts=attempts, retrying=retrying,
+    )
+    if notice_failed:
+        # The issue's last word is still the retraction promising a
+        # retry; chat is now the only place that says it stopped.
+        message += (
+            " The note saying so could not be posted on the issue, which "
+            "still promises a retry."
+        )
+    return message
+
+
 def reclone_message(repo: str, set_aside: Path) -> str:
     """The chat line for a clone that was set aside and cloned again
     (#234). Names where the old copy went, because nothing deletes it."""
@@ -3168,6 +3285,23 @@ def poller_start(
                             pass
                     return
 
+                # The agent finished and the relay could not publish the
+                # branch (#268). Un-marked so the next poll runs it
+                # again, bounded, because the issue is already marked
+                # seen and nothing else would ever bring it back. No
+                # early return: a fix round that failed to push still
+                # has a pull request below that needs its merge watcher.
+                publish_note = await settle_publish_failure(
+                    github, poller, repo, issue_number, result,
+                )
+                if publish_note is not None:
+                    console.print(f"[yellow]{publish_note}[/yellow]")
+                    if connected_transport is not None:
+                        try:
+                            await connected_transport.send(publish_note)
+                        except Exception:
+                            pass
+
                 # Lock-contended DURING PR verification (issue #29): the
                 # PR already exists AND verification decided it wasn't
                 # ready (_verify_and_fix_pr only returns this error from

{ctrlrelay-0.16.3 → ctrlrelay-0.17.0}/src/ctrlrelay/core/archived.py

@@ -25,6 +25,8 @@ and an unarchived repo recovers on its own.
 from __future__ import annotations
 
 import asyncio
+import time
+from collections.abc import Callable
 from dataclasses import dataclass, field
 from typing import Any
 
@@ -37,6 +39,10 @@ _logger = get_logger("core.archived")
 # cycle, and a hung lookup would delay every repo behind it. Timing out
 # just means "unknown" — the repo is polled as normal.
 ARCHIVED_PROBE_TIMEOUT_SECONDS = 20
+# How long a confirmed "not archived" answer is kept (#282). Each probe is a
+# GitHub call on an account several machines share, and a repo is archived
+# rarely; a repo archived meanwhile is noticed within this long.
+ACTIVE_ANSWER_SECONDS = 6 * 3600
 
 
 @dataclass
@@ -62,6 +68,10 @@ class ArchivedRepoTracker:
     # the cache miss before either awaits, so the "one probe, one log"
     # contract in the docstring above is only true single-threaded.
     _locks: dict[str, asyncio.Lock] = field(default_factory=dict, repr=False)
+    # Repo -> monotonic time until which a confirmed "not archived" answer
+    # stands (#282). Only a definite answer is kept; an error never is.
+    _active_until: dict[str, float] = field(default_factory=dict, repr=False)
+    clock: Callable[[], float] = field(default=time.monotonic, repr=False)
 
     async def is_archived(self, repo: str) -> bool:
         """Return True only for a confirmed-archived repo.
@@ -73,6 +83,8 @@ class ArchivedRepoTracker:
         """
         if repo in self.archived_repos:
             return True
+        if self._active_until.get(repo, 0.0) > self.clock():
+            return False
 
         lock = self._locks.setdefault(repo, asyncio.Lock())
         async with lock:
@@ -108,6 +120,10 @@ class ArchivedRepoTracker:
         # `is True` on purpose: a truthy non-boolean (a Mock, a "true"
         # string from a future gh format change) must not skip a repo.
         if result is not True:
+            if result is False:
+                # A definite "not archived": kept for a while (#282). A
+                # truthy non-boolean is not definite and is not kept.
+                self._active_until[repo] = self.clock() + ACTIVE_ANSWER_SECONDS
             return False
 
         self.archived_repos.add(repo)

{ctrlrelay-0.16.3 → ctrlrelay-0.17.0}/src/ctrlrelay/core/config.py

@@ -349,7 +349,7 @@ class WebConfig(BaseModel):
     refresh_seconds: int = Field(default=5, ge=1)
     # How often the waiting line asks GitHub. One search per check, plus
     # one query per include label; below 15 s that spends the rate limit.
-    github_check_seconds: int = Field(default=60, ge=15)
+    github_check_seconds: int = Field(default=300, ge=15)
     # A running card with no new agent step for this long, and no CI wait
     # or review open, is marked "looks stuck".
     stale_after_minutes: int = Field(default=15, ge=1)

{ctrlrelay-0.16.3 → ctrlrelay-0.17.0}/src/ctrlrelay/core/github.py

@@ -6,6 +6,7 @@ import asyncio
 import json
 import re
 import shutil
+from collections.abc import Sequence
 from dataclasses import dataclass, field
 from typing import Any
 
@@ -95,6 +96,21 @@ def _find_gh() -> str:
     return "gh"
 
 
+
+# GitHub refuses search queries longer than 256 characters; kept below it.
+_SEARCH_QUERY_MAX = 240
+
+# One page of ``search/issues`` as one JSON line, with the rows in
+# ``gh issue list``'s field names (#282).
+_SEARCH_PAGE_JQ = (
+    "{incomplete: .incomplete_results, total: .total_count, items: [.items[] | "
+    "{number, title, state, body, labels: [.labels[] | {name}], "
+    "assignees: [.assignees[] | {login}], createdAt: .created_at, "
+    "updatedAt: .updated_at, "
+    "repo: (.repository_url | sub(\"^https://api.github.com/repos/\"; \"\"))}]}"
+    " | tojson"
+)
+
 @dataclass
 class GitHubCLI:
     """Async wrapper around the gh CLI."""
@@ -365,6 +381,96 @@ class GitHubCLI:
             issue["repo"] = (issue.get("repository") or {}).get("nameWithOwner", "")
         return issues
 
+    async def search_open_issues(
+        self,
+        *,
+        repos: Sequence[str],
+        assignee: str | None = None,
+        label: str | None = None,
+    ) -> dict[str, list[dict[str, Any]]]:
+        """Open issues in ``repos`` assigned to ``assignee`` or carrying
+        ``label``, in ONE search rather than one call per repo (#282): the
+        poller's intake, whatever the number of repos.
+
+        GitHub's search API directly (``gh api search/issues``), because
+        it says when an answer is partial: a page marked
+        ``incomplete_results`` (the search timed out on GitHub's side), or
+        fewer rows than ``total_count`` (more than search returns), raises
+        ``GitHubError`` rather than pass for complete, and so do empty or
+        unreadable output. Scoped to the owners of ``repos``; rows are kept
+        only for ``repos`` (matched without regard to case) and keyed by
+        the configured name. Every configured repo is a key, with ``[]``
+        when nothing matched, so "looked, found nothing" differs from "did
+        not look", which raises. Rows use ``gh issue list``'s field names.
+        """
+        if (assignee is None) == (label is None):
+            raise ValueError("pass exactly one of assignee or label")
+        by_name = {r.lower(): r for r in repos}
+        owners = sorted({r.split("/", 1)[0] for r in repos if "/" in r})
+        base = ["is:issue", "is:open"]
+        if assignee is not None:
+            base.append(f"assignee:{assignee}")
+        else:
+            base.append('label:"' + label.replace('"', "") + '"')
+        # GitHub caps a search query's length, so owners are split across
+        # as few queries as fit: the count grows with the number of
+        # owners, never with the number of repos.
+        queries: list[list[str]] = [[]]
+        for owner in owners:
+            term = f"user:{owner}"
+            if queries[-1] and len(" ".join(base + queries[-1] + [term])) > _SEARCH_QUERY_MAX:
+                queries.append([])
+            queries[-1].append(term)
+        rows: list[dict[str, Any]] = []
+        for owner_terms in queries:
+            rows += await self._search_issue_pages(" ".join(base + owner_terms))
+        out: dict[str, list[dict[str, Any]]] = {r: [] for r in repos}
+        for row in rows:
+            repo = by_name.get(str(row.get("repo", "")).lower())
+            if repo is not None:
+                out[repo].append(row)
+        return out
+
+    async def _search_issue_pages(self, query: str) -> list[dict[str, Any]]:
+        """Every row of one search, or ``GitHubError`` when the answer
+        could be partial or could not be read."""
+        output = await self._run_gh(
+            "api", "-X", "GET", "search/issues", "--paginate",
+            "-f", "q=" + query, "-f", "per_page=100",
+            "--jq", _SEARCH_PAGE_JQ,
+        )
+        pages = [json.loads(line) for line in output.splitlines() if line.strip()]
+        if not pages or not all(isinstance(p, dict) and "items" in p for p in pages):
+            raise GitHubError("gh api search/issues gave no readable answer")
+        if any(p.get("incomplete") for p in pages):
+            raise GitHubError("GitHub marked the search incomplete")
+        rows = [row for p in pages for row in p["items"]]
+        totals = {p.get("total") for p in pages}
+        # Every page must agree on the total: one that changed mid-way means
+        # the result set moved while it was being read.
+        total = totals.pop() if len(totals) == 1 else None
+        if not isinstance(total, int) or len(rows) < total:
+            raise GitHubError(
+                f"the search returned {len(rows)} of {total} issues, so the "
+                "answer may be incomplete"
+            )
+        return rows
+
+    async def list_label_events(
+        self,
+        repo: str,
+        issue_number: int,
+    ) -> list[dict[str, Any]]:
+        """``labeled`` events for an issue, oldest first, every page. On a
+        ``labeled`` event ``actor`` is the account that added the label
+        (unlike an ``assigned`` event, where it is the assignee, #274)."""
+        output = await self._run_gh(
+            "api", "--paginate",
+            f"/repos/{repo}/issues/{issue_number}/events",
+            "--jq", '.[] | select(.event=="labeled")',
+        )
+        return [json.loads(line) for line in output.splitlines() if line.strip()]
+
     async def current_login(self) -> str:
         """The login ``gh`` is authenticated as (``gh api user``).