ctrlrelay 0.16.4__tar.gz → 0.17.0__tar.gz

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

@@ -7,6 +7,34 @@ 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
@@ -2048,7 +2076,8 @@ 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.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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ctrlrelay
-Version: 0.16.4
+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.4 → ctrlrelay-0.17.0}/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.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ctrlrelay"
-version = "0.16.4"
+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.4 → 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.4 → 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.4 → 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``).