fix(install): treat throttled GitHub probe as indeterminate, not inaccessible (#2037)

* chore: release v0.24.0

Bump pyproject.toml and uv.lock to 0.24.0 and move the [Unreleased]
CHANGELOG block to [0.24.0] - 2026-07-05 (one so-what entry per merged PR).
MINOR bump: new `apm config list` alias (#1991) and Antigravity `trigger: glob`
frontmatter support (#1984); no BREAKING changes. Lint mirror green locally
(ruff check + format, pylint R0801, auth-signals).

Post-merge: tag v0.24.0 to trigger the release workflow.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* fix(install): treat throttled GitHub probe as indeterminate, not inaccessible

The pre-flight accessibility probe treated a rate-limited 403/429 (primary
60/hr or secondary concurrency limit) as 'package not accessible' and aborted
the install -- a false negative, since a throttled response is no evidence the
repo is missing. On single-IP runners that concentrate many public-package
installs (the consolidated macOS release job), this made the release/nightly
integration suite flake red for days.

Detect a genuine rate-limit response (403 + X-RateLimit-Remaining: 0, or
403/429 + Retry-After) and let the install proceed so the download step becomes
the source of truth. Genuine 404s and permission 403s still fail closed. Adds
unit coverage for the helpers and the allow-through / fail-closed end-to-end
paths. Lint mirror green.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* chore: spec-conformance waiver for rate-limit probe hardening

apm-spec-waiver: robustness bugfix -- throttled GitHub probe no longer false-negatives a public package; existing install existence-validation contract is unchanged (no new normative behaviour)

---------

Co-authored-by: danielmeppiel <danielmeppiel@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: danielmeppiel

CHANGELOG.md

@@ -51,6 +51,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- `apm install` no longer aborts with a false "package not accessible" error
+  when GitHub's API rate limit (primary 60/hr or secondary concurrency) throttles
+  the pre-flight probe; a throttled response is now treated as indeterminate and
+  the download step confirms the package. Genuine 404s and permission 403s still
+  fail closed. (#2032)
 - Generated `CLAUDE.md` now uses a single H1 title with nested H2/H3 sections,
   fixing duplicate top-level headings in Claude Code. (by @WilliamK112, #2016)
 - `apm install` now deploys hook script directories as self-contained bundles

src/apm_cli/install/validation.py

@@ -58,6 +58,54 @@ def _is_tls_failure(exc: BaseException) -> bool:
     return False
 
 
+# Marker prefix used on RuntimeError messages raised when the GitHub REST
+# probe is throttled (primary 60/hr or secondary concurrency rate limit).
+# A throttled response is NOT evidence the repo is missing, so the marker
+# lets the caller proceed to the download step (the real source of truth)
+# instead of surfacing a false "package not accessible" error.
+_RATE_LIMIT_PREFIX = "GitHub API rate limit"
+
+
+def _is_rate_limit_failure(exc: BaseException) -> bool:
+    """Return True if exc (or any cause in its chain) is a rate-limit throttle."""
+    cur: BaseException | None = exc
+    seen = 0
+    while cur is not None and seen < 8:
+        if _RATE_LIMIT_PREFIX in str(cur):
+            return True
+        cur = cur.__cause__ or cur.__context__
+        seen += 1
+    return False
+
+
+def _raise_if_rate_limited(resp, host_display: str) -> None:
+    """Raise a marked RuntimeError when *resp* is a GitHub rate-limit throttle.
+
+    GitHub signals primary exhaustion with HTTP 403 + ``X-RateLimit-Remaining: 0``
+    and secondary (concurrency) limits with 403/429 + a ``Retry-After`` header.
+    Either way the repo's existence is unknown, so the marker lets the caller
+    proceed rather than report a false negative. Plain 403s (SSO / permission)
+    carry neither signal and fall through to the normal not-accessible path.
+    """
+    if resp.status_code not in (403, 429):
+        return
+    remaining = resp.headers.get("X-RateLimit-Remaining")
+    retry_after = resp.headers.get("Retry-After")
+    if resp.status_code == 429 or remaining == "0" or retry_after:
+        raise RuntimeError(f"{_RATE_LIMIT_PREFIX} hit for {host_display} ({resp.status_code})")
+
+
+def _log_rate_limit_allow(host_display: str, verbose_log, logger) -> None:
+    """Note that a throttled probe is allowed through to the download step."""
+    if logger:
+        logger.info(
+            f"GitHub API rate limit hit while checking {host_display}; skipping the "
+            "pre-flight accessibility probe and letting the download step confirm the package"
+        )
+    if verbose_log:
+        verbose_log(f"rate limit reached for {host_display}; proceeding to download")
+
+
 def _log_tls_failure(host_display: str, exc: BaseException, verbose_log, logger) -> None:
     """Surface a TLS verification failure with an actionable CA-trust hint.
 
@@ -593,6 +641,7 @@ def _check_repo(token, git_env) -> bool:
         if resp.status_code == 404 and token:
             # 404 with token could mean no access -- raise to trigger fallback
             raise RuntimeError(f"API returned {resp.status_code}")
+        _raise_if_rate_limited(resp, host_info.display_name)
         raise RuntimeError(f"API returned {resp.status_code}: {resp.reason}")
 
     try:
@@ -612,6 +661,9 @@ def _check_repo(token, git_env) -> bool:
         if _is_tls_failure(exc):
             _log_tls_failure(host_info.display_name, exc, verbose_log, logger)
             return False
+        if _is_rate_limit_failure(exc):
+            _log_rate_limit_allow(host_info.display_name, verbose_log, logger)
+            return True
         if verbose_log:
             try:
                 ctx = auth_resolver.build_error_context(
@@ -687,6 +739,7 @@ def _check_repo_fallback(token, git_env) -> bool:
             return True
         if verbose_log:
             verbose_log(f"API fallback -> {resp.status_code} {resp.reason}")
+        _raise_if_rate_limited(resp, host_info.display_name)
         raise RuntimeError(f"API returned {resp.status_code}")
 
     try:
@@ -703,6 +756,9 @@ def _check_repo_fallback(token, git_env) -> bool:
             # See note above: logged once here, skip auth context render.
             _log_tls_failure(host, exc, verbose_log, logger)
             return False
+        if _is_rate_limit_failure(exc):
+            _log_rate_limit_allow(host, verbose_log, logger)
+            return True
         if verbose_log:
             try:
                 ctx = auth_resolver.build_error_context(

tests/unit/install/test_validation_rate_limit.py

@@ -0,0 +1,131 @@
+"""Tests for the GitHub API rate-limit classification path in install.validation.
+
+Bug: on a single-IP runner that concentrates many public-package installs
+(e.g. the consolidated macOS release job), the accessibility probe hits
+GitHub's primary (60/hr) or secondary (concurrency) rate limit and gets a
+403/429. The old code treated that as "package not accessible" and aborted
+the install -- a false negative, since a throttled response is no evidence
+the repo is missing. After the fix a throttled probe is allowed through so
+the download step becomes the source of truth, while genuine 404s and plain
+permission 403s still fail closed.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from apm_cli.install import validation
+
+
+class TestRateLimitHelpers:
+    def test_is_rate_limit_failure_detects_marker(self):
+        exc = RuntimeError("GitHub API rate limit hit for github.com (403)")
+        assert validation._is_rate_limit_failure(exc) is True
+
+    def test_is_rate_limit_failure_detects_via_cause_chain(self):
+        original = RuntimeError("GitHub API rate limit hit for github.com (429)")
+        wrapped = RuntimeError("authenticated retry also failed")
+        wrapped.__cause__ = original
+        assert validation._is_rate_limit_failure(wrapped) is True
+
+    def test_is_rate_limit_failure_false_for_generic_errors(self):
+        assert validation._is_rate_limit_failure(RuntimeError("API returned 404")) is False
+        assert validation._is_rate_limit_failure(ValueError("nope")) is False
+
+    def test_is_rate_limit_failure_bounded_chain_walk(self):
+        exc = RuntimeError("oops")
+        exc.__cause__ = exc
+        assert validation._is_rate_limit_failure(exc) is False
+
+    def test_raise_if_rate_limited_primary_exhaustion(self):
+        resp = MagicMock(status_code=403, headers={"X-RateLimit-Remaining": "0"})
+        with pytest.raises(RuntimeError, match=r"GitHub API rate limit"):
+            validation._raise_if_rate_limited(resp, "github.com")
+
+    def test_raise_if_rate_limited_secondary_retry_after(self):
+        resp = MagicMock(status_code=403, headers={"Retry-After": "60"})
+        with pytest.raises(RuntimeError, match=r"GitHub API rate limit"):
+            validation._raise_if_rate_limited(resp, "github.com")
+
+    def test_raise_if_rate_limited_http_429(self):
+        resp = MagicMock(status_code=429, headers={})
+        with pytest.raises(RuntimeError, match=r"GitHub API rate limit"):
+            validation._raise_if_rate_limited(resp, "github.com")
+
+    def test_raise_if_rate_limited_ignores_plain_403(self):
+        # SSO / permission 403 carries no rate-limit signal -> no raise.
+        resp = MagicMock(status_code=403, headers={"X-RateLimit-Remaining": "4900"})
+        validation._raise_if_rate_limited(resp, "github.com")
+
+    def test_raise_if_rate_limited_ignores_404(self):
+        resp = MagicMock(status_code=404, headers={"Retry-After": "60"})
+        validation._raise_if_rate_limited(resp, "github.com")
+
+
+class TestValidateRateLimitClassification:
+    """End-to-end: a throttled probe returns True (allow-through)."""
+
+    def _setup_resolver(self, token=None):
+        resolver = MagicMock()
+        host_info = MagicMock()
+        host_info.api_base = "https://api.github.com"
+        host_info.display_name = "github.com"
+        host_info.kind = "github"
+        host_info.has_public_repos = True
+        resolver.classify_host.return_value = host_info
+        ctx = MagicMock(source="env", token_type="pat", token=token)
+        resolver.resolve.return_value = ctx
+        resolver.resolve_for_dep.return_value = ctx
+        return resolver
+
+    def test_throttled_probe_allows_through(self):
+        """Both anon and token attempts hit the limit -> proceed to download."""
+        resolver = self._setup_resolver(token="ghp_fake")
+
+        def _throttled_fallback(host, op, **kwargs):
+            try:
+                return op(None, {})
+            except Exception:
+                # Authenticated retry also throttled; exception propagates.
+                return op("ghp_fake", {})
+
+        resolver.try_with_fallback.side_effect = _throttled_fallback
+
+        logger = MagicMock()
+        rate_limited = MagicMock(
+            ok=False,
+            status_code=403,
+            reason="Forbidden",
+            headers={"X-RateLimit-Remaining": "0"},
+        )
+
+        with patch("apm_cli.install.validation.requests.get", return_value=rate_limited):
+            result = validation._validate_package_exists(
+                "octocat/hello-world",
+                verbose=False,
+                auth_resolver=resolver,
+                logger=logger,
+            )
+
+        assert result is True
+
+    def test_plain_403_still_returns_false(self):
+        """Permission 403 (no rate-limit signal) must still fail closed."""
+        resolver = self._setup_resolver()
+        resolver.try_with_fallback.side_effect = lambda host, op, **kw: op(None, {})
+
+        forbidden = MagicMock(
+            ok=False,
+            status_code=403,
+            reason="Forbidden",
+            headers={"X-RateLimit-Remaining": "4900"},
+        )
+
+        with patch("apm_cli.install.validation.requests.get", return_value=forbidden):
+            result = validation._validate_package_exists(
+                "octocat/private-repo", verbose=False, auth_resolver=resolver
+            )
+
+        assert result is False