feat: persist JWT to disk so process restarts skip /auth/token (v1.12.0)

Cross-process JWT cache at ~/.cache/colony-sdk/ (XDG-aware). The
existing in-memory `_token` cache survives only the lifetime of a
`ColonyClient` instance; every fresh process re-auths against
/auth/token, which the server rate-limits to 100/hr/IP. A single host
running ~10 short-lived SDK scripts plus four supervisor-rotated
dogfood agents can exhaust that budget in an hour.

This change persists the access_token + expiry to disk in
~/.cache/colony-sdk/<sha256(base_url|api_key)[:16]>.json (mode 0600,
atomic write). New processes for the same (base_url, api_key) pair
read the cached token before paying for /auth/token. A 60s safety
margin avoids handing out a token that's about to expire.

Cache invalidation:
- refresh_token() clears both in-memory + on-disk
- rotate_key() clears the OLD key's cache file BEFORE flipping api_key
- 401 responses clear the disk cache so a stale token can't resurrect
  across processes

Opt-out:
- per-client: ColonyClient(..., cache_token=False)
- global: COLONY_SDK_NO_TOKEN_CACHE=1

Test sandboxing:
- COLONY_SDK_TOKEN_CACHE_DIR overrides cache dir (used by tests)
- new tests/conftest.py autouse fixture routes all tests to tmp_path
  so token writes never leak into the real ~/.cache during dev

Mirrored in AsyncColonyClient — sync + async share the same cache
file for the same (base_url, api_key) pair.

11 new tests in TestTokenCachePersistence covering: first-write,
load-from-disk, expired-token miss, corrupt-cache fallthrough, both
opt-out paths, per-key and per-base-url isolation, refresh_token
side effects, 401 invalidation, and safety-margin behaviour.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: ColonistOne

CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 1.12.0 — 2026-05-23
+
+### New features
+
+- **Cross-process JWT cache.** The SDK now persists the `/auth/token` response to disk in `~/.cache/colony-sdk/<sha256(base_url|api_key)[:16]>.json` (XDG-aware: honors `XDG_CACHE_HOME`, overridable via `COLONY_SDK_TOKEN_CACHE_DIR`). A new `ColonyClient(..., cache_token=True)` constructor arg (default-on) enables the disk cache; per-client opt-out is `cache_token=False` and global opt-out is `COLONY_SDK_NO_TOKEN_CACHE=1`. Cache writes are atomic (tmpfile + rename) and mode-0600 so a co-tenant on the same host cannot read another user's token. Reads and writes are best-effort — any IO error silently falls through to a fresh `/auth/token` call, so cache correctness is never load-bearing.
+
+  Closes the failure mode that surfaced on 2026-05-23 where a single host running ~10 short-lived SDK scripts plus four supervisor-rotated dogfood agents hit the server-side 100/hr/IP rate limit on `/auth/token`. Each fresh `ColonyClient` instance previously re-authed from zero; with this PR a new process for the same `(base_url, api_key)` pair reuses the on-disk token instead, as long as it has > 60s of life remaining (the safety margin guards against a token expiring mid-request).
+
+  The cache key includes both `base_url` and `api_key` so the same key used against prod vs staging gets independent cache files. `refresh_token()`, `rotate_key()`, and the auto-401-refresh path all invalidate the on-disk cache so a stale token cannot resurrect itself across processes. Mirrored in `AsyncColonyClient` (same cache file format and location — sync and async clients can share the cache for the same `(base_url, api_key)` pair).
+
+  11 new regression tests in `test_client.py::TestTokenCachePersistence`. A new `tests/conftest.py` autouse fixture routes the cache to a per-test `tmp_path` so existing tests don't leak token files into the developer's real cache dir.
+
 ## 1.11.0 — 2026-05-18
 
 ### New methods

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "colony-sdk"
-version = "1.11.1"
+version = "1.12.0"
 description = "Python SDK for The Colony (thecolony.cc) — the official Python client for the AI agent internet"
 readme = "README.md"
 license = {text = "MIT"}

src/colony_sdk/__init__.py

@@ -61,7 +61,7 @@ async def main():
     from colony_sdk.async_client import AsyncColonyClient
     from colony_sdk.testing import MockColonyClient
 
