claude-multiacc 2.0.49 → 2.0.51

package/lib/codex_credit_selection.py

@@ -0,0 +1,166 @@
+"""Local Codex shim credit fallback and durable paid-refusal receipts.
+
+Only reads telemetry already collected by codex-accounts; never calls a provider.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+from datetime import datetime, timezone
+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 codex_credit_local_scope import pool_actor, merged_local_refusals, local_refusal_key
+from selector_primitives import canonical_sha256, timestamp
+
+
+def read_json(path):
+    try:
+        value = json.loads(path.read_text())
+        return value if isinstance(value, dict) else {}
+    except (OSError, ValueError):
+        return {}
+
+
+def write_json(path, value):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_name(f"{path.name}.{os.getpid()}.tmp")
+    with temporary.open("w") as target:
+        os.chmod(temporary, 0o600)
+        json.dump(value, target, separators=(",", ":"))
+    temporary.replace(path)
+
+
+def marker_allows(directory, now):
+    try:
+        lines = (directory / ".limited").read_text().splitlines()
+        if float(lines[0]) <= now:
+            return True
+        fields = dict(item.split("=", 1) for item in lines[1].split() if "=" in item)
+        reason = fields.get("reason")
+        return reason in {"limits", "client-rate-limit"} or (
+            reason == "credit-refused" and bool(credit_refusal_view(directory)))
+    except FileNotFoundError:
+        return True
+    except (OSError, ValueError, IndexError):
+        return False
+
+
+def candidate(directory, now, wallets, refusals):
+    data = read_json(directory / "limits.json")
+    credits = normalize_credits(data.get("credits"), datetime.fromtimestamp(now, timezone.utc))
+    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)):
+        return None
+    if not marker_allows(directory, now):
+        return None
+    # A paid fallback needs evidence that the subscription is exhausted. At90-99%
+    # the ordinary reserve still takes precedence and its existing gate/band apply.
+    values = [data.get(key) for key in ("weekly_percent", "session_percent")]
+    exhausted = any(isinstance(v, (int, float)) and not isinstance(v, bool) and v >= 100 for v in values)
+    if not exhausted and credits["ordinary_usage_allowed"] is not False:
+        return None
+    return {"directory": str(directory), "credits": credits, "credit_active_holders": 0}
+
+
+def active_holders(root, now, cleanup=False):
+    holders = {}
+    for record in root.glob("acct-*/.credit-sessions/*.json"):
+        data = read_json(record)
+        try:
+            pid = int(record.stem)
+            if pid <= 0 or now - float(data["launched_at"]) > 86400:
+                continue
+            os.kill(pid, 0)
+        except (KeyError, ValueError, OSError):
+            if cleanup:
+                record.unlink(missing_ok=True)
+            continue
+        account = data.get("account_id")
+        holders[account] = holders.get(account, 0) + 1
+    return holders
+
+
+def pick(now, directories):
+    snapshots = [read_json(Path(directory) / "limits.json") for directory in directories]
+    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))]
+    if not rows:
+        return ""
+    holders = active_holders(Path(directories[0]).parent, now)
+    for row in rows:
+        row["credit_active_holders"] = holders.get(row["credits"]["account_id"], 0)
+    best = min(credit_rank(row) for row in rows)
+    rows = [row for row in rows if credit_rank(row) == best]
+    root = Path(directories[0]).parent
+    try:
+        previous = (root / ".last-pick").read_text().strip()
+    except OSError:
+        previous = ""
+    peers = [row for row in rows if Path(row["directory"]).name != previous] or rows
+    return min(peers, key=lambda row: canonical_sha256(
+        [str(now), str(os.getppid()), row["credits"]["account_id"], row["directory"]]))["directory"]
+
+
+def record_launch(directory, pid, now):
+    active_holders(directory.parent, now, cleanup=True)
+    credits = read_json(directory / "limits.json").get("credits") or {}
+    write_json(directory / ".credit-sessions" / f"{pid}.json", {
+        "account_id": credits.get("account_id"), "balance": credits.get("balance"), "launched_at": now,
+        "credit_actor_email": pool_actor(directory)})
+
+
+def record_refusal(directory, pid, now):
+    launch = read_json(directory / ".credit-sessions" / f"{pid}.json")
+    current = (read_json(directory / "limits.json").get("credits") or {})
+    balance = launch.get("balance")
+    if not launch:
+        balance = current.get("balance")
+    write_json(directory / ".credit-refused.json", {
+        "credit_blocked_at": datetime.fromtimestamp(now, timezone.utc).isoformat(),
+        "credit_blocked_balance": balance, "limited_reason": "credits",
+        "account_id": launch.get("account_id") or current.get("account_id"),
+        "credit_actor_email": launch.get("credit_actor_email", pool_actor(directory))})
+    (directory / ".credit-sessions" / f"{pid}.json").unlink(missing_ok=True)
+
+
+def credit_refusal_view(directory):
+    directory = Path(directory)
+    refusal = read_json(directory / ".credit-refused.json")
+    account = (read_json(directory / "limits.json").get("credits") or {}).get("account_id")
+    if not account or refusal.get("account_id") != account:
+        return {}
+    actor = pool_actor(directory)
+    if refusal.get("credit_actor_email") and refusal["credit_actor_email"] != actor:
+        return {}
+    try:
+        _, blocked_at = timestamp(refusal.get("credit_blocked_at"))
+    except ValueError:
+        blocked_at = None
+    return {"credit_blocked_at": blocked_at,
+            "credit_blocked_balance": balance_value(refusal.get("credit_blocked_balance")),
+            "limited_reason": "credits"}
+
+
+def main(argv):
+    now = time.time()
+    if argv[0] == "pick":
+        print(pick(float(argv[1]), argv[2:]))
+    elif argv[0] == "record":
+        record_launch(Path(argv[1]), int(argv[2]), now)
+    elif argv[0] == "refuse":
+        record_refusal(Path(argv[1]), int(argv[2]), now)
+    else:
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/lib/codex_credits.py

@@ -0,0 +1,162 @@
+"""Spendable Codex credits from the existing usage read; never redeem or infer funds."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from decimal import Decimal, InvalidOperation
+import json
+import os
+import re
+import time
+
+_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",
+}
+
+
+def _iso(value: float) -> str:
+    return datetime.fromtimestamp(value, timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def _balance(value):
+    if value is None:
+        return None
+    if not isinstance(value, str) or len(value) > 128 or not _DECIMAL.fullmatch(value):
+        raise ValueError("invalid credit balance")
+    try:
+        number = Decimal(value)
+    except InvalidOperation as error:
+        raise ValueError("invalid credit balance") from error
+    result = format(number, "f")
+    return result.rstrip("0").rstrip(".") if "." in result else result
+
+
+def _identity(value):
+    return value if isinstance(value, str) and _IDENTITY.fullmatch(value) else None
+
+
+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")))
+    try:
+        balance = _balance(raw.get("balance"))
+    except ValueError as error:
+        raise ValueError("invalid_credits") from error
+    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),
+    }
+
+
+def credit_view(value, now: float | None = None, stale_after: int = 900) -> dict | None:
+    """Sanitize the stored snapshot, preserving its own timestamp and unknown values."""
+    if not isinstance(value, dict):
+        return None
+    if type(value.get("has_credits")) is not bool or type(value.get("unlimited")) is not bool:
+        return None
+    try:
+        stamp = datetime.fromisoformat(value["fetched_at"].replace("Z", "+00:00"))
+        if stamp.tzinfo is None or stamp.timestamp() <= 0:
+            return None
+        age = (time.time() if now is None else now) - stamp.timestamp()
+        balance = _balance(value.get("balance"))
+    except (KeyError, ValueError, TypeError, AttributeError, OverflowError):
+        return None
+    reached = value.get("limit_reached_type")
+    out = {
+        "has_credits": value["has_credits"], "unlimited": value["unlimited"], "balance": balance,
+        "fetched_at": _iso(stamp.timestamp()), "account_id": _identity(value.get("account_id")),
+        "ordinary_usage_allowed": _optional_bool(value.get("ordinary_usage_allowed")),
+        "spend_control_reached": _optional_bool(value.get("spend_control_reached")),
+        "limit_reached_type": _limit_type(reached),
+        "age_seconds": max(0, int(age)), "stale": age > stale_after or age < -30,
+    }
+    error = value.get("last_error")
+    if error:
+        out["last_error"] = error if isinstance(error, str) and error in _ERRORS else "usage_read_failed"
+        out["stale"] = True
+        stamp = value.get("last_error_at")
+        if isinstance(stamp, str) and len(stamp) <= 64:
+            try:
+                parsed = datetime.fromisoformat(stamp.replace("Z", "+00:00"))
+                if parsed.tzinfo is not None and parsed.timestamp() > 0:
+                    out["last_error_at"] = _iso(parsed.timestamp())
+            except (ValueError, OverflowError):
+                pass
+    return out
+
+
+def failed_credits(previous, error: str, now: float) -> dict | None:
+    """A failed read invalidates spending evidence without inventing a zero balance."""
+    out = credit_view(previous, now)
+    if out is not None:
+        out.update(last_error=error if error in _ERRORS else "usage_read_failed",
+                   last_error_at=_iso(now), stale=True)
+    return out
+
+
+def collect_credits(usage, account_id: str, now: float, previous=None) -> dict | None:
+    try:
+        return snapshot_from_usage(usage, account_id, now)
+    except ValueError as error:
+        return failed_credits(previous, str(error), now)
+
+
+def record_read_failure(path: str, previous: dict, error: str, now: float) -> None:
+    """Persist a bounded non-secret failure while retaining earlier usage observations."""
+    out = dict(previous)
+    out.update(last_error=error if error in _ERRORS else "usage_read_failed", last_error_at=int(now))
+    credits = failed_credits(out.get("credits"), error, now)
+    if credits is not None:
+        out["credits"] = credits
+    else:
+        out.pop("credits", None)
+    temporary = path + ".tmp"
+    with open(temporary, "w", encoding="utf-8") as handle:
+        json.dump(out, handle, indent=1)
+    os.replace(temporary, path)

