claude-multiacc 2.0.51 → 2.0.52

package/bin/codex

@@ -1348,7 +1348,7 @@ else
     [ "$AR_PROBE" = "1" ] \
       || sel_log "all-limited fallback=$(basename "$PICK_DIR") weekly=$(fresh_field "$PICK_DIR" weekly_percent || echo '?')%"
   # Keep the same ChatGPT login. The helper never enables API keys and fails closed
-  # on stale/unknown wallets, spend controls and unresolved paid refusals.
+  # on unknown wallets, authentication errors, spend controls and unresolved paid refusals.
   elif [ "${CODEX_MULTIACC_CREDITS:-1}" != "0" ] && [ "${#paid[@]}" -gt 0 ] \
     && credit_pick="$("$MCP_PYBIN" "$SELF_DIR/../lib/codex_credit_selection.py" \
       pick "$now" "${paid[@]}" 2>/dev/null)" && [ -n "$credit_pick" ]; then

package/bin/codex-accounts

@@ -1075,6 +1075,12 @@ cmd_relogin() {
   [ -z "$failed" ]
 }
 
+codex_limits_lock_release() {
+  [ -n "${LIMITS_LOCK:-}" ] && "$PYBIN" "$LIB_DIR/codex_limits_lock.py" release "$LIMITS_LOCK" "$$"
+  LIMITS_LOCK=""
+  return 0
+}
+
 cmd_limits() {
   require_manifest
   local quiet=0 force=0 json=0
@@ -1088,23 +1094,14 @@ cmd_limits() {
   done
   local lock="$ACC_ROOT/.locks/limits"
   mkdir -p "$ACC_ROOT/.locks"
-  if ! mkdir "$lock" 2>/dev/null; then
-    local age=$(( $(epoch_now) - $(file_mtime "$lock") ))
-    if [ "$age" -lt 120 ]; then
-      # A --json caller still gets the document (built from the state on disk) —
-      # a machine-readable verb must never answer a concurrent run with silence.
-      if [ "$json" = "1" ]; then emit_report_json limits; return $?; fi
-      [ "$quiet" = "1" ] || echo "another limits refresh is running; skipping"
-      return 0
-    fi
-    rm -rf "$lock"
-    if ! mkdir "$lock" 2>/dev/null; then
-      if [ "$json" = "1" ]; then emit_report_json limits; return $?; fi
-      return 0
-    fi
+  if ! "$PYBIN" "$LIB_DIR/codex_limits_lock.py" acquire "$lock" "$$"; then
+    # JSON callers still get the cached document while a live refresh owns the lock.
+    if [ "$json" = "1" ]; then emit_report_json limits; return $?; fi
+    [ "$quiet" = "1" ] || echo "another limits refresh is running; skipping"
+    return 0
   fi
   LIMITS_LOCK="$lock"
-  trap limits_lock_release EXIT
+  trap codex_limits_lock_release EXIT
   rotate_log limits.log
   # The >=90% exclusion rule is a hard requirement: the manifest may tighten it but
   # never loosen it, or an account could sit at 95% and still be selected.
@@ -1121,7 +1118,7 @@ root, threshold, quiet, url, force, lib_dir = (sys.argv[1], int(sys.argv[2]),
 sys.path.insert(0, lib_dir)
 from codex_reset_telemetry import refresh_reset_credits
 from codex_credits import collect_credits, failed_credits, record_read_failure
-now = time.time()
+from codex_usage_fetch import fetch_usage, failure_kind, retry_delay
 # Don't re-fetch an account whose data is younger than this (endpoint rate-limits).
 MIN_FETCH_INTERVAL = int(os.environ.get('CODEX_MULTIACC_MIN_FETCH', '240'))
 
@@ -1396,6 +1393,7 @@ def refresh_oauth(aid, d, cpath):
     return tok
 
 for acct in manifest.get('accounts', []):
+    now = time.time()
     aid = acct['id']
     d = os.path.join(root, aid)
     if not os.path.isdir(d):
@@ -1418,7 +1416,8 @@ for acct in manifest.get('accounts', []):
             continue
         retry_at = prev.get('retry_after', 0)
         if retry_at > now:
-            say(f'{aid}: backing off after 429 ({int(retry_at - now)}s left); limits left as-is')
+            reason = '429' if prev.get('last_error') in (None, 'http_429') else 'usage read failure'
+            say(f'{aid}: backing off after {reason} ({int(retry_at - now)}s left); limits left as-is')
             continue
 
     bearer = None
@@ -1448,7 +1447,7 @@ for acct in manifest.get('accounts', []):
     if not bearer:
         # Fail OPEN: no usable bearer => leave existing state; never block work on telemetry.
         say(f'{aid}: no fresh bearer (expired or missing chatgpt auth); limits left as-is')
-        record_read_failure(lpath, prev, 'unauthenticated', now)
+        record_read_failure(lpath, prev, 'unauthenticated', time.time())
         continue
     if not account_id:
         account_id = str((jwt_claims(bearer).get('https://api.openai.com/auth') or {})
@@ -1464,28 +1463,16 @@ for acct in manifest.get('accounts', []):
         headers['chatgpt-account-id'] = account_id
     req = urllib.request.Request(url, headers=headers)
     try:
-        resp = urllib.request.urlopen(req, timeout=15)
-        data = json.loads(resp.read().decode())
-    except urllib.error.HTTPError as e:
-        if e.code == 429:
-            # Respect Retry-After; otherwise exponential backoff capped at 30 min.
-            try:
-                wait = int(e.headers.get('Retry-After') or 0)
-            except (TypeError, ValueError):
-                wait = 0
-            if wait <= 0:
-                wait = min(1800, max(120, int(prev.get('backoff', 60)) * 2))
-            prev['retry_after'] = int(now + wait)
-            prev['backoff'] = wait
-            say(f'{aid}: rate limited (429); backing off {wait}s; failing open')
-        else:
-            say(f'{aid}: usage fetch failed (HTTP {e.code}); failing open')
-        error = f'http_{e.code}' if e.code in (401, 403, 429) else 'http_error'
-        record_read_failure(lpath, prev, error, now)
-        continue
+        data = fetch_usage(req)
+        now = time.time()
     except Exception as e:
-        say(f'{aid}: usage fetch failed ({e}); failing open')
-        record_read_failure(lpath, prev, 'usage_read_failed', now)
+        now = time.time()
+        error = failure_kind(e)
+        wait = retry_delay(e, prev, now)
+        prev.update(retry_after=int(now + wait), backoff=wait)
+        label = 'rate limited (429)' if error == 'http_429' else f'usage fetch failed ({error})'
+        say(f'{aid}: {label}; backing off {wait}s; failing open')
+        record_read_failure(lpath, prev, error, now)
         continue
 
     def pct_of(v):
@@ -1595,7 +1582,7 @@ for acct in manifest.get('accounts', []):
             walk(data, [])
     except Exception as e:
         say(f'{aid}: unexpected usage payload shape ({e}); failing open')
-        record_read_failure(lpath, prev, 'invalid_usage', now)
+        record_read_failure(lpath, prev, 'invalid_usage', time.time())
         continue
     # Successful fetch: fresh buckets replace everything, backoff state is dropped.
     # THREE selection signals, same reset asymmetry as the claude pool:
@@ -1848,7 +1835,7 @@ PYEOF
   local refresh_rc=$?
   # Release the lock BEFORE the report: a --json caller must not hold the refresh
   # lock while a consumer reads its output.
-  limits_lock_release
+  codex_limits_lock_release
   trap - EXIT
   # The refresher fails open per account; a NON-zero status means the pass itself
   # broke (unreadable manifest, dead python). Report the state anyway — stale data

package/docs/CODEX.md

@@ -110,14 +110,35 @@ Wallet freshness uses its own `fetched_at`, independently of the usage windows a
 earned-reset redemption. Failed usage or malformed wallet reads retain the last known
 balance and timestamp with bounded `last_error`/`last_error_at` fields and `stale: true`.
 A successful wallet read clears that failure. Old or future-dated snapshots also become
-stale; the default report horizon is 900 seconds, matching Codex telemetry. An account
-with no previous wallet stays unknown after a failed read. Reports never expose raw
+stale; the default report horizon is 900 seconds, matching Codex telemetry. This freshness
+label is informational for ordinary credit admission: a previously confirmed positive balance
+or explicit unlimited allowance remains usable through failed refreshes and old observations,
+without a fallback age limit. A failed usage HTTP 401/403 is a telemetry failure, not proof
+that the native CLI's inference login is invalid. Missing authentication, an identity mismatch,
+failed refusal-record access, actual authentication parks and provider spending restrictions
+still deny admission. Invalid or more than 30-seconds-future timestamps never authorize it.
+An account with no previous wallet stays unknown after a failed read. Reports never expose raw
 provider errors, arbitrary response fields or authentication material through this object.
+Partial wallet payloads retain measured funds and can add explicit provider spending restrictions;
+they never clear a previous restriction. A successful full wallet read is required to clear it.
 A successful earned reset marks pre-reset admission facts `usage_reset_pending` until
-the next usage read, so newly refilled included quota is used before paid fallback.
+the next usage read. Cached funds remain usable during that gap; the selector may still label
+the capacity as credit-backed until telemetry confirms the refill. The native Codex client
+uses the provider's live allowance and determines actual billing independently of that label.
 
-Collection adds no network request, inference, purchase, redemption or billing-mode
-change. Earned `usage.reset_credits_available` remain separate: they reset included
+Collection adds no separate balance request, inference, purchase, redemption or billing-mode
+change. The existing usage GET retries a transient routing, DNS, timeout or 5xx failure once
+within a 15-second monotonic budget, with each socket timeout capped at 10 seconds; operating-system
+DNS/socket operations can exceed that budget. HTTP 401/403/429 and responses with `Retry-After`
+are never retried immediately. Failures back off per account, honoring `Retry-After` seconds or
+dates, otherwise doubling from 120 seconds to 900 seconds (1800 for 429). Failed polls keep
+confirmed balances and their original timestamps. Successful observations use the response time,
+not the start of a potentially slow whole-pool pass. Logs and reports distinguish
+`network_unreachable`, `dns_unavailable`, `usage_timeout`, `connection_reset`, `tls_error` and
+`edge_challenge` without exposing raw errors. A live collector's PID-and-birth-bound lock does
+not expire after two minutes; dead collectors' locks can be reclaimed without overlapping a live pass.
+
+Earned `usage.reset_credits_available` remain separate: they reset included
 quota, whereas this wallet funds usage after included quota is exhausted. API-key
 authentication remains unsupported. Consumers must preserve the wallet's timestamp,
 identity, spend-control refusals and failure state when deciding whether credit-backed
@@ -126,9 +147,11 @@ The shim's wallet-and-member-bound paid-refusal receipt is reported separately a
 `usage.credit_blocked_at`, `usage.credit_blocked_balance`, and `usage.limited_reason: "credits"`.
 A genuine paid quota refusal writes `.credit-refused.json` and a `.limited` marker with
 `reason=credit-refused`. Authentication and temporary service errors do not create credit
-refusals. Paid work can retry after 600 seconds and a strictly newer successful observation;
-a newer increased balance permits earlier recovery. Zero funds, missing observations and
-provider spending restrictions still deny paid work. Included quota can recover independently.
+refusals. Paid work can retry after 600 seconds and a strictly newer successful, fresh observation;
+a newer increased balance permits earlier recovery, also requiring a successful fresh read.
+A cached positive balance alone never clears an actual paid refusal. Confirmed finite zero,
+missing monetary observations and provider spending restrictions still deny paid work.
+Included quota can recover independently.
 Copies of the same member share the receipt; different known members of a workspace do not.
 
 ### Credit-aware selection
@@ -141,8 +164,9 @@ this fallback. Explicit account pins continue to represent the caller's choice.
 `multiacc-select --capabilities` advertises `codex_credits_v1`. A caller enables the additive
 policy with `credit_fallback: true` and may request only paid candidates through
 `required_funding_tier: "credits"`. `credit_max_age_seconds` defaults to 900 (accepted range
-30–3600); observations more than 30 seconds in the future cannot authorize spending.
-Optional candidate fields are:
+30–3600) for freshness reporting and paid-refusal recovery. It does not expire a confirmed
+positive balance for ordinary credit admission. Observations more than 30 seconds in the future
+cannot authorize spending. Optional candidate fields are:
 
 | Field | Meaning |
 | --- | --- |
@@ -158,11 +182,15 @@ Successful opted-in responses include `credit_capability`, `funding_tier` (`incl
 balance, billing identity, unlimited flag and active holder count; when supplied, the actor
 email is also preserved in the normalized proof and score. New monetary observations replace
 older balances across wallet copies; balances are never summed or merged by maximum.
-Failed monetary observations cannot resurrect an older positive balance. Member permissions,
-actor observation timestamps and local authentication/identity failures remain separate from
-shared finances. Refusals propagate only within the same wallet/member identity; unknown
-actors are handled conservatively. Paid ranking compares balance per active holder, then
-uses the existing deterministic rotation for ties.
+Financial and member-control observations are ordered by their actual `fetched_at`, never a
+later failed refresh's `last_error_at`. An old cached positive balance cannot replace a newer
+confirmed zero; an old cached allowance cannot erase a newer confirmed member restriction.
+Explicit unlimited allowance remains distinct from finite balances, including null or zero.
+Member permissions, actor observation timestamps and local authentication/identity failures
+remain separate from shared finances. Refusals propagate only within the same wallet/member
+identity; an unknown member's refusal stays with its runner and account slot. Failed or partial reads
+retain restrictive member controls until that source successfully refreshes them. Paid ranking compares
+balance per active holder, then uses the existing deterministic rotation for ties.
 
 The schema and selector version remain `pool-selection.v2` / `2.0.1`. Requests without the
 credit opt-in retain their prior outputs and digests. Extra credit candidate fields without

package/lib/codex_credit_controls.py

@@ -0,0 +1,27 @@
+"""Normalize explicit provider spending controls independently of wallet amounts."""
+
+_LIMIT_TYPES = {
+    "rate_limit_reached", "workspace_owner_credits_depleted", "workspace_member_credits_depleted",
+    "workspace_owner_usage_limit_reached", "workspace_member_usage_limit_reached",
+}
+
+
+def limit_type(value):
+    if isinstance(value, dict):
+        value = value.get("type", "unknown")
+    if value is None:
+        return None
+    return value if isinstance(value, str) and value in _LIMIT_TYPES else "unknown"
+
+
+def usage_controls(usage, root):
+    limit = root.get("rate_limit")
+    limit = limit if isinstance(limit, dict) else {}
+    ordinary = usage.get("ordinary_usage_allowed", usage.get("ordinaryUsageAllowed", limit.get("allowed")))
+    reached = root.get("rate_limit_reached_type", root.get("rateLimitReachedType", limit.get("limit_reached_type")))
+    spend = root.get("spend_control")
+    spend = spend if isinstance(spend, dict) else {}
+    spend_reached = root.get("spend_control_reached", root.get("spendControlReached", spend.get("reached")))
+    return {"ordinary_usage_allowed": ordinary if type(ordinary) is bool else None,
+            "spend_control_reached": spend_reached if type(spend_reached) is bool else None,
+            "limit_reached_type": limit_type(reached)}

package/lib/codex_credit_selection.py

@@ -14,7 +14,7 @@ from pathlib import Path
 
 from selector_credits import balance_value, normalize_credits, refusal_recovered
 from selector_funding import credit_rank, wallet_snapshots
-from selector_credit_scope import merge_wallet
+from selector_credit_scope import actor_observations, merge_actor, merge_wallet
 from codex_credit_local_scope import pool_actor, merged_local_refusals, local_refusal_key
 from selector_primitives import canonical_sha256, timestamp
 
@@ -51,9 +51,10 @@ def marker_allows(directory, now):
         return False
 
 
-def candidate(directory, now, wallets, refusals):
+def candidate(directory, now, wallets, refusals, observations):
     data = read_json(directory / "limits.json")
     credits = normalize_credits(data.get("credits"), datetime.fromtimestamp(now, timezone.utc))
+    credits = merge_actor(credits, observations.get(local_refusal_key(directory, credits)))
     credits = merge_wallet(credits, wallets.get(credits["account_id"]))
     refusal = dict(credit_refusal_view(directory), **refusals.get(local_refusal_key(directory, credits), {}))
     if not credits["available"] or not refusal_recovered(refusal, credits, datetime.fromtimestamp(now, timezone.utc)):
@@ -88,10 +89,15 @@ def active_holders(root, now, cleanup=False):
 
 
 def pick(now, directories):
-    snapshots = [read_json(Path(directory) / "limits.json") for directory in directories]
+    snapshots = [dict(read_json(Path(directory) / "limits.json"),
+                      credit_actor_email=pool_actor(Path(directory)),
+                      runner_id=str(Path(directory).parent.resolve()), account_id=Path(directory).name)
+                 for directory in directories]
+    observations = actor_observations(snapshots, datetime.fromtimestamp(now, timezone.utc), 900)
     wallets = wallet_snapshots(snapshots, datetime.fromtimestamp(now, timezone.utc), 900)
     refusals = merged_local_refusals(directories, read_json, credit_refusal_view)
-    rows = [row for directory in directories if (row := candidate(Path(directory), now, wallets, refusals))]
+    rows = [row for directory in directories
+            if (row := candidate(Path(directory), now, wallets, refusals, observations))]
     if not rows:
         return ""
     holders = active_holders(Path(directories[0]).parent, now)

package/lib/codex_credits.py

@@ -9,17 +9,16 @@ import os
 import re
 import time
 
+from codex_usage_fetch import TRANSPORT_ERRORS
+from codex_credit_controls import limit_type as _limit_type, usage_controls as _controls
+
 _DECIMAL = re.compile(r"(?:0|[1-9][0-9]*)(?:\.[0-9]+)?\Z")
 _IDENTITY = re.compile(r"[A-Za-z0-9][A-Za-z0-9_.:@/-]{0,199}\Z")
-_LIMIT_TYPES = {
-    "rate_limit_reached", "workspace_owner_credits_depleted", "workspace_member_credits_depleted",
-    "workspace_owner_usage_limit_reached", "workspace_member_usage_limit_reached",
-}
 _ERRORS = {
     "missing_credits", "invalid_credits", "account_mismatch", "unauthenticated",
     "usage_read_failed", "invalid_usage", "http_401", "http_403", "http_429", "http_error",
     "usage_reset_pending",
-}
+} | TRANSPORT_ERRORS
 
 
 def _iso(value: float) -> str:
@@ -47,39 +46,24 @@ def _optional_bool(value):
     return value if type(value) is bool else None
 
 
-def _limit_type(value):
-    if isinstance(value, dict):
-        value = value.get("type", "unknown")
-    if value is None:
-        return None
-    return value if isinstance(value, str) and value in _LIMIT_TYPES else "unknown"
-
-
 def snapshot_from_usage(usage: dict, account_id: str, now: float) -> dict:
     """Bind the provider's wallet and admission facts to the authenticated account."""
     if not isinstance(usage, dict):
         raise ValueError("invalid_usage")
     root = usage.get("rateLimits")
     root = root if isinstance(root, dict) else usage
-    raw = root.get("credits")
-    if not isinstance(raw, dict):
-        raise ValueError("missing_credits")
-    has_credits = raw.get("has_credits", raw.get("hasCredits"))
-    if type(has_credits) is not bool or type(raw.get("unlimited")) is not bool:
-        raise ValueError("invalid_credits")
     response_id = usage.get("account_id", usage.get("accountId"))
     expected, reported = _identity(account_id), _identity(response_id)
     if response_id is not None and not reported:
         raise ValueError("account_mismatch")
     if expected and reported and expected != reported:
         raise ValueError("account_mismatch")
-    limit = root.get("rate_limit")
-    limit = limit if isinstance(limit, dict) else {}
-    ordinary = usage.get("ordinary_usage_allowed", usage.get("ordinaryUsageAllowed", limit.get("allowed")))
-    reached = root.get("rate_limit_reached_type", root.get("rateLimitReachedType", limit.get("limit_reached_type")))
-    spend = root.get("spend_control")
-    spend = spend if isinstance(spend, dict) else {}
-    spend_reached = root.get("spend_control_reached", root.get("spendControlReached", spend.get("reached")))
+    raw = root.get("credits")
+    if not isinstance(raw, dict):
+        raise ValueError("missing_credits")
+    has_credits = raw.get("has_credits", raw.get("hasCredits"))
+    if type(has_credits) is not bool or type(raw.get("unlimited")) is not bool:
+        raise ValueError("invalid_credits")
     try:
         balance = _balance(raw.get("balance"))
     except ValueError as error:
@@ -87,9 +71,7 @@ def snapshot_from_usage(usage: dict, account_id: str, now: float) -> dict:
     return {
         "has_credits": has_credits, "unlimited": raw["unlimited"], "balance": balance,
         "fetched_at": _iso(now), "account_id": reported or expected,
-        "ordinary_usage_allowed": _optional_bool(ordinary),
-        "spend_control_reached": _optional_bool(spend_reached),
-        "limit_reached_type": _limit_type(reached),
+        **_controls(usage, root),
     }
 
 
@@ -132,9 +114,11 @@ def credit_view(value, now: float | None = None, stale_after: int = 900) -> dict
 
 
 def failed_credits(previous, error: str, now: float) -> dict | None:
-    """A failed read invalidates spending evidence without inventing a zero balance."""
+    """Keep the last measured amount and its age when a telemetry read fails."""
     out = credit_view(previous, now)
     if out is not None:
+        if out.get("last_error") in ("account_mismatch", "unauthenticated"):
+            return out
         out.update(last_error=error if error in _ERRORS else "usage_read_failed",
                    last_error_at=_iso(now), stale=True)
     return out
@@ -142,9 +126,21 @@ def failed_credits(previous, error: str, now: float) -> dict | None:
 
 def collect_credits(usage, account_id: str, now: float, previous=None) -> dict | None:
     try:
-        return snapshot_from_usage(usage, account_id, now)
+        result = snapshot_from_usage(usage, account_id, now)
+        if previous and result["has_credits"] and not result["unlimited"] and result["balance"] is None:
+            raise ValueError("invalid_credits")
+        return result
     except ValueError as error:
-        return failed_credits(previous, str(error), now)
+        result = failed_credits(previous, str(error), now)
+        if result is not None and str(error) in ("missing_credits", "invalid_credits"):
+            root = usage.get("rateLimits")
+            root = root if isinstance(root, dict) else usage
+            controls = _controls(usage, root)
+            if controls["spend_control_reached"] is True:
+                result["spend_control_reached"] = True
+            if controls["limit_reached_type"] not in (None, "rate_limit_reached"):
+                result["limit_reached_type"] = controls["limit_reached_type"]
+        return result
 
 
 def record_read_failure(path: str, previous: dict, error: str, now: float) -> None:

package/lib/codex_limits_lock.py

@@ -0,0 +1,56 @@
+"""Keep a live Codex usage collector's lock even when a slow pass exceeds two minutes."""
+
+from __future__ import annotations
+
+import fcntl
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import time
+
+
+def process_birth(pid: int) -> str:
+    try:
+        os.kill(pid, 0)
+        result = subprocess.run(["ps", "-p", str(pid), "-o", "lstart="],
+                                capture_output=True, text=True, timeout=5, check=False)
+        return result.stdout.strip() if result.returncode == 0 else ""
+    except (OSError, subprocess.TimeoutExpired):
+        return ""
+
+
+def change_lock(path: Path, pid: int, release: bool = False) -> bool:
+    """Serialize ownership changes; the owner process lifetime governs the lease."""
+    birth = process_birth(pid)
+    if not birth:
+        return False
+    with path.with_suffix(".guard").open("a") as guard:
+        fcntl.flock(guard, fcntl.LOCK_EX)
+        owner = {}
+        try:
+            owner = json.loads((path / "owner.json").read_text())
+        except (OSError, ValueError):
+            pass
+        ours = owner == {"pid": pid, "birth": birth}
+        if release:
+            if ours:
+                shutil.rmtree(path)
+            return ours
+        if path.exists():
+            owner_pid = owner.get("pid") if isinstance(owner, dict) else None
+            if isinstance(owner_pid, int) and owner_pid > 0:
+                if owner.get("birth") and process_birth(owner_pid) == owner["birth"]:
+                    return False
+            elif time.time() - path.stat().st_mtime < 120:
+                return False
+            shutil.rmtree(path)
+        path.mkdir()
+        (path / "owner.json").write_text(json.dumps({"pid": pid, "birth": birth}))
+        return True
+
+
+if __name__ == "__main__":
+    sys.exit(0 if change_lock(Path(sys.argv[2]), int(sys.argv[3]), sys.argv[1] == "release") else 1)

package/lib/codex_usage_fetch.py

@@ -0,0 +1,85 @@
+"""Read-only usage transport with bounded retries and non-secret failure categories."""
+
+from __future__ import annotations
+
+from email.utils import parsedate_to_datetime
+import errno
+import json
+import socket
+import ssl
+import time
+import urllib.error
+import urllib.request
+
+TRANSPORT_ERRORS = {
+    "network_unreachable", "dns_unavailable", "usage_timeout", "connection_reset",
+    "tls_error", "edge_challenge",
+}
+
+
+def failure_kind(error: Exception) -> str:
+    """Classify the exception without retaining URLs, headers, bodies, or tokens."""
+    if isinstance(error, urllib.error.HTTPError):
+        if ((error.headers or {}).get("cf-mitigated") or "").lower() == "challenge":
+            return "edge_challenge"
+        return f"http_{error.code}" if error.code in (401, 403, 429) else "http_error"
+    reason = error.reason if isinstance(error, urllib.error.URLError) else error
+    if isinstance(reason, socket.gaierror):
+        return "dns_unavailable"
+    if isinstance(reason, (socket.timeout, TimeoutError)):
+        return "usage_timeout"
+    if isinstance(reason, ssl.SSLError):
+        return "tls_error"
+    if isinstance(reason, OSError):
+        if reason.errno in (errno.EHOSTUNREACH, errno.ENETUNREACH, errno.ENETDOWN):
+            return "network_unreachable"
+        if reason.errno in (errno.ECONNRESET, errno.ECONNREFUSED, errno.EPIPE):
+            return "connection_reset"
+    if isinstance(error, (ValueError, UnicodeError)):
+        return "invalid_usage"
+    return "usage_read_failed"
+
+
+def retryable(error: Exception) -> bool:
+    if isinstance(error, urllib.error.HTTPError):
+        return error.code in (500, 502, 503, 504) and not (error.headers or {}).get("Retry-After")
+    return failure_kind(error) in TRANSPORT_ERRORS - {"tls_error", "edge_challenge"}
+
+
+def fetch_usage(request, budget: float = 15):
+    """Retry once within a monotonic budget; OS DNS/socket operations retain their own timeouts."""
+    deadline = time.monotonic() + budget
+    for attempt in range(2):
+        remaining = max(0.1, deadline - time.monotonic())
+        try:
+            with urllib.request.urlopen(request, timeout=min(10, remaining)) as response:
+                result = json.loads(response.read().decode())
+            if not isinstance(result, dict):
+                raise ValueError("invalid usage object")
+            return result
+        except Exception as error:
+            if isinstance(error, urllib.error.HTTPError):
+                error.close()
+            if attempt or not retryable(error) or time.monotonic() >= deadline:
+                raise
+
+
+def retry_delay(error: Exception, previous: dict, now: float) -> int:
+    """Honor Retry-After; otherwise back off transient failures without hammering an account."""
+    header = (error.headers or {}).get("Retry-After") if isinstance(error, urllib.error.HTTPError) else None
+    if header:
+        try:
+            delay = int(header)
+        except (TypeError, ValueError):
+            try:
+                delay = int(parsedate_to_datetime(header).timestamp() - now)
+            except (TypeError, ValueError, OverflowError):
+                delay = 0
+        if delay > 0:
+            return delay
+    try:
+        prior = int(previous.get("backoff", 60))
+    except (TypeError, ValueError):
+        prior = 60
+    ceiling = 1800 if failure_kind(error) == "http_429" else 900
+    return min(ceiling, max(120, prior * 2))