orbi-cli 0.7.5__tar.gz → 0.7.6__tar.gz

{orbi_cli-0.7.5/src/orbi_cli.egg-info → orbi_cli-0.7.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: orbi-cli
-Version: 0.7.5
+Version: 0.7.6
 Summary: Orbi — local AI development worker: claims GitHub Issues, runs Pi in isolated worktrees, and delivers PRs (GitHub Issues + labels are the only state store).
 Author: xqliu
 License-Expression: AGPL-3.0-only OR LicenseRef-Sustainable-Use-1.0

{orbi_cli-0.7.5 → orbi_cli-0.7.6}/pyproject.toml

@@ -44,7 +44,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "orbi-cli"
-version = "0.7.5"
+version = "0.7.6"
 description = "Orbi — local AI development worker: claims GitHub Issues, runs Pi in isolated worktrees, and delivers PRs (GitHub Issues + labels are the only state store)."
 readme = "README.md"
 requires-python = ">=3.14"

{orbi_cli-0.7.5 → orbi_cli-0.7.6}/src/orbi/__init__.py

@@ -18,4 +18,4 @@ the package would shadow the installed package for every process with
 the checkout root on sys.path. The direct-execution compatibility entry
 is `python3 -m orbi.cli` (development path only).
 """
-__version__ = "0.7.5"
+__version__ = "0.7.6"

{orbi_cli-0.7.5 → orbi_cli-0.7.6}/src/orbi/failure.py

@@ -16,14 +16,17 @@ ignored (`parse` returns `None`) instead of failing the resume path.
 new code is a deliberate contract change here and in `docs/workflow.mdx`
 (EN + ZH); `classify` maps an exception to them and an unknown one to
 `unclassified`, never to a missing block, so the prose cannot drift.
+A failure that knows its reason at the source carries the record itself
+(`BaseBranchMissingError`); the reporter uses it as it is.
 """
 from __future__ import annotations
 
 import dataclasses
 import json
 import re
+import subprocess
 
-from orbi import language
+from orbi import gh_response, language
 
 SCHEMA_VERSION = 1
 
@@ -45,7 +48,10 @@ REASON_CODES = frozenset({
     # A transient GitHub API/server failure (5xx, secondary rate limit,
     # `GraphQL: Something went wrong`): the same operation may succeed.
     "github_transient",
-    # The delivery's own tests failed and the code must change.
+    # Legacy only (Issue #1759): nothing in production raises it any
+    # more. The runner runs no tests of its own, and a red CI check is
+    # routed by the `GateCIFailure` type. It stays in the closed set so
+    # an already-written comment still parses; `classify` never produces it.
     "tests_failed",
     # The bounded review/fix budget is spent — a human decision.
     "review_budget_exhausted",
@@ -91,11 +97,42 @@ class Failure:
     outcome: str = "blocked"
     schema: int = SCHEMA_VERSION
 
+    def with_outcome(self, outcome: str) -> Failure:
+        """The same record for another delivery outcome.
+
+        A failure that decided its reason at the source (Issue #1756)
+        carries the record already; the caller only supplies the
+        outcome, never a re-derivation from the message.
+        """
+        return dataclasses.replace(self, outcome=outcome)
+
 
 class FailureError(ValueError):
     """A failure block is present in the body but cannot be parsed."""
 
 
+class ReleaseGateWaitTimeout(RuntimeError):
+    """A release gate spent its bounded wait budget without a decision.
+
+    The release state machine reports this wait as `blocked`: the budget
+    is bounded on purpose, so the next step is a human's, never the
+    automatic requeue a transient GitHub failure gets (Issue #1760). The
+    classification reads THIS type, never the words of the message.
+    """
+
+
+class GitHubPermissionDenied(RuntimeError):
+    """A GitHub 403 with quota left: the credential lacks the permission.
+
+    The release gate receives that status from `gh_response` but reports
+    it with its own reader-facing sentence (the one naming the missing
+    `Checks:read` scope), so the meaning travels on the TYPE: `classify`
+    reads the type, never the sentence — which is why the broad
+    `credential` word could be dropped from the text markers without
+    losing the permission repair (Issue #1760).
+    """
+
+
 def render(record: Failure) -> str:
     """Render the single hidden v1 block for one failure.
 
@@ -206,12 +243,20 @@ _PROVIDER_QUOTA_RE = re.compile(
     r"\b429\b|quota|resource_exhausted|retry in|usage limit has been reached",
     re.IGNORECASE,
 )
-# The word markers of a provider authentication failure. `pi_process`'s
-# early-exit classifier (`_classify_startup_exit`) matches this SAME
-# tuple (plus the 401/403 status codes), so the two classifications
-# cannot drift into two lists (Issue #1465).
+# The word markers `pi_process`'s early-exit classifier
+# (`_classify_startup_exit`) matches, plus the 401/403 status codes: the
+# provider's own words stay the Pi startup classification's (Issue #1465),
+# and `failure` reads them from the one regex below.
 PROVIDER_AUTH_WORDS = ("unauthorized", "forbidden", "api key")
 
+# The text-only credential markers. GitHub failures no longer read this
+# one: they carry the response status (`gh_response`), which is exact,
+# while `forbidden` and `credential` were broad enough to match a branch
+# or check name inside the command's argv (Issue #1760). The remaining
+# markers serve the Pi / model-provider detail, which only gives text
+# (Issue #1465): its 401 shapes, its rejected-key sentences and
+# `unauthorized`; `forbidden` stays in `PROVIDER_AUTH_WORDS` for
+# `pi_process`'s own startup classifier, which is not this regex.
 _CREDENTIAL_MISSING_RE = re.compile(
     r"bad credentials"
     r"|(?:http|status)\s+401\b"
@@ -221,8 +266,7 @@ _CREDENTIAL_MISSING_RE = re.compile(
     r"|(?:^|[\s\"'(])401:"
     r"|authentication (?:failed|required|fails)"
     r"|incorrect api key"
-    r"|" + "|".join(re.escape(word) for word in PROVIDER_AUTH_WORDS)
-    + r"|credential",
+    r"|unauthorized",
     re.IGNORECASE,
 )
 # The explicit GitHub rejection when a push creates or updates an
@@ -244,23 +288,34 @@ _WORKFLOW_PERMISSION_RE = re.compile(
 # terminal progress scene and the short milestone; only the last
 # sentence differs by whether a delivery PR already exists.
 _WORKFLOW_PERMISSION_CAUSE_KEY = "failure.workflow_cause"
-_TESTS_FAILED_RE = re.compile(
-    r"\btests? failed\b|\d+ failed", re.IGNORECASE,
-)
-# Git's answer to `git fetch origin <branch>` when the remote has no such
-# branch (Issue #1749): the two wordings real Git emits, and nothing else —
-# a generic fetch failure keeps its existing classification.
-_BASE_BRANCH_MISSING_RE = re.compile(
-    r"could ?n['o]t find remote ref", re.IGNORECASE,
-)
+# The remaining text-only transient markers: network-level failures and
+# GitHub's own server sentences. This set names no timeout — a GitHub
+# request reports its status, and a real transport timeout IS a
+# `subprocess.TimeoutExpired` (Issue #1760).
 _GITHUB_TRANSIENT_RE = re.compile(
     r"http 5\d\d|http 429|rate limit|"
     r"something went wrong while executing your query|"
     r"internal server error|connection reset|connection refused|"
-    r"temporary failure in name resolution|network is unreachable|"
-    r"timed out|timeout",
+    r"temporary failure in name resolution|network is unreachable",
     re.IGNORECASE,
 )
+# A non-GitHub subprocess — a Pi session, a Git fetch/push — reports a
+# timeout in its own words and gives neither a status nor a timeout type:
+# there the wording is all that exists (the same text-only carve-out the
+# provider failure reasons keep, Issue #1465/#1760).
+_TEXT_TIMEOUT_RE = re.compile(r"timed out|timeout", re.IGNORECASE)
+
+
+def _timeout_is_text_only(error: BaseException | None) -> bool:
+    """Whether only the failure's text can say it was a timeout.
+
+    `subprocess.TimeoutExpired` IS a timeout (decided by type) and a
+    GitHub request reports its status, so neither reads the wording; a
+    non-gh subprocess (Pi, `git fetch`/`git push`) has only its output.
+    """
+    command = getattr(error, "cmd", None)
+    return isinstance(command, list) and command[:1] != ["gh"]
+
 
 # reason_code -> (action_code, retry_safe). `retry_safe` is whether a
 # plain re-queue can succeed WITHOUT a human repair: a transient GitHub
@@ -278,36 +333,87 @@ DISPOSITIONS: dict[str, tuple[str, bool]] = {
 }
 
 
+class BaseBranchMissingError(RuntimeError):
+    """The configured base branch does not exist on the remote (Issue #1756).
+
+    Raised by the first delivery step `freeze_base` → `fetch_base_ref`
+    only after the fetch failed AND the remote itself answered
+    `git ls-remote --heads` with nothing: the fact is decided at the
+    source, so no consumer has to read Git's error text — Git localizes
+    it (`LANG` / `LC_MESSAGES`), and a text match would classify the
+    same failure differently on a non-English host.
+
+    `base_branch` is the CONFIGURED branch and `failure_record` is the
+    record the failure report uses as it is; the text classifier never
+    runs for this failure. `stderr` keeps the failed fetch's own output
+    as evidence: `_failure_detail` reads it into the run details, so the
+    reader still sees what Git said without it deciding anything
+    (Issues #1749, #1753).
+    """
+
+    def __init__(self, base_branch: str, *, stderr: str | None = None):
+        super().__init__(
+            f"base branch {base_branch!r} does not exist on origin",
+        )
+        self.base_branch = base_branch
+        self.stderr = stderr
+        action_code, retry_safe = DISPOSITIONS["base_branch_missing"]
+        self.failure_record = Failure(
+            reason_code="base_branch_missing",
+            action_code=action_code,
+            retry_safe=retry_safe,
+        )
+
+
 def classify(detail: str, *, outcome: str = "blocked",
              provider_quota: bool = False, review_budget: bool = False,
              human_decision: bool = False,
-             unrecoverable: bool = False) -> Failure:
+             unrecoverable: bool = False,
+             error: BaseException | None = None) -> Failure:
     """Map one delivery exception to the machine-readable failure record.
 
     The caller supplies the type-derived flags (the runner owns the
-    exception classes); an explicit type wins over the message markers,
-    and every marker that is not recognized falls through to
-    `unclassified`, so the block is never omitted. The mapping is the
-    single source both the comment block and the reader-facing
-    Action/Reason rendering use.
+    exception classes) and, when it has one, the failing exception itself
+    (`error`). Its TYPE and the HTTP response status it carries decide
+    BEFORE every text marker — a 401, a 429/5xx, a rate-limited 403, a
+    permission 403, a transport timeout and a bounded gate wait are read
+    from the failure itself, never from words that the command's argv
+    could also contain (Issue #1760). Every marker that is not recognized
+    falls through to `unclassified`, so the block is never omitted. The
+    mapping is the single source both the comment block and the
+    reader-facing Action/Reason rendering use.
     """
     if provider_quota:
         reason_code = "provider_quota"
     elif review_budget:
         reason_code = "review_budget_exhausted"
-    elif human_decision:
+    elif human_decision or isinstance(error, ReleaseGateWaitTimeout):
+        # A bounded wait that ran out is a human's decision, never a
+        # transient failure to requeue (Issue #1760).
         reason_code = "human_decision_required"
+    elif isinstance(error, subprocess.TimeoutExpired):
+        # A transport timeout is transient by type, whatever it says.
+        reason_code = "github_transient"
+    elif gh_response.authentication_required(error):
+        reason_code = "credential_missing"
+    elif gh_response.transient(error):
+        reason_code = "github_transient"
+    elif gh_response.status_of(error) == 403 or isinstance(
+            error, GitHubPermissionDenied):
+        # A 403 with quota left is a permission failure: the same repair
+        # as a rejected credential. A caller that re-wraps that status in
+        # its own sentence (the release gate's missing Checks:read) keeps
+        # it on the type.
+        reason_code = "credential_missing"
     elif _WORKFLOW_PERMISSION_RE.search(detail):
         # The explicit App/workflows refusal is an authorization the AI
         # cannot grant: the existing `credential_missing` /
         # `check_credentials` category, a repair required before retry.
         reason_code = "credential_missing"
-    elif _BASE_BRANCH_MISSING_RE.search(detail):
-        reason_code = "base_branch_missing"
     elif _CREDENTIAL_MISSING_RE.search(detail):
         reason_code = "credential_missing"
-    elif _TESTS_FAILED_RE.search(detail):
-        reason_code = "tests_failed"
+    elif _timeout_is_text_only(error) and _TEXT_TIMEOUT_RE.search(detail):
+        reason_code = "github_transient"
     elif _GITHUB_TRANSIENT_RE.search(detail):
         reason_code = "github_transient"
     elif _PROVIDER_QUOTA_RE.search(detail):
@@ -370,19 +476,23 @@ def workflow_permission_action(
 
 
 def terminal_action(record: Failure,
-                    language_code: str) -> str:
+                    language_code: str, *,
+                    base_branch: str | None = None) -> str:
     """The reader action for the implement-phase terminal handler.
 
     An unrecognized failure says the cause could not be determined
     instead of implying the Issue text is the problem (Issue #1651); a
-    missing base branch names its one repair (Issue #1749); every other
-    recognized terminal failure keeps the existing generic action.
+    missing base branch names the branch and both repairs — create it, or
+    pick an existing one where the repository was set up — plus how to
+    restart the Issue (Issue #1749, #1753); every other recognized
+    terminal failure keeps the existing generic action.
     """
     if record.reason_code == "unclassified":
         return language.text(language_code, "failure.terminal_unclassified")
     if record.reason_code == "base_branch_missing":
         return language.text(
             language_code, "failure.terminal_base_branch_missing",
+            base_branch=base_branch or "-",
         )
     return language.text(language_code, "failure.terminal_generic")
 
@@ -391,15 +501,16 @@ def terminal_reason(detail: str, record: Failure, *,
                     base_branch: str | None, language_code: str) -> str:
     """The reader-facing reason of the implement-phase terminal handler.
 
-    The missing-base-branch failure names the CONFIGURED branch: Git's own
-    `couldn't find remote ref <value>` line is the evidence, never the
-    setting a human has to repair (Issue #1749). Every other terminal
+    The missing-base-branch failure names the CONFIGURED branch and keeps
+    Git's raw answer out of the sentence: the remote's own `git ls-remote`
+    probe is the evidence the run details carry, never the setting a human
+    has to repair (Issues #1749, #1753, #1756). Every other terminal
     failure keeps the generic stopped-delivery sentence.
     """
     if record.reason_code == "base_branch_missing":
         return language.text(
             language_code, "failure.base_branch_missing_reason",
-            base_branch=base_branch or "-", detail=detail,
+            base_branch=base_branch or "-",
         )
     return language.text(
         language_code, "runner.delivery_stopped_reason", detail=detail,
@@ -465,8 +576,11 @@ def _failure_summary(reason: str,
     summary = re.sub(r"CalledProcessError\([^)]*\)",
                      command_failed, summary)
     summary = _redact_local_paths(summary)
-    summary = re.sub(r"\s+", " ", summary).strip(" .;:")
-    if not summary:
+    # Trailing dots are kept: a catalog sentence ("... start from.")
+    # reaches the reader as written (Issue #1753), while a trailing
+    # separator from exception text is noise.
+    summary = re.sub(r"\s+", " ", summary).strip(" ;:")
+    if not summary.strip("."):
         summary = command_failed
     if stderr:
         # Setup tools often write informational lines before the provider's
@@ -480,7 +594,9 @@ def _failure_summary(reason: str,
             else stderr.rstrip().rsplit("\n", 1)[-1].strip()
         )
         if stderr_summary and stderr_summary not in summary:
-            summary = f"{summary}: {stderr_summary}"
+            # The sentence separator never doubles the punctuation the
+            # summary already ends with.
+            summary = f"{summary.rstrip(' .;:')}: {stderr_summary}"
     return summary[:500]
 
 

{orbi_cli-0.7.5 → orbi_cli-0.7.6}/src/orbi/failure_report.py

@@ -135,12 +135,16 @@ def is_unrecoverable_failure(exc: BaseException) -> bool:
 # markers live in `orbi.failure` (Issue #1229 keeps this module small).
 def _classify_failure(exc: BaseException, *, outcome: str) -> failure.Failure:
     """Map one delivery exception to the machine-readable failure record."""
+    carried = getattr(exc, "failure_record", None)
+    if isinstance(carried, failure.Failure):  # decided at the source (#1756)
+        return carried.with_outcome(outcome)
     return failure.classify(
         _failure_detail(exc),
         provider_quota=isinstance(exc, RateLimitExhaustedError),
         review_budget=isinstance(exc, ReviewRoundsExhausted),
         human_decision=isinstance(exc, HumanDecisionRequired),
         unrecoverable=isinstance(exc, UnrecoverableDeliveryError),
+        error=exc,
         outcome=outcome,
     )
 

orbi_cli-0.7.6/src/orbi/gh_response.py

@@ -0,0 +1,220 @@
+"""The response a failed `gh` request received, read from gh's own output.
+
+A GitHub failure is classified from the HTTP status the response carries,
+never from the error text: the detail of a `CalledProcessError` also holds
+the command's argv, so a branch, label or check named `credential` or
+`forbidden` could be read as a credential problem (Issue #1760).
+
+`gh api --include` (documented: "Include HTTP response status line and
+headers in the output") prints the status line and the response headers in
+front of the body — for a failed request too, verified against gh 2.100.0:
+a 403 prints `HTTP/2.0 403 Forbidden`, its headers and the error body on
+stdout, writes one line to stderr and exits 1. `X-Ratelimit-Remaining` is
+one of those headers, and a 403 with `0` remaining is GitHub's rate limit,
+while a 403 with quota left is a permission failure. The status is
+therefore read from the response itself.
+
+The other structural source is gh's documented exit code: `gh help
+exit-codes` says "If a command requires authentication, the exit code will
+be 4", which covers the gh subcommands that print no response headers.
+
+JSON output escapes newlines inside string values, so a line that starts
+with a status line can only be gh's own header block — a body that merely
+QUOTES an HTTP example keeps it inside one JSON string.
+
+An empty body prints no line at all: gh's output is then the status line
+and the headers, and the stripped stdout ends after the last header. That
+block is still complete — the body it carries is the empty string.
+"""
+from __future__ import annotations
+
+import re
+import subprocess
+
+# gh's documented exit code for "requires authentication".
+GITHUB_AUTH_EXIT_CODE = 4
+INCLUDE_FLAG = "--include"
+
+# gh subcommands other than `gh api` print no response status line, so
+# their server-side failures keep GitHub's own sentences. Read only when
+# the request carried NO status at all: a response status always wins.
+_GH_SERVER_FAILURE_RE = re.compile(
+    r"http 5\d\d|http 429|rate limit|"
+    r"something went wrong while executing your query|internal server error",
+    re.IGNORECASE,
+)
+_STATUS_LINE_RE = re.compile(r"HTTP/\d+(?:\.\d+)? (\d{3})\b")
+# RFC 9110 header field name followed by ":". Deliberately strict: a block
+# only counts when every line up to the blank line is a header, so body
+# text cannot be mistaken for response metadata.
+_HEADER_LINE_RE = re.compile(r"^[A-Za-z0-9!#$%&'*+.^_`|~-]+:")
+_RATELIMIT_RE = re.compile(r"^x-ratelimit-remaining:\s*(\d+)\s*$", re.IGNORECASE)
+
+
+class GitHubRequestFailed(subprocess.CalledProcessError):
+    """A failed gh request carrying the HTTP response it received.
+
+    `status` is the status the response itself reported, or None when the
+    request produced no response (a connection failure). A
+    `CalledProcessError` subclass, so every existing
+    `except subprocess.CalledProcessError` handler keeps its behaviour.
+    """
+
+    def __init__(self, returncode: int, cmd: list[str],
+                 output: str | None = None, stderr: str | None = None, *,
+                 status: int | None = None,
+                 ratelimit_remaining: int | None = None) -> None:
+        super().__init__(returncode, cmd, output=output, stderr=stderr)
+        self.status = status
+        self.ratelimit_remaining = ratelimit_remaining
+
+    @property
+    def rate_limited(self) -> bool:
+        """GitHub's rate limit is a 403 with no quota left."""
+        return self.status == 403 and self.ratelimit_remaining == 0
+
+    @property
+    def authentication_required(self) -> bool:
+        """A rejected credential: an HTTP 401, or gh's auth exit code."""
+        return self.status == 401 or self.returncode == GITHUB_AUTH_EXIT_CODE
+
+
+def include_headers(command: list[str]) -> list[str]:
+    """Return `command` asking `gh api` to print the response status line.
+
+    Only `gh api` prints response headers; every other gh subcommand keeps
+    its argv (its authentication failure is gh's own exit code).
+    """
+    if command[:2] != ["gh", "api"]:
+        return command
+    if INCLUDE_FLAG in command or "-i" in command:
+        return command
+    return [*command, INCLUDE_FLAG]
+
+
+def _header_block_end(lines: list[str], start: int) -> int | None:
+    """Index of the first line after a header block, or None if not one.
+
+    A block also ends at the end of the output: gh prints no body line at
+    all when the response body is empty (a `--jq` filter that selects
+    nothing, a `204`), and the caller's stripped stdout then ends right
+    after the last header — without the trailing blank line. A status
+    line followed by header lines and nothing else is still gh's header
+    block, never body text (Issue #1760).
+    """
+    index = start + 1
+    if index >= len(lines) or not (
+        _HEADER_LINE_RE.match(lines[index]) or lines[index][:1] in " \t"
+    ):
+        return None
+    while index < len(lines):
+        line = lines[index]
+        if not line:
+            return index + 1
+        if not (_HEADER_LINE_RE.match(line) or line[:1] in " \t"):
+            return None
+        index += 1
+    return len(lines)
+
+
+def response_parts(output: str | None) -> tuple[int | None, int | None, str]:
+    """Split gh's output into (status, x-ratelimit-remaining, body).
+
+    Every header block is removed from the body, including the ones gh
+    prints between the pages of a `--paginate` read (the JSON separator
+    shares the line with the next page's status line). The LAST block wins:
+    a failed paginated request ends on the response that failed.
+    """
+    lines = str(output or "").splitlines()
+    statuses: list[int] = []
+    remaining: int | None = None
+    body: list[str] = []
+    index = 0
+    while index < len(lines):
+        line = lines[index]
+        prefix = ""
+        candidate = line
+        if candidate[:1] in "[,":
+            prefix, candidate = candidate[:1], candidate[1:]
+        match = _STATUS_LINE_RE.match(candidate)
+        end = _header_block_end(lines, index) if match else None
+        if match is not None and end is not None:
+            statuses.append(int(match.group(1)))
+            for header in lines[index + 1:end]:
+                header_match = _RATELIMIT_RE.match(header)
+                if header_match:
+                    remaining = int(header_match.group(1))
+            body.append(prefix)
+            index = end
+            continue
+        body.append(line)
+        index += 1
+    return (
+        statuses[-1] if statuses else None,
+        remaining,
+        "\n".join(body).strip(),
+    )
+
+
+def failed_request(
+    exc: subprocess.CalledProcessError,
+) -> GitHubRequestFailed:
+    """Return `exc` carrying the status of the response it received.
+
+    An already structured error is returned unchanged, so the wrapper can
+    re-raise without losing the status.
+    """
+    if isinstance(exc, GitHubRequestFailed):
+        return exc
+    status, remaining, _ = response_parts(exc.stdout)
+    return GitHubRequestFailed(
+        exc.returncode, exc.cmd,
+        output=exc.output, stderr=exc.stderr,
+        # A 2xx status next to a non-zero exit is an incomplete read, not a
+        # failed request: it carries no failure status.
+        status=status if status is not None and status >= 400 else None,
+        ratelimit_remaining=remaining,
+    )
+
+
+def transient_command(failure: GitHubRequestFailed) -> bool:
+    """Whether a failed gh command is worth retrying.
+
+    The response status decides whenever gh printed one — a permission
+    failure is never retried. A `gh` subcommand other than `gh api`
+    prints no response headers, so it keeps GitHub's own server
+    sentences: there is no status to read, and dropping that signal would
+    turn a GitHub-side 5xx on a plain scan read back into the crashed
+    tick the bounded retry exists to prevent (Issue #738). A retried
+    mutation stays guarded by the caller's `already_applied` check.
+    """
+    if failure.status is not None or failure.authentication_required:
+        return transient(failure)
+    detail = " ".join(
+        str(part or "") for part in (failure.stderr, failure.stdout))
+    return _GH_SERVER_FAILURE_RE.search(detail) is not None
+
+
+def status_of(exc: BaseException | None) -> int | None:
+    """The HTTP status a failed gh request carried, or None."""
+    return exc.status if isinstance(exc, GitHubRequestFailed) else None
+
+
+def authentication_required(exc: BaseException) -> bool:
+    """Whether the failed request was refused for its credential."""
+    return isinstance(exc, GitHubRequestFailed) and exc.authentication_required
+
+
+def transient(exc: BaseException) -> bool:
+    """Whether the failed request is worth retrying.
+
+    Transient: a rate limit (403 with no quota left), 429 and every 5xx.
+    A rejected credential (401 / gh's auth exit code) and every other
+    client failure are not — retrying them cannot succeed.
+    """
+    if not isinstance(exc, GitHubRequestFailed):
+        return False
+    if exc.rate_limited:
+        return True
+    status = exc.status
+    return status is not None and (status == 429 or 500 <= status <= 599)