package/lib/report.py

@@ -49,6 +49,8 @@ import keychain  # noqa: E402
 from audit import creds_doc_state, token_verified  # noqa: E402
 from claude_client_error import org_access_verified_at  # noqa: E402
 from claude_reset import marker_superseded, record_from  # noqa: E402
+from codex_credits import credit_view  # noqa: E402
+from codex_credit_selection import credit_refusal_view  # noqa: E402
 
 SCHEMA = 'claude-multiacc/pool.v1'
 
@@ -262,6 +264,10 @@ def _usage(d, stale_after):
     out = {'fetched_at': _iso(fetched), 'source': lim.get('source'),
            'max_percent': lim.get('max_percent'), 'weekly_percent': lim.get('weekly_percent'),
            'session_percent': lim.get('session_percent'), 'buckets': buckets}
+    credits = credit_view(lim.get('credits'), stale_after=stale_after)
+    if credits is not None:
+        out['credits'] = credits
+        out.update(credit_refusal_view(d))
     reset_count = lim.get('reset_credits_available')
     reset_stamp = _iso(lim.get('reset_credits_fetched_at'))
     if type(reset_count) is int and 0 <= reset_count <= 1_000_000 and reset_stamp:

package/lib/selector_credit_scope.py

@@ -0,0 +1,55 @@
+"""Wallet finances are shared; actor permissions, authentication and refusals are not."""
+
+from __future__ import annotations
+
+from decimal import Decimal
+
+from selector_primitives import timestamp
+
+FINANCIAL_FIELDS = ("has_credits", "unlimited", "balance", "account_id")
+
+
+def actor_email(raw: dict) -> str | None:
+    value = raw.get("credit_actor_email")
+    return value.strip().lower() or None if isinstance(value, str) else None
+
+
+def wallet_available(credits: dict) -> bool:
+    balance = credits.get("balance")
+    funds = credits["unlimited"] or (credits["has_credits"] and balance is not None and Decimal(balance) > 0)
+    return bool(credits["fresh"] and not credits["last_error"] and funds)
+
+
+def merge_wallet(local: dict, wallet: dict | None) -> dict:
+    if wallet is None:
+        return local
+    merged = dict(local)
+    merged.update({key: wallet[key] for key in FINANCIAL_FIELDS})
+    merged["available"] = bool(local["fresh"] and not local["last_error"]
+                               and not local["spend_control_reached"] and wallet["available"])
+    return merged
+
+
+def actor_key(raw: dict) -> tuple:
+    credits = raw.get("credits") or {}
+    account, actor = credits.get("account_id"), actor_email(raw)
+    if actor:
+        return account, actor
+    return account, None, raw.get("runner_id"), raw.get("account_id")
+
+
+def actor_refusals(candidates: list[dict]) -> dict:
+    refusals = {}
+    for raw in candidates:
+        if not raw.get("credit_blocked_at") or (raw.get("credits") or {}).get("last_error"):
+            continue
+        try:
+            _, blocked = timestamp(raw["credit_blocked_at"])
+        except ValueError:
+            continue
+        key = actor_key(raw)
+        previous = refusals.get(key)
+        if key[0] and (previous is None or blocked > previous["credit_blocked_at"]):
+            refusals[key] = {"credit_blocked_at": blocked,
+                             "credit_blocked_balance": raw.get("credit_blocked_balance")}
+    return refusals

