claude-multiacc 2.0.64 → 2.0.66

package/bin/claude-accounts

@@ -1708,7 +1708,7 @@ token_identity_receipt() { # Unknown results must never overwrite a peer's prove
 limits_distribute_now() {
   local lock="$ACC_ROOT/tmp/limits-push.lock"
   mkdir -p "$ACC_ROOT/tmp" 2>/dev/null || return 0
-  if ! mkdir "$lock" 2>/dev/null; then
+  if ! atomic_mkdir "$lock" 2>/dev/null; then
     # A DETACHED push that is killed (logout, reboot, pkill) never runs its EXIT trap,
     # and mkdir can never take a lock dir nobody will remove: one stranded lock
     # silently stopped ALL telemetry distribution on the live pool from 2026-09-03
@@ -1721,7 +1721,7 @@ limits_distribute_now() {
     # exactly as before.
     [ $(( $(epoch_now) - $(file_mtime "$lock") )) -gt 600 ] || return 0
     rm -rf "$lock" 2>/dev/null
-    mkdir "$lock" 2>/dev/null || return 0
+    atomic_mkdir "$lock" 2>/dev/null || return 0
     log_to sync.log "stale limits-push lock broken (older than 600s); distributing"
   fi
   trap 'rmdir "$lock" 2>/dev/null || true' EXIT
@@ -1792,7 +1792,7 @@ cmd_limits() {
   done
   local lock="$ACC_ROOT/.locks/limits"
   mkdir -p "$ACC_ROOT/.locks"
-  if ! mkdir "$lock" 2>/dev/null; then
+  if ! atomic_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) —
@@ -1802,7 +1802,7 @@ cmd_limits() {
       return 0
     fi
     rm -rf "$lock"
-    if ! mkdir "$lock" 2>/dev/null; then
+    if ! atomic_mkdir "$lock" 2>/dev/null; then
       if [ "$json" = "1" ]; then emit_report_json limits; return $?; fi
       return 0
     fi
@@ -1846,12 +1846,6 @@ TOKEN_URL = os.environ.get('CLAUDE_MULTIACC_TOKEN_URL',
                            'https://console.anthropic.com/v1/oauth/token')
 CLIENT_ID = os.environ.get('CLAUDE_MULTIACC_CLIENT_ID',
                            '9d1c250a-e61b-44d9-88ed-5944d1962f5e')
-# Only refresh a token that has been expired for a while: a LIVE session refreshes
-# its own credential within moments of expiry, so a long-expired one proves no
-# other writer is active (refresh tokens rotate; two racing refreshers strand one).
-REFRESH_MIN_EXPIRED = 300
-REFRESH_FAIL_BACKOFF = 600     # transient (network/5xx/429): retry in 10 min
-REFRESH_DENIED_BACKOFF = 21600  # 4xx = grant likely revoked: 6h; re-login needed anyway
 # A usage fetch the server says will never succeed (x-should-retry: false — e.g. the
 # 403 "does not meet scope requirement user:profile" that a setup token ALWAYS gets)
 # is not a hiccup to retry every pass. Retrying it is what manufactured the 429s that
@@ -2008,39 +2002,12 @@ def park_dead_grant(aid, d, slug, detail):
     say(f'{aid}: {detail} — re-login needed (claude-accounts relogin {aid})')
 
 
-# The client's own write lock: proper-lockfile's DIRECTORY <dir>/.storage-write.lock, stale
-# after 15 s (lib/mcp_oauth.py ClientLock). Claude Code takes it around every write of its
-# credential document, file or Keychain item alike — re-read, one change, the whole
-# document back — and its write FAILS after about 7.5 s of retries on a held lock. So the
-# refresher never holds it across the token POST: a lock held when a refresh would start
-# skips that refresh (nothing has rotated yet; the next pass retries), and the
-# check-and-set and the write take it after the POST, waiting longer, because a rotated
-# grant must land: past the wait (or with no helper) it is written as before, without it.
-try:
-    from mcp_oauth import CLIENT_LOCK, CLIENT_LOCK_STALE_S, ClientLock  # noqa: E402
-except Exception:  # noqa: BLE001 — fail open: refresh exactly as before, unlocked
-    ClientLock = None
-CLIENT_LOCK_PROBE_S = 1.0   # a client's write takes milliseconds: held this long, it is busy
+# Legacy Keychain migration needs only the client's short storage-write lock.
+# Refresh request locking and credential CAS live in claude_oauth_refresh.py.
+from mcp_oauth import ClientLock  # noqa: E402
 CLIENT_LOCK_WAIT_S = 10.0
 
 
-def client_lock_busy(d):
-    """A live writer holds <d>'s client lock, and still does CLIENT_LOCK_PROBE_S later."""
-    if ClientLock is None:
-        return False
-    path = os.path.join(d, CLIENT_LOCK)
-    deadline = time.monotonic() + CLIENT_LOCK_PROBE_S
-    while True:
-        try:
-            if time.time() - os.stat(path).st_mtime > CLIENT_LOCK_STALE_S:
-                return False             # its holder is gone; the write takes it over
-        except OSError:
-            return False                 # no lock: nobody is writing
-        if time.monotonic() >= deadline:
-            return True
-        time.sleep(0.05)
-
-
 class FileStore:
     """The OAuth credential as `.credentials.json`: atomic 0600 writes. The client keeps
     its MCP servers' OAuth state (mcpOAuth, mcpOAuthClientConfig) in this same file, so
@@ -2141,166 +2108,13 @@ def oauth_store(d):
 
 
 def refresh_oauth(aid, d, store):
-    """Refresh a long-expired OAuth access token via the refresh-token grant and
-    persist the ROTATED credential atomically (0600 file, or the Keychain item it
-    came from). Returns the new bearer, or None (fail open: the stored credential
-    is never touched on failure). Failures back off via <dir>/.oauth-refresh.json —
-    a side file, NOT limits.json, because telemetry state must only ever reflect
-    real usage fetches."""
-    spath = os.path.join(d, '.oauth-refresh.json')
-    try:
-        doc = store.read()
-        o = doc.get('claudeAiOauth') if isinstance(doc, dict) else None
-        # Present-but-null/non-object claudeAiOauth (interrupted or reset credential
-        # write) must degrade THIS account only, like every other malformed input; and a
-        # document with no login in it at all (MCP state alone) has nothing to refresh.
-        if not isinstance(o, dict):
-            return None
-    except Exception:
-        return None
-    # NB: no "must have an accessToken" gate. A credential whose access token was
-    # cleared but whose REFRESH token is alive is exactly the shape a grant is supposed
-    # to recover from; requiring the dead half to be present meant such an account could
-    # never come back, and (with a setup token beside it) went dark for telemetry
-    # forever. The expiresAt gate below is what protects a live session's credential.
-    if not o.get('refreshToken'):
-        park_dead_grant(aid, d, 'no-refresh-token',
-                        'credential has no refresh token and its access token expired')
-        return None
-    if o.get('expiresAt', 0) / 1000.0 > now - REFRESH_MIN_EXPIRED:
-        return None  # not expired long enough to prove no live session owns it
-    if o.get('refreshTokenExpiresAt', 0) / 1000.0 <= now:
-        # Nothing can revive this account: park it so the shim stops selecting it
-        # (every run under it would fail with "OAuth session expired").
-        park_dead_grant(aid, d, 'refresh-token-expired',
-                        'the refresh token itself expired; only a re-login can fix it')
-        return None
-    if not force:
-        try:
-            if json.load(open(spath)).get('retry_after', 0) > now:
-                return None  # earlier refresh failure still backing off
-        except Exception:
-            pass
-
-    def back_off(wait, why, denials=0):
-        try:
-            with open(spath + '.tmp', 'w') as f:
-                json.dump({'retry_after': int(now + wait), 'error': why,
-                           'denials': denials,
-                           'at': time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime())}, f)
-            os.replace(spath + '.tmp', spath)
-        except Exception:
-            pass
-        say(f'{aid}: oauth refresh failed ({why}); backing off {wait}s; limits left as-is')
+    # Import failures skip this account through the caller's guard; never rotate
+    # without the native request lock. The helper owns the full refresh transaction.
+    from claude_oauth_refresh import OAuthRefresher
+    return OAuthRefresher(now=now, force=force, token_url=TOKEN_URL, client_id=CLIENT_ID,
+                          say=say, park_dead_grant=park_dead_grant,
+                          clear_expired=clear_expired).refresh(aid, d, store)
 
-    if client_lock_busy(d):
-        # The client is writing this credential right now (it may be its own refresh of
-        # the same grant): no request is sent, so nothing rotates, and no backoff is noted.
-        say(f'{aid}: oauth refresh skipped — the client holds its credential lock '
-            f'({CLIENT_LOCK}); the next pass retries')
-        return None
-    started_with = o['refreshToken']
-    body = json.dumps({'grant_type': 'refresh_token',
-                       'refresh_token': o['refreshToken'],
-                       'client_id': CLIENT_ID}).encode()
-    req = urllib.request.Request(TOKEN_URL, data=body, headers={
-        'Content-Type': 'application/json',
-        'User-Agent': 'claude-multiacc/1.0',
-    })
-    try:
-        data = json.loads(urllib.request.urlopen(req, timeout=30).read().decode())
-    except urllib.error.HTTPError as e:
-        if e.code in (400, 401, 403):
-            # A 4xx from the TOKEN endpoint is only proof of a dead grant when the
-            # server says so (OAuth's invalid_grant). Everything else 4xx — a bad
-            # client_id, an endpoint change, a WAF page, a provider incident — would
-            # hit EVERY account at once, so it must never park the whole pool on the
-            # first try: back off, and only park after this account has been refused
-            # repeatedly.
-            body = ''
-            try:
-                body = e.read().decode('utf-8', 'replace')[:400]
-            except Exception:
-                pass
-            denials = 1
-            try:
-                denials = int(json.load(open(spath)).get('denials', 0)) + 1
-            except Exception:
-                pass
-            if 'invalid_grant' in body:
-                park_dead_grant(aid, d, f'refresh-denied-http-{e.code}',
-                                'the refresh grant was refused as invalid_grant (revoked or rotated away)')
-            elif denials >= 3:
-                park_dead_grant(aid, d, f'refresh-denied-http-{e.code}',
-                                f'the refresh grant was refused {denials} times in a row')
-            back_off(REFRESH_DENIED_BACKOFF,
-                     f'HTTP {e.code} — refresh token may be revoked; re-login needed',
-                     denials=denials)
-        else:
-            back_off(REFRESH_FAIL_BACKOFF, f'HTTP {e.code}')
-        return None
-    except Exception as e:
-        back_off(REFRESH_FAIL_BACKOFF, str(e)[:200])
-        return None
-    tok = data.get('access_token') if isinstance(data, dict) else None
-    if not tok:
-        back_off(REFRESH_DENIED_BACKOFF, 'no access_token in response')
-        return None
-    o['accessToken'] = tok
-    # The grant ROTATES the refresh token: persist it (and both expiries) or the
-    # account is stranded — hence atomic write, and a loud message if it fails.
-    if data.get('refresh_token'):
-        o['refreshToken'] = data['refresh_token']
-    if data.get('expires_in'):
-        o['expiresAt'] = int((now + float(data['expires_in'])) * 1000)
-    else:
-        # No expires_in in the response: assume a conservative 1h. Leaving the old
-        # (past) expiresAt would make every later pass re-run the grant in a loop.
-        o['expiresAt'] = int((now + 3600) * 1000)
-    if data.get('refresh_token_expires_in'):
-        o['refreshTokenExpiresAt'] = int((now + float(data['refresh_token_expires_in'])) * 1000)
-    # CHECK-AND-SET. The grant rotates, and a live claude session refreshes the same
-    # file. REFRESH_MIN_EXPIRED makes that unlikely, not impossible — and losing the
-    # race by overwriting means the session's newer credential is destroyed. If the
-    # on-disk refresh token is no longer the one this grant was issued against, the
-    # other writer won: keep its result, discard ours. Both under the client's own lock,
-    # so no client write lands between the check and the write.
-    lock = ClientLock(d, CLIENT_LOCK_WAIT_S) if ClientLock is not None else None
-    try:
-        held = lock is not None and lock.acquire()
-    except Exception:  # noqa: BLE001 — the rotated grant lands either way
-        held = False
-    if lock is not None and not held and os.path.isdir(lock.path):
-        say(f'{aid}: the client kept its credential lock ({CLIENT_LOCK}) past '
-            f'{int(CLIENT_LOCK_WAIT_S)}s — writing the rotated login without it')
-    try:
-        try:
-            disk = store.read().get('claudeAiOauth', {})
-            if isinstance(disk, dict) and disk.get('refreshToken') != started_with:
-                say(f'{aid}: credential was refreshed by something else mid-flight — '
-                    f'keeping the newer one in the {store.kind}')
-                return None
-        except Exception:
-            pass
-        try:
-            # Only the login is ours: both stores write it INTO the document as it is now,
-            # so the MCP state the client saved meanwhile (mcpOAuth) is never rolled back.
-            store.write({'claudeAiOauth': o})
-        except Exception as e:
-            say(f'{aid}: token refreshed but credentials NOT persisted ({e}) — re-login may be needed')
-            return None
-    finally:
-        if held:
-            lock.release()
-    try:
-        os.remove(spath)
-    except OSError:
-        pass
-    # The grant answered: whatever parked this account before, it authenticates now.
-    if clear_expired(d):
-        say(f'{aid}: dead-auth marker cleared (refresh grant works again)')
-    say(f'{aid}: oauth access token refreshed via refresh-token grant')
-    return tok
 
 for acct in manifest.get('accounts', []):
     aid = acct['id']
@@ -2400,8 +2214,8 @@ for acct in manifest.get('accounts', []):
             bearer, source = tok, 'oauth'
     # A setup token is a LAST RESORT and only for an account that has no OAuth
     # credential at all. Where one exists but could not be used this pass — its
-    # access token expired moments ago (refresh_oauth waits REFRESH_MIN_EXPIRED to
-    # prove no live session owns it), a refresh backoff, or a Keychain this session
+    # access token expired moments ago (refresh_oauth gives the native
+    # client a five-minute grace period), a refresh backoff, or a Keychain this session
     # cannot open — spending the token is guaranteed to earn a 403 it can never not
     # earn, and that 403 used to park the whole ACCOUNT for six hours. Telemetry then
     # froze for an account whose OAuth would have worked on the very next pass, and

package/bin/codex

@@ -156,6 +156,20 @@ cli_positional_at() { # argv -> prints the index of its first positional argumen
   return 1
 }
 
+# Account/model capabilities are resolved only after the serving account is known.
+# The helper is optional so a damaged install retains the shim's fail-open contract.
+codex_native_argv() {
+  CODEX_SPEED_ARGV=("$@")
+  if [ -f "$SELF_DIR/../lib/codex_speed.sh" ]; then
+    . "$SELF_DIR/../lib/codex_speed.sh"
+    codex_speed_prepare "$@" || return $?
+  fi
+}
+codex_native_exec() {
+  codex_native_argv "$@" || exit $?
+  exec "$REAL" ${CODEX_SPEED_ARGV[@]+"${CODEX_SPEED_ARGV[@]}"}
+}
+
 # Whether argv is `codex [global options] mcp add|remove …`.
 mcp_mutation_argv() {
   local i j
@@ -252,7 +266,7 @@ if [ -n "${CODEX_HOME:-}" ] \
     mcp_oauth_ensure "$CODEX_HOME"
   fi
   mcp_nested_mirror "$@" || true
-  exec "$REAL" "$@"
+  codex_native_exec "$@"
 fi
 
 now="$(date +%s)"
@@ -1074,6 +1088,9 @@ ar_argv_ok() { # the argv codex is about to get
         model:*) case "$a" in ''|-*) return 1 ;; esac ;;
         effort:model_reasoning_effort=?*)
           case "${a#model_reasoning_effort=}" in *[!$AR_LOWER]*) return 1 ;; esac ;;
+        effort:service_tier=*)
+          case "${a#service_tier=}" in default|fast|priority|ultrafast|'"default"'|'"fast"'|'"priority"'|'"ultrafast"'|"'default'"|"'fast'"|"'priority'"|"'ultrafast'") ;; *) return 1 ;; esac ;;
+        effort:features.fast_mode=true) ;;
         *) return 1 ;;
       esac
       want=""
@@ -1272,7 +1289,7 @@ if [ -n "${CODEX_ACCOUNT:-}" ] && [ "$AR_PROBE" != "1" ]; then
     mcp_ensure "$d"
     mcp_oauth_ensure "$d"
     mcp_mirror_run "$d" "$@" || true
-    exec "$REAL" "$@"
+    codex_native_exec "$@"
   fi
   sel_log "pin-invalid account=$CODEX_ACCOUNT (no such dir; random fallback)"
 fi
@@ -1343,7 +1360,7 @@ if [ "${#valid[@]}" -eq 0 ]; then
     [ -t 2 ] && printf 'codex-multiacc: no pool account is usable (%s) — see: codex-accounts expired, then: codex-accounts relogin\n' \
       "${ids# }" >&2
   fi
-  exec "$REAL" "$@"
+  codex_native_exec "$@"
 fi
 
 # ---- rotation ----------------------------------------------------------------
@@ -1657,14 +1674,14 @@ if [ "$wants_retry" = "0" ]; then
   fi
   ar_scrub_env
   [ "$AR_NO_DAEMON" != 1 ] || set -- --no-daemon "$@"
-  exec "$REAL" "$@"
+  codex_native_exec "$@"
 fi
 
 # Retry path: buffer stdio so a retried call never double-emits partial output.
 mkdir -p "$ACC_ROOT/tmp" 2>/dev/null || true
 tmpd="$(mktemp -d "$ACC_ROOT/tmp/shim.XXXXXX" 2>/dev/null)" || {
   export CODEX_HOME="$pick"
-  exec "$REAL" "$@"
+  codex_native_exec "$@"
 }
 trap 'rm -rf "$tmpd"' EXIT
 
@@ -1673,7 +1690,7 @@ trap 'rm -rf "$tmpd"' EXIT
 # nonzero — a hard failure. Verify now, fall back to plain exec if we cannot.
 if ! : > "$tmpd/out" 2>/dev/null || ! : > "$tmpd/err" 2>/dev/null; then
   export CODEX_HOME="$pick"
-  exec "$REAL" "$@"
+  codex_native_exec "$@"
 fi
 
 stdin_file=""
@@ -1708,8 +1725,9 @@ cur="$pick"
 rc=0
 while :; do
   if [ -n "$stdin_file" ]; then exec 3< "$stdin_file"; else exec 3< /dev/null; fi
+  CODEX_HOME="$cur" codex_native_argv "$@" || exit $?
   CODEX_HOME="$cur" CODEX_MULTIACC_SELECTED_HOME="$cur" \
-    codex_retry_run "$REAL" "$@" <&3 > "$tmpd/out" 2> "$tmpd/err"
+    codex_retry_run "$REAL" ${CODEX_SPEED_ARGV[@]+"${CODEX_SPEED_ARGV[@]}"} <&3 > "$tmpd/out" 2> "$tmpd/err"
   rc=$?
   exec 3<&-
   if [ "$rc" -ne 0 ] && [ "$attempt" -eq 1 ] \

package/bin/codex-accounts

@@ -106,6 +106,10 @@ USAGE
       every install and self-update runs it, and each limits pass refreshes its own pool's
       copy once it is an hour old. --if-stale leaves a younger copy alone; --quiet prints
       nothing. show prints the merged catalog.
+  codex-accounts speed --account-dir DIR --model MODEL --speed normal|fast|ultrafast [--json]
+      resolve speed from this account's native model catalog. Ultrafast verifies
+      account access through native model/list without inference; unknown or
+      unavailable access falls back to Fast. Never changes account configuration.
   codex-accounts post-sync                  (server side) seed dirs, fix perms, quick verify
   codex-accounts mcp add <name> [--provider claude|codex|both] [--scope user]
                           [-e KEY=VAL]... [-H 'Header: v']... [--transport stdio|http]
@@ -144,6 +148,8 @@ ENV
                         'none' = local-only, nothing is pushed anywhere
   CODEX_MULTIACC_SYNC_ROOT / _SYNC_REPO   remote pool root / addon repo for it
   CODEX_ACCOUNT         pin the shim to one account
+  CODEX_SPEED           normal|fast|ultrafast for this launch; unavailable Ultrafast uses Fast
+  CODEX_SPEED_MODEL     model hint for app-server launches that choose their model over RPC
   CODEX_SHIM_RETRY=0    disable the `codex exec` auto-retry
   CODEX_MULTIACC_DISABLE=1  bypass the shim entirely
   CODEX_MULTIACC_AUTO_RESET=0  disable automatic usage-reset redemption
@@ -156,6 +162,12 @@ EOF
 
 require_manifest() { [ -f "$MANIFEST" ] || die "no manifest at $MANIFEST — run claude-multiacc install first"; }
 
+cmd_speed() {
+  local native
+  native="$(find_real_codex "$_self" 2>/dev/null)" || native=""
+  "$PYBIN" "$LIB_DIR/codex_speed.py" --native-cli "$native" "$@"
+}
+
 cmd_configure() {
   require_manifest
   local apply=0 check=0 arg rc
@@ -257,11 +269,11 @@ PYEOF
 # later contender legitimately re-took.
 login_lock_acquire() { # $1 = lock dir; nonzero when someone else holds it
   local L="$1"
-  if ! mkdir "$L" 2>/dev/null; then
+  if ! atomic_mkdir "$L" 2>/dev/null; then
     [ $(( $(epoch_now) - $(file_mtime "$L") )) -gt 1800 ] || return 1
     mv "$L" "$L.stale.$$" 2>/dev/null || return 1
     rm -rf "$L.stale.$$" 2>/dev/null
-    mkdir "$L" 2>/dev/null || return 1
+    atomic_mkdir "$L" 2>/dev/null || return 1
   fi
   : > "$L/owner.$$" 2>/dev/null || true
   return 0
@@ -2477,7 +2489,7 @@ PYEOF
 # distribution for as long as the arg loops rejected the flag. An UNKNOWN verb must still
 # FAIL, or the probe stops meaning what it says — so this list must hold exactly the verbs
 # the dispatcher below implements, and a test pins that both ways.
-_KNOWN_VERBS="list status add import export-credential export-cred import-credential import-cred adopt dedupe remove login expired relogin re-login sync configure verify limits post-sync health self-update init-pool mcp model-catalog"
+_KNOWN_VERBS="list status add import export-credential export-cred import-credential import-cred adopt dedupe remove login expired relogin re-login sync configure verify limits post-sync health self-update init-pool mcp model-catalog speed"
 case " $_KNOWN_VERBS " in
   *" ${1:-help} "*)
     # ...but never past a literal `--`: from there on the words belong to an MCP
@@ -2510,6 +2522,7 @@ case "${1:-help}" in
   init-pool) shift; cmd_init_pool "$@" ;;
   mcp) shift; cmd_mcp "$@" ;;
   model-catalog) shift; cmd_model_catalog "$@" ;;
+  speed) shift; cmd_speed "$@" ;;
   help|--help|-h) usage ;;
   *) usage; exit 1 ;;
 esac

package/docs/AUTORESUME.md

@@ -225,7 +225,16 @@ The prompt is submitted automatically:
 - **To replace the whole text**, set `CLAUDE_MULTIACC_AUTORESUME_PROMPT` or
   `CODEX_MULTIACC_AUTORESUME_PROMPT`.
 
-### Model and effort
+### Model, effort, and Codex speed
+
+Codex relaunches also carry the most recently saved `service_tier` from the
+thread's own settings or turn context. Normal, Fast, and Ultrafast remain the same
+across account rotation; Ultrafast becomes Fast when the selected destination
+account/model does not advertise it. Claude receives no speed flag. The shim
+updates the named thread's tier through native `thread/resume` before launching
+the CLI, because native resume restores a saved tier ahead of `-c` configuration.
+See [Session speed](CODEX.md#session-speed) for capability discovery and the
+`CODEX_SPEED` launch override.
 
 The watcher reads the model and effort from the session's own history when it decides to
 relaunch, so a `/model` or `/effort` switch made after the launch is honoured:

package/docs/CODEX.md

@@ -92,6 +92,45 @@ Codex-specific notes:
 - **API-key logins are rejected** — ChatGPT subscription accounts only, matching the
   addon's no-API-keys rule.
 
+## Session speed
+
+Set `CODEX_SPEED=normal`, `fast`, or `ultrafast` for a Codex launch. Normal explicitly
+uses the standard tier, even when an account's configuration defaults to Fast.
+The setting also works with `CODEX_ACCOUNT` and `CODEX_HOME` pins. Explicit native
+`-c service_tier=...` overrides take precedence. Claude has no corresponding option.
+
+```bash
+CODEX_SPEED=fast codex
+CODEX_SPEED=ultrafast codex exec -m gpt-6.1-sol 'Review the changed code'
+codex-accounts speed --account-dir ~/.codex-accounts/acct-18 --model gpt-6.1-sol --speed ultrafast --json
+```
+
+The shim reads **the selected account's** native model catalog, never an e-mail or
+a plan-name guess. Ultrafast falls back to Fast when that account/model does not
+advertise it. Every Ultrafast launch verifies the native account's `model/list`
+with no inference, so even a copied cache cannot grant another account access;
+an inconclusive read falls back to Fast.
+Catalog probes use a temporary SQLite index, preserving the account's normal
+session-index work. The inspection command above uses the same native check for
+Ultrafast.
+
+Quota retries resolve the speed again for the next account. Automatic quota
+resumes carry the speed recorded in the session history. For those resumes and
+explicit speed requests on a named session UUID, the shim applies the resolved
+tier through native `thread/resume` before launching the resumed CLI: Codex
+currently restores its saved tier ahead of process configuration. That
+preparation sends no turn and preserves the conversation. A failed preparation
+stops the launch instead of silently selecting another speed.
+
+App-server callers may supply `CODEX_SPEED_MODEL` when their model is chosen over
+RPC. Read the resolved `config.service_tier` with native `config/read` and pass it
+as `serviceTier` on `thread/start`, `thread/resume`, and `turn/start`; otherwise
+saved thread settings can override the process configuration.
+
+The [official speed documentation](https://learn.chatgpt.com/docs/agent-configuration/speed)
+describes Fast's higher usage and Ultrafast access for Pro $500 and eligible
+Enterprise/Edu plans. Actual account/model capabilities remain authoritative.
+
 ## Spendable Codex credits
 
 The existing authenticated usage GET also supplies the account's spendable Codex