pr-review-agent 0.16.0__tar.gz

pr_review_agent-0.16.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Prasad Talasila
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pr_review_agent-0.16.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: pr-review-agent
+Version: 0.16.0
+Summary: Locally-hosted LLM-based PR review agent with enforced usage budgets
+License-Expression: MIT
+License-File: LICENSE
+Author: The INTO-CPS Association
+Requires-Python: >=3.10,<3.15
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: PyYAML (>=6.0)
+Requires-Dist: click (>=8.1,<9)
+Requires-Dist: httpx (>=0.27)
+Project-URL: Repository, https://github.com/prasadtalasila/pr-review-agent
+Description-Content-Type: text/markdown
+
+# pr-review-agent
+
+<p align="center">
+<b>A locally-hosted LLM pull request reviewer that cannot overspend and cannot
+be summoned by a stranger.</b>
+</p>
+
+A single Python asyncio daemon with a SQLite store, running on a private host.
+It polls on pull requests of a GitHub repository for exactly two events:
+
+1. a freshly opened pull request whose author is pre-approved;
+2. a comment containing `@claude` whose commenter is pre-approved.
+
+and performs code review using Claude CLI and posts review comments on the pull request.
+
+## 🚀 Quickstart
+
+_Requires_: Python **3.10 – 3.14** and python virtualenv.
+Download [latest release](https://github.com/prasadtalasila/pr-review-agent/releases). 
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+
+# download the latest release
+pip install pr_review_agent-<version>-py3-none-any.whl
+
+pr-review-agent config generate      # writes ./config.yaml
+# update config; `config generate --full` writes the commented template
+pr-review-agent config validate
+
+# get GitHub PAT with read and write permissions on pull requests
+GITHUB_TOKEN=xxxx pr-review-agent host check            # can this host reach it all?
+GITHUB_TOKEN=xxxx pr-review-agent daemon start          # reads ./config.yaml
+GITHUB_TOKEN=xxxx pr-review-agent daemon start --config /etc/pr-review-agent/config.yaml
+```
+
+Installing the package puts `pr-review-agent` on the path. Commands follow a
+`pr-review-agent <noun> <verb>` grammar, grouped by the setup workflow:
+`config` → `host` → `daemon`. `--config` is optional: without it a command
+reads `config.yaml` from the directory it is started in, which is also where
+`state.db` is written.
+
+## 🗂 Documentation
+
+| Document | Answers |
+| :-- | :-- |
+| [docs/CONFIG.md](docs/CONFIG.md) | What settings exist, what does each accept, and why are unknown keys an error? |
+| [docs/DESIGN.md](docs/DESIGN.md) | Why does this exist and why is it shaped like this? The four constraints, every alternative considered and rejected, the billing-mode question that is still open, and how prompt injection is handled |
+| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | What actually runs? The components, the path an event takes, the package layout, and which layer may import which |
+| [docs/TRIGGERS.md](docs/TRIGGERS.md) | What starts a review and what does not? Every reason code and its log level, what counts as a mention, the dedupe keys, and why identity is a number |
+| [docs/POLLER.md](docs/POLLER.md) | How does it learn something happened without an inbound port? The three endpoints, the rate-limit arithmetic, the adaptive interval, the retry rules, and how a comment payload is mapped to a pull request |
+| [docs/DAEMON.md](docs/DAEMON.md) | What runs continuously, and what is it careful not to do? The cycle, the cold-start spend bound, the two watermark ordering rules, and how it shuts down |
+| [docs/QUEUE.md](docs/QUEUE.md) | Where does an accepted trigger wait, and what stops one review being paid for twice? Dedupe, the per-pull-request lease, why leases expire instead of renewing, and the retry bound |
+| [docs/STORAGE.md](docs/STORAGE.md) | What has to survive a restart, and what does a lost watermark actually cost? Why SQLite, and why a watermark only moves forward |
+| [docs/WORKSPACE.md](docs/WORKSPACE.md) | How does a pull request's code get onto disk, and why is none of it ever run? The bare mirror, the per-run worktree, the untrusted-tree hardening, and the diff-size caps |
+| [docs/BUDGET.md](docs/BUDGET.md) | The rolling windows and the share that guarantees human headroom, reserve-then-settle under concurrency, the degradation ladder, the circuit breaker, and what is still not built |
+| [docs/WORKER.md](docs/WORKER.md) | What drains the queue? The claim-run-settle loop, what a failed run settles at and why, which failures retry and which are permanent, what a run leaves behind, the supervisor, and why not a process per review |
+| [docs/PUBLISHER.md](docs/PUBLISHER.md) | How does a review become visible, and what stops the agent approving anything? The 👀 at claim time, the live `head_sha` re-check, one comment per pull request, `publish.dry_run`, and why a failed publish never costs a second review |
+| [docs/ENGINE.md](docs/ENGINE.md) | How does a different coding agent plug in? The one swappable step, what an engine is given and must return, the capability record, and why every adapter is a CLI subprocess rather than an SDK |
+| [docs/ROADMAP.md](docs/ROADMAP.md) | What is built, what is next, the acceptance checklist, and the known gaps |
+| [DEVELOPER.md](DEVELOPER.md) | How do I set up, test, lint and build this? |
+| [CLAUDE.md](CLAUDE.md) | The behavioural guidelines applied to every change |
+| [AGENTS.md](AGENTS.md) | The coding-assistant conventions |
+

pr_review_agent-0.16.0/README.md

@@ -0,0 +1,64 @@
+# pr-review-agent
+
+<p align="center">
+<b>A locally-hosted LLM pull request reviewer that cannot overspend and cannot
+be summoned by a stranger.</b>
+</p>
+
+A single Python asyncio daemon with a SQLite store, running on a private host.
+It polls on pull requests of a GitHub repository for exactly two events:
+
+1. a freshly opened pull request whose author is pre-approved;
+2. a comment containing `@claude` whose commenter is pre-approved.
+
+and performs code review using Claude CLI and posts review comments on the pull request.
+
+## 🚀 Quickstart
+
+_Requires_: Python **3.10 – 3.14** and python virtualenv.
+Download [latest release](https://github.com/prasadtalasila/pr-review-agent/releases). 
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+
+# download the latest release
+pip install pr_review_agent-<version>-py3-none-any.whl
+
+pr-review-agent config generate      # writes ./config.yaml
+# update config; `config generate --full` writes the commented template
+pr-review-agent config validate
+
+# get GitHub PAT with read and write permissions on pull requests
+GITHUB_TOKEN=xxxx pr-review-agent host check            # can this host reach it all?
+GITHUB_TOKEN=xxxx pr-review-agent daemon start          # reads ./config.yaml
+GITHUB_TOKEN=xxxx pr-review-agent daemon start --config /etc/pr-review-agent/config.yaml
+```
+
+Installing the package puts `pr-review-agent` on the path. Commands follow a
+`pr-review-agent <noun> <verb>` grammar, grouped by the setup workflow:
+`config` → `host` → `daemon`. `--config` is optional: without it a command
+reads `config.yaml` from the directory it is started in, which is also where
+`state.db` is written.
+
+## 🗂 Documentation
+
+| Document | Answers |
+| :-- | :-- |
+| [docs/CONFIG.md](docs/CONFIG.md) | What settings exist, what does each accept, and why are unknown keys an error? |
+| [docs/DESIGN.md](docs/DESIGN.md) | Why does this exist and why is it shaped like this? The four constraints, every alternative considered and rejected, the billing-mode question that is still open, and how prompt injection is handled |
+| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | What actually runs? The components, the path an event takes, the package layout, and which layer may import which |
+| [docs/TRIGGERS.md](docs/TRIGGERS.md) | What starts a review and what does not? Every reason code and its log level, what counts as a mention, the dedupe keys, and why identity is a number |
+| [docs/POLLER.md](docs/POLLER.md) | How does it learn something happened without an inbound port? The three endpoints, the rate-limit arithmetic, the adaptive interval, the retry rules, and how a comment payload is mapped to a pull request |
+| [docs/DAEMON.md](docs/DAEMON.md) | What runs continuously, and what is it careful not to do? The cycle, the cold-start spend bound, the two watermark ordering rules, and how it shuts down |
+| [docs/QUEUE.md](docs/QUEUE.md) | Where does an accepted trigger wait, and what stops one review being paid for twice? Dedupe, the per-pull-request lease, why leases expire instead of renewing, and the retry bound |
+| [docs/STORAGE.md](docs/STORAGE.md) | What has to survive a restart, and what does a lost watermark actually cost? Why SQLite, and why a watermark only moves forward |
+| [docs/WORKSPACE.md](docs/WORKSPACE.md) | How does a pull request's code get onto disk, and why is none of it ever run? The bare mirror, the per-run worktree, the untrusted-tree hardening, and the diff-size caps |
+| [docs/BUDGET.md](docs/BUDGET.md) | The rolling windows and the share that guarantees human headroom, reserve-then-settle under concurrency, the degradation ladder, the circuit breaker, and what is still not built |
+| [docs/WORKER.md](docs/WORKER.md) | What drains the queue? The claim-run-settle loop, what a failed run settles at and why, which failures retry and which are permanent, what a run leaves behind, the supervisor, and why not a process per review |
+| [docs/PUBLISHER.md](docs/PUBLISHER.md) | How does a review become visible, and what stops the agent approving anything? The 👀 at claim time, the live `head_sha` re-check, one comment per pull request, `publish.dry_run`, and why a failed publish never costs a second review |
+| [docs/ENGINE.md](docs/ENGINE.md) | How does a different coding agent plug in? The one swappable step, what an engine is given and must return, the capability record, and why every adapter is a CLI subprocess rather than an SDK |
+| [docs/ROADMAP.md](docs/ROADMAP.md) | What is built, what is next, the acceptance checklist, and the known gaps |
+| [DEVELOPER.md](DEVELOPER.md) | How do I set up, test, lint and build this? |
+| [CLAUDE.md](CLAUDE.md) | The behavioural guidelines applied to every change |
+| [AGENTS.md](AGENTS.md) | The coding-assistant conventions |

pr_review_agent-0.16.0/pyproject.toml

@@ -0,0 +1,88 @@
+[project]
+name = "pr-review-agent"
+version = "0.16.0"
+description = "Locally-hosted LLM-based PR review agent with enforced usage budgets"
+readme = "README.md"
+requires-python = ">=3.10,<3.15"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "The INTO-CPS Association" }]
+classifiers = [
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+    "PyYAML>=6.0",
+    "httpx>=0.27",
+    "click>=8.1,<9",
+]
+
+[project.urls]
+Repository = "https://github.com/prasadtalasila/pr-review-agent"
+
+# Without this the wheel ships the package and no command: `pip install` puts
+# `pr_review_agent` on the path and nothing in `bin/`, so an operator who
+# installed the released artefact had `python -m pr_review_agent.daemon` and
+# no `pr-review-agent`.
+[project.scripts]
+pr-review-agent = "pr_review_agent.cli:main"
+
+[build-system]
+requires = ["poetry-core>=2.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+packages = [{ include = "pr_review_agent", from = "src" }]
+# The config templates are data, not code, so nothing would pull them into the
+# distribution on its own -- and for thirteen releases nothing did, leaving a
+# quickstart that told the operator to copy a file the wheel had never
+# contained. `config generate` reads them from here.
+include = [
+    { path = "src/pr_review_agent/templates/*.yaml", format = "sdist" },
+    { path = "src/pr_review_agent/templates/*.yaml", format = "wheel" },
+]
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.3"
+pytest-cov = "^6.0"
+ruff = "^0.9"
+pylint = "^3.3"
+pyright = "^1.1"
+pytest-asyncio = "^0.24"
+cryptography = ">=42"
+
+[tool.poetry.group.docs]
+optional = true
+
+[tool.poetry.group.docs.dependencies]
+mkdocs-material = ">=9.7,<10.0"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+# The client and poller are asyncio-native; every async test in the suite
+# wants the default event loop, so marking each one individually is noise.
+asyncio_mode = "auto"
+# A `live` test runs a real coding agent and spends real tokens, so it is
+# deselected by default and never runs in CI. `-m live` opts in.
+addopts = ["-m", "not live"]
+markers = ["live: runs a real engine binary and spends tokens; opt in with -m live"]
+
+[tool.coverage.run]
+source = ["src/pr_review_agent"]
+branch = true
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.pyright]
+include = ["src", "tests"]
+pythonVersion = "3.10"
+typeCheckingMode = "basic"

