claude-multiacc 2.0.50 → 2.0.52

package/bin/codex

@@ -468,7 +468,7 @@ limited_hard_blocked() { # $1 acct dir
   local m="$1/.limited" line="" p
   if [ -f "$m" ]; then
     line="$(sed -n 2p "$m" 2>/dev/null)"
-    case "$line" in *reason=client-rate-limit*|*reason=error-cooldown*) return 0 ;; esac
+    case "$line" in *reason=client-rate-limit*|*reason=error-cooldown*|*reason=credit-refused*) return 0 ;; esac
     p="$(limited_percent_of "$1")"
     if [ "$p" -ge 0 ] 2>/dev/null; then
       [ "$p" -ge 100 ]
@@ -841,7 +841,7 @@ ar_set_hist() { # $1 comma list class:epoch -> AR_HIST: well-formed entries, new
 # rollout line must not pin an account out for days — a peer may have redeemed its reset
 # in the meantime. The scheduled 5-minute limits pass marks the real window properly.
 ar_mark_cooldown() { # $1 acct dir
-  local m="$1/.limited" cur="" until=$((now + 600))
+  local m="$1/.limited" cur="" until=$((now + 600)) reason="${2:-error-cooldown}"
   if [ -f "$m" ]; then
     IFS= read -r cur < "$m" 2>/dev/null || cur=""
     num_ok "$cur" || cur=0
@@ -849,7 +849,7 @@ ar_mark_cooldown() { # $1 acct dir
   fi
   {
     echo "$until"
-    echo "bucket=error-cooldown percent=? marked_at=$(date -u +%Y-%m-%dT%H:%M:%SZ) reason=error-cooldown"
+    echo "bucket=$reason percent=? marked_at=$(date -u +%Y-%m-%dT%H:%M:%SZ) reason=$reason"
   } 2>/dev/null > "$1/.limited.$$" \
     && mv -f "$1/.limited.$$" "$m" 2>/dev/null \
     || rm -f "$1/.limited.$$" 2>/dev/null || true
@@ -896,6 +896,7 @@ ar_token_dead() { # $1 session id (the token's, else the file's) or empty
 ar_relaunch() { # $1 token
   local tok="$1" base f line k v n=0 a age
   local ver="" prov="" cls="" acct="" sid="" cwd="" depth="" avoid="" hist="" chain=""
+  local funding="" funding_pid=""
   ar_word_ok "$tok" 8 || return 1
   base="$AR_DIR/r-$tok"
   f="$base.relaunch"
@@ -919,6 +920,8 @@ ar_relaunch() { # $1 token
       avoid) avoid="$v" ;;
       hist) hist="$v" ;;
       chain) ar_word_ok "$v" 1 && chain="$v" ;;
+      funding_tier) [ "$v" = credits ] && funding=credits ;;
+      funding_pid) num_ok "$v" && funding_pid="$v" ;;
     esac
   done < "$f"
   age=$((now - $(file_mtime "$f")))
@@ -939,7 +942,16 @@ ar_relaunch() { # $1 token
   fi
   if [ -n "$acct" ] && [ -d "$ACC_ROOT/$acct" ]; then
     case "$cls" in
-      quota) ar_mark_cooldown "$ACC_ROOT/$acct" ;;
+      quota)
+        if [ "$funding" = credits ] && [ -n "$funding_pid" ]; then
+          "$MCP_PYBIN" "$SELF_DIR/../lib/codex_credit_selection.py" \
+            refuse "$ACC_ROOT/$acct" "$funding_pid" 2>/dev/null || true
+        fi
+        if [ "$funding" = credits ]; then
+          ar_mark_cooldown "$ACC_ROOT/$acct" credit-refused
+        else
+          ar_mark_cooldown "$ACC_ROOT/$acct"
+        fi ;;
       auth) ar_mark_auth "$ACC_ROOT/$acct" ;;
     esac
   fi
