agentbundle 0.35.0__tar.gz → 0.35.1__tar.gz

{agentbundle-0.35.0/agentbundle.egg-info → agentbundle-0.35.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentbundle
-Version: 0.35.0
+Version: 0.35.1
 Summary: npm for your coding agent. Install packs of skills, subagents, and hooks into any repo, for every major agent.
 Author-email: eugenelim <eugenelim@users.noreply.github.com>
 License-Expression: Apache-2.0 OR MIT

{agentbundle-0.35.0 → agentbundle-0.35.1}/agentbundle/catalogue.py

@@ -182,6 +182,7 @@ def _verification_failure_message(
     *,
     fallback_note: str,
     offer_opt_out: bool = True,
+    empty_store: bool = False,
 ) -> str:
     """Explain a verification failure in terms of the adopter's next action.
 
@@ -196,13 +197,35 @@ def _verification_failure_message(
     the message never advises setting a variable that is already set.
     """
     host = urllib.parse.urlsplit(url).netloc
-    steps = [
-        "  1. Install from a local clone — needs no HTTPS at all:\n"
+
+    # Numbered at render time: the empty-store step only appears when it applies,
+    # and a hardcoded list would misnumber every step after it.
+    steps: list[str] = []
+    if empty_store:
+        # Almost certainly, not certainly: a populated capath is excluded before
+        # we get here, but the store could still be empty *and* the network
+        # inspected.
+        remedy = (
+            '       open "/Applications/Python 3.x/Install Certificates.command"\n'
+            "     Or point it at the system bundle:\n"
+            "       export SSL_CERT_FILE=/etc/ssl/cert.pem"
+            if sys.platform == "darwin"
+            else "       install your certificate authorities into this "
+            "interpreter's trust\n"
+            "     store, or set SSL_CERT_FILE to a PEM bundle containing them"
+        )
+        steps.append(
+            "This Python trusts ZERO certificate authorities, so every HTTPS\n"
+            "     request from it fails — almost certainly not a corporate-proxy\n"
+            "     problem. Fix the interpreter's trust store:\n" + remedy
+        )
+    steps += [
+        "Install from a local clone — needs no HTTPS at all:\n"
         "       git clone <catalogue-repo> && agentbundle install --pack "
         "<pack> ./<clone>",
-        "  2. Ask your IT team for the corporate CA bundle, then:\n"
+        "Ask your IT team for the corporate CA bundle, then:\n"
         "       export AGENTBUNDLE_CA_BUNDLE=/path/to/corporate-ca.pem",
-        "  3. Check whether a different Python already trusts this network. "
+        "Check whether a different Python already trusts this network. "
         "Interpreters\n"
         "     do not share a certificate store, so one may work where another "
         "fails:\n"
@@ -212,7 +235,7 @@ def _verification_failure_message(
         "     SSL_CERT_FILE at its cafile. Creating a virtualenv does NOT "
         "change trust —\n"
         "     a venv inherits its base interpreter's store unchanged.",
-        "  4. Confirm your proxy allows every host in the redirect chain. A "
+        "Confirm your proxy allows every host in the redirect chain. A "
         "GitHub\n"
         "     archive fetch redirects github.com to codeload.github.com; an "
         "allowlist\n"
@@ -221,16 +244,24 @@ def _verification_failure_message(
     ]
     if offer_opt_out:
         steps.append(
-            "  5. Set AGENTBUNDLE_NO_SYSTEM_TRUST=1 to see the raw "
-            "verification error."
+            "Set AGENTBUNDLE_NO_SYSTEM_TRUST=1 to see the raw verification error."
+        )
+    body = "\n\n".join(f"  {n}. {s}" for n, s in enumerate(steps, start=1))
+
+    if empty_store:
+        diagnosis = (
+            f"The certificate for {host} could not be verified. {fallback_note}"
+        )
+    else:
+        diagnosis = (
+            f"The certificate for {host} could not be verified. {fallback_note} On "
+            "a corporate network this usually means a TLS-inspecting proxy "
+            "re-signs traffic with a private root CA that Python does not read."
         )
-    body = "\n\n".join(steps)
     return (
         f"Failed to fetch catalogue archive: {url} — {detail}\n"
         "\n"
-        f"The certificate for {host} could not be verified. {fallback_note} On a "
-        "corporate network this usually means a TLS-inspecting proxy re-signs "
-        "traffic with a private root CA that Python does not read.\n"
+        f"{diagnosis}\n"
         "\n"
         "Troubleshooting, cheapest first:\n"
         "\n"
@@ -253,15 +284,29 @@ def _fetch_and_extract(url: str, dest: Path) -> None:
     system_trust = _system_trust_module()
 
     def attempt(context: ssl.SSLContext) -> None:
+        # Buffer to a seekable temporary file rather than extracting straight
+        # from the response, because "r|gz" is forward-only and that breaks on
+        # Windows. A catalogue carries symlinks (CLAUDE.md -> AGENTS.md); when
+        # os.symlink is unavailable — the default on Windows without Developer
+        # Mode or SeCreateSymbolicLink — tarfile falls back to copying the link
+        # target, which means re-reading a member the stream has already passed.
+        # On a forward-only stream that raises
+        # "seeking backwards is not allowed"; "r:gz" over a real file lets the
+        # fallback do its job. Observed in the field on Windows; macOS and Linux
+        # never hit it because os.symlink succeeds there.
+        #
         # B310: constant github.com archive base assembled from parsed owner/repo/ref.
         with urllib.request.urlopen(  # nosec B310
             url, timeout=_FETCH_TIMEOUT_S, context=context
-        ) as resp, tarfile.open(fileobj=resp, mode="r|gz") as tf:
-            # filter="data" rejects unsafe members (absolute paths, ..
-            # links, devices, setuid bits) — Python 3.12+ default but
-            # explicit for 3.11 compatibility and to silence the 3.14
-            # DeprecationWarning. Path-jail is belt; this is braces.
-            tf.extractall(path=dest, filter="data")
+        ) as resp, tempfile.TemporaryFile() as spool:
+            shutil.copyfileobj(resp, spool)
+            spool.seek(0)
+            with tarfile.open(fileobj=spool, mode="r:gz") as tf:
+                # filter="data" rejects unsafe members (absolute paths, ..
+                # links, devices, setuid bits) — Python 3.12+ default but
+                # explicit for 3.11 compatibility and to silence the 3.14
+                # DeprecationWarning. Path-jail is belt; this is braces.
+                tf.extractall(path=dest, filter="data")
 
     try:
         attempt(system_trust.build_context())
@@ -292,7 +337,13 @@ def _fetch_and_extract(url: str, dest: Path) -> None:
         # administrator trust store to read, a second connection against an
         # identical context would be pure noise, and claiming the anchors "did
         # not complete the chain" would send the adopter after the wrong cause.
-        anchors = system_trust.system_anchor_pem()
+        # An interpreter with an empty trust store is a different fault from an
+        # inspected network: nothing verifies, and the administrator keychain
+        # alone cannot repair it because it holds private roots, not public ones.
+        # Observed in the field on a python.org macOS build whose
+        # Install Certificates.command was never run.
+        empty_store = system_trust.default_store_is_empty()
+        anchors = system_trust.system_anchor_pem(include_public_roots=empty_store)
         if not anchors:
             # Two different causes, and conflating them misdirects the adopter.
             # Off macOS the fallback does not apply at all. *On* macOS it applied
@@ -314,9 +365,11 @@ def _fetch_and_extract(url: str, dest: Path) -> None:
                     "the operating system's trust store."
                 )
             raise CatalogueError(
-                _verification_failure_message(url, detail, fallback_note=note)
+                _verification_failure_message(
+                    url, detail, fallback_note=note, empty_store=empty_store
+                )
             ) from exc
-        _retry_with_system_trust(url, dest, attempt, anchors)
+        _retry_with_system_trust(url, dest, attempt, anchors, empty_store=empty_store)
     except tarfile.TarError as exc:
         raise CatalogueError(
             f"Failed to extract tarball from {url}: {exc}"
@@ -328,6 +381,8 @@ def _retry_with_system_trust(
     dest: Path,
     attempt: Callable[[ssl.SSLContext], None],
     anchors: str,
+    *,
+    empty_store: bool = False,
 ) -> None:
     """Retry *attempt* once against operating-system trust *anchors*.
 
@@ -339,14 +394,48 @@ def _retry_with_system_trust(
     """
     system_trust = _system_trust_module()
     host = urllib.parse.urlsplit(url).netloc
-    print(
-        f"agentbundle: certificate verification failed for {host}; "
-        "retrying with operating-system trust anchors",
-        file=sys.stderr,
-    )
-    exhausted = (
-        "The operating-system trust anchors did not complete the chain either."
-    )
+    if empty_store:
+        # Recovering the fetch is not the same as fixing the interpreter: the
+        # anchors are loaded in memory for this process only. Saying so is the
+        # difference between a one-off rescue and quietly masking a broken
+        # Python that will fail the adopter's next pip or requests call.
+        # Name the wider trust set explicitly. The narrow decision was already
+        # auditable; this one adds a public root set on top, and a trust decision
+        # the adopter cannot see is one they cannot audit.
+        extra = (
+            "the administrator keychain plus the system public certificate "
+            "bundle" if sys.platform == "darwin" else "operating-system trust anchors"
+        )
+        fix = (
+            '  open "/Applications/Python 3.x/Install Certificates.command"\n'
+            "  (or: export SSL_CERT_FILE=/etc/ssl/cert.pem)"
+            if sys.platform == "darwin"
+            else "  install your certificate authorities into this interpreter's\n"
+            "  trust store, or set SSL_CERT_FILE to a PEM bundle"
+        )
+        print(
+            f"agentbundle: this Python trusts no certificate authorities, so "
+            f"verification failed for {host}. Retrying against {extra} — this "
+            "rescues the install but does not fix the interpreter, so every "
+            "other tool will keep failing. To stop that:\n" + fix,
+            file=sys.stderr,
+        )
+    else:
+        print(
+            f"agentbundle: certificate verification failed for {host}; "
+            "retrying with operating-system trust anchors",
+            file=sys.stderr,
+        )
+    if empty_store:
+        exhausted = (
+            "This Python trusts no certificate authority at all — its trust store "
+            "is empty — and the operating-system anchors did not complete the "
+            "chain either."
+        )
+    else:
+        exhausted = (
+            "The operating-system trust anchors did not complete the chain either."
+        )
     # Attempt 1 may have extracted part of the archive before failing mid-stream.
     # Clearing the destination keeps the retry from layering a second download
     # over the first and producing a catalogue that is a mix of both.
@@ -359,7 +448,9 @@ def _retry_with_system_trust(
         # wrapped by urlopen and would otherwise escape as a bare exception.
         detail = getattr(exc, "reason", None) or exc
         raise CatalogueError(
-            _verification_failure_message(url, detail, fallback_note=exhausted)
+            _verification_failure_message(
+                url, detail, fallback_note=exhausted, empty_store=empty_store
+            )
         ) from exc
     except tarfile.TarError as exc:
         raise CatalogueError(

{agentbundle-0.35.0 → agentbundle-0.35.1}/agentbundle/system_trust.py

@@ -58,22 +58,36 @@ from pathlib import Path
 
 from agentbundle.catalogue import CatalogueError
 
-# One keychain, deliberately. ``System.keychain`` needs administrator or MDM
-# rights to write, and it is where a corporate proxy root actually lands — so it
-# is the only store that holds the material this feature exists to find.
-#
-# Apple's ``SystemRootCertificates.keychain`` is *not* read. The retry context
-# already starts from ``create_default_context()``, so the public roots are
-# present; adding Apple's root program on top would widen trust to a second,
-# independently curated set for no gain. Measured on a corporate host: reading
-# System.keychain alone produced exactly the same anchor count as reading both,
-# i.e. Apple's keychain contributed nothing while enlarging the trust surface on
-# the one fetch path with no post-transport integrity check.
+# The administrator keychain, always. It needs administrator or MDM rights to
+# write, and it is where a corporate proxy root actually lands — so it is the
+# store that holds the material this feature exists to find.
 #
 # The user's ``login.keychain-db`` is absent and must stay absent: it is writable
 # without administrator rights, so a root landing there is not an IT decision.
 _ADMIN_KEYCHAINS = ("/Library/Keychains/System.keychain",)
 
+# Apple's public TLS roots, read **only** when the default trust store holds no
+# anchors — see ``system_anchor_pem``. RFC-0086 D4 excluded Apple's material
+# outright; the erratum narrows that to this one state, where an interpreter
+# trusts nothing and the administrator keychain cannot repair it because it holds
+# private roots.
+#
+# Read the *file*, not the keychain, and the distinction is load-bearing.
+# ``/etc/ssl/cert.pem`` is Apple's own TLS-purpose export: root-owned, and
+# measured on a current host it carries 128 certificates and **zero**
+# Apple-operated roots. Dumping ``SystemRootCertificates.keychain`` instead
+# yields 158, of which 14 are Apple-operated and several are single-purpose —
+# ``Apple Platform Code Signing {ECC,RSA} Root CA``, ``Developer ID
+# Certification Authority``, ``Apple Platform Bootstrap ECC Root CA``. None of
+# those carry an EKU extension, so OpenSSL's server-auth purpose check does not
+# exclude them; Apple confines them through trust settings, which
+# ``find-certificate`` discards. Trusting code-signing roots for TLS is not what
+# an unconfigured interpreter was missing. The file also needs no subprocess.
+_APPLE_TLS_BUNDLE = "/etc/ssl/cert.pem"
+
+# Fallback only, if the export above is absent on some macOS version.
+_APPLE_ROOT_KEYCHAIN = "/System/Library/Keychains/SystemRootCertificates.keychain"
+
 _SECURITY_BIN = "/usr/bin/security"
 
 _PEM_MARKER = "BEGIN CERTIFICATE"
@@ -136,8 +150,47 @@ def resolve_trust_paths(env: dict | None = None) -> tuple[str | None, str | None
     return (cafile or None, capath or None)
 
 
-def system_anchor_pem() -> str | None:
-    """Return administrator-keychain certificates as PEM text, or ``None``.
+def default_store_is_empty(env: dict | None = None) -> bool:
+    """True when this interpreter trusts no certificate authority at all.
+
+    Distinct from a corporate-network failure and far more common than it looks:
+    a python.org macOS interpreter whose ``Install Certificates.command`` was
+    never run reports ``cafile=None`` and loads zero anchors, so *every* HTTPS
+    request fails, not just ones crossing an inspecting proxy.
+
+    Zero is the trigger, deliberately — not a threshold. A small store may be a
+    legitimate pinned bundle; an empty one cannot verify anything and is always
+    a broken or unconfigured interpreter.
+
+    A populated ``capath`` disqualifies the interpreter from this diagnosis even
+    when the count reads zero: OpenSSL loads a hashed directory lazily, so
+    ``get_ca_certs()`` reports nothing until a certificate from it has been used.
+    Such an interpreter may well be verifying fine, and calling it empty would
+    both widen its trust and tell an adopter behind a real proxy that their
+    problem is something else.
+    """
+    # One try around everything: resolve_trust_paths raises CatalogueError (a
+    # ValueError) on a bundle path that vanished between the caller's first
+    # attempt and this check, and this helper is called from inside an `except`
+    # block where an escape would mask the original error.
+    try:
+        capath = resolve_trust_paths(env)[1] or ssl.get_default_verify_paths().capath
+        if capath:
+            with contextlib.suppress(OSError):
+                if any(Path(capath).iterdir()):
+                    return False
+        return not build_context(env).get_ca_certs()
+    except (OSError, ssl.SSLError, ValueError):
+        return False
+
+
+def system_anchor_pem(*, include_public_roots: bool = False) -> str | None:
+    """Return operating-system keychain certificates as PEM text, or ``None``.
+
+    Reads the administrator keychain. When *include_public_roots* is set — which
+    the caller decides by asking ``default_store_is_empty`` — Apple's root
+    program is read as well, because an interpreter that trusts nothing cannot be
+    repaired from private roots alone.
 
     macOS only, because it is the only platform where Python does not already
     consult the operating system's trust store — see the module docstring. Every
@@ -157,8 +210,23 @@ def system_anchor_pem() -> str | None:
     if sys.platform != "darwin":
         return None
 
+    keychains = _ADMIN_KEYCHAINS
     chunks: list[str] = []
-    for keychain in _ADMIN_KEYCHAINS:
+
+    if include_public_roots:
+        bundle = Path(_APPLE_TLS_BUNDLE)
+        loaded = False
+        with contextlib.suppress(OSError):
+            text = bundle.read_text(encoding="utf-8", errors="replace")
+            if _PEM_MARKER in text:
+                chunks.append(text)
+                loaded = True
+        if not loaded:
+            # The export is missing; fall back to the keychain rather than
+            # leaving an interpreter that trusts nothing with no route at all.
+            keychains = (*_ADMIN_KEYCHAINS, _APPLE_ROOT_KEYCHAIN)
+
+    for keychain in keychains:
         argv = [_SECURITY_BIN, "find-certificate", "-a", "-p", keychain]
         try:
             out = _RUNNER(argv)

{agentbundle-0.35.0 → agentbundle-0.35.1}/agentbundle/version.py

@@ -14,7 +14,7 @@ import tomllib
 from importlib.resources import files
 from pathlib import Path
 
-CLI_VERSION = "0.35.0"
+CLI_VERSION = "0.35.1"
 
 _HERE = Path(__file__).resolve().parent
 

{agentbundle-0.35.0 → agentbundle-0.35.1/agentbundle.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentbundle
-Version: 0.35.0
+Version: 0.35.1
 Summary: npm for your coding agent. Install packs of skills, subagents, and hooks into any repo, for every major agent.
 Author-email: eugenelim <eugenelim@users.noreply.github.com>
 License-Expression: Apache-2.0 OR MIT

{agentbundle-0.35.0 → agentbundle-0.35.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentbundle"
-version = "0.35.0"
+version = "0.35.1"
 description = "npm for your coding agent. Install packs of skills, subagents, and hooks into any repo, for every major agent."
 requires-python = ">=3.11"
 dependencies = []

{agentbundle-0.35.0 → agentbundle-0.35.1}/tests/integration/test_trust_fallback_tls.py

@@ -128,7 +128,7 @@ def test_attempt_one_genuinely_fails_against_an_unknown_authority(
     tls_server, tmp_path, monkeypatch
 ):
     """The premise: without the authority, real TLS verification fails."""
-    monkeypatch.setattr(system_trust, "system_anchor_pem", lambda: None)
+    monkeypatch.setattr(system_trust, "system_anchor_pem", lambda **k: None)
     with pytest.raises(CatalogueError) as exc:
         catalogue._fetch_and_extract(tls_server, tmp_path)
     assert "could not be verified" in str(exc.value)
@@ -145,7 +145,7 @@ def test_the_fallback_recovers_a_real_failing_handshake(
     import agentbundle.system_trust as st
 
     original = st.system_anchor_pem
-    st.system_anchor_pem = lambda: tls_fixtures["ca_pem"]
+    st.system_anchor_pem = lambda **k: tls_fixtures["ca_pem"]
     try:
         catalogue._fetch_and_extract(tls_server, tmp_path)
     finally:
@@ -166,7 +166,7 @@ def test_a_dirty_dump_still_recovers(tls_server, tls_fixtures, tmp_path):
 
     garbage = "-----BEGIN CERTIFICATE-----\nnot base64\n-----END CERTIFICATE-----\n"
     original = st.system_anchor_pem
-    st.system_anchor_pem = lambda: garbage + tls_fixtures["ca_pem"] + garbage
+    st.system_anchor_pem = lambda **k: garbage + tls_fixtures["ca_pem"] + garbage
     try:
         catalogue._fetch_and_extract(tls_server, tmp_path)
     finally:
@@ -181,7 +181,7 @@ def test_opt_out_refuses_to_recover(tls_server, tls_fixtures, tmp_path, monkeypa
     import agentbundle.system_trust as st
 
     original = st.system_anchor_pem
-    st.system_anchor_pem = lambda: tls_fixtures["ca_pem"]
+    st.system_anchor_pem = lambda **k: tls_fixtures["ca_pem"]
     try:
         with pytest.raises(CatalogueError) as exc:
             catalogue._fetch_and_extract(tls_server, tmp_path)

{agentbundle-0.35.0 → agentbundle-0.35.1}/tests/unit/test_catalogue_trust_fallback.py

@@ -11,6 +11,7 @@ only, per the convention in test_https_catalogue.py.
 from __future__ import annotations
 
 import io
+import os
 import ssl
 import sys
 import tarfile
@@ -104,7 +105,7 @@ def test_verification_failure_retries_once_with_system_anchors(
 ):
     stub = _Stub([_verify_error(), _tarball()])
     monkeypatch.setattr(urllib.request, "urlopen", stub)
-    monkeypatch.setattr(system_trust, "system_anchor_pem", _an_anchor_pem)
+    monkeypatch.setattr(system_trust, "system_anchor_pem", lambda **k: _an_anchor_pem())
 
     catalogue._fetch_and_extract(URL, tmp_path)
 
@@ -125,7 +126,7 @@ def test_retry_uses_a_different_context_carrying_the_anchors(
     """
     stub = _Stub([_verify_error(), _tarball()])
     monkeypatch.setattr(urllib.request, "urlopen", stub)
-    monkeypatch.setattr(system_trust, "system_anchor_pem", _an_anchor_pem)
+    monkeypatch.setattr(system_trust, "system_anchor_pem", lambda **k: _an_anchor_pem())
 
     catalogue._fetch_and_extract(URL, tmp_path)
 
@@ -147,7 +148,7 @@ def test_no_retry_when_no_system_anchors_are_available(
     monkeypatch.setattr(sys, "platform", "linux")
     stub = _Stub([_verify_error()])
     monkeypatch.setattr(urllib.request, "urlopen", stub)
-    monkeypatch.setattr(system_trust, "system_anchor_pem", lambda: None)
+    monkeypatch.setattr(system_trust, "system_anchor_pem", lambda **k: None)
 
     with pytest.raises(CatalogueError) as exc:
         catalogue._fetch_and_extract(URL, tmp_path)
@@ -168,7 +169,7 @@ def test_empty_admin_keychain_on_macos_names_the_real_cause(
     monkeypatch.setattr(sys, "platform", "darwin")
     stub = _Stub([_verify_error()])
     monkeypatch.setattr(urllib.request, "urlopen", stub)
-    monkeypatch.setattr(system_trust, "system_anchor_pem", lambda: None)
+    monkeypatch.setattr(system_trust, "system_anchor_pem", lambda **k: None)
 
     with pytest.raises(CatalogueError) as exc:
         catalogue._fetch_and_extract(URL, tmp_path)
@@ -182,7 +183,7 @@ def test_empty_admin_keychain_on_macos_names_the_real_cause(
 def test_fallback_notice_fires_once(monkeypatch, tmp_path, capsys, no_env):
     stub = _Stub([_verify_error(), _tarball()])
     monkeypatch.setattr(urllib.request, "urlopen", stub)
-    monkeypatch.setattr(system_trust, "system_anchor_pem", _an_anchor_pem)
+    monkeypatch.setattr(system_trust, "system_anchor_pem", lambda **k: _an_anchor_pem())
     catalogue._fetch_and_extract(URL, tmp_path)
     err = capsys.readouterr().err
     assert err.count("retrying with operating-system trust anchors") == 1, err
@@ -218,7 +219,7 @@ def test_opt_out_suppresses_the_retry(monkeypatch, tmp_path, no_env):
 def test_retry_failure_raises_catalogue_error(monkeypatch, tmp_path, no_env):
     stub = _Stub([_verify_error(), _verify_error()])
     monkeypatch.setattr(urllib.request, "urlopen", stub)
-    monkeypatch.setattr(system_trust, "system_anchor_pem", _an_anchor_pem)
+    monkeypatch.setattr(system_trust, "system_anchor_pem", lambda **k: _an_anchor_pem())
     with pytest.raises(CatalogueError):
         catalogue._fetch_and_extract(URL, tmp_path)
     assert len(stub.calls) == 2
@@ -232,7 +233,7 @@ def test_retry_failure_raises_catalogue_error(monkeypatch, tmp_path, no_env):
 def test_unrepairable_failure_names_cause_and_next_action(monkeypatch, tmp_path, no_env):
     stub = _Stub([_verify_error(), _verify_error()])
     monkeypatch.setattr(urllib.request, "urlopen", stub)
-    monkeypatch.setattr(system_trust, "system_anchor_pem", _an_anchor_pem)
+    monkeypatch.setattr(system_trust, "system_anchor_pem", lambda **k: _an_anchor_pem())
     with pytest.raises(CatalogueError) as exc:
         catalogue._fetch_and_extract(URL, tmp_path)
     message = str(exc.value)
@@ -252,7 +253,7 @@ def test_message_does_not_recommend_a_virtualenv_as_a_fix(monkeypatch, tmp_path,
     """
     stub = _Stub([_verify_error(), _verify_error()])
     monkeypatch.setattr(urllib.request, "urlopen", stub)
-    monkeypatch.setattr(system_trust, "system_anchor_pem", _an_anchor_pem)
+    monkeypatch.setattr(system_trust, "system_anchor_pem", lambda **k: _an_anchor_pem())
     with pytest.raises(CatalogueError) as exc:
         catalogue._fetch_and_extract(URL, tmp_path)
     message = str(exc.value)
@@ -293,3 +294,156 @@ def test_read_phase_failures_are_wrapped_not_leaked(monkeypatch, tmp_path, no_en
             catalogue._fetch_and_extract(URL, tmp_path)
         assert URL in str(exc.value)
         assert len(stub.calls) == 1, "a non-certificate failure must not retry"
+
+
+def test_empty_store_message_names_the_real_cause(monkeypatch, tmp_path, no_env):
+    """Your user's exact state: zero anchors, no proxy, admin keychain no help.
+
+    The old message blamed a TLS-inspecting proxy, which was actively
+    misleading — nothing was intercepting them.
+    """
+    monkeypatch.setattr(sys, "platform", "darwin")
+    monkeypatch.setattr(system_trust, "default_store_is_empty", lambda *a, **k: True)
+    monkeypatch.setattr(system_trust, "system_anchor_pem", lambda **k: _an_anchor_pem())
+    stub = _Stub([_verify_error(), _verify_error()])
+    monkeypatch.setattr(urllib.request, "urlopen", stub)
+
+    with pytest.raises(CatalogueError) as exc:
+        catalogue._fetch_and_extract(URL, tmp_path)
+
+    message = str(exc.value)
+    assert "trusts ZERO certificate authorities" in message
+    assert "Install Certificates.command" in message
+    # Softened from an absolute after security review: a populated capath is
+    # excluded before we get here, but a store can still be empty AND the
+    # network inspected.
+    assert "almost certainly not a corporate-proxy" in message
+    assert "TLS-inspecting proxy" not in message, "must not blame a proxy here"
+
+
+def test_empty_store_asks_for_public_roots(monkeypatch, tmp_path, no_env):
+    """The fallback must widen to Apple's roots only in the empty-store case."""
+    calls: list[bool] = []
+
+    def anchors(*, include_public_roots: bool = False):
+        calls.append(include_public_roots)
+        return _an_anchor_pem()
+
+    monkeypatch.setattr(system_trust, "system_anchor_pem", anchors)
+    monkeypatch.setattr(urllib.request, "urlopen", _Stub([_verify_error(), _tarball()]))
+
+    monkeypatch.setattr(system_trust, "default_store_is_empty", lambda *a, **k: True)
+    catalogue._fetch_and_extract(URL, tmp_path)
+    assert calls == [True], "empty store must request the public roots"
+
+    calls.clear()
+    monkeypatch.setattr(system_trust, "default_store_is_empty", lambda *a, **k: False)
+    monkeypatch.setattr(urllib.request, "urlopen", _Stub([_verify_error(), _tarball()]))
+    catalogue._fetch_and_extract(URL, tmp_path)
+    assert calls == [False], "intact store must not request the public roots"
+
+
+def test_successful_empty_store_recovery_still_tells_the_adopter(
+    monkeypatch, tmp_path, capsys, no_env
+):
+    """Recovering the fetch must not silently mask a broken interpreter.
+
+    The anchors are loaded in memory for this process only, so the adopter's
+    next pip or requests call fails the same way. A green install with no
+    explanation is how that goes unnoticed.
+    """
+    monkeypatch.setattr(system_trust, "default_store_is_empty", lambda *a, **k: True)
+    monkeypatch.setattr(system_trust, "system_anchor_pem", lambda **k: _an_anchor_pem())
+    monkeypatch.setattr(urllib.request, "urlopen", _Stub([_verify_error(), _tarball()]))
+
+    monkeypatch.setattr(sys, "platform", "darwin")
+    catalogue._fetch_and_extract(URL, tmp_path)
+
+    err = capsys.readouterr().err
+    assert "trusts no certificate authorities" in err
+    assert "does not fix the interpreter" in err
+    # Pin the platform: the remedy is macOS-specific, so asserting it without
+    # pinning passes on a developer's Mac and fails on a Linux runner.
+    assert "Install Certificates.command" in err
+    assert (tmp_path / "repo-main" / "pack.toml").exists(), "install must still succeed"
+
+
+def test_empty_store_notice_off_macos_omits_mac_only_advice(
+    monkeypatch, tmp_path, capsys, no_env
+):
+    """The same misdirection this change removes, in the other direction.
+
+    Telling a Linux adopter to open an /Applications path is the macOS-only
+    remedy leaking onto a platform that cannot use it.
+    """
+    monkeypatch.setattr(sys, "platform", "linux")
+    monkeypatch.setattr(system_trust, "default_store_is_empty", lambda *a, **k: True)
+    monkeypatch.setattr(system_trust, "system_anchor_pem", lambda **k: _an_anchor_pem())
+    monkeypatch.setattr(urllib.request, "urlopen", _Stub([_verify_error(), _tarball()]))
+
+    catalogue._fetch_and_extract(URL, tmp_path)
+
+    err = capsys.readouterr().err
+    assert "trusts no certificate authorities" in err
+    assert "Install Certificates.command" not in err
+    assert "SSL_CERT_FILE" in err
+
+
+def test_intact_store_recovery_keeps_the_short_notice(
+    monkeypatch, tmp_path, capsys, no_env
+):
+    """The corporate case is not an unconfigured interpreter — don't say it is."""
+    monkeypatch.setattr(system_trust, "default_store_is_empty", lambda *a, **k: False)
+    monkeypatch.setattr(system_trust, "system_anchor_pem", lambda **k: _an_anchor_pem())
+    monkeypatch.setattr(urllib.request, "urlopen", _Stub([_verify_error(), _tarball()]))
+
+    catalogue._fetch_and_extract(URL, tmp_path)
+
+    err = capsys.readouterr().err
+    assert "retrying with operating-system trust anchors" in err
+    assert "trusts no certificate authorities" not in err
+
+
+def _tarball_with_symlink() -> bytes:
+    """A catalogue-shaped archive: a regular file, then a symlink pointing back.
+
+    This is the real shape — the catalogue carries CLAUDE.md -> AGENTS.md, and
+    the target precedes the link in the archive.
+    """
+    buf = io.BytesIO()
+    with tarfile.open(fileobj=buf, mode="w:gz") as tf:
+        payload = b"# agents\n"
+        target = tarfile.TarInfo("repo-main/AGENTS.md")
+        target.size = len(payload)
+        tf.addfile(target, io.BytesIO(payload))
+        link = tarfile.TarInfo("repo-main/CLAUDE.md")
+        link.type = tarfile.SYMTYPE
+        link.linkname = "AGENTS.md"
+        tf.addfile(link)
+    return buf.getvalue()
+
+
+def test_symlink_archive_extracts_where_symlinks_cannot_be_created(
+    monkeypatch, tmp_path, no_env
+):
+    """Windows regression: os.symlink fails, so tarfile copies the target instead.
+
+    That fallback re-reads a member that already went past, which a forward-only
+    stream cannot do — the field error was
+    'seeking backwards is not allowed'. Simulated here by making os.symlink
+    fail, so the case is covered on every platform rather than only on Windows.
+    """
+    def no_symlinks(*a, **k):
+        raise OSError("symbolic link privilege not held")
+
+    monkeypatch.setattr(os, "symlink", no_symlinks)
+    monkeypatch.setattr(
+        urllib.request, "urlopen", _Stub([_tarball_with_symlink()])
+    )
+
+    catalogue._fetch_and_extract(URL, tmp_path)
+
+    assert (tmp_path / "repo-main" / "AGENTS.md").exists()
+    claude = tmp_path / "repo-main" / "CLAUDE.md"
+    assert claude.exists(), "the link target must be copied when links are unavailable"
+    assert claude.read_text() == "# agents\n", "copy must carry the target's content"