pr_review_agent-0.16.0/src/pr_review_agent/_compat.py

@@ -0,0 +1,32 @@
+"""Standard-library shims for the Python versions this package supports.
+
+The package supports 3.10 through 3.14. Anything here exists solely because a
+name is missing on the oldest of those; each shim is deleted, not rewritten,
+once the floor rises past the version that needs it.
+"""
+
+from __future__ import annotations
+
+import sys
+
+if sys.version_info >= (3, 11):
+    from enum import StrEnum
+else:  # pragma: no cover - exercised on 3.10 only
+    from enum import Enum
+
+    class StrEnum(str, Enum):
+        """`enum.StrEnum` for Python 3.10.
+
+        A plain ``(str, Enum)`` mixin is not equivalent: on 3.10 it inherits
+        ``Enum.__str__``, so ``str(member)`` yields ``"Endpoint.OPEN_PULLS"``
+        rather than the member's value. Anything that interpolates a member
+        into a string -- a log line, a dict key written to disk -- would then
+        change meaning with the interpreter version. Delegating ``__str__``
+        and ``__format__`` to ``str`` restores the 3.11 behaviour.
+        """
+
+        __str__ = str.__str__
+        __format__ = str.__format__
+
+
+__all__ = ["StrEnum"]

pr_review_agent-0.16.0/src/pr_review_agent/_startup.py

