ctrlrelay 0.16.4__tar.gz → 0.17.1__tar.gz

{ctrlrelay-0.16.4 → ctrlrelay-0.17.1}/CHANGELOG.md

@@ -7,6 +7,67 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.17.1] - 2026-11-01
+
+### Fixed
+
+- Installed bridge and poller units carry the token variable the configured
+  transport names, not a fixed Telegram one. `ctrlrelay install
+  launchd|systemd` and `ctrlrelay setup --install-daemons` read
+  `transport.<type>.bot_token_env` and render `Environment=<that
+  name>=<value>` (systemd) or the matching plist entry (launchd), with the
+  value taken from that variable in the installing shell. A Mattermost
+  install previously got a unit naming `CTRLRELAY_TELEGRAM_TOKEN`, which it
+  never sets, so the bridge could not log in once systemd or launchd started
+  it — the server here only worked because the line had been added by hand.
+  The unresolved-variable hint names the same variable, and the install
+  commands take `--config` to say which `orchestrator.yaml` to read
+  (closes #267)
+- Updating a repository's clone no longer deletes local branches GitHub does
+  not have. The fetch paired `--prune` with `refs/heads/*:refs/heads/*`, which
+  tells git to delete every local branch missing from origin: a branch made in
+  the clone went with `- [deleted]  (none)  -> held`. The worktree stayed,
+  but its branch ref was gone, so a blocked session whose branch was never
+  pushed lost the branch the next time any run touched that repo, and its
+  commits could later be garbage-collected. The fetch is now two: the
+  `dependabot/*` branches, which never carry local work and are the refs that
+  actually pile up, are still pruned; every other branch is fetched without
+  `--prune`. The cost is that a branch GitHub deleted now lingers in the
+  clone, since a prune cannot tell it from one GitHub never had — the
+  branch-reuse path already recognises a local-only ref and decides whether
+  its commits are merged. Because a renamed default branch is no longer
+  pruned either, each update also asks GitHub which branch is the default
+  and points the clone at it when it changed and the branch here is at origin's
+  commit (#243).
+
+## [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
@@ -2048,7 +2109,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.4...HEAD
+[Unreleased]: https://github.com/AInvirion/ctrlrelay/compare/v0.17.1...HEAD
+[0.17.1]: https://github.com/AInvirion/ctrlrelay/compare/v0.17.0...v0.17.1
+[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

{ctrlrelay-0.16.4 → ctrlrelay-0.17.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ctrlrelay
-Version: 0.16.4
+Version: 0.17.1
 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.4 → ctrlrelay-0.17.1}/docs/cli.md

@@ -68,7 +68,7 @@ Key flags:
 | `--telegram-chat-id ID` | none | Required for `--transport=telegram`. |
 | `--personalization-repo OWNER/REPO` | none | Adds a personalization block. |
 | `--no-personalization` | off | Skip the personalization prompt entirely. |
-| `--install-daemons` | (prompted) | Render and write launchd/systemd unit files. Reads `$CTRLRELAY_TELEGRAM_TOKEN` so the rendered plist isn't a placeholder. |
+| `--install-daemons` | (prompted) | Render and write launchd/systemd unit files. Reads the token variable the chosen transport names (`$CTRLRELAY_TELEGRAM_TOKEN`, `$CTRLRELAY_MATTERMOST_TOKEN`) so the rendered unit isn't a placeholder. |
 | `--skip-archived/--include-archived` | skip | gh repo list filter. |
 | `--skip-forks/--include-forks` | skip | gh repo list filter. |
 | `--yes` / `-y` | off | Accept every default; never prompt. |

{ctrlrelay-0.16.4 → ctrlrelay-0.17.1}/docs/configuration.md

@@ -404,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"]
 ```
@@ -415,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. |
 
@@ -623,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.4 → ctrlrelay-0.17.1}/docs/operations.md

@@ -34,12 +34,19 @@ and restart on failure — the templates below already do this.
 
 Recommended: let `ctrlrelay install launchd` render the plists for you.
 It substitutes `${USER}`, `${HOME}`, the absolute `ctrlrelay` path,
-your working directory, and (when exported) `CTRLRELAY_TELEGRAM_TOKEN`
-into the in-package templates and writes them to
-`~/Library/LaunchAgents/`.
+your working directory, and (when exported) your chat token into the
+in-package templates and writes them to `~/Library/LaunchAgents/`.
+
+The token goes into the plist under the variable your transport names
+in `transport.<type>.bot_token_env` — `CTRLRELAY_TELEGRAM_TOKEN` for
+Telegram, `CTRLRELAY_MATTERMOST_TOKEN` for Mattermost, or whatever you
+renamed that setting to. The command reads your `orchestrator.yaml` to
+find out which; pass `--config` if it is somewhere the usual search
+does not look. Export that variable before running, or the plist keeps
+a placeholder and the command says which variable to export.
 
 ```bash
-export CTRLRELAY_TELEGRAM_TOKEN=your-bot-token
+export CTRLRELAY_MATTERMOST_TOKEN=your-bot-token   # or _TELEGRAM_, per your config
 ctrlrelay install launchd \
   --workdir ~/Projects/ctrlrelay \
   --label-prefix com.yourname \
@@ -158,8 +165,13 @@ launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.example.ctrlrelay-po
 Recommended: `ctrlrelay install systemd` renders the user unit files
 for you (no root needed) and writes them to `~/.config/systemd/user/`.
 
+As on macOS, the bridge and poller units carry the token under the
+variable `transport.<type>.bot_token_env` names, read from your
+`orchestrator.yaml` (`--config` to point at a different one). Export
+that variable before running.
+
 ```bash
-export CTRLRELAY_TELEGRAM_TOKEN=your-bot-token
+export CTRLRELAY_MATTERMOST_TOKEN=your-bot-token   # or _TELEGRAM_, per your config
 ctrlrelay install systemd \
   --workdir ~/Projects/ctrlrelay \
   --poller-interval 300
@@ -190,6 +202,8 @@ After=network-online.target
 [Service]
 Type=simple
 WorkingDirectory=%h/Projects/ctrlrelay
+# The variable your transport names in bot_token_env — use
+# CTRLRELAY_MATTERMOST_TOKEN on a Mattermost config.
 Environment=CTRLRELAY_TELEGRAM_TOKEN=your-bot-token-here
 ExecStart=%h/.local/bin/ctrlrelay bridge start --foreground
 Restart=always
@@ -211,6 +225,8 @@ After=network-online.target ctrlrelay-bridge.service
 [Service]
 Type=simple
 WorkingDirectory=%h/Projects/ctrlrelay
+# The variable your transport names in bot_token_env — use
+# CTRLRELAY_MATTERMOST_TOKEN on a Mattermost config.
 Environment=CTRLRELAY_TELEGRAM_TOKEN=your-bot-token-here
 ExecStart=%h/.local/bin/ctrlrelay poller start --foreground --interval 300
 Restart=always

{ctrlrelay-0.16.4 → ctrlrelay-0.17.1}/pyproject.toml

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

{ctrlrelay-0.16.4 → ctrlrelay-0.17.1}/src/ctrlrelay/cli.py

@@ -5052,6 +5052,12 @@ def setup(
         console.print("  daemon unit files:")
         for p in result.daemon_units:
             console.print(f"    - {p}")
+        if result.daemon_unresolved:
+            console.print(
+                "  [yellow]warning:[/yellow] the units still carry "
+                f"{', '.join('${'+v+'}' for v in result.daemon_unresolved)}; "
+                "export it and re-run with --force, or edit the files by hand."
+            )
         console.print(
             "\n[bold]Next:[/bold] bootstrap the daemons via:\n"
             "  launchctl bootstrap gui/$(id -u) <plist>"
@@ -5463,13 +5469,50 @@ def _print_install_summary(
                 f"  [yellow]warning:[/yellow] unresolved template variables: "
                 f"{', '.join('${'+v+'}' for v in unit.unresolved)}"
             )
-            if "CTRLRELAY_TELEGRAM_TOKEN" in unit.unresolved:
+            # Name the variable this install actually needs. It is
+            # whatever `transport.<type>.bot_token_env` says, so hinting
+            # a fixed CTRLRELAY_TELEGRAM_TOKEN sent a Mattermost
+            # operator to export a variable nothing reads (#267).
+            if unit.token_env_var in unit.unresolved:
                 console.print(
-                    "  [dim]hint: export CTRLRELAY_TELEGRAM_TOKEN before "
+                    f"  [dim]hint: export {unit.token_env_var} before "
                     "re-running, or edit the file by hand.[/dim]"
                 )
 
 
+def _install_token_env_var(config_path: str | None) -> str:
+    """Which env var the rendered units should carry the chat token in.
+
+    Reads the active transport's ``bot_token_env`` so a Mattermost box
+    gets its own variable (#267). Exits non-zero on a config that was
+    asked for and cannot be loaded: rendering the Telegram default on
+    the strength of a path the operator got wrong would write a unit for
+    a transport they are not running. Finding no config at all is a
+    different case — nothing names a transport, so the historical
+    default stands and the summary flags it as unresolved.
+    """
+    from ctrlrelay.install import DEFAULT_TOKEN_ENV_VAR, token_env_var_from_config
+
+    if config_path is None:
+        try:
+            path = resolve_config_path(None)
+        except ConfigError:
+            console.print(
+                f"[yellow]No orchestrator.yaml found, so nothing names the chat "
+                f"transport: the units carry ${DEFAULT_TOKEN_ENV_VAR}. Pass "
+                "--config to use your transport's token variable.[/yellow]"
+            )
+            return DEFAULT_TOKEN_ENV_VAR
+    else:
+        path = resolve_config_path(config_path)
+    try:
+        config = load_config(path)
+    except ConfigError as e:
+        console.print(f"[red]Error loading config:[/red] {e}")
+        raise typer.Exit(1)
+    return token_env_var_from_config(config)
+
+
 @install_app.command("launchd")
 def install_launchd(
     workdir: Path = typer.Option(
@@ -5499,9 +5542,18 @@ def install_launchd(
         "--dry-run",
         help="Print what would be written without touching the filesystem.",
     ),
+    config_path: str | None = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
+    ),
 ) -> None:
     """Render and install bridge + poller plists for macOS launchd.
 
+    The plists carry the chat token in the variable the configured
+    transport names, so export that variable before running.
+
     After running, load the agents with:
       launchctl bootstrap gui/$(id -u) <plist-path>
     """
@@ -5512,6 +5564,7 @@ def install_launchd(
         label_prefix=label_prefix,
         poller_interval=poller_interval,
         target_dir=target_dir,
+        token_env_var=_install_token_env_var(config_path),
     )
     written: list[Path] = []
     if not dry_run:
@@ -5547,9 +5600,18 @@ def install_systemd(
         "--dry-run",
         help="Print what would be written without touching the filesystem.",
     ),
+    config_path: str | None = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
+    ),
 ) -> None:
     """Render and install bridge, poller and status-page systemd user units (Linux).
 
+    The bridge and poller units carry the chat token in the variable the
+    configured transport names, so export that variable before running.
+
     After running, enable with:
       systemctl --user daemon-reload
       systemctl --user enable --now ctrlrelay-bridge.service
@@ -5562,6 +5624,7 @@ def install_systemd(
         workdir=workdir,
         poller_interval=poller_interval,
         target_dir=target_dir,
+        token_env_var=_install_token_env_var(config_path),
     )
     written: list[Path] = []
     if not dry_run:

{ctrlrelay-0.16.4 → ctrlrelay-0.17.1}/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.4 → ctrlrelay-0.17.1}/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.4 → ctrlrelay-0.17.1}/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``).