package/lib/selector_credits.py

@@ -0,0 +1,99 @@
+"""Pure, fail-closed credit telemetry normalization; no files or provider calls."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from decimal import Decimal, InvalidOperation
+
+from selector_primitives import DECIMAL_RE, timestamp
+
+CAPABILITY = "codex_credits_v1"
+CREDIT_FIELDS = {
+    "has_credits", "unlimited", "balance", "fetched_at", "account_id", "ordinary_usage_allowed",
+    "spend_control_reached", "limit_reached_type", "last_error", "last_error_at", "stale", "age_seconds"}
+OPTIONAL_CANDIDATE_FIELDS = {
+    "credits", "credit_capable", "credit_active_holders", "credit_blocked_at", "credit_blocked_balance",
+    "limited_reason", "credit_actor_email"}
+
+
+def balance_value(value: object) -> str | None:
+    """Credits are arbitrary nonnegative decimals, never percentages or money."""
+    if not isinstance(value, str) or len(value) > 100 or not DECIMAL_RE.fullmatch(value):
+        return None
+    try:
+        number = Decimal(value)
+        if number < 0 or not number.is_finite():
+            return None
+        plain = format(number, "f")
+        return plain.rstrip("0").rstrip(".") if "." in plain else plain
+    except (InvalidOperation, ValueError):
+        return None
+
+
+def credit_candidate_error(raw: dict, field: str) -> str | None:
+    if "credit_capable" in raw and not isinstance(raw["credit_capable"], bool):
+        return f"{field}.credit_capable"
+    holders = raw.get("credit_active_holders", 0)
+    if isinstance(holders, bool) or not isinstance(holders, int) or not 0 <= holders <= 1_000_000:
+        return f"{field}.credit_active_holders"
+    for name in ("credit_blocked_at", "credit_blocked_balance", "limited_reason", "credit_actor_email"):
+        if raw.get(name) is not None and not isinstance(raw[name], str):
+            return f"{field}.{name}"
+    actor = raw.get("credit_actor_email")
+    if actor is not None and (len(actor) > 320 or any(c in actor for c in "\r\n\0")):
+        return f"{field}.credit_actor_email"
+    credits = raw.get("credits")
+    if credits is None:
+        return None
+    if not isinstance(credits, dict) or set(credits) - CREDIT_FIELDS:
+        return f"{field}.credits"
+    for name in ("balance", "fetched_at", "account_id", "limit_reached_type", "last_error", "last_error_at"):
+        if credits.get(name) is not None and not isinstance(credits[name], str):
+            return f"{field}.credits.{name}"
+    for name in ("has_credits", "unlimited", "ordinary_usage_allowed", "spend_control_reached", "stale"):
+        if credits.get(name) is not None and not isinstance(credits[name], bool):
+            return f"{field}.credits.{name}"
+    return None
+
+
+def normalize_credits(raw: object, now: datetime, max_age: int = 900) -> dict:
+    raw = raw if isinstance(raw, dict) else {}
+    balance = balance_value(raw.get("balance"))
+    account = raw.get("account_id")
+    account = account.strip() if isinstance(account, str) and len(account) <= 256 else None
+    try:
+        observed, fetched_at = timestamp(raw.get("fetched_at"))
+        fresh = -30 <= (now - observed).total_seconds() <= max_age and raw.get("stale") is not True
+    except (ValueError, TypeError):
+        fetched_at, fresh = None, False
+    reached = raw.get("limit_reached_type")
+    reached = reached.lower() if isinstance(reached, str) else None
+    restricted = raw.get("spend_control_reached") is True or reached not in {
+        None, "", "rate_limit_reached", "usage_limit_reached", "weekly_limit_reached", "session_limit_reached"}
+    available = (raw.get("unlimited") is True or
+                 (raw.get("has_credits") is True and balance is not None and Decimal(balance) > 0))
+    return {
+        "has_credits": raw.get("has_credits") is True, "unlimited": raw.get("unlimited") is True,
+        "balance": balance, "account_id": account or None, "fetched_at": fetched_at,
+        "ordinary_usage_allowed": raw.get("ordinary_usage_allowed")
+        if isinstance(raw.get("ordinary_usage_allowed"), bool) else None,
+        "spend_control_reached": restricted, "limit_reached_type": reached,
+        "last_error": bool(raw.get("last_error")), "fresh": fresh,
+        "available": bool(fresh and account and available and not restricted and not raw.get("last_error"))}
+
+
+def refusal_recovered(raw: dict, credits: dict, now: datetime) -> bool:
+    """Retry a funded wallet only after cooldown and a newer successful observation."""
+    blocked = raw.get("credit_blocked_at")
+    if not blocked:
+        return raw.get("limited_reason") != "credits"
+    try:
+        blocked_time, _ = timestamp(blocked)
+        fetched, _ = timestamp(credits.get("fetched_at"))
+    except (ValueError, TypeError):
+        return False
+    old = balance_value(raw.get("credit_blocked_balance"))
+    current = credits.get("balance")
+    increased = old is not None and current is not None and Decimal(current) > Decimal(old)
+    cooled = (now - blocked_time).total_seconds() >= 600
+    return bool(fetched > blocked_time and credits["available"] and (increased or cooled))

package/lib/selector_funding.py

@@ -0,0 +1,111 @@
+"""Opted-in funding tiers preserve the legacy session gate and weekly band."""
+
+from __future__ import annotations
+
+from decimal import Decimal, localcontext
+
+from selector_credits import CAPABILITY, normalize_credits, refusal_recovered
+from selector_credit_scope import actor_email, actor_key, actor_refusals, merge_wallet, wallet_available
+from selector_primitives import timestamp
+
+
+def wallet_snapshots(candidates: list[dict], now, max_age: int) -> dict:
+    wallets = {}
+    for raw in candidates:
+        credits = normalize_credits(raw.get("credits"), now, max_age)
+        key = credits["account_id"]
+        error = (raw.get("credits") or {}).get("last_error")
+        if not key or error in {"account_mismatch", "unauthenticated", "http_401", "http_403"}:
+            continue
+        credits["available"] = wallet_available(credits)
+        observed = credits["fetched_at"] or ""
+        if error:
+            try:
+                _, failed_at = timestamp(raw["credits"].get("last_error_at"))
+                observed = max(observed, failed_at)
+            except ValueError:
+                pass
+        credits["wallet_observed_at"] = observed
+        previous = wallets.get(key)
+        rank = (observed, not credits["available"])
+        if previous is None or rank > (previous["wallet_observed_at"], not previous["available"]):
+            wallets[key] = credits
+    return wallets
+
+
+def apply_funding(rows: list[dict], candidates: list[dict], now, request: dict) -> None:
+    max_age = request.get("credit_max_age_seconds", 900)
+    wallets = wallet_snapshots(candidates, now, max_age)
+    refusals = actor_refusals(candidates)
+    holders = {}
+    for raw in candidates:
+        account = (raw.get("credits") or {}).get("account_id")
+        holders[account] = max(holders.get(account, 0), raw.get("credit_active_holders", 0))
+    for row, raw in zip(rows, candidates):
+        credits = normalize_credits(raw.get("credits"), now, max_age)
+        credits = merge_wallet(credits, wallets.get(credits["account_id"]))
+        receipt = dict(raw, **refusals.get(actor_key(raw), {}))
+        known = row["quota_known"]
+        measured = [Decimal(row[key]) for key in ("weekly_pct", "session_pct") if row[key] is not None]
+        peak = max(measured) if measured else None
+        exhausted = peak is not None and peak >= 100
+        exhausted |= row["engine"] == "codex" and credits["ordinary_usage_allowed"] is False
+        reserve = peak is not None and 90 <= peak < 100
+        tier = "credits" if exhausted else "reserve" if reserve else "included"
+        recovered = refusal_recovered(receipt, credits, now)
+        reason = raw.get("limited_reason")
+        usage_park = reason == "usage" or (reason == "credits" and recovered)
+        park = row["exclusion_code"] in {"status_not_active", "account_limited"}
+        safe = row["status"] in {"active", "limited"} and (not park or usage_park)
+        paid = (row["engine"] == "codex" and raw.get("credit_capable") is True
+                and credits["available"] and recovered and safe)
+        # Retry normalization with just usage parks removed; independent auth, stale
+        # heartbeat, incapable provider and active reservations retain their exclusions.
+        if park and safe and ((tier == "credits" and paid) or (tier == "reserve" and known)):
+            from selector_policy import normalize_candidate
+            unparked = dict(raw, status="active", limited_until=None)
+            refreshed = normalize_candidate(unparked, now, row["input_ordinal"])
+            row["eligible"], row["exclusion_code"] = refreshed["eligible"], refreshed["exclusion_code"]
+        if row["eligible"] and tier == "credits" and not paid:
+            row["eligible"], row["exclusion_code"] = False, "credits_unavailable"
+        required = request.get("required_funding_tier")
+        if row["eligible"] and required and required != tier:
+            row["eligible"], row["exclusion_code"] = False, "funding_tier_excluded"
+        row.update(funding_tier=tier, credits=credits, credit_capable=raw.get("credit_capable") is True,
+                   credit_active_holders=holders.get(credits["account_id"], 0),
+                   credit_blocked_at=receipt.get("credit_blocked_at"),
+                   credit_blocked_balance=receipt.get("credit_blocked_balance"), limited_reason=reason)
+        if "credit_actor_email" in raw:
+            row["credit_actor_email"] = actor_email(raw)
+
+
+def best_funding_tier(rows: list[dict]) -> list[dict]:
+    order = {"included": 0, "reserve": 1, "credits": 2}
+    best = min(order[row["funding_tier"]] for row in rows)
+    return [row for row in rows if order[row["funding_tier"]] == best]
+
+
+def credit_rank(row: dict) -> tuple:
+    credits, holders = row["credits"], row["credit_active_holders"]
+    with localcontext() as context:
+        context.prec = 110
+        share = Decimal(credits["balance"] or "0") / (holders + 1)
+    return (not credits["unlimited"], holders if credits["unlimited"] else -share)
+
+
+def funding_proof(request: dict, winner: dict) -> dict:
+    return {"credit_capability": CAPABILITY, "credit_fallback": True,
+            "required_funding_tier": request.get("required_funding_tier"),
+            "credit_max_age_seconds": request.get("credit_max_age_seconds", 900),
+            "funding_tier": winner["funding_tier"]}
+
+
+def funding_score(winner: dict) -> dict:
+    score = {"funding_tier": winner["funding_tier"],
+            "credit_balance": winner["credits"]["balance"],
+            "credit_account_id": winner["credits"]["account_id"],
+            "credit_active_holders": winner["credit_active_holders"],
+            "credit_unlimited": winner["credits"]["unlimited"]}
+    if "credit_actor_email" in winner:
+        score["credit_actor_email"] = winner["credit_actor_email"]
+    return score