@@ -0,0 +1,66 @@
+"""What a command-line entry point does before it can do anything else.
+
+``host check`` and ``daemon start`` each need the same two things: the GitHub
+token, and a validated ``config.yaml``. Sharing the step keeps one answer to
+"what does exit status 3 mean" rather than two that drift apart.
+
+The two halves are separate functions because one command needs only one of
+them. ``config validate`` asks whether a file is loadable, and a combined
+step would have made it refuse to answer on a host that has no token --
+demanding a credential to parse YAML. So the token check is its own call, and
+the commands that need both make both.
+
+The token is read from the environment, never from ``config.yaml``, so it can
+come from a systemd ``EnvironmentFile`` or a secret manager without ever
+being a file the repository could swallow. It is never printed: a
+:class:`StartupError` says what was missing, not what was sent.
+"""
+
+from __future__ import annotations
+
+import os
+
+from .config import Config, ConfigError
+
+TOKEN_ENV = "GITHUB_TOKEN"
+
+
+class StartupError(RuntimeError):
+    """Raised when the token or the configuration file is unusable."""
+
+
+def require_token() -> str:
+    """The GitHub token, or :class:`StartupError` if the environment has none.
+
+    A non-zero exit rather than a default: running without a token is worse
+    than stopping, because every failure it causes surfaces later and
+    further from the cause.
+    """
+    token = os.environ.get(TOKEN_ENV)
+    if not token:
+        raise StartupError(f"{TOKEN_ENV} is not set")
+    return token
+
+
+def load_config(config_path: str) -> Config:
+    """The validated configuration, or :class:`StartupError` if unusable.
+
+    ``ConfigError`` is re-raised as ``StartupError`` so a caller has one
+    exception type to catch for "this host is not set up", whichever half
+    of the setup is missing.
+    """
+    try:
+        return Config.load(config_path)
+    except ConfigError as exc:
+        raise StartupError(str(exc)) from exc
+
+
+def startup(config_path: str) -> tuple[Config, str]:
+    """Both halves, token first.
+
+    The order is load-bearing: a missing token is the cheaper and more
+    common misconfiguration, and reporting it before parsing keeps the
+    first error an operator sees the one they most likely caused.
+    """
+    token = require_token()
+    return load_config(config_path), token

