diffbutler 0.6.0__tar.gz → 0.6.1__tar.gz

{diffbutler-0.6.0 → diffbutler-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: diffbutler
-Version: 0.6.0
+Version: 0.6.1
 Summary: A terminal dashboard for human-directed AI code reviews.
 Keywords: code-review,github,terminal,ai
 License-Expression: MIT
@@ -34,7 +34,7 @@ Keep track of what each pull request needs next: AI review, your review, or auth
 changes. Start an AI review, discuss its findings in the agent's own session, and
 finish your review in the browser.
 
-![DiffButler dashboard showing pull requests and the next review action](diffbutler.png)
+![DiffButler dashboard showing pull requests and the next review action](https://raw.githubusercontent.com/heikkitoivonen/diffbutler/main/diffbutler.png)
 
 ## Install
 
@@ -108,8 +108,8 @@ The dashboard shows active reviews, including followed PRs whose GitHub review
 requests have disappeared after you posted feedback. Waiting-for-author reviews
 stay visible across refreshes and restarts. If an approved PR receives new commits,
 it reappears as `done+` at the end of the queue without starting another AI review.
-Authenticated polling slows when API quota is scarce and speeds back up when it
-recovers, accounting for refresh cost and time until the quota resets.
+Polling spreads API quota evenly until it resets, leaving 10% in reserve: it slows
+when quota is scarce or refreshes are costly and speeds back up when quota recovers.
 
 Select a PR with the arrow keys, then work through the review:
 
@@ -128,7 +128,8 @@ Select a PR with the arrow keys, then work through the review:
    starts a new run with the current reviewer and replaces the current review details.
    Ask questions and explicitly tell the agent which comments to post, if any.
 3. Exit the agent to return to the dashboard, which refreshes activity from GitHub.
-   Press `w` if you are waiting for author changes, or `o` to review in your browser.
+   Press `o` to open the PR in your browser at any time; it does not change the state.
+   Press `w` if you are waiting for author changes, or `a` once you are ready to approve.
 4. After approving on GitHub, press `m` to mark the task complete locally. DiffButler
    also detects your approval, closure, or merge and cleans up owned session resources
    while retaining review history.
@@ -140,7 +141,7 @@ uses the agent's [native permission controls](docs/native-reviews.md#native-perm
 and read-only review instructions; source sent to the agent may go to its model provider.
 
 - `/`: Filter the queue.
-- `a`: Toggle monitoring all open PRs in configured repositories.
+- `A`: Toggle monitoring all open PRs in configured repositories.
 - `b`: Browse accessible PRs and follow one.
 - `R`: Find and add a PR by link or number, then review it; choose a repository if
   the number is ambiguous. Explicitly selected PRs bypass queue visibility filters.
@@ -161,6 +162,29 @@ PRs assigned to you are also hidden by default, even when
 you are requested directly or through a team. Set `include_assigned_prs = true` in
 `[ui]` to include them, or select one with `R`.
 
+### How PRs move through the board
+
+Solid arrows are actions you take; dashed arrows happen automatically.
+
+How a PR arrives:
+
+![Flow diagram: review requests and all-PR monitoring reach the board through polling, browsing adds followed PRs, and your own or assigned PRs are hidden unless enabled; R adds a PR directly and starts a review. New PRs start as pending unless already approved, closed, or merged.](https://raw.githubusercontent.com/heikkitoivonen/diffbutler/main/docs/diagrams/pr-arrival.svg)
+
+How its status changes:
+
+![State diagram: r queues a review, the worker runs it, and the result is approve or check; w, a, and m move a PR between author, approve, and done; Ctrl+C or a failed agent returns it to pending; GitHub commits, your submitted reviews, and closes or merges move it automatically; new commits after approval show done+.](https://raw.githubusercontent.com/heikkitoivonen/diffbutler/main/docs/diagrams/pr-status.svg)
+
+`r`, `a`, `w`, and `m` work from any open status, not only along the arrows shown,
+though `r` refuses while a review is already queued or running. New commits on a
+`done+` PR keep it `done+` rather than returning it to `pending`.
+
+How it leaves:
+
+![Flow diagram: m, your approval, or a close or merge moves a PR to done and history; k removes it until a refresh finds it still requested or monitored; becoming an assignee hides it unless include_assigned_prs is set or it was selected with R.](https://raw.githubusercontent.com/heikkitoivonen/diffbutler/main/docs/diagrams/pr-exit.svg)
+
+A PR stays on the board when its review request is withdrawn; press `k` to remove it.
+A PR you only followed stays away after `k` until you follow it again.
+
 ## Reset
 
 Close running DiffButler sessions, then run:

{diffbutler-0.6.0 → diffbutler-0.6.1}/README.md

@@ -6,7 +6,7 @@ Keep track of what each pull request needs next: AI review, your review, or auth
 changes. Start an AI review, discuss its findings in the agent's own session, and
 finish your review in the browser.
 
-![DiffButler dashboard showing pull requests and the next review action](diffbutler.png)
+![DiffButler dashboard showing pull requests and the next review action](https://raw.githubusercontent.com/heikkitoivonen/diffbutler/main/diffbutler.png)
 
 ## Install
 
@@ -80,8 +80,8 @@ The dashboard shows active reviews, including followed PRs whose GitHub review
 requests have disappeared after you posted feedback. Waiting-for-author reviews
 stay visible across refreshes and restarts. If an approved PR receives new commits,
 it reappears as `done+` at the end of the queue without starting another AI review.
-Authenticated polling slows when API quota is scarce and speeds back up when it
-recovers, accounting for refresh cost and time until the quota resets.
+Polling spreads API quota evenly until it resets, leaving 10% in reserve: it slows
+when quota is scarce or refreshes are costly and speeds back up when quota recovers.
 
 Select a PR with the arrow keys, then work through the review:
 
@@ -100,7 +100,8 @@ Select a PR with the arrow keys, then work through the review:
    starts a new run with the current reviewer and replaces the current review details.
    Ask questions and explicitly tell the agent which comments to post, if any.
 3. Exit the agent to return to the dashboard, which refreshes activity from GitHub.
-   Press `w` if you are waiting for author changes, or `o` to review in your browser.
+   Press `o` to open the PR in your browser at any time; it does not change the state.
+   Press `w` if you are waiting for author changes, or `a` once you are ready to approve.
 4. After approving on GitHub, press `m` to mark the task complete locally. DiffButler
    also detects your approval, closure, or merge and cleans up owned session resources
    while retaining review history.
@@ -112,7 +113,7 @@ uses the agent's [native permission controls](docs/native-reviews.md#native-perm
 and read-only review instructions; source sent to the agent may go to its model provider.
 
 - `/`: Filter the queue.
-- `a`: Toggle monitoring all open PRs in configured repositories.
+- `A`: Toggle monitoring all open PRs in configured repositories.
 - `b`: Browse accessible PRs and follow one.
 - `R`: Find and add a PR by link or number, then review it; choose a repository if
   the number is ambiguous. Explicitly selected PRs bypass queue visibility filters.
@@ -133,6 +134,29 @@ PRs assigned to you are also hidden by default, even when
 you are requested directly or through a team. Set `include_assigned_prs = true` in
 `[ui]` to include them, or select one with `R`.
 
+### How PRs move through the board
+
+Solid arrows are actions you take; dashed arrows happen automatically.
+
+How a PR arrives:
+
+![Flow diagram: review requests and all-PR monitoring reach the board through polling, browsing adds followed PRs, and your own or assigned PRs are hidden unless enabled; R adds a PR directly and starts a review. New PRs start as pending unless already approved, closed, or merged.](https://raw.githubusercontent.com/heikkitoivonen/diffbutler/main/docs/diagrams/pr-arrival.svg)
+
+How its status changes:
+
+![State diagram: r queues a review, the worker runs it, and the result is approve or check; w, a, and m move a PR between author, approve, and done; Ctrl+C or a failed agent returns it to pending; GitHub commits, your submitted reviews, and closes or merges move it automatically; new commits after approval show done+.](https://raw.githubusercontent.com/heikkitoivonen/diffbutler/main/docs/diagrams/pr-status.svg)
+
+`r`, `a`, `w`, and `m` work from any open status, not only along the arrows shown,
+though `r` refuses while a review is already queued or running. New commits on a
+`done+` PR keep it `done+` rather than returning it to `pending`.
+
+How it leaves:
+
+![Flow diagram: m, your approval, or a close or merge moves a PR to done and history; k removes it until a refresh finds it still requested or monitored; becoming an assignee hides it unless include_assigned_prs is set or it was selected with R.](https://raw.githubusercontent.com/heikkitoivonen/diffbutler/main/docs/diagrams/pr-exit.svg)
+
+A PR stays on the board when its review request is withdrawn; press `k` to remove it.
+A PR you only followed stays away after `k` until you follow it again.
+
 ## Reset
 
 Close running DiffButler sessions, then run:

{diffbutler-0.6.0 → diffbutler-0.6.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "diffbutler"
-version = "0.6.0"
+version = "0.6.1"
 description = "A terminal dashboard for human-directed AI code reviews."
 readme = "README.md"
 requires-python = ">=3.14"

{diffbutler-0.6.0 → diffbutler-0.6.1}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "diffbutler"
-version = "0.6.0"
+version = "0.6.1"
 description = "A terminal dashboard for human-directed AI code reviews."
 readme = "README.md"
 requires-python = ">=3.14"

{diffbutler-0.6.0 → diffbutler-0.6.1}/src/diffbutler/config/default.toml

@@ -5,7 +5,7 @@ reviewers = []
 
 [general]
 # Minimum: 60 seconds with authenticated accounts, 600 with any public account.
-# poll_interval_s = 600 # Override the minimum; low authenticated quota slows polling.
+# poll_interval_s = 600 # Override the minimum; low quota slows polling.
 max_concurrent_reviews = 2
 # Omit workspace_root to follow $XDG_DATA_HOME/diffbutler/reviews
 # (default ~/.local/share/diffbutler/reviews).
@@ -37,7 +37,7 @@ checkout = "worktree" # Native reviews currently use pinned source snapshots.
 include_own_prs = false # Set true to review PRs authored by your account.
 include_assigned_prs = false # Set true to review PRs assigned to your account.
 columns = ["number", "title", "author", "state"]
-sort_by = "attention"
+sort_by = "state"
 sort_desc = true
 preview_pane = true
 default_filter = "active"

{diffbutler-0.6.0 → diffbutler-0.6.1}/src/diffbutler/config/settings.py

@@ -125,7 +125,7 @@ class UI(Section):
             "state",
         ]
     )
-    sort_by: str = "attention"
+    sort_by: str = "state"
     sort_desc: bool = True
     preview_pane: bool = True
     default_filter: Literal[

{diffbutler-0.6.0 → diffbutler-0.6.1}/src/diffbutler/core/application.py

@@ -90,8 +90,13 @@ async def browse_configured(
         return await service.browse_prs(query, cursor)
 
 
-async def review_targets_configured(path: Path | None, value: str) -> tuple[ReviewTarget, ...]:
-    """Resolve without following PRs or requesting any AI work."""
+async def review_targets_configured(
+    path: Path | None, value: str, *, deadline: float | None = None
+) -> tuple[ReviewTarget, ...]:
+    """Resolve without following PRs or requesting any AI work.
+
+    deadline is the event-loop time by which number lookups must finish.
+    """
     value = value.strip()
     numeric = re.fullmatch(r"#?([1-9][0-9]*)", value)
     if not numeric and not value.startswith("https://"):
@@ -108,7 +113,9 @@ async def review_targets_configured(path: Path | None, value: str) -> tuple[Revi
                 continue
             async with remote_service(store, settings, index) as service:
                 if numeric:
-                    prs = await numbered_prs(service.forge, config.repositories, int(numeric[1]))
+                    prs = await numbered_prs(
+                        service.forge, config.repositories, int(numeric[1]), deadline=deadline
+                    )
                 else:
                     try:
                         ref = service.forge.ref(value)

{diffbutler-0.6.0 → diffbutler-0.6.1}/src/diffbutler/core/dashboard.py

@@ -54,7 +54,7 @@ class DashboardRow(BaseModel):
 
 
 class SortSpec(BaseModel):
-    column: str = "attention"
+    column: str = "state"
     descending: bool = True
 
 
@@ -274,6 +274,12 @@ async def state_configured(
         return row.tracked.pull_request.url
 
 
+async def url_configured(path: Path | None, value: str, login: str | None) -> str:
+    """Resolve a tracked PR's URL without changing its state."""
+    async with local_store(path) as (queue, _):
+        return (await resolve_local(queue, value, login)).tracked.pull_request.url
+
+
 async def refresh_configured(path: Path | None, value: str, login: str | None) -> PullRequestRow:
     """Refresh one PR, preserving a durable pending indication on any failure."""
     async with local_store(path) as (queue, settings):

{diffbutler-0.6.0 → diffbutler-0.6.1}/src/diffbutler/core/polling.py

@@ -78,17 +78,15 @@ class Poller:
                     if previous != (budget.interval, budget.wait_for_reset):
                         logging.getLogger(__name__).info(
                             "Polling adjusted host=%s login=%s resource=%s interval_s=%.1f "
-                            "remaining=%d limit=%d reset_in_s=%.1f cost=%.1f "
-                            "external_calls_per_s=%.3f wait_for_reset=%s",
+                            "remaining=%d limit=%d reset_in_s=%.1f cost=%.1f wait_for_reset=%s",
                             sample.host,
-                            sample.login,
+                            sample.login or "(anonymous)",
                             sample.quota.resource,
                             budget.interval,
                             sample.quota.remaining,
                             sample.quota.limit,
                             sample.quota.reset_at.timestamp() - self.now(),
                             budget.cost,
-                            budget.external_rate,
                             budget.wait_for_reset,
                         )
                 self.changed.set()

diffbutler-0.6.1/src/diffbutler/core/pr_lookup.py

@@ -0,0 +1,83 @@
+"""Read-only resolution of explicit review targets across repository scopes."""
+
+import asyncio
+import math
+from dataclasses import dataclass
+
+from diffbutler.domain.forge import Account, PRRef, PullRequest, repository_matches
+from diffbutler.forges.base import ForgeError, ReadForge
+
+
+@dataclass(frozen=True)
+class ReviewTarget:
+    forge_index: int
+    account: Account
+    pull_request: PullRequest
+
+
+async def open_pr(forge: ReadForge, ref: PRRef, *, listed: bool = False) -> PullRequest | None:
+    """Open PR at ref, or None when it is missing or, for listed repositories, unreadable."""
+    try:
+        pr = await forge.get_pull_request(ref)
+    except ForgeError as exc:
+        # A listed repository can deny PR reads (disabled, blocked, or metadata-only
+        # access); rate limits carry retry_after and still fail the lookup.
+        if exc.status == 404 or (listed and exc.status in {403, 451} and exc.retry_after is None):
+            return None
+        raise
+    if pr.ref != ref:
+        raise ForgeError("Forge returned a different PR identity")
+    return pr if pr.state == "open" else None
+
+
+# Reads kept in reserve after a scan: the account check, then following the chosen
+# PR (account checks, the PR, and its first activity pages) on a fresh client.
+FOLLOW_UP_READS = 10
+
+
+def check_budget(forge: ReadForge, number: int, reads: int, deadline: float | None) -> None:
+    """Fail before reads that would reach low-quota pacing or outlast the deadline."""
+    budget = forge.read_budget()
+    if budget.requests is not None and reads + FOLLOW_UP_READS > budget.requests:
+        raise ForgeError(
+            f"Checking PR #{number} in {reads} more repositories needs more requests "
+            f"than the forge's rate limit can spare ({budget.requests}); "
+            "enter the full PR link or retry after the limit resets"
+        )
+    if deadline is not None:
+        needed = (reads + FOLLOW_UP_READS) * budget.seconds_per_request
+        if needed > deadline - asyncio.get_running_loop().time():
+            raise ForgeError(
+                f"Checking PR #{number} in {reads} more repositories and following it "
+                f"would take about {math.ceil(needed)} seconds, longer than the lookup "
+                "allows; enter the full PR link"
+            )
+
+
+async def numbered_prs(
+    forge: ReadForge, repositories: list[str], number: int, *, deadline: float | None = None
+) -> tuple[PullRequest, ...]:
+    """Resolve exact numbers directly after expanding owner repository scopes.
+
+    deadline is an event-loop time. When owner scopes were listed, each read first
+    checks that the remaining reads fit the forge's spare quota and the deadline.
+    """
+    refs: dict[PRRef, bool] = {}
+    for repository in dict.fromkeys(repositories):
+        if not repository.endswith("/*"):
+            refs[forge.ref(f"{repository}#{number}")] = False
+            continue
+        for name in await forge.list_repositories(repository.removesuffix("/*")):
+            ref = forge.ref(f"{name}#{number}")
+            if ref.forge != forge.id or not repository_matches(repository, ref):
+                raise ForgeError("Forge returned a repository outside the requested owner")
+            refs.setdefault(ref, True)
+    budgeted = any(refs.values())
+    found: list[PullRequest] = []
+    for index, (ref, listed) in enumerate(refs.items()):
+        if budgeted:
+            # Rechecking before every read also covers retries that used extra quota.
+            check_budget(forge, number, len(refs) - index, deadline)
+        if pr := await open_pr(forge, ref, listed=listed):
+            found.append(pr)
+    return tuple(found)

{diffbutler-0.6.0 → diffbutler-0.6.1}/src/diffbutler/domain/forge.py

@@ -130,6 +130,14 @@ class RateLimit:
     reset_at: datetime
 
 
+@dataclass(frozen=True)
+class ReadBudget:
+    """Reads a forge can spare from its quota (None if unknown) and seconds per read."""
+
+    requests: int | None
+    seconds_per_request: float
+
+
 @dataclass(frozen=True)
 class ForgeHealth:
     account: Account

diffbutler-0.6.1/src/diffbutler/domain/polling.py

@@ -0,0 +1,67 @@
+"""Pure quota budgeting for read-only polling; timestamps are supplied by the caller."""
+
+from dataclasses import dataclass
+
+from diffbutler.domain.forge import RateLimit
+
+# Share of each quota left unspent by polling for interactive actions and other clients.
+RESERVE_SHARE = 0.1
+
+
+@dataclass(frozen=True)
+class PollQuota:
+    host: str
+    login: str  # Empty for anonymous access, which no GitHub login can collide with.
+    quota: RateLimit
+    requests: int
+    observed_at: float
+
+    @property
+    def key(self) -> tuple[str, str, str]:
+        return self.host, self.login.casefold(), self.quota.resource
+
+
+class QuotaBudget:
+    """Spreads one account/resource's spare quota evenly over the time until reset.
+
+    Each update recomputes the interval from the latest headers, so consumption by
+    other clients is reflected in the next refresh's remaining count.
+    """
+
+    def __init__(self, minimum: float) -> None:
+        self.minimum = minimum
+        self.interval = minimum
+        self.sample: PollQuota | None = None
+        self.average_cost = 0.0
+        self.cost = 0.0
+        self.wait_for_reset = False
+
+    def update(self, sample: PollQuota, *, successful: bool, now: float) -> None:
+        self.sample = sample
+        requests = max(1, sample.requests)
+        if not self.average_cost:
+            self.average_cost = requests
+        elif successful:
+            self.average_cost = 0.5 * requests + 0.5 * self.average_cost
+        else:
+            # An incomplete refresh is not evidence that the queue became cheaper.
+            self.average_cost = max(self.average_cost, requests)
+        cost = max(requests, self.average_cost)
+        self.cost = cost if successful else max(self.cost, cost)
+
+        quota = sample.quota
+        remaining_time = max(0, quota.reset_at.timestamp() - now)
+        usable = quota.remaining - RESERVE_SHARE * quota.limit
+        self.wait_for_reset = usable < self.cost and remaining_time > 0
+        budget_interval = self.cost * remaining_time / usable if usable > 0 else 0
+        self.interval = max(self.minimum, budget_interval)
+
+    def next_start(self, started: float, now: float) -> float:
+        assert self.sample is not None
+        reset = self.sample.quota.reset_at.timestamp() + 1
+        if now >= reset:
+            # Wake to get fresh headers, even if the previous interval was very long.
+            return started + self.minimum
+        if self.wait_for_reset:
+            return reset
+        return min(started + self.interval, reset)

{diffbutler-0.6.0 → diffbutler-0.6.1}/src/diffbutler/forges/base.py

@@ -11,6 +11,7 @@ from diffbutler.domain.forge import (
     PRQuery,
     PRRef,
     PullRequest,
+    ReadBudget,
 )
 from diffbutler.domain.sync import ReviewActivity
 
@@ -32,6 +33,7 @@ class ReadForge(Protocol):
     async def whoami(self) -> Account: ...
     async def list_review_requests(self) -> Discovery: ...
     async def list_repositories(self, owner: str) -> tuple[str, ...]: ...
+    def read_budget(self) -> ReadBudget: ...
     async def search_pull_requests(self, query: PRQuery, cursor: str | None = None) -> PRPage: ...
     async def get_pull_request(self, ref: PRRef) -> PullRequest: ...
     def ref(self, value: str) -> PRRef: ...

{diffbutler-0.6.0 → diffbutler-0.6.1}/src/diffbutler/forges/diagnostics.py

@@ -3,7 +3,7 @@
 from collections.abc import Generator
 from contextlib import contextmanager
 from contextvars import ContextVar
-from dataclasses import dataclass, field
+from dataclasses import dataclass, field, replace
 
 from diffbutler.domain.forge import RateLimit
 from diffbutler.domain.polling import PollQuota
@@ -34,25 +34,24 @@ class RateLimitObservations:
     cooldown_until: float = 0
 
     def quotas(self) -> tuple[PollQuota, ...]:
-        result: dict[tuple[str, str, str], PollQuota] = {}
-        for (source, _), observed in self.resources.items():
-            if not source.authenticated or source.login is None or observed.latest is None:
+        latest: dict[tuple[str, str, str], PollQuota] = {}
+        requests: dict[tuple[str, str, str], int] = {}
+        for (source, resource), observed in self.resources.items():
+            # Anonymous clients on one host share its per-IP quota.
+            login = source.login if source.authenticated else ""
+            if login is None:
+                continue
+            key = source.host, login.casefold(), resource
+            requests[key] = requests.get(key, 0) + observed.requests
+            if observed.latest is None:
                 continue
             sample = PollQuota(
-                source.host, source.login, observed.latest, observed.requests, observed.observed_at
+                source.host, login, observed.latest, observed.requests, observed.observed_at
             )
-            previous = result.get(sample.key)
-            if previous is not None:
-                latest = sample if sample.observed_at >= previous.observed_at else previous
-                sample = PollQuota(
-                    latest.host,
-                    latest.login,
-                    latest.quota,
-                    sample.requests + previous.requests,
-                    latest.observed_at,
-                )
-            result[sample.key] = sample
-        return tuple(result.values())
+            previous = latest.get(key)
+            if previous is None or sample.observed_at >= previous.observed_at:
+                latest[key] = sample
+        return tuple(replace(sample, requests=requests[key]) for key, sample in latest.items())
 
 
 _observations: ContextVar[RateLimitObservations | None] = ContextVar(

{diffbutler-0.6.0 → diffbutler-0.6.1}/src/diffbutler/forges/github/adapter.py

@@ -14,6 +14,7 @@ from diffbutler.domain.forge import (
     PRQuery,
     PRRef,
     PullRequest,
+    ReadBudget,
     RequestedPR,
     TeamMembership,
     identity_part,
@@ -152,6 +153,9 @@ class GitHubForge:
     async def list_repositories(self, owner: str) -> tuple[str, ...]:
         return await list_repositories(self.http, owner)
 
+    def read_budget(self) -> ReadBudget:
+        return self.http.read_budget()
+
     def search_ref(self, value: str) -> PRRef:
         url = self.http.checked_url(value)
         path = url.path.removeprefix(self.http.base_url.path)

{diffbutler-0.6.0 → diffbutler-0.6.1}/src/diffbutler/forges/github/http.py

@@ -14,7 +14,8 @@ from typing import ClassVar
 
 import httpx
 
-from diffbutler.domain.forge import RateLimit
+from diffbutler.domain.forge import RateLimit, ReadBudget
+from diffbutler.domain.polling import RESERVE_SHARE
 from diffbutler.forges.base import ForgeError
 from diffbutler.forges.diagnostics import (
     RateLimitSource,
@@ -53,6 +54,8 @@ class ReadResponse:
 class GitHubHTTP:
     DEFAULT_REQUEST_INTERVAL: ClassVar[float] = 1.0
     AUTHENTICATED_REQUEST_INTERVAL: ClassVar[float] = 0.1
+    # Below polling's reserve, pacing spreads the remaining requests until reset.
+    LOW_QUOTA_SHARE: ClassVar[float] = RESERVE_SHARE
 
     def __init__(
         self,
@@ -106,6 +109,8 @@ class GitHubHTTP:
         self.limits: dict[str, RateLimit] = {}
         self.cache: OrderedDict[str, ReadResponse] = OrderedDict()
         self.blocked_until = 0.0
+        self.responses = 0
+        self.response_seconds = 0.0
         self.lock = asyncio.Lock()
 
     async def paced_get(self, url: httpx.URL, headers: dict[str, str]) -> httpx.Response:
@@ -132,7 +137,7 @@ class GitHubHTTP:
                 interval = self.request_interval
                 if resource == "search" and not self.authenticated:
                     interval = max(interval, 6.1)
-                if limit and 0 < limit.remaining <= limit.limit * 0.2:
+                if limit and 0 < limit.remaining <= limit.limit * self.LOW_QUOTA_SHARE:
                     interval = max(
                         interval, (limit.reset_at.timestamp() - previous) / limit.remaining
                     )
@@ -161,6 +166,8 @@ class GitHubHTTP:
         except httpx.RequestError:
             logging.getLogger(__name__).exception("GitHub transport failed resource=%s", resource)
             raise
+        self.responses += 1
+        self.response_seconds += time.monotonic() - began
         self.record_limit(response.headers)
         quota = self.limits.get(resource)
         logging.getLogger(__name__).log(
@@ -177,6 +184,15 @@ class GitHubHTTP:
         )
         return response
 
+    def read_budget(self) -> ReadBudget:
+        """Core reads available before low-quota pacing starts, and observed seconds per read."""
+        limit = self.limits.get("core")
+        spare = None
+        if limit and limit.reset_at.timestamp() > self.now():
+            spare = max(0, limit.remaining - math.ceil(limit.limit * self.LOW_QUOTA_SHARE))
+        latency = self.response_seconds / self.responses if self.responses else 0.0
+        return ReadBudget(spare, max(self.request_interval, latency))
+
     def checked_url(self, value: str | httpx.URL) -> httpx.URL:
         try:
             url = self.base_url.join(value)