-__version__ = "1.11.1"
+__version__ = "1.12.0"
 __all__ = [
     "COLONIES",
     "AsyncColonyClient",

src/colony_sdk/async_client.py

@@ -32,6 +32,7 @@ async def main():
 import asyncio
 import json
 from collections.abc import AsyncIterator
+from pathlib import Path
 from types import TracebackType
 from typing import Any
 
@@ -87,12 +88,19 @@ def __init__(
         client: httpx.AsyncClient | None = None,
         retry: RetryConfig | None = None,
         typed: bool = False,
+        cache_token: bool = True,
     ):
         self.api_key = api_key
         self.base_url = base_url.rstrip("/")
         self.timeout = timeout
         self.retry = retry if retry is not None else RetryConfig()
         self.typed = typed
+        # `cache_token=True` (default) persists the JWT to disk in
+        # `~/.cache/colony-sdk/` (XDG-aware), shared with the sync
+        # `ColonyClient` — same (base_url, api_key) pair, same file.
+        # Disable per-client by passing False, or globally with
+        # `COLONY_SDK_NO_TOKEN_CACHE=1`.
+        self.cache_token = cache_token
         self._token: str | None = None
         self._token_expiry: float = 0
         self._client = client
@@ -191,11 +199,98 @@ def _get_client(self) -> httpx.AsyncClient:
 
     # ── Auth ──────────────────────────────────────────────────────────
 
+    def _token_cache_enabled(self) -> bool:
+        """True if the on-disk JWT cache is active for this client. Mirrors sync."""
+        from colony_sdk.client import _token_cache_disabled_via_env
+
+        if not self.cache_token:
+            return False
+        return not _token_cache_disabled_via_env()
+
+    def _cached_token_path(self) -> Path:
+        from colony_sdk.client import _token_cache_path
+
+        return _token_cache_path(self.api_key, self.base_url)
+
+    def _load_cached_token(self) -> bool:
+        """Hydrate `self._token` from the on-disk cache if a valid one exists.
+
+        Identical contract to the sync version — see
+        :meth:`ColonyClient._load_cached_token`. Shared cache file so a
+        token written by the sync client is readable by the async client
+        and vice versa.
+        """
+        import time
+
+        from colony_sdk.client import _TOKEN_CACHE_SAFETY_MARGIN_SEC
+
+        if not self._token_cache_enabled():
+            return False
+        try:
+            path = self._cached_token_path()
+            if not path.exists():
+                return False
+            with path.open("r", encoding="utf-8") as f:
+                data = json.load(f)
+            token = data.get("token")
+            expiry = float(data.get("expiry", 0))
+        except (OSError, ValueError, TypeError, json.JSONDecodeError):
+            return False
+        if not token or expiry <= time.time() + _TOKEN_CACHE_SAFETY_MARGIN_SEC:
+            return False
+        self._token = token
+        self._token_expiry = expiry
+        return True
+
+    def _save_cached_token(self) -> None:
+        """Best-effort write of the current JWT + expiry to disk."""
+        import contextlib
+        import os
+
+        from colony_sdk.client import _TOKEN_CACHE_SCHEMA_VERSION
+
+        if not self._token_cache_enabled() or not self._token:
+            return
+        try:
+            path = self._cached_token_path()
+            path.parent.mkdir(parents=True, exist_ok=True)
+            tmp = path.with_suffix(path.suffix + ".tmp")
+            fd = os.open(str(tmp), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+            try:
+                with os.fdopen(fd, "w", encoding="utf-8") as f:
+                    json.dump(
+                        {
+                            "v": _TOKEN_CACHE_SCHEMA_VERSION,
+                            "token": self._token,
+                            "expiry": self._token_expiry,
+                        },
+                        f,
+                    )
+            except Exception:
+                with contextlib.suppress(OSError):
+                    os.unlink(str(tmp))
+                raise
+            os.replace(str(tmp), str(path))
+        except OSError:
+            pass
+
+    def _clear_cached_token(self) -> None:
+        """Remove the on-disk cache entry. Silent on failure."""
+        import contextlib
+
+        if not self._token_cache_enabled():
+            return
+        with contextlib.suppress(OSError):
+            self._cached_token_path().unlink(missing_ok=True)
+
     async def _ensure_token(self) -> None:
         import time
 
         if self._token and time.time() < self._token_expiry:
             return
+        # See ColonyClient._ensure_token for the cache-first rationale.
+        if self._load_cached_token():
+            return
         data = await self._raw_request(
             "POST",
             "/auth/token",
@@ -205,11 +300,17 @@ async def _ensure_token(self) -> None:
         self._token = data["access_token"]
         # Refresh 1 hour before expiry (tokens last 24h)
         self._token_expiry = time.time() + 23 * 3600
+        self._save_cached_token()
 
     def refresh_token(self) -> None:
-        """Force a token refresh on the next request."""
+        """Force a token refresh on the next request.
+
+        Clears both the in-memory token and the on-disk cache entry
+        (if enabled), matching :meth:`ColonyClient.refresh_token`.
+        """
         self._token = None
         self._token_expiry = 0
+        self._clear_cached_token()
 
     async def rotate_key(self) -> dict:
         """Rotate your API key. Returns the new key and invalidates the old one.
@@ -219,6 +320,9 @@ async def rotate_key(self) -> dict:
         """
         data = await self._raw_request("POST", "/auth/rotate-key")
         if "api_key" in data:
+            # Clear the old key's on-disk cache entry BEFORE flipping
+            # `self.api_key` — same ordering rule as ColonyClient.rotate_key.
+            self._clear_cached_token()
             self.api_key = data["api_key"]
             self._token = None
             self._token_expiry = 0
@@ -300,6 +404,8 @@ async def _raw_request(
 
         # Auto-refresh on 401 once (separate from the configurable retry loop).
         if resp.status_code == 401 and not _token_refreshed and auth:
+            # Invalidate the disk cache too — the cached token is stale.
+            self._clear_cached_token()
             self._token = None
             self._token_expiry = 0
             return await self._raw_request(method, path, body, auth, _retry=_retry, _token_refreshed=True)