pr_review_agent-0.16.0/src/pr_review_agent/bootstrap.py

@@ -0,0 +1,225 @@
+"""Pre-flight checks to run on the deployment host before the daemon does.
+
+The daemon is outbound-only, so the first question about any host is whether
+it can get *out* -- to `api.github.com` for polling and publishing, and to
+`api.anthropic.com` for the review itself. On an allowlist-based firewall
+that is the most common cause of schedule slip, and it is cheap to answer
+before anything else is built on the assumption.
+
+Three things are checked, in the order they would bite:
+
+**Every watched endpoint answers.** The three repo-wide paths are fetched
+with the same client the poller uses, so a failure here is the failure the
+poller would have had: a blocked route, a bad token, a repository the token
+cannot see.
+
+**A repeat request comes back 304.** This is the one worth running even on a
+host with obviously working egress. The whole rate-limit budget rests on
+conditional requests being free, and an intercepting proxy that strips or
+rewrites `ETag` turns every poll into a full 200 -- silently, and only
+visibly once the budget runs out mid-week.
+
+**Git can fetch, and is new enough.** The review needs the code on disk, and
+that is a different host from the API -- `github.com`, not `api.github.com`
+-- so on an allowlist-based firewall it is a different rule, and the
+poller's route answering proves nothing about it. The version is checked
+first because below 2.32 `GIT_CONFIG_GLOBAL` is ignored *without an error*,
+which would leave the checkout's whole hardening absent while appearing to
+be in force.
+
+**Anthropic is reachable.** No API key is sent and none is needed: any HTTP
+status proves the route exists, and only a transport error is a failure.
+
+The token is read from the environment, never from `config.yaml`, and is
+never printed -- the checks report what happened, not what was sent.
+"""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+import httpx
+
+from .config import Config
+from .poller.client import GitHubClient, GitHubClientError, PollResult
+from .poller.endpoints import RepoEndpoints
+from .workspace.gitcmd import MINIMUM_GIT_VERSION, WorkspaceError, git_version, run_git
+from .workspace.repo import GITHUB_BASE
+
+# Unauthenticated, so it answers 401; that is a route, which is all we ask.
+ANTHROPIC_PROBE_URL = "https://api.anthropic.com/v1/models"
+
+_CONDITIONAL = "github conditional GET"
+_GIT_VERSION = "git version"
+_GIT_ROUTE = "git fetch route"
+#: An `ls-remote` that has not answered in half a minute is a blocked route,
+#: not a slow one, and the operator is waiting at a terminal.
+_LS_REMOTE_TIMEOUT = 30.0
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    """The outcome of one check, in a form an operator can act on."""
+
+    name: str
+    ok: bool
+    detail: str
+
+
+async def check_github(
+    client: GitHubClient, endpoints: RepoEndpoints
+) -> list[CheckResult]:
+    """Fetch all three watched endpoints, then re-fetch one conditionally."""
+    results: list[CheckResult] = []
+    revisit: tuple[str, str] | None = None
+    for endpoint, path in endpoints.all_paths().items():
+        name = f"github {endpoint}"
+        try:
+            result = await client.get(path)
+        except GitHubClientError as exc:
+            results.append(CheckResult(name, False, str(exc)))
+            continue
+        results.append(CheckResult(name, True, _budget(result)))
+        if revisit is None and result.etag is not None:
+            revisit = (path, result.etag)
+    results.append(await _check_conditional(client, revisit))
+    results.append(await _check_write_scope(client, endpoints))
+    return results
+
+
+async def _check_write_scope(
+    client: GitHubClient, endpoints: RepoEndpoints
+) -> CheckResult:
+    """Can this token post a review comment?
+
+    Read-only scope was sufficient while nothing published, and DESIGN.md
+    said so. It is not now: without write scope a review is polled for,
+    claimed, paid for and computed, and then fails on the last call -- the
+    most expensive possible way to find out about a misconfigured token.
+
+    An absent ``permissions`` object warns rather than fails. A fine-grained
+    token need not report one, and refusing to start over a field GitHub
+    chose not to send would make the check worse than no check.
+    """
+    name = "github write scope"
+    try:
+        result = await client.get(endpoints.repository())
+    except GitHubClientError as exc:
+        return CheckResult(name, False, str(exc))
+    permissions = (
+        result.data.get("permissions") if isinstance(result.data, dict) else None
+    )
+    if not isinstance(permissions, dict) or "push" not in permissions:
+        return CheckResult(
+            name, True, "could not determine write scope from this token"
+        )
+    if not permissions["push"]:
+        return CheckResult(
+            name, False, "the token has no write access; the publisher cannot post"
+        )
+    return CheckResult(name, True, "the token may post comments")
+
+
+async def check_git(repo: str, base_url: str = GITHUB_BASE) -> list[CheckResult]:
+    """Is git new enough, and does the fetch route work?
+
+    The version comes first because it is what makes the rest of the
+    checkout's hardening real: below 2.32, ``GIT_CONFIG_GLOBAL`` is ignored
+    *without an error*, so the control that neutralises the host's gitconfig
+    is simply absent while appearing to be in force.
+
+    The route is a second question from the poller's. `github.com` and
+    `api.github.com` are different hosts and, on an allowlist-based
+    firewall, different rules -- so the poller's route answering says
+    nothing at all about this one.
+    """
+    results: list[CheckResult] = []
+    try:
+        version = await git_version()
+    except WorkspaceError as exc:
+        results.append(CheckResult(_GIT_VERSION, False, str(exc)))
+        return results
+
+    found = ".".join(str(part) for part in version)
+    wanted = ".".join(str(part) for part in MINIMUM_GIT_VERSION)
+    results.append(
+        CheckResult(
+            _GIT_VERSION,
+            version >= MINIMUM_GIT_VERSION,
+            f"found {found}, need at least {wanted}",
+        )
+    )
+
+    url = f"{base_url.rstrip('/')}/{repo}.git"
+    try:
+        await run_git("ls-remote", "--heads", url, timeout=_LS_REMOTE_TIMEOUT)
+    except WorkspaceError as exc:
+        results.append(CheckResult(_GIT_ROUTE, False, str(exc)))
+    else:
+        results.append(CheckResult(_GIT_ROUTE, True, f"{url} answers"))
+    return results
+
+
+async def check_anthropic(client: httpx.AsyncClient) -> CheckResult:
+    """Prove the route to Anthropic exists; any HTTP status counts."""
+    name = "anthropic reachable"
+    try:
+        response = await client.get(ANTHROPIC_PROBE_URL)
+    except httpx.HTTPError as exc:
+        return CheckResult(name, False, f"no route: {exc}")
+    return CheckResult(name, True, f"HTTP {response.status_code}")
+
+
+async def run_checks(config: Config, token: str) -> list[CheckResult]:
+    """Run every check for the repository ``config`` names."""
+    endpoints = RepoEndpoints(config.github.owner, config.github.name)
+    github = GitHubClient(token)
+    anthropic = httpx.AsyncClient()
+    try:
+        results = await check_github(github, endpoints)
+        results.extend(await check_git(config.github.repo))
+        results.append(await check_anthropic(anthropic))
+    finally:
+        await github.aclose()
+        await anthropic.aclose()
+    return results
+
+
+async def _check_conditional(
+    client: GitHubClient, revisit: tuple[str, str] | None
+) -> CheckResult:
+    """Re-request a path with its own ETag and insist on a 304."""
+    if revisit is None:
+        return CheckResult(_CONDITIONAL, False, "no endpoint returned an ETag")
+    path, etag = revisit
+    try:
+        result = await client.get(path, etag=etag)
+    except GitHubClientError as exc:
+        return CheckResult(_CONDITIONAL, False, str(exc))
+    if result.changed:
+        return CheckResult(
+            _CONDITIONAL,
+            False,
+            "got 200, not 304 -- an ETag is being stripped in transit, "
+            "or the repository changed between the two requests",
+        )
+    return CheckResult(_CONDITIONAL, True, "304 Not Modified")
+
+
+def _budget(result: PollResult) -> str:
+    if result.rate_limit is None:
+        return "no rate-limit headers"
+    return f"{result.rate_limit.remaining}/{result.rate_limit.limit} remaining"
+
+
+def report(results: Sequence[CheckResult]) -> int:
+    """Print every result and return the exit status: 1 if any failed."""
+    for result in results:
+        print(f"{'PASS' if result.ok else 'FAIL'}  {result.name}: {result.detail}")
+    failed = [result.name for result in results if not result.ok]
+    if failed:
+        print(f"\n{len(failed)} check(s) failed: {', '.join(failed)}", file=sys.stderr)
+        return 1
+    return 0