@@ -1073,6 +1085,7 @@ ar_spawn_watcher() { # $1 provider, $2 picked acct dir, then the argv codex is a
     printf 'acct=%s\nacct_dir=%s\ncwd=%s\nlaunched=%s\n' "${pick##*/}" "$pick" "$PWD" "$(date +%s)"
     printf 'tmux=%s\npane=%s\nself=%s\nacc_root=%s\n' "$TMUX" "$TMUX_PANE" "$SELF" "$root"
     printf 'depth=%s\navoid=%s\nhist=%s\nchain=%s\n' "$AR_DEPTH" "$AR_AVOID" "$AR_HIST" "$AR_CHAIN"
+    printf 'funding_tier=%s\n' "$AR_TIER"
   } 2>/dev/null > "$st.tmp" && mv -f "$st.tmp" "$st" 2>/dev/null || {
     rm -f "$st.tmp" "$AR_DIR/$$.argv" 2>/dev/null
     return 1
@@ -1320,6 +1333,12 @@ else
   for d in "${valid[@]}"; do
     if ar_avoided "$d" || limited_hard_blocked "$d"; then hard+=("$d"); else soft+=("$d"); fi
   done
+  paid=()
+  if [ "${#hard[@]}" -gt 0 ]; then
+    for d in "${hard[@]}"; do
+      ar_avoided "$d" || paid+=("$d")
+    done
+  fi
   # A probe only ASKS: the fallback lines below would claim a pick nobody launched.
   if [ "${#soft[@]}" -gt 0 ]; then
     AR_TIER=soft
@@ -1328,6 +1347,15 @@ else
     PICK_STRICT=0
     [ "$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 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
+    AR_TIER=credits
+    PICK_DIR="$credit_pick"
+    PICK_BAND_COUNT=0
+    PICK_GATE_COUNT=0
   else
     AR_TIER=hard
     # Every account is exhausted RIGHT NOW: nothing serves, so hand out the one that
@@ -1384,6 +1412,9 @@ fi
 # CODEX_ACCOUNT pin deliberately does not: a pin is a caller overriding selection,
 # not a turn in the rotation.
 remember_pick "$pick"
+if [ "$AR_TIER" = "credits" ]; then
+  "$MCP_PYBIN" "$SELF_DIR/../lib/codex_credit_selection.py" record "$pick" "$$" 2>/dev/null || true
+fi
 # The picked account carries every registered MCP server before the client starts.
 mcp_ensure "$pick"
 
@@ -1408,9 +1439,12 @@ if [ "$stale" = 1 ] && [ -x "$SELF_DIR/codex-accounts" ]; then
 fi
 
 acct="$(basename "$pick")"
+credit_funding_log=""
+[ "$AR_TIER" = "credits" ] && credit_funding_log=" funding=credits"
 sel_log "$acct weekly=$(fresh_field "$pick" weekly_percent || echo '?')%" \
   "session=$(fresh_field "$pick" session_percent || echo '?')%" \
-  "band=${HEADROOM_BAND} band-count=${PICK_BAND_COUNT} session-gate=${SESSION_GATE_LOG} session-ok=${PICK_GATE_COUNT} pwd=$PWD"
+  "band=${HEADROOM_BAND} band-count=${PICK_BAND_COUNT} session-gate=${SESSION_GATE_LOG}" \
+  "session-ok=${PICK_GATE_COUNT} pwd=$PWD${credit_funding_log}"
 
 export CODEX_SHIM_ACTIVE=1
 
@@ -1427,7 +1461,8 @@ fi
 # A service-spawned pipe that never EOFs must take the plain exec path, or the
 # stdin pre-buffering below would hang the call.
 wants_retry=0
-if [ "${CODEX_SHIM_RETRY:-1}" != "0" ] && [ "${#eligible[@]}" -ge 2 ]; then
+if [ "${CODEX_SHIM_RETRY:-1}" != "0" ] \
+  && { [ "${#eligible[@]}" -ge 2 ] || [ "$AR_TIER" = "credits" ]; }; then
   for a in "$@"; do
     case "$a" in exec|e) wants_retry=1; break ;; esac
   done
@@ -1493,8 +1528,10 @@ fi
 # the pool on its own — the shim's guess must never outlive the evidence for it.
 PARK_AUTH='not (logged|signed) in|authentication (required|failed)|please run `?codex login|run `?codex login`? to|401 unauthorized|token .{0,12}(expired|revoked)|refresh token.{0,20}(expired|invalid|revoked)|invalid_grant|could not refresh'
 PARK_ORG='disabled by (your )?(workspace )?admin|admin (has )?disabled|(workspace|organization) has disabled (codex|chatgpt)|codex.{0,20}disabled for (your|this) (workspace|organization)'
+CREDIT_LIMITPAT='usage_limit_exceeded|usage limit|weekly limit|quota exceeded|insufficient.{0,20}credits'
+CREDIT_LIMITPAT+='|out of credits|credits.{0,20}exhausted|spend.control'
 LIMITPAT='rate[ _-]?limit|usage limit|limit (reached|exceeded)|too many requests|"?429"?|quota exceeded|hit your usage limit'
-ERRPAT="$LIMITPAT|$PARK_AUTH|$PARK_ORG"'|401|403|unauthorized|authentication[_ ]error|invalid[_ ](bearer|token|api key)|token (expired|revoked|invalid)|oauth.*(error|expired|invalid)'
+ERRPAT="$LIMITPAT|$CREDIT_LIMITPAT|$PARK_AUTH|$PARK_ORG"'|401|403|unauthorized|authentication[_ ]error|invalid[_ ](bearer|token|api key)|token (expired|revoked|invalid)|oauth.*(error|expired|invalid)'
 PARK_SOFT_AUTH=3600      # 1h: a mis-parked healthy account is back within the hour
 PARK_SOFT_ORG=21600      # 6h: a workspace policy will not change in minutes
 
@@ -1514,8 +1551,14 @@ while :; do
     # auth word must get the self-expiring cooldown, never a park.
     park_reason=""
     park_soft=0
-    if grep -qiE "$LIMITPAT" "$tmpd/out" "$tmpd/err" 2>/dev/null; then
-      :
+    cooldown_reason=error-cooldown
+    if grep -qiE "$LIMITPAT|$CREDIT_LIMITPAT" "$tmpd/out" "$tmpd/err" 2>/dev/null; then
+      if [ "$AR_TIER" = "credits" ] \
+        && grep -qiE "$CREDIT_LIMITPAT" "$tmpd/out" "$tmpd/err" 2>/dev/null \
+        && ! grep -qiE 'not your usage limit|temporarily limiting|overloaded' "$tmpd/out" "$tmpd/err"; then
+        "$MCP_PYBIN" "$SELF_DIR/../lib/codex_credit_selection.py" refuse "$cur" "$$" 2>/dev/null || true
+        cooldown_reason=credit-refused
+      fi
     elif grep -qiE "$PARK_ORG" "$tmpd/out" "$tmpd/err" 2>/dev/null; then
       park_reason="org-blocked"
       park_detail="a workspace admin has disabled Codex access for the account"
@@ -1536,14 +1579,15 @@ while :; do
     else
       {
         echo $((now + 600))
-        echo "bucket=error-cooldown percent=? marked_at=$(date -u +%Y-%m-%dT%H:%M:%SZ) reason=error-cooldown"
+        echo "bucket=$cooldown_reason percent=? marked_at=$(date -u +%Y-%m-%dT%H:%M:%SZ) reason=$cooldown_reason"
       } 2>/dev/null > "$cur/.limited.$$" \
         && mv -f "$cur/.limited.$$" "$cur/.limited" 2>/dev/null \
         || rm -f "$cur/.limited.$$" 2>/dev/null || true
     fi
     next=""
     n="${#eligible[@]}"
-    start=$((RANDOM % n))
+    start=0
+    [ "$n" -gt 0 ] && start=$((RANDOM % n))
     i=0
     while [ "$i" -lt "$n" ]; do
       c="${eligible[$(((start + i) % n))]}"

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.
@@ -1120,7 +1117,8 @@ root, threshold, quiet, url, force, lib_dir = (sys.argv[1], int(sys.argv[2]),
     sys.argv[3] == '1', sys.argv[4], sys.argv[5] == '1', sys.argv[6])
 sys.path.insert(0, lib_dir)
 from codex_reset_telemetry import refresh_reset_credits
-now = time.time()
+from codex_credits import collect_credits, failed_credits, record_read_failure
+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'))
 
@@ -1395,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):
@@ -1417,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
@@ -1447,6 +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', time.time())
         continue
     if not account_id:
         account_id = str((jwt_claims(bearer).get('https://api.openai.com/auth') or {})
@@ -1462,29 +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
-            tmp = lpath + '.tmp'
-            with open(tmp, 'w') as f:
-                json.dump(prev, f, indent=1)
-            os.replace(tmp, lpath)
-            say(f'{aid}: rate limited (429); backing off {wait}s; failing open')
-        else:
-            say(f'{aid}: usage fetch failed (HTTP {e.code}); failing open')
-        continue
+        data = fetch_usage(req)
+        now = time.time()
     except Exception as e:
-        say(f'{aid}: usage fetch failed ({e}); failing open')
+        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):
@@ -1594,6 +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', time.time())
         continue
     # Successful fetch: fresh buckets replace everything, backoff state is dropped.
     # THREE selection signals, same reset asymmetry as the claude pool:
@@ -1662,6 +1651,9 @@ for acct in manifest.get('accounts', []):
         b.pop('_reset_known', None)
     out = {'fetched_at': int(now), 'source': 'chatgpt'}
     out.update(reset_view)
+    credits = collect_credits(data, account_id, now, prev.get('credits'))
+    if credits is not None:
+        out['credits'] = credits
     if live:
         out['max_percent'] = maxp
     if weeklyp is not None:
@@ -1694,6 +1686,8 @@ for acct in manifest.get('accounts', []):
         # refreshed account; the next scheduled pass replaces it with server truth.
         out['fetched_at'] = 0
         out['auto_reset'] = reset_result
+        if credits is not None:
+            out['credits'] = failed_credits(credits, 'usage_reset_pending', now)
     tmp = lpath + '.tmp'
     with open(tmp, 'w') as f:
         json.dump(out, f, indent=1)
@@ -1841,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/bin/multiacc-select

@@ -11,6 +11,7 @@ from pathlib import Path
 ROOT = Path(__file__).resolve().parents[1]
 sys.path.insert(0, str(ROOT / "lib"))
 
+from selector_credits import CAPABILITY  # noqa: E402
 from selector_policy import select  # noqa: E402
 from selector_primitives import SCHEMA, SELECTOR_VERSION  # noqa: E402
 
@@ -32,7 +33,11 @@ def _strict_object(pairs: list[tuple[str, object]]) -> dict:
 def main() -> int:
     if sys.argv[1:] in (["--help"], ["-h"]):
         print("usage: multiacc-select --request-json - --response-json -\n"
-              "       multiacc-select --version")
+              "       multiacc-select --version|--capabilities")
+        return 0
+    if sys.argv[1:] == ["--capabilities"]:
+        print(json.dumps({"schema": SCHEMA, "selector_version": SELECTOR_VERSION,
+                          "capabilities": [CAPABILITY]}, separators=(",", ":")))
         return 0
     if sys.argv[1:] == ["--version"]:
         print(SELECTOR_VERSION)

package/docs/CODEX.md

@@ -79,6 +79,124 @@ Codex-specific notes:
 - **API-key logins are rejected** — ChatGPT subscription accounts only, matching the
   addon's no-API-keys rule.
 
+## Spendable Codex credits
+
+The existing authenticated usage GET also supplies the account's spendable Codex
+credit wallet. `codex-accounts list/status/limits --json` exposes it as `usage.credits`:
+
+```json
+{
+  "has_credits": true,
+  "unlimited": false,
+  "balance": "61812.452075",
+  "fetched_at": "2026-10-04T12:00:00Z",
+  "account_id": "provider-account-id",
+  "ordinary_usage_allowed": false,
+  "spend_control_reached": false,
+  "limit_reached_type": "rate_limit_reached",
+  "age_seconds": 0,
+  "stale": false
+}
+```
+
+`balance` is a decimal string in provider credit units, never dollars or a percentage.
+A measured `"0"`, unknown `null`, and `unlimited: true` remain distinct. Missing `credits`
+means no usable observation exists. `account_id` binds the read to the authenticated
+provider account; a conflicting response identity invalidates the observation.
+The two admission booleans and limit type preserve explicit provider facts; missing
+values are `null`, never inferred from usage percentages or reset dates.
+
+Wallet freshness uses its own `fetched_at`, independently of the usage windows and
+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. 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. 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 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
+work is possible; `has_credits: true` alone is insufficient.
+The shim's wallet-and-member-bound paid-refusal receipt is reported separately as
+`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, 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
+
+The standalone shim keeps its session gate and weekly band for included quota, then tries
+its existing 90–99% reserve before spendable credits. It uses the existing ChatGPT login;
+no API-key switch, re-login or billing toggle is needed. `CODEX_MULTIACC_CREDITS=0` disables
+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) 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 |
+| --- | --- |
+| `credits` | The sanitized wallet observation shown above. |
+| `credit_capable` | Caller-confirmed runner support; must be true for paid admission. |
+| `credit_active_holders` | Active holders of this shared wallet, not just the local slot. |
+| `credit_actor_email` | Normalized member email, or null when unknown. |
+| `credit_blocked_at`, `credit_blocked_balance` | The latest actual paid-refusal receipt. |
+| `limited_reason` | `usage` for included quota, `credits` for a paid refusal; other parks remain blocked. |
+
+Successful opted-in responses include `credit_capability`, `funding_tier` (`included`,
+`reserve`, or `credits`) and corresponding score fields. Credit scores carry the decimal
+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.
+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
+opt-in are rejected. Callers must check the capability before issuing paid requests; an old
+runner must never silently execute a decision it cannot enforce.
+
 ```bash
 codex-accounts add                    # sign in a new ChatGPT account (device code —
                                       # open the URL in any browser, enter the code)

package/lib/autoresume.py

@@ -125,9 +125,9 @@ MONTHS = {m: i for i, m in enumerate(
     ("jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"), 1)}
 
 STATE_KEYS = ("v", "provider", "pid", "ppid", "acct", "acct_dir", "cwd", "launched", "tmux",
-              "pane", "self", "acc_root", "depth", "avoid", "hist", "chain")
+              "pane", "self", "acc_root", "depth", "avoid", "hist", "chain", "funding_tier")
 RELAUNCH_KEYS = ("v", "provider", "class", "acct", "reset", "rtype", "marked", "sid", "cwd",
-                 "depth", "avoid", "hist", "chain")
+                 "depth", "avoid", "hist", "chain", "funding_tier", "funding_pid")
 HIST_KEEP = 32
 
 # ---- knobs --------------------------------------------------------------------------
@@ -806,6 +806,8 @@ def format_relaunch(fields):
     value carrying a line break (or NUL) cannot be written faithfully: ValueError."""
     lines = []
     for key in RELAUNCH_KEYS:
+        if key in ("funding_tier", "funding_pid") and key not in fields:
+            continue
         val = "" if fields.get(key) is None else str(fields[key])
         if any(c in val for c in "\0\n\r"):
             raise ValueError("unwritable value for " + key)
@@ -939,6 +941,7 @@ def load_state(path):
         "tmux": kv["tmux"], "pane": kv["pane"], "self": kv["self"],
         "acc_root": acc_root, "depth": int(depth),
         "avoid": kv.get("avoid", ""), "hist": kv.get("hist", ""), "chain": chain,
+        "funding_tier": "credits" if kv.get("funding_tier") == "credits" else "included",
     }
 
 
@@ -1956,6 +1959,8 @@ class Watcher:
         fields = relaunch_fields(self.provider, verdict, self.acct, self.sid, cwd,
                                  self.st["depth"], avoid,
                                  hist_append(self.st["hist"], cls, now), self.chain)
+        if self.provider == "codex" and self.st.get("funding_tier") == "credits":
+            fields.update(funding_tier="credits", funding_pid=str(self.pid))
         try:
             keys = send_keys_argvs(sock, self.st["pane"], self.provider, token, self.sid,
                                    self.st["self"], self.root)

package/lib/autoresume_probe.py

@@ -31,7 +31,7 @@ def parse_probe(out):
             pick, tier = match.group(1), match.group(2)
     if pick and not ACCT_RE.match(pick):
         return "", ""
-    if tier not in ("eligible", "soft", "hard", "none"):
+    if tier not in ("eligible", "soft", "credits", "hard", "none"):
         return "", ""
     return pick, tier
 
@@ -44,7 +44,7 @@ def probe_allows(cls, pick, tier, current):
     below-threshold requirement; transient/crash may retry anywhere still usable.
     """
     if cls == "quota":
-        return tier in ("eligible", "soft") and bool(pick) and pick != current
+        return tier in ("eligible", "soft", "credits") and bool(pick) and pick != current
     if cls in ROTATE:
         return tier == "eligible" and bool(pick) and pick != current
-    return tier in ("eligible", "soft") and bool(pick)
+    return tier in ("eligible", "soft", "credits") and bool(pick)

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)}