claude-multiacc 2.0.6 → 2.0.8

package/README.md

@@ -70,8 +70,9 @@ repo bin/ first on PATH (rc-file block)    /root/claude-multiacc/  (addon repo)
    (Claude Code disabled for that account). Those can only fail, so they never enter
    selection.
 4. Among the accounts that remain valid **on this machine** (an OAuth login —
-   `.credentials.json`, or a macOS Keychain item this session can open — or
-   `server.token` present) and not limit-excluded, pick the one with the **most remaining
+   `.credentials.json`, or a macOS Keychain item this session can open — or a
+   `server.token` that passes its first inference preflight) and not limit-excluded,
+   pick the one with the **most remaining
    headroom** (see below). On equal headroom the pool **rotates away from the account it
    just handed out** and samples the rest at random — so quitting a session and starting
    another one moves you along the pool, while a burst of parallel `claude -p` runs still
@@ -103,6 +104,10 @@ this one is *down*, and handing work to it guarantees a hard failure. Two kinds:
 - **Dead login** (`EXPIRED`) — refresh token expired, grant revoked, or a real call that
   came back *"OAuth session expired and could not be refreshed"*. Fixed by
   `claude-accounts relogin`.
+- **Rejected setup-token** (`EXPIRED`) — token presence and `claude auth status` do not
+  prove inference works. Before a portable token carries its first real command on a
+  machine, the shim privately verifies it. A 401 parks that exact account and reselects,
+  so direct, TUI, and `--resume` calls do not expose the rejected token's failure.
 - **Org-blocked** (`BLOCKED`) — the account authenticates fine, but the run comes back
   *"Your organization has disabled Claude subscription access for Claude Code"*. Handled
   like any other dead login (`claude-accounts relogin` re-issues the grant and normally
@@ -112,7 +117,8 @@ this one is *down*, and handing work to it guarantees a hard failure. Two kinds:
   park deliberately survives credential refreshes (a new access token says nothing about
   an org policy).
 
-`claude-accounts expired` lists exactly what is excluded, why, and the fix for each.
+`claude-accounts expired` lists what is excluded and also labels a token-only account
+`UNVERIFIED` until `claude-accounts verify` or the shim's first-use preflight proves it.
 Exclusion self-heals, but only against the evidence it was based on: a **credential**
 park (dead login) clears as soon as a newer credential lands — a re-login, or a refresh
 by another process — or when a usage fetch authenticates; a **policy** park (org block)

package/bin/claude

@@ -559,14 +559,17 @@ client_auth_scan() { # $1 acct dir
   return 1
 }
 
-mark_client_auth_dead() { # $1 acct dir
-  local soft=$((now + 3600)) marked
+mark_proven_auth_dead() { # $1 acct dir, $2 fixed safe detail
+  local marked
   marked="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
-  { echo "$now"; echo "reason=auth-error soft_until=$soft marked_at=$marked" \
-      "detail=client session failed to authenticate"; } \
+  { echo "$now"; echo "reason=auth-error marked_at=$marked detail=$2"; } \
     2>/dev/null > "$1/.expired.$$" && mv -f "$1/.expired.$$" "$1/.expired" 2>/dev/null \
     || rm -f "$1/.expired.$$" 2>/dev/null || true
-  sel_log "$(basename "$1") parked (auth-error until $soft) — client-reported"
+}
+
+mark_client_auth_dead() { # $1 acct dir
+  mark_proven_auth_dead "$1" "client session failed to authenticate"
+  sel_log "$(basename "$1") parked (auth-error) — client-reported"
 }
 
 mark_client_limit() { # $1 acct dir, $2 reset epoch, $3 rate limit type
@@ -717,6 +720,50 @@ acct_token() { # $1 = acct dir; prints token if the dir must authenticate by tok
   fi
 }
 
+# A setup-token has no identity or readable expiry, and `claude auth status` only
+# checks its shape. Test each token once on this machine with a real inference before
+# allowing it to carry a user's command. This closes the direct/TUI/--resume gap where
+# a revoked token exposed one 401 and was only parked on the following invocation.
+token_digest() { # $1 token; prints a non-secret sha256 digest
+  local h=""
+  if command -v shasum >/dev/null 2>&1; then
+    h="$(printf '%s' "$1" | shasum -a 256 2>/dev/null)"
+  elif command -v sha256sum >/dev/null 2>&1; then
+    h="$(printf '%s' "$1" | sha256sum 2>/dev/null)"
+  fi
+  printf '%s' "$h" | cut -d ' ' -f1
+}
+
+token_preflight() { # $1 acct dir, $2 setup-token; rc 1 only for proven invalid auth
+  local d="$1" tok="$2" digest marker tmpd token_auth_pat rc=0
+  digest="$(token_digest "$tok")"
+  [ -n "$digest" ] || return 0
+  marker="$d/.server-token-verified"
+  [ -f "$marker" ] && grep -qx "$digest" "$marker" 2>/dev/null && return 0
+  mkdir -p "$ACC_ROOT/tmp" 2>/dev/null || return 0
+  tmpd="$(mktemp -d "$ACC_ROOT/tmp/token-check.XXXXXX" 2>/dev/null)" || return 0
+  printf 'Reply with exactly: OK\n' \
+    | CLAUDE_CONFIG_DIR="$d" CLAUDE_CODE_OAUTH_TOKEN="$tok" CLAUDE_SHIM_ACTIVE=1 \
+      "$REAL" -p --output-format text --max-turns 1 > "$tmpd/out" 2> "$tmpd/err" || rc=$?
+  token_auth_pat='failed to authenticate|oauth (access )?token is invalid|oauth session expired'
+  token_auth_pat="$token_auth_pat|please run /login|invalid bearer token|authentication_error"
+  if [ "$rc" -ne 0 ] \
+    && grep -qiE "$token_auth_pat" "$tmpd/out" "$tmpd/err" 2>/dev/null; then
+    rm -f "$marker" 2>/dev/null || true
+    mark_proven_auth_dead "$d" "portable OAuth token rejected by inference preflight"
+    sel_log "$(basename "$d") parked (auth-error) — setup-token preflight returned 401"
+    rm -rf "$tmpd"
+    return 1
+  fi
+  if [ "$rc" -eq 0 ] && LC_ALL=C grep -qx 'OK' "$tmpd/out" 2>/dev/null; then
+    { umask 077; printf '%s\n' "$digest" > "$marker.$$"; } 2>/dev/null \
+      && mv -f "$marker.$$" "$marker" 2>/dev/null \
+      || rm -f "$marker.$$" 2>/dev/null || true
+  fi
+  rm -rf "$tmpd"
+  return 0
+}
+
 # Explicit pin wins over everything — markers, and even missing auth: the
 # add/login ceremony pins to a dir that has no credentials yet, and the login
 # must land exactly there, never in a randomly selected account's dir.
@@ -731,7 +778,14 @@ if [ -n "${CLAUDE_ACCOUNT:-}" ]; then
     # pinned account with a stale login fail outright ("OAuth session expired") while
     # the very same account worked unpinned.
     tok="$(acct_token "$d")"
-    [ -n "$tok" ] && export CLAUDE_CODE_OAUTH_TOKEN="$tok"
+    if [ -n "$tok" ]; then
+      if ! token_preflight "$d" "$tok"; then
+        printf 'claude-multiacc: pinned account %s has an invalid portable OAuth token (401)\n' \
+          "$CLAUDE_ACCOUNT" >&2
+        exit 1
+      fi
+      export CLAUDE_CODE_OAUTH_TOKEN="$tok"
+    fi
     sel_capture_session "$d"
     exec "$REAL" "$@"
   fi
@@ -937,6 +991,21 @@ else
   fi
 fi
 pick="$PICK_DIR"
+
+# The preflight can prove the selected token dead without exposing its 401 to the
+# caller. Re-enter selection so the new .expired marker is applied and another
+# account serves the original command. The bounded depth also handles several revoked
+# fleet tokens in a row without a loop when no usable account remains.
+tok="$(acct_token "$pick")"
+if [ -n "$tok" ] && ! token_preflight "$pick" "$tok"; then
+  preflight_depth="${CLAUDE_MULTIACC_PREFLIGHT_DEPTH:-0}"
+  num_ok "$preflight_depth" || preflight_depth=0
+  if [ "$preflight_depth" -lt 64 ]; then
+    export CLAUDE_MULTIACC_PREFLIGHT_DEPTH=$((preflight_depth + 1))
+    exec "$SELF" "$@"
+  fi
+fi
+unset CLAUDE_MULTIACC_PREFLIGHT_DEPTH
 # Remember the pick so the NEXT run does not hand back the same account. An explicit
 # CLAUDE_ACCOUNT pin deliberately does not: a pin is a caller overriding selection,
 # not a turn in the rotation.

package/bin/claude-accounts

@@ -1016,9 +1016,9 @@ cmd_login() {
 }
 
 cmd_expired() {
-  # Which accounts CANNOT authenticate right now — the pool's re-login worklist.
-  # Same rule the shim selects by (lib/audit.py), so what is listed here is exactly
-  # what is excluded from selection.
+  # Accounts proven dead plus token-only accounts that have never passed a real call.
+  # Presence/shape is not authentication: without strict token evidence, `expired`
+  # falsely rendered a revoked setup-token as healthy.
   require_manifest
   local quiet=0
   while [ $# -gt 0 ]; do
@@ -1028,7 +1028,8 @@ cmd_expired() {
     esac
   done
   local rows bad
-  rows="$(account_audit)" || die "the account audit failed — cannot say which logins are dead"
+  rows="$(account_audit strict-tokens)" \
+    || die "the account audit failed — cannot say which logins are dead"
   if [ -z "$rows" ]; then
     # No rows at all: either the pool is genuinely empty, or the manifest lost its
     # accounts. Never render that as "all clear".
@@ -1038,7 +1039,8 @@ cmd_expired() {
     fi
     die "the manifest lists accounts but none could be audited — check $MANIFEST"
   fi
-  bad="$(printf '%s\n' "$rows" | awk -F'\t' 'NF >= 4 && $1 != "" && ($4 == "expired" || $4 == "blocked" || $4 == "missing") { print $1 }')"
+  bad="$(printf '%s\n' "$rows" \
+    | awk -F'\t' 'NF >= 4 && $1 != "" && $4 ~ /^(expired|blocked|missing|unverified)$/ { print $1 }')"
   if [ "$quiet" = "1" ]; then
     [ -n "$bad" ] || return 0
     printf '%s\n' "$bad"
@@ -1056,8 +1058,8 @@ cmd_expired() {
       printf "  %-9s %-28s %-9s fix: %s\n", "", "", "", $7
     }
     END {
-      if (bad == 0) printf "All %d account(s) with a login on this machine can authenticate.\n", ok
-      else printf "\n%d account(s) cannot be used, %d fine.\n", bad, ok
+      if (bad == 0) printf "All %d account(s) with auth on this machine can authenticate (verified).\n", ok
+      else printf "\n%d account(s) are dead or unverified, %d verified.\n", bad, ok
       if (remote > 0) {
         printf "\nNot logged in here on purpose (another machine owns the grant):\n"
         printf "%s", rem
@@ -1273,6 +1275,7 @@ cmd_limits() {
 import hashlib, json, os, sys, time, urllib.request
 sys.path = [sys.argv[6]] + [p for p in sys.path if p not in ('', '.')]
 import keychain  # noqa: E402  (macOS Keychain-held logins; a no-op elsewhere)
+from audit import creds_doc_state  # noqa: E402  (one rule for "can this credential work")
 
 root, threshold, quiet, url, force = sys.argv[1], int(sys.argv[2]), sys.argv[3] == '1', sys.argv[4], sys.argv[5] == '1'
 now = time.time()
@@ -1655,6 +1658,18 @@ for acct in manifest.get('accounts', []):
     locked = store == 'locked'
     if locked:
         store = None
+    # "This account has an OAuth login that could still work." A Keychain-held one
+    # only the Mac's own launchd probe can open counts: it is unusable HERE, not
+    # broken. A provably DEAD grant (no refresh token, or a refresh token that has
+    # itself expired) does not count — for that account the setup token really is
+    # the only bearer left, and it must still get its one try.
+    oauth_alive = locked
+    if store is not None:
+        try:
+            oauth_alive = creds_doc_state(store.read(), now)[0] == 'ok'
+        except Exception:
+            oauth_alive = True   # unreadable is not proof of death: do not spend the token
+    has_oauth = oauth_alive
     if store is not None:
         try:
             c = store.read().get('claudeAiOauth', {})
@@ -1672,7 +1687,19 @@ for acct in manifest.get('accounts', []):
             tok = None
         if tok:
             bearer, source = tok, 'oauth'
-    if not bearer and os.path.isfile(tpath):
+    # 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
+    # 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
+    # the shim ranked the pool on hour-old readings. Waiting for the next pass costs
+    # minutes; the token costs six hours and answers nothing.
+    if not bearer and has_oauth:
+        say(f'{aid}: oauth credential not usable this pass; NOT spending the setup '
+            f'token on a usage endpoint that always refuses it — retrying next pass')
+    elif not bearer and os.path.isfile(tpath):
         # Once this endpoint has refused THIS token file for lacking a scope, asking
         # again is guaranteed to fail and only spends the account's hourly budget —
         # which is how a permanent authorization problem disguised itself as a rate
@@ -1717,6 +1744,14 @@ for acct in manifest.get('accounts', []):
         except Exception:
             pass
 
+        def save_prev():
+            """Persist the account's telemetry state as-is (no backoff, no invented
+            freshness) — used when what failed says nothing about the ACCOUNT."""
+            tmp = lpath + '.tmp'
+            with open(tmp, 'w') as f:
+                json.dump(prev, f, indent=1)
+            os.replace(tmp, lpath)
+
         def park(wait, note):
             """Record a failed fetch WITHOUT inventing freshness: fetched_at is left
             exactly as it was, so a parked account still reads as stale everywhere."""
@@ -1724,10 +1759,7 @@ for acct in manifest.get('accounts', []):
             prev['backoff'] = wait
             prev['last_error'] = note
             prev['last_error_at'] = int(now)
-            tmp = lpath + '.tmp'
-            with open(tmp, 'w') as f:
-                json.dump(prev, f, indent=1)
-            os.replace(tmp, lpath)
+            save_prev()
 
         if e.code == 429:
             # Respect Retry-After; otherwise exponential backoff capped at 30 min.
@@ -1765,8 +1797,16 @@ for acct in manifest.get('accounts', []):
                 tdigest = token_digest(tpath)
                 if tdigest:
                     prev['token_scope_denied'] = tdigest
-            park(wait, f'HTTP {e.code} (source={source})'
-                       + (' — permanent, server said do not retry' if denied else ''))
+            if scope_denied and source == 'token':
+                # A refusal of the TOKEN is a fact about that credential, not about
+                # the account: parking the account here also blocked the OAuth path,
+                # so an account that merely missed one refresh went dark for six
+                # hours. The digest above already stops this token being spent again;
+                # leave the account free to try its OAuth login next pass.
+                save_prev()
+            else:
+                park(wait, f'HTTP {e.code} (source={source})'
+                           + (' — permanent, server said do not retry' if denied else ''))
             if scope_denied and source == 'token':
                 # The exact shape of this outage: a setup token is minted WITHOUT the
                 # user:profile scope the usage endpoint requires, so an account whose
@@ -1775,7 +1815,8 @@ for acct in manifest.get('accounts', []):
                 say(f'{aid}: usage endpoint refuses the setup token (HTTP {e.code} — a '
                     f'setup token has no user:profile scope). Telemetry is DEAD for this '
                     f'account until it has an OAuth login here: claude-accounts login {aid}. '
-                    f'Backing off {wait}s.')
+                    f'This token will not be offered again; the ACCOUNT is not parked, so '
+                    f'an OAuth login works the moment it lands.')
             elif denied:
                 say(f'{aid}: usage fetch refused for good (HTTP {e.code}, source={source}); '
                     f'backing off {wait}s — re-login needed: claude-accounts login {aid}')
@@ -1972,7 +2013,7 @@ cmd_verify() {
     real="$(find_real_claude "$_self")" || die "real claude binary not found"
   fi
   "$PYBIN" - "$ACC_ROOT" "$quick" "$real" "$LIB_DIR" "$(machine_kind)" <<'PYEOF'
-import json, os, re, subprocess, sys, time
+import hashlib, json, os, re, subprocess, sys, time
 
 root, quick, real = sys.argv[1], sys.argv[2] == '1', sys.argv[3]
 sys.path = [sys.argv[4]] + [p for p in sys.path if p not in ('', '.')]
@@ -2079,10 +2120,11 @@ for acct in manifest.get('accounts', []):
     if has_token and (not has_creds or cred_state != 'ok'):
         env['CLAUDE_CODE_OAUTH_TOKEN'] = open(tpath).read().strip()
     t0 = time.time()
+    uses_token = 'CLAUDE_CODE_OAUTH_TOKEN' in env
     try:
-        r = subprocess.run([real, '-p', 'Reply with exactly: OK'],
+        r = subprocess.run([real, '-p', '--output-format', 'text', '--max-turns', '1'],
                            env=env, capture_output=True, text=True, timeout=240,
-                           stdin=subprocess.DEVNULL, cwd=root)
+                           input='Reply with exactly: OK\n', cwd=root)
     except subprocess.TimeoutExpired:
         print(f'{aid} {acct["email"]}: FAIL (timeout after 240s)')
         failures += 1
@@ -2095,6 +2137,16 @@ for acct in manifest.get('accounts', []):
             os.remove(os.path.join(d, '.expired'))
         except OSError:
             pass
+        if uses_token:
+            try:
+                digest = hashlib.sha256(open(tpath, 'rb').read().strip()).hexdigest()
+                temp = os.path.join(d, '.server-token-verified.tmp')
+                with open(temp, 'w') as f:
+                    f.write(digest + '\n')
+                os.chmod(temp, 0o600)
+                os.replace(temp, os.path.join(d, '.server-token-verified'))
+            except OSError:
+                pass
         print(f'{aid} {acct["email"]}: PASS ({dt:.1f}s) -> {out[:60]!r}')
     else:
         err = (r.stderr or '').strip()[:200]
@@ -2108,6 +2160,10 @@ for acct in manifest.get('accounts', []):
             hint = (f' — ORG BLOCKED, excluded from the pool; '
                     f'try: claude-accounts relogin {aid}')
         elif AUTH_ERR.search(out) or AUTH_ERR.search(err):
+            try:
+                os.remove(os.path.join(d, '.server-token-verified'))
+            except OSError:
+                pass
             mark_expired(d, 'auth-error', 'a real call came back not-authenticated')
             hint = f' — login is dead, run: claude-accounts relogin {aid}'
         print(f'{aid} {acct["email"]}: FAIL rc={r.returncode} '

package/docs/ACCOUNT_OPERATIONS.md

@@ -373,6 +373,12 @@ repointed via `CLAUDE_BIN=/usr/local/bin/claude` and restarted healthy.
   automatically, so this only surfaces when *every* account needs a re-login (the shim
   then falls back to the machine's own `~/.claude` login) or when it was pinned with
   `CLAUDE_ACCOUNT`.
+- **"Please run /login · API Error: 401 OAuth access token is invalid"** — the portable
+  setup-token is rejected even though its presence and `claude auth status` look healthy.
+  The shim now runs a private first-use inference, parks a rejected token, and reselects
+  before direct, TUI, or `--resume` work sees the 401. Run `claude-accounts verify` to
+  check every token immediately; `claude-accounts expired` reports token-only accounts
+  as `UNVERIFIED` until that proof exists.
 - **Everything marked limited** — the shim still runs (least-utilized fallback);
   check `selection.log` for `all-limited` lines.
 - **Sync fails** — `tail ~/.claude-accounts/sync.log`; it's ssh/rsync to the manifest's

package/lib/audit.py

@@ -12,6 +12,7 @@ States:
            neither dead nor missing; just not usable from here
   missing  no auth on this machine, and this machine is supposed to own the grant
   remote   no auth here, but the manifest says another machine owns it (informational)
+  unverified  a setup-token exists but has not passed inference on this machine
 
 Only 'ok' accounts are selectable; everything else is excluded by the shim.
 
@@ -25,6 +26,7 @@ Run directly for a TSV dump:  python3 lib/audit.py <acc-root> [mac|linux]
 Columns: id, email, home, state, label, reason, fix
 """
 
+import hashlib
 import json
 import os
 import re
@@ -192,7 +194,7 @@ def oauth_login(d, now):
 
 
 LABELS = {'ok': 'OK', 'expired': 'EXPIRED', 'blocked': 'BLOCKED', 'locked': 'KEYCHAIN LOCKED',
-          'missing': 'NO LOGIN', 'remote': 'ELSEWHERE'}
+          'missing': 'NO LOGIN', 'remote': 'ELSEWHERE', 'unverified': 'UNVERIFIED'}
 
 # `import --home` speaks mac|server; machine_kind() speaks mac|linux. Same two boxes,
 # two vocabularies — normalize, or an un-authenticated account on the very machine that
@@ -227,10 +229,22 @@ def _fix_for(state, aid):
         # stuck in an ssh session CAN do is mint the portable token from here — the
         # setup-token ceremony is a fresh browser grant and never reads the keychain.
         return f'claude-accounts mint {aid}   (portable; or use it from the Mac\'s GUI session)'
+    if state == 'unverified':
+        return 'claude-accounts verify'
     return ''
 
 
-def audit_account(root, acct, now=None, machine=None):
+def _token_verified(d, tpath):
+    """Whether this exact setup-token passed an inference on this machine."""
+    try:
+        digest = hashlib.sha256(open(tpath, 'rb').read().strip()).hexdigest()
+        saved = open(os.path.join(d, '.server-token-verified')).read().strip()
+        return bool(digest) and saved == digest
+    except OSError:
+        return False
+
+
+def audit_account(root, acct, now=None, machine=None, require_verified_token=False):
     now = time.time() if now is None else now
     aid = acct.get('id', '')
     d = os.path.join(root, aid)
@@ -263,14 +277,23 @@ def audit_account(root, acct, now=None, machine=None):
         if state == 'ok' or has_token:
             # A portable token authenticates on its own, so a dead credential beside it
             # is not fatal — same rule the shim applies.
-            row['state'] = 'ok'
-            row['reason'] = reason if state == 'ok' else f'{reason}; using server.token'
+            if state != 'ok' and require_verified_token and not _token_verified(d, tpath):
+                row['state'] = 'unverified'
+                row['reason'] = 'server.token has not passed an inference on this machine'
+            else:
+                row['state'] = 'ok'
+                row['reason'] = reason if state == 'ok' else f'{reason}; using server.token'
         else:
             row['state'], row['reason'] = 'expired', reason
         return done(row)
     if has_token:
         age = int((now - _mtime(tpath)) / 86400)
-        row['reason'] = f'server.token present (minted ~{age}d ago)'
+        if require_verified_token and not _token_verified(d, tpath):
+            row['state'] = 'unverified'
+            row['reason'] = (f'server.token present (minted ~{age}d ago) but has not passed '
+                             'an inference on this machine')
+        else:
+            row['reason'] = f'server.token present (minted ~{age}d ago)'
         return done(row)
     if login['state'] == 'locked':
         row['state'], row['reason'] = 'locked', login['reason']
@@ -299,7 +322,11 @@ def audit_all(root, machine=None, now=None):
 if __name__ == '__main__':
     root = sys.argv[1]
     machine = sys.argv[2] if len(sys.argv) > 2 else None
-    for r in audit_all(root, machine=machine):
+    strict_tokens = len(sys.argv) > 3 and sys.argv[3] == 'strict-tokens'
+    for a in json.load(open(os.path.join(root, 'accounts.json'))).get('accounts', []):
+        if not isinstance(a, dict) or not VALID_ID.fullmatch(str(a.get('id', ''))):
+            continue
+        r = audit_account(root, a, machine=machine, require_verified_token=strict_tokens)
         # Tabs are the field separator, so no field may contain one.
         print('\t'.join(str(r[k]).replace('\t', ' ')
                         for k in ('id', 'email', 'home', 'state', 'label', 'reason', 'fix')))

package/lib/common.sh

@@ -499,11 +499,11 @@ clear_auth_markers() { # $1 = acct dir
 # Fails LOUD (nonzero, message on stderr): callers decide policy from these rows, and a
 # silently empty audit reads exactly like a perfectly healthy pool.
 account_audit() {
-  local out rc err="$ACC_ROOT/tmp/audit.$$.err"
+  local mode="${1:-}" out rc err="$ACC_ROOT/tmp/audit.$$.err"
   mkdir -p "$ACC_ROOT/tmp" 2>/dev/null || true
   # stderr goes to a file, never into the rows — a stray warning must not become a
   # bogus account line.
-  out="$("$PYBIN" "$AUDIT_PY" "$ACC_ROOT" "$(machine_kind)" 2>"$err")"
+  out="$("$PYBIN" "$AUDIT_PY" "$ACC_ROOT" "$(machine_kind)" "$mode" 2>"$err")"
   rc=$?
   if [ "$rc" -ne 0 ]; then
     printf '%s: cannot audit accounts (%s)\n' "$PROVIDER_CLI" "$(tail -1 "$err" 2>/dev/null)" >&2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-multiacc",
-  "version": "2.0.6",
+  "version": "2.0.8",
   "description": "Unified Claude Code and OpenAI Codex subscription pooling with quota-aware selection.",
   "type": "module",
   "bin": {

package/tests/run-tests.sh

@@ -84,6 +84,14 @@ if [ $# -eq 0 ] && [ -n "${FAKE_DO_LOGIN:-}" ] && [ -n "${CLAUDE_CONFIG_DIR:-}"
 fi
 ctl="${FAKE_CTL:-/nonexistent}"
 acct="$(basename "${CLAUDE_CONFIG_DIR:-none}")"
+case "${CLAUDE_CODE_OAUTH_TOKEN:-}" in
+  *REVOKED*)
+    echo "Please run /login · API Error: 401 OAuth access token is invalid." >&2
+    exit 1 ;;
+esac
+case " $* " in
+  *" -p --output-format text --max-turns 1 "*) echo "OK"; exit 0 ;;
+esac
 if [ -f "$ctl" ] && grep -qx "fail:$acct" "$ctl" 2>/dev/null; then
   echo "API Error: 429 rate limit exceeded" >&2
   exit 1
@@ -492,6 +500,40 @@ out="$(claude 2>&1)"
 check "dead creds + portable token still authenticate" "TOK=sk-ant-oat01-rescue-token" "$out"
 rm -f "$ACC/acct-01/server.token"
 
+# A revoked setup-token must be rejected BEFORE it carries the user's real command.
+# The 401 stays inside the preflight, the account gets a durable auth marker, and the
+# untouched --resume invocation continues on the next healthy account.
+printf '%s' "$DEAD_CREDS" > "$ACC/acct-01/.credentials.json"
+printf '%s' "$HEALTHY_CREDS" > "$ACC/acct-02/.credentials.json"
+printf 'sk-ant-oat01-REVOKEDREVOKEDREVOKEDREVOKEDREVOKEDREVOKED' > "$ACC/acct-01/server.token"
+printf '{"fetched_at":%s,"max_percent":1,"buckets":[]}' "$now" > "$ACC/acct-01/limits.json"
+printf '{"fetched_at":%s,"max_percent":50,"buckets":[]}' "$now" > "$ACC/acct-02/limits.json"
+rm -f "$ACC/.last-pick" "$ACC/acct-01/.expired" "$ACC/acct-01/.server-token-verified"
+out="$(claude --resume d6ccbac0-6643-4780-a99e-3afa1683478e 2>&1)"
+check "revoked setup-token fails over before --resume" "CFG=acct-02" "$out"
+case "$out" in
+  *"API Error: 401"*) t_fail "revoked setup-token hides preflight 401" "401 reached caller" ;;
+  *) t_ok "revoked setup-token hides preflight 401" ;;
+esac
+grep -q 'reason=auth-error' "$ACC/acct-01/.expired" 2>/dev/null \
+  && t_ok "revoked setup-token writes .expired" \
+  || t_fail "revoked setup-token marker" ".expired missing"
+if grep -q 'soft_until=' "$ACC/acct-01/.expired" 2>/dev/null; then
+  t_fail "proven token rejection is durable" "marker has a soft expiry"
+else
+  t_ok "proven token rejection is durable"
+fi
+out="$(CLAUDE_ACCOUNT=acct-01 claude --resume d6ccbac0-6643-4780-a99e-3afa1683478e 2>&1)"
+rc=$?
+check "pinned revoked setup-token is classified before --resume" \
+  "invalid portable OAuth token (401)" "$out"
+[ "$rc" -ne 0 ] && t_ok "pinned revoked setup-token exits nonzero" \
+  || t_fail "pinned revoked setup-token rc" "rc=$rc"
+rm -f "$ACC/acct-01/server.token" "$ACC/acct-01/.expired" \
+  "$ACC/acct-01/.server-token-verified" "$ACC"/acct-*/limits.json
+printf '%s' "$DEAD_CREDS" > "$ACC/acct-01/.credentials.json"
+printf '%s' "$DEAD_CREDS" > "$ACC/acct-02/.credentials.json"
+
 # every account dead => stock passthrough. The reason lands in selection.log; the
 # stderr hint is terminal-only, so a service-spawned `claude -p` stays byte-clean.
 out="$(claude 2>&1)"
@@ -1791,17 +1833,21 @@ EOF
          claude-accounts limits --force 2>&1)"
   check "a scope-denied 403 names the missing scope" "user:profile" "$out"
   check "a scope-denied 403 names the ceremony that fixes it" "claude-accounts login acct-01" "$out"
-  check "a scope-denied 403 backs off instead of retrying" "Backing off" "$out"
+  # The CREDENTIAL is refused for good (the digest below stops it being offered
+  # again); the ACCOUNT is deliberately NOT parked, because parking it also blocked
+  # the OAuth path and froze telemetry for hours on accounts whose login was fine.
+  check "a scope-denied 403 retires the token, not the account" \
+    "This token will not be offered again" "$out"
   python3 - "$SD/acct-01/limits.json" "$now" <<'EOF'
 import json, sys
 lim = json.load(open(sys.argv[1]))
 now = int(sys.argv[2])
-assert lim['retry_after'] > now + 3600, lim          # parked for hours, not minutes
+assert lim.get('token_scope_denied'), lim            # THIS token is retired
+assert not lim.get('retry_after'), lim               # ...but the account is not parked
 assert lim['fetched_at'] == now - 950000, lim        # a FAILURE never invents freshness
-assert 'HTTP 403' in lim['last_error'], lim
 EOF
-  [ $? -eq 0 ] && t_ok "a refused fetch records a long backoff and keeps its stale fetched_at" \
-    || t_fail "403 backoff state" "see $SD/acct-01/limits.json"
+  [ $? -eq 0 ] && t_ok "a refused token is retired without parking the account, keeping its stale fetched_at" \
+    || t_fail "403 credential-scoped state" "see $SD/acct-01/limits.json"
 
   # The whole point: the next scheduled pass must NOT spend another request. Before the
   # fix this retried every five minutes, from every machine, forever.
@@ -1809,9 +1855,12 @@ EOF
   out="$(CLAUDE_ACCOUNTS_ROOT="$SD" CLAUDE_MULTIACC_USAGE_URL="http://127.0.0.1:$uport/scope-denied" \
          claude-accounts limits 2>&1)"
   after="$(wc -l < "$uhits")"
-  [ "$before" = "$after" ] && t_ok "a parked account is not re-fetched on the next pass" \
+  [ "$before" = "$after" ] && t_ok "a retired token is not re-offered on the next pass" \
     || t_fail "403 retry storm" "endpoint hit again ($before -> $after requests)"
-  check "the parked account says why it is waiting" "backing off after HTTP 403" "$out"
+  # It is the CREDENTIAL that is spent, so the message names the ceremony that
+  # replaces it rather than a clock the operator would otherwise sit and watch.
+  check "and says what would fix it, not how long to wait" \
+    "telemetry stays dark until: claude-accounts login acct-01" "$out"
 
   # Any other non-2xx backs off too — a 5xx retried every pass is the same storm.
   rm -f "$SD/acct-01/limits.json"
@@ -1990,6 +2039,57 @@ EOF
   [ "$before" = "$after" ] && t_ok "a token already refused for scope is not offered again" \
     || t_fail "token re-offered" "endpoint hit again ($before -> $after)"
   check "and the message says what would fix it" "claude-accounts login acct-01" "$out"
+  # ---- an OAuth account NEVER spends its setup token here, and a token refusal
+  # ---- never parks the ACCOUNT ------------------------------------------------
+  # Live symptom (my-mini, 2026-08-28): acct-02/acct-05 sat 1-5 HOURS stale with
+  # "backing off after HTTP 403 (source=token) — permanent" while their OAuth
+  # credentials were fine. The chain: the access token had expired minutes ago, so
+  # refresh_oauth declined (REFRESH_MIN_EXPIRED proves no live session owns it),
+  # the probe fell through to the setup token, the endpoint refused it for scope,
+  # and that parked the whole ACCOUNT for six hours — blocking the OAuth path that
+  # would have worked on the very next pass. The shim then ranked the pool on
+  # hour-old readings and said so ("usage telemetry is 1h old").
+  SD2="$WORK/token-poison"
+  mkdir -p "$SD2/acct-01" "$SD2/tmp"
+  : > "$SD2/.limits-kick"
+  cat > "$SD2/accounts.json" <<EOF
+{ "version": 1, "server": "root@203.0.113.1", "server_root": "/root/.claude-accounts",
+  "server_repo": "/root/claude-multiacc", "threshold": 90,
+  "accounts": [ {"id": "acct-01", "email": "poison@test", "home": "mac",
+                 "added_at": "2026-08-28T00:00:00Z"} ] }
+EOF
+  # An OAuth credential whose ACCESS token expired a moment ago: too recent for
+  # refresh_oauth to touch, so this pass has no bearer it may use.
+  printf '{"claudeAiOauth":{"accessToken":"sk-ant-oat01-justexpired","refreshToken":"r","expiresAt":%s000,"refreshTokenExpiresAt":9999999999999}}' \
+    "$((now - 30))" > "$SD2/acct-01/.credentials.json"
+  printf 'sk-ant-oat01-PORTABLE0001\n' > "$SD2/acct-01/server.token"
+  before="$(wc -l < "$uhits")"
+  out="$(CLAUDE_ACCOUNTS_ROOT="$SD2" CLAUDE_MULTIACC_USAGE_URL="http://127.0.0.1:$uport/scope-denied" \
+         claude-accounts limits 2>&1)"
+  after="$(wc -l < "$uhits")"
+  [ "$before" = "$after" ] \
+    && t_ok "an OAuth account never spends its setup token on the usage endpoint" \
+    || t_fail "token spent" "the endpoint was called ($before -> $after) with a token that can only 403"
+  check "and it says it will simply retry" "retrying next pass" "$out"
+  [ ! -f "$SD2/acct-01/limits.json" ] \
+    && t_ok "no six-hour park is written for an account that merely missed a refresh" \
+    || t_fail "account parked" "$(cat "$SD2/acct-01/limits.json")"
+
+  # A token-only account still tries once (that is the only way to learn), but the
+  # refusal must park the CREDENTIAL, not the account: the digest is remembered and
+  # no retry_after is written, so a later OAuth login is free to work immediately.
+  rm -f "$SD2/acct-01/.credentials.json" "$SD2/acct-01/limits.json"
+  CLAUDE_ACCOUNTS_ROOT="$SD2" CLAUDE_MULTIACC_USAGE_URL="http://127.0.0.1:$uport/scope-denied" \
+    claude-accounts limits >/dev/null 2>&1
+  python3 - "$SD2/acct-01/limits.json" <<'EOF'
+import json, sys
+d = json.load(open(sys.argv[1]))
+assert d.get('token_scope_denied'), d
+assert not d.get('retry_after'), f"the account was parked by a credential refusal: {d}"
+EOF
+  [ $? -eq 0 ] && t_ok "a token scope refusal parks the credential, never the account" \
+    || t_fail "token refusal parked the account" "see $SD2/acct-01/limits.json"
+
   # Re-minting the token is a new credential, so it earns a fresh try.
   printf 'sk-ant-oat01-REMINTED01\n' > "$SD/acct-01/server.token"
   before="$(wc -l < "$uhits")"
@@ -2358,12 +2458,23 @@ check "mint --paste rejects an API key" "not a subscription setup-token" "$out"
 # account and park it.
 printf '{"claudeAiOauth":{"accessToken":"sk-ant-oat01-dead","refreshToken":"r","expiresAt":1000000000000,"refreshTokenExpiresAt":1000000000000}}' > "$ACC/acct-01/.credentials.json"
 printf 'sk-ant-oat01-token-for-01' > "$ACC/acct-01/server.token"
-rm -f "$ACC/acct-01/.expired"
+rm -f "$ACC/acct-01/.expired" "$ACC/acct-01/.server-token-verified"
+out="$(claude-accounts expired 2>&1)"
+check "expired does not call an unverified setup-token healthy" "acct-01" "$out"
+check "expired labels an unverified setup-token" "UNVERIFIED" "$out"
+check "expired gives the setup-token verification fix" "claude-accounts verify" "$out"
 out="$(claude-accounts verify 2>&1)"
 case "$out" in *"acct-01 a@test: PASS"*) t_ok "verify uses the portable token when the credential is dead" ;;
   *) t_fail "verify token fallback" "expected acct-01 PASS, got: $(printf '%s' "$out" | grep acct-01)" ;; esac
 [ ! -f "$ACC/acct-01/.expired" ] && t_ok "verify does not park an account its token can run" \
   || t_fail "verify token fallback" "healthy token-auth account was parked"
+[ -f "$ACC/acct-01/.server-token-verified" ] \
+  && t_ok "verify records proof for the exact setup-token" \
+  || t_fail "verify setup-token proof" ".server-token-verified missing"
+state="$(python3 "$REPO_DIR/lib/audit.py" "$ACC" "$(uname -s | tr '[:upper:]' '[:lower:]')" \
+  strict-tokens | awk -F'\t' '$1=="acct-01"{print $4}')"
+[ "$state" = "ok" ] && t_ok "verified setup-token is no longer false-unknown" \
+  || t_fail "verified setup-token audit" "expected ok, got: $state"
 rm -f "$ACC/acct-01/server.token"
 printf '{"claudeAiOauth":{"accessToken":"sk-ant-oat01-test01","refreshToken":"r","expiresAt":9999999999999,"refreshTokenExpiresAt":9999999999999}}' > "$ACC/acct-01/.credentials.json"