claude-multiacc 1.0.13 → 1.0.15

package/bin/claude-accounts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # claude-accounts — manage the claude-multiacc account pool.
 # Subcommands: list status add import remove mint sync verify limits post-sync health
-#              expired relogin
+#              expired relogin export-credential import-credential
 set -u
 # lib/audit.py is imported by several subcommands; keep the install tree free of
 # __pycache__ (it may be root-owned, read-only, or an npm global prefix).
@@ -22,8 +22,8 @@ usage() {
 claude-accounts — multi-account pool manager for claude-multiacc
 
 USAGE
-  claude-accounts list                      brief account list
-  claude-accounts status                    full health: auth, per-bucket limits, markers
+  claude-accounts list [--json]             brief account list (--json: machine-readable)
+  claude-accounts status [--json]           full health: auth, per-bucket limits, markers
   claude-accounts add [email] [--token] [--force]
       login-FIRST: runs the full Claude Code login (`claude auth login` — the normal
       browser sign-in, no long-lived-token step-up), then registers only after the
@@ -51,17 +51,34 @@ USAGE
   claude-accounts adopt <acct-NN>           make acct-NN THIS machine's existing
                                             default ~/.claude login (dir symlink —
                                             single credential file, no grant fork)
+  claude-accounts export-credential <acct-NN> [--out PATH] [--identity-only]
+      print a self-contained JSON blob (credential + identity metadata) for a
+      PORTABLE account, i.e. one with a setup-token. REFUSES a machine-local OAuth
+      credential (exit 3) — those cannot be copied; sign in on the machine that
+      needs them, or run 'mint <acct-NN>' once to make the account portable.
+      --identity-only exports registry metadata with NO credential material.
+      Exit: 0 ok, 3 machine-local, 4 no credential, 5 unusable material.
+  claude-accounts import-credential [acct-NN] [--in PATH|-] [--home mac|server]
+                                    [--force] [--no-sync]
+      install a blob from export-credential (stdin by default): creates the account
+      dir + manifest entry as needed, or refreshes the credential of the account
+      that already owns that email. Non-interactive — this is how a daemon
+      distributes accounts to a machine.
   claude-accounts remove <acct-NN> [--yes]  delete account (propagates to server)
   claude-accounts dedupe [--yes]            remove any account registered twice
                                             (same email), keeping one per email
   claude-accounts mint <acct-NN>            mint server token via `claude setup-token`
       --paste               paste an already-minted token instead of running setup-token
-  claude-accounts sync                      push manifest+tokens to the server AND any
-                                            manifest 'peers' (extra machines). Mac only.
-                                            A pool with a 'sync-role' file saying
+  claude-accounts sync [--no-server]        push manifest+tokens to the sync target AND
+                                            any manifest 'peers' (extra machines). Mac
+                                            only. A pool with a 'sync-role' file saying
                                             'replica' never pushes (it receives).
+                                            --no-server (or a pool whose target is
+                                            'none') keeps sync LOCAL: validate + seed +
+                                            fix perms, push nowhere — for pools a panel
+                                            or runner daemon distributes.
   claude-accounts verify [--quick]          auth matrix; full mode runs `-p "reply OK"` per account
-  claude-accounts limits [--quiet] [--force]
+  claude-accounts limits [--quiet] [--force] [--json]
       refresh usage buckets, apply >=90% markers. Auto-refreshes long-expired
       OAuth access tokens via the refresh-token grant (rotated credential is
       persisted), so idle accounts keep fresh telemetry and stay selectable.
@@ -73,7 +90,12 @@ USAGE
   claude-accounts post-sync                 (server side) seed dirs, fix perms, quick verify
 
 ENV
-  CLAUDE_ACCOUNTS_DIR   override ~/.claude-accounts
+  CLAUDE_ACCOUNTS_ROOT  pool root, overriding ~/.claude-accounts — one isolated pool
+                        per app-robot instance on a shared machine (legacy spelling
+                        CLAUDE_ACCOUNTS_DIR still works)
+  CLAUDE_MULTIACC_SYNC_TARGET  sync target (user@host), overriding the manifest;
+                        'none' = local-only, nothing is pushed anywhere
+  CLAUDE_MULTIACC_SYNC_ROOT / _SYNC_REPO   remote pool root / addon repo for it
   CLAUDE_ACCOUNT        pin the shim to one account
   CLAUDE_SHIM_RETRY=0   disable -p auto-retry
   CLAUDE_MULTIACC_DISABLE=1  bypass the shim entirely
@@ -95,17 +117,19 @@ next_id() {
   done
 }
 
-manifest_add_account() { # id email home
-  "$PYBIN" - "$MANIFEST" "$1" "$2" "$3" <<'PYEOF'
+manifest_add_account() { # id email home [added_at]
+  "$PYBIN" - "$MANIFEST" "$1" "$2" "$3" "${4:-}" <<'PYEOF'
 import json, sys, time
-path, aid, email, home = sys.argv[1:5]
+path, aid, email, home, added_at = sys.argv[1:6]
 doc = json.load(open(path))
 accounts = [a for a in doc.get('accounts', []) if a['id'] != aid]
 accounts.append({
     'id': aid,
     'email': email,
     'home': home,
-    'added_at': time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime()),
+    # An imported account keeps the added_at it was registered with on the machine it
+    # came from, so the same account reads identically across the fleet.
+    'added_at': added_at or time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime()),
 })
 accounts.sort(key=lambda a: a['id'])
 doc['accounts'] = accounts
@@ -128,6 +152,17 @@ for a in json.load(open(sys.argv[1])).get('accounts', []):
 PYEOF
 }
 
+manifest_email_of() { # prints the email registered for <id>, empty if unknown
+  [ -f "$MANIFEST" ] || return 0
+  "$PYBIN" - "$MANIFEST" "$1" <<'PYEOF' 2>/dev/null
+import json, sys
+for a in json.load(open(sys.argv[1])).get('accounts', []):
+    if isinstance(a, dict) and a.get('id') == sys.argv[2]:
+        print(a.get('email', ''))
+        break
+PYEOF
+}
+
 manifest_del_account() { # id
   "$PYBIN" - "$MANIFEST" "$1" <<'PYEOF'
 import json, sys
@@ -143,8 +178,11 @@ PYEOF
 }
 
 auto_sync() { # best effort after mutations, Mac only, loud on failure
-  [ "$(machine_kind)" = "mac" ] || return 0
   [ "${CLAUDE_MULTIACC_NO_SYNC:-0}" = "1" ] && return 0
+  # Local-only pool (target 'none'): there is nothing to push — the panel/runner
+  # daemon distributes accounts — so a mutation must not warn about a missing server.
+  sync_target_is_local "$(sync_target)" && return 0
+  [ "$(machine_kind)" = "mac" ] || return 0
   # A replica pool never pushes (the source machine owns the account set) —
   # silently, so every mutation on a replica does not nag about it.
   sync_is_replica && return 0
@@ -154,6 +192,14 @@ auto_sync() { # best effort after mutations, Mac only, loud on failure
 
 cmd_list() {
   require_manifest
+  local json=0
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --json) json=1; shift ;;
+      *) die "unknown option: $1 (usage: claude-accounts list [--json])" ;;
+    esac
+  done
+  if [ "$json" = "1" ]; then emit_report_json list; return $?; fi
   "$PYBIN" - "$MANIFEST" "$ACC_ROOT" "$LIB_DIR" "$(machine_kind)" <<'PYEOF'
 import json, os, re, sys
 doc = json.load(open(sys.argv[1]))
@@ -205,6 +251,14 @@ PYEOF
 
 cmd_status() {
   require_manifest
+  local json=0
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --json) json=1; shift ;;
+      *) die "unknown option: $1 (usage: claude-accounts status [--json])" ;;
+    esac
+  done
+  if [ "$json" = "1" ]; then emit_report_json status; return $?; fi
   "$PYBIN" - "$MANIFEST" "$ACC_ROOT" "$LIB_DIR" "$(machine_kind)" <<'PYEOF'
 import json, os, sys, time
 doc = json.load(open(sys.argv[1]))
@@ -213,6 +267,25 @@ sys.path = [sys.argv[3]] + [p for p in sys.path if p not in ('', '.')]
 from audit import audit_account   # noqa: E402  (shared with the shim's rule)
 machine = sys.argv[4]
 now = time.time()
+# Must match the shim's window (bin/claude), or status would call data "fresh" that
+# selection has already stopped ranking on. Same fallback as the shim for a garbled
+# override: a bad env var must never be the thing that stops status from printing.
+try:
+    STALE_AFTER = int(os.environ.get('CLAUDE_MULTIACC_STALE_AFTER') or 3600)
+except ValueError:
+    STALE_AFTER = 3600
+if STALE_AFTER <= 0:
+    STALE_AFTER = 3600
+
+def telem_fetched_at(aid):
+    """Epoch of aid's last SUCCESSFUL usage fetch, or 0. Never raises: this file is
+    hand-editable and syncs between machines, and one corrupt copy must not stop
+    status from printing the pool-wide verdict it exists to show."""
+    try:
+        v = json.load(open(os.path.join(root, aid, 'limits.json'))).get('fetched_at', 0)
+    except Exception:
+        return 0
+    return v if isinstance(v, (int, float)) and not isinstance(v, bool) and v > 0 else 0
 
 def last_pick(aid):
     path = os.path.join(root, 'selection.log')
@@ -234,12 +307,15 @@ print(f"server    : {doc.get('server','-')}  (root: {doc.get('server_root','-')}
 print(f"threshold : {doc.get('threshold', 90)}% (any bucket at/above => account excluded)")
 print()
 needs_login = []
+selectable_ids = []
 for a in doc.get('accounts', []):
     aid = a['id']
     d = os.path.join(root, aid)
     st = audit_account(root, a, machine=machine)
     if st['state'] in ('expired', 'blocked', 'missing'):
         needs_login.append(aid)
+    else:
+        selectable_ids.append(aid)
     banner = {'ok': '', 'remote': '  [not logged in here — grant lives elsewhere]',
               'missing': '  ** NO LOGIN — claude-accounts relogin %s **' % aid,
               'expired': '  ** LOGIN EXPIRED — claude-accounts relogin %s **' % aid,
@@ -271,9 +347,33 @@ for a in doc.get('accounts', []):
     if os.path.isfile(lpath):
         try:
             lim = json.load(open(lpath))
-            age = int(now - lim.get('fetched_at', 0))
+            if not isinstance(lim, dict):
+                raise ValueError('not an object')
+            fetched = telem_fetched_at(aid)
+            age = int(now - fetched) if fetched else None
             parts = [f"{b['name']}={b['percent']}%" for b in lim.get('buckets', [])]
-            print(f"  limits      : {'  '.join(parts) or '(none)'}  [{age}s old, max {lim.get('max_percent')}%]")
+            if age is None:
+                shown = 'never fetched'
+            elif age >= 86400:
+                shown = f'{age // 86400}d {age % 86400 // 3600}h old'
+            elif age >= 3600:
+                shown = f'{age // 3600}h {age % 3600 // 60}m old'
+            else:
+                shown = f'{age}s old'
+            # Loud, because stale numbers do not look stale: they look like a healthy
+            # account sitting at 2%. Past the ranking window the shim ignores them
+            # entirely and picks at random, so the reading below is decoration.
+            stale = age is None or age > STALE_AFTER
+            flag = '  << STALE — NOT USED FOR RANKING' if stale else ''
+            print(f"  limits      : {'  '.join(parts) or '(none)'}  [{shown}, max {lim.get('max_percent')}%]{flag}")
+            err = lim.get('last_error')
+            if isinstance(err, str) and err:
+                when = lim.get('last_error_at')
+                ago = f' ({int(now - when)}s ago)' if isinstance(when, (int, float)) else ''
+                print(f"  telemetry   : last fetch FAILED{ago}: {err}")
+                retry = lim.get('retry_after', 0)
+                if isinstance(retry, (int, float)) and retry > now:
+                    print(f"                retrying in {int(retry - now)}s")
         except Exception as e:
             print(f"  limits      : unreadable ({e})")
     else:
@@ -295,6 +395,40 @@ for a in doc.get('accounts', []):
 if needs_login:
     print(f"{len(needs_login)} account(s) are EXCLUDED from selection: {', '.join(needs_login)}")
     print("What each one needs: claude-accounts expired")
+# Pool-wide verdict. Per-account ages are easy to skim past; "the pool is picking at
+# random" is not. This is the line that would have caught an eleven-day outage on the
+# first day someone ran status.
+# The verdict comes from lib/report.py so this text, `--json`, and the shim's own
+# ranking can never drift apart — a status that disagrees with selection is worse than
+# no status at all.
+try:
+    from report import telemetry_state, build   # noqa: E402
+    doc_rows = build(root, 'claude', machine, 'status')['accounts']
+    verdict = telemetry_state(doc_rows, now)
+except Exception as e:
+    verdict = 'unknown'
+    verdict_err = str(e)[:200]
+if verdict == 'unknown':
+    # Silence here would recreate the observability half of the incident: a blind pool
+    # that says nothing. Say the verdict could not be computed, and why.
+    print(f"RANKING STATE UNKNOWN: could not compute the pool-wide telemetry verdict "
+          f"({verdict_err}). Check the per-account ages above by hand.")
+elif verdict == 'blind':
+    print("RANKING IS BLIND: no account has usage telemetry inside the "
+          f"{STALE_AFTER}s window, and the last readings are too old to mean anything, "
+          "so every account scores the same and `claude` picks at RANDOM — including "
+          "accounts that are nearly out of weekly headroom.")
+    print("  why : see the 'telemetry' lines above (a setup token cannot read the usage "
+          "endpoint — it has no user:profile scope; only an OAuth login on this machine can)")
+    print("  fix : claude-accounts limits --force   # then, if it still fails:")
+    print("        claude-accounts login <acct-NN>  # per account, on THIS machine")
+elif verdict == 'degraded':
+    print("RANKING IS DEGRADED: no account has telemetry inside the "
+          f"{STALE_AFTER}s window, so `claude` is ranking on the last readings whose "
+          "weekly bucket has not reset yet. Better than random, but it cannot see usage "
+          "since those readings were taken.")
+    print("  fix : claude-accounts limits --force   # then, if it still fails:")
+    print("        claude-accounts login <acct-NN>  # per account, on THIS machine")
 PYEOF
 }
 
@@ -922,11 +1056,12 @@ cmd_relogin() {
 
 cmd_limits() {
   require_manifest
-  local quiet=0 force=0
+  local quiet=0 force=0 json=0
   while [ $# -gt 0 ]; do
     case "$1" in
       --quiet) quiet=1; shift ;;
       --force) force=1; shift ;;   # ignore freshness/backoff (manual override)
+      --json) json=1; quiet=1; shift ;;   # refresh silently, then emit the report
       *) die "unknown option: $1" ;;
     esac
   done
@@ -935,14 +1070,20 @@ cmd_limits() {
   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"
-    mkdir "$lock" 2>/dev/null || return 0
+    if ! mkdir "$lock" 2>/dev/null; then
+      if [ "$json" = "1" ]; then emit_report_json limits; return $?; fi
+      return 0
+    fi
   fi
-  # shellcheck disable=SC2064
-  trap "rm -rf '$lock'" EXIT
+  LIMITS_LOCK="$lock"
+  trap limits_lock_release EXIT
   rotate_log limits.log
   # NB: expired OAuth access tokens are refreshed inside the Python below via the
   # refresh-token grant. (`claude auth status` was tried for this and does NOT
@@ -955,12 +1096,12 @@ cmd_limits() {
   [ "$threshold" -gt 90 ] && threshold=90
   [ "$threshold" -lt 1 ] && threshold=90
   "$PYBIN" - "$ACC_ROOT" "$threshold" "$quiet" "$USAGE_URL" "$force" <<'PYEOF' 2>>"$ACC_ROOT/limits.log"
-import json, os, sys, time, urllib.request
+import hashlib, json, os, sys, time, urllib.request
 
 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()
 # Don't re-fetch an account whose data is younger than this (endpoint rate-limits).
-MIN_FETCH_INTERVAL = int(os.environ.get('CLAUDE_MULTIACC_MIN_FETCH', '45'))
+MIN_FETCH_INTERVAL = int(os.environ.get('CLAUDE_MULTIACC_MIN_FETCH', '240'))
 
 # OAuth refresh-token grant — the same endpoint + public client id Claude Code
 # itself uses to keep .credentials.json alive. An account that sits idle past its
@@ -976,6 +1117,13 @@ CLIENT_ID = os.environ.get('CLAUDE_MULTIACC_CLIENT_ID',
 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
+# then hid the real cause for days, so a definitive refusal parks for 6h and says
+# exactly which ceremony fixes it.
+USAGE_DENIED_BACKOFF = 21600
+USAGE_FAIL_BACKOFF = 900       # anything else non-2xx: 15 min, doubling to 30
 
 def say(msg):
     if not quiet:
@@ -997,6 +1145,15 @@ def parse_iso(s):
 # 4xx from the refresh endpoint), never for a transient network/5xx/429 hiccup.
 def mark_expired(d, slug, detail=''):
     mpath = os.path.join(d, '.expired')
+    # An org-blocked marker is the strongest statement there is about an account and
+    # only `verify` or a re-login may lift it (see clear_expired). Overwriting its
+    # REASON with a weaker one is how it gets lifted by accident: the next successful
+    # fetch sees a reason clear_expired is willing to drop, and the block vanishes.
+    try:
+        if 'reason=org-blocked' in open(mpath, errors='replace').read():
+            return
+    except OSError:
+        pass
     try:
         with open(mpath + '.tmp', 'w') as f:
             f.write(f'{int(now)}\n')
@@ -1028,6 +1185,39 @@ try:
 except Exception as e:
     sys.exit(f'cannot read manifest: {e}')
 
+def token_digest(path):
+    """Stable, non-secret identifier for a credential file's CONTENTS. Used to
+    remember which setup token this endpoint refused, so a re-minted one still gets a
+    try while the refused one is never spent again. Truncated: this only has to
+    distinguish credentials, and a full hash of a secret is not something to write
+    into a file that syncs between machines."""
+    try:
+        with open(path, 'rb') as f:
+            return hashlib.sha256(f.read()).hexdigest()[:16]
+    except OSError:
+        return None
+
+
+def park_dead_grant(aid, d, slug, detail):
+    """Park an account whose OAuth grant is dead — UNLESS it also has a portable setup
+    token, in which case the grant being dead proves nothing about the account: the
+    token still authenticates every real call. Parking it would take a perfectly
+    working account out of the pool over a credential the pool does not need for work,
+    only for telemetry. (The shim's auth_dead() checks the .expired marker BEFORE
+    server.token, so a marker written here really would remove it.)"""
+    try:
+        portable = os.path.getsize(os.path.join(d, 'server.token')) > 0
+    except OSError:
+        portable = False
+    if portable:
+        say(f'{aid}: OAuth grant is dead ({slug}) but its setup token still works — '
+            f'staying in the pool. TELEMETRY is dead for it until it has an OAuth login '
+            f'here: claude-accounts login {aid}')
+        return
+    mark_expired(d, slug, detail)
+    say(f'{aid}: {detail} — re-login needed (claude-accounts relogin {aid})')
+
+
 def refresh_oauth(aid, d, cpath):
     """Refresh a long-expired OAuth access token via the refresh-token grant and
     persist the ROTATED credential atomically (0600). Returns the new bearer, or
@@ -1044,20 +1234,22 @@ def refresh_oauth(aid, d, cpath):
             return None
     except Exception:
         return None
-    if not o.get('accessToken'):
-        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'):
-        mark_expired(d, 'no-refresh-token',
-                     'credential has no refresh token and its access token expired')
+        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").
-        mark_expired(d, 'refresh-token-expired',
-                     'the refresh token itself expired; only a re-login can fix it')
-        say(f'{aid}: refresh token expired — re-login needed (claude-accounts relogin {aid})')
+        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:
@@ -1077,6 +1269,7 @@ def refresh_oauth(aid, d, cpath):
             pass
         say(f'{aid}: oauth refresh failed ({why}); backing off {wait}s; limits left as-is')
 
+    started_with = o['refreshToken']
     body = json.dumps({'grant_type': 'refresh_token',
                        'refresh_token': o['refreshToken'],
                        'client_id': CLIENT_ID}).encode()
@@ -1105,11 +1298,11 @@ def refresh_oauth(aid, d, cpath):
             except Exception:
                 pass
             if 'invalid_grant' in body:
-                mark_expired(d, f'refresh-denied-http-{e.code}',
-                             'the refresh grant was refused as invalid_grant (revoked or rotated away)')
+                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:
-                mark_expired(d, f'refresh-denied-http-{e.code}',
-                             f'the refresh grant was refused {denials} times in a row')
+                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)
@@ -1137,10 +1330,26 @@ def refresh_oauth(aid, d, cpath):
     if data.get('refresh_token_expires_in'):
         o['refreshTokenExpiresAt'] = int((now + float(data['refresh_token_expires_in'])) * 1000)
     doc['claudeAiOauth'] = o
+    # 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.
+    try:
+        with open(cpath) as f:
+            disk = json.load(f).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 on disk')
+            return None
+    except Exception:
+        pass
     try:
         fd = os.open(cpath + '.tmp', os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
         with os.fdopen(fd, 'w') as f:
             json.dump(doc, f)
+            f.flush()
+            os.fsync(f.fileno())
         os.replace(cpath + '.tmp', cpath)
     except Exception as e:
         say(f'{aid}: token refreshed but credentials NOT persisted ({e}) — re-login may be needed')
@@ -1172,18 +1381,43 @@ for acct in manifest.get('accounts', []):
             prev = json.load(open(lpath))
         except Exception:
             prev = {}
+    # Valid JSON is not the same as a usable document: `[]`, `null` and `"broken"` all
+    # parse, and every prev.get() below would then raise OUTSIDE the try — killing the
+    # loop and starving every account after this one of telemetry. One corrupt file
+    # must cost exactly one account.
+    if not isinstance(prev, dict):
+        prev = {}
+
+    def num(key, default=0):
+        """A field of the wrong type is the same as an absent one. limits.json is
+        hand-editable, syncs between machines, and is written by more than one
+        version of this tool at once."""
+        v = prev.get(key, default)
+        return v if isinstance(v, (int, float)) and not isinstance(v, bool) else default
+
     if not force:
-        age = now - prev.get('fetched_at', 0)
+        age = now - num('fetched_at')
         if age < MIN_FETCH_INTERVAL:
             continue
-        retry_at = prev.get('retry_after', 0)
+        retry_at = num('retry_after')
         if retry_at > now:
-            say(f'{aid}: backing off after 429 ({int(retry_at - now)}s left); limits left as-is')
+            # Name the ACTUAL error. Reporting every park as a 429 is what let an
+            # unauthorized account read as merely rate-limited for eleven days.
+            why = prev.get('last_error')
+            why = why if isinstance(why, str) and why else 'a failed fetch'
+            say(f'{aid}: backing off after {why} ({int(retry_at - now)}s left); limits left as-is')
             continue
 
+    # BEARER ORDER MATTERS, and it is not the obvious one. A setup token authenticates
+    # inference forever but is minted WITHOUT the user:profile scope this endpoint
+    # requires, so it can only ever produce a 403 here. Trying it before the OAuth
+    # refresh grant — which is what this did — killed telemetry for accounts whose
+    # refresh token was still perfectly good, purely because a server.token sat beside
+    # it. OAuth first, refresh second, token only as a genuine last resort.
     bearer = None
     source = None
     cpath = os.path.join(d, '.credentials.json')
+    tpath = os.path.join(d, 'server.token')
     if os.path.isfile(cpath):
         try:
             c = json.load(open(cpath)).get('claudeAiOauth', {})
@@ -1191,11 +1425,6 @@ for acct in manifest.get('accounts', []):
                 bearer, source = c['accessToken'], 'oauth'
         except Exception:
             pass
-    tpath = os.path.join(d, 'server.token')
-    if not bearer and os.path.isfile(tpath):
-        t = open(tpath).read().strip()
-        if t:
-            bearer, source = t, 'token'
     if not bearer and os.path.isfile(cpath):
         # Hard fail-open guard: NOTHING a single account's refresh does may abort
         # the loop — every account after it would silently starve of telemetry.
@@ -1206,6 +1435,25 @@ for acct in manifest.get('accounts', []):
             tok = None
         if tok:
             bearer, source = tok, 'oauth'
+    if 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
+        # limit. Keyed on the file's mtime, so re-minting the token retries it.
+        # Keyed on a non-secret digest of the token itself, not its mtime: `sync`
+        # pushes tokens with rsync -a (mtimes preserved) and two different tokens can
+        # land on the same whole second, either of which would skip a credential that
+        # was never actually refused.
+        denied_digest = prev.get('token_scope_denied')
+        tdigest = token_digest(tpath)
+        if not force and tdigest and denied_digest == tdigest:
+            say(f'{aid}: setup token cannot read usage (no user:profile scope) and there '
+                f'is no OAuth login here — telemetry stays dark until: '
+                f'claude-accounts login {aid}')
+            continue
+        t = open(tpath).read().strip()
+        if t:
+            bearer, source = t, 'token'
     if not bearer:
         # Fail OPEN: no usable bearer => leave existing state; never block work on telemetry.
         say(f'{aid}: no fresh bearer (expired oauth and/or no token); limits left as-is')
@@ -1221,6 +1469,24 @@ for acct in manifest.get('accounts', []):
         resp = urllib.request.urlopen(req, timeout=15)
         data = json.loads(resp.read().decode())
     except urllib.error.HTTPError as e:
+        body = ''
+        try:
+            body = e.read().decode('utf-8', 'replace')[:400]
+        except Exception:
+            pass
+
+        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."""
+            prev['retry_after'] = int(now + wait)
+            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)
+
         if e.code == 429:
             # Respect Retry-After; otherwise exponential backoff capped at 30 min.
             try:
@@ -1228,19 +1494,69 @@ for acct in manifest.get('accounts', []):
             except (TypeError, ValueError):
                 wait = 0
             if wait <= 0:
-                wait = min(1800, max(120, int(prev.get('backoff', 60)) * 2))
+                wait = min(1800, max(120, int(num('backoff', 60)) * 2))
+            park(wait, f'HTTP 429 (rate limited, source={source})')
+            say(f'{aid}: rate limited (429); backing off {wait}s; failing open')
+        else:
+            # EVERY non-2xx now backs off. Before this only a 429 did, so a permanent
+            # refusal was re-issued on every scheduled pass from every machine in the
+            # fleet — and those retries are what earned the 429s that made an
+            # unauthorized account look merely rate-limited. Telemetry then sat frozen
+            # while the shim ranked the whole pool NEUTRAL, i.e. picked at random.
+            denied = (str(e.headers.get('x-should-retry') or '').lower() == 'false'
+                      or 'scope requirement' in body)
+            # A setup token can NEVER grow the user:profile scope, so that refusal is
+            # permanent and parks for hours. Any other "do not retry" may well be a
+            # policy or endpoint issue someone fixes in minutes — park it for an hour,
+            # not six, so recovery does not wait on a human running --force.
+            scope_denied = denied and 'scope requirement' in body
+            if scope_denied:
+                wait = USAGE_DENIED_BACKOFF
+            elif denied:
+                wait = USAGE_DENIED_BACKOFF // 6
+            else:
+                wait = min(1800, max(USAGE_FAIL_BACKOFF,
+                                     int(num('backoff', USAGE_FAIL_BACKOFF // 2)) * 2))
+            if scope_denied and source == 'token':
+                # Remember WHICH token was refused, so this credential is never spent
+                # on this endpoint again — but a freshly minted one still gets a try.
+                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':
+                # The exact shape of this outage: a setup token is minted WITHOUT the
+                # user:profile scope the usage endpoint requires, so an account whose
+                # OAuth grant lapsed keeps working for inference and goes permanently
+                # dark for telemetry. Only a sign-in ON THIS MACHINE restores it.
+                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.')
+            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}')
+            else:
+                say(f'{aid}: usage fetch failed (HTTP {e.code}); backing off {wait}s; failing open')
+        continue
+    except Exception as e:
+        # Network/parse trouble is transient by nature, but it still must not be retried
+        # every 5 minutes forever — that is how a fleet talks itself into a 429.
+        wait = min(1800, max(USAGE_FAIL_BACKOFF,
+                             int(num('backoff', USAGE_FAIL_BACKOFF // 2)) * 2))
+        try:
             prev['retry_after'] = int(now + wait)
             prev['backoff'] = wait
+            prev['last_error'] = str(e)[:200]
+            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)
-            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
-    except Exception as e:
-        say(f'{aid}: usage fetch failed ({e}); failing open')
+        except Exception:
+            pass
+        say(f'{aid}: usage fetch failed ({e}); backing off {wait}s; failing open')
         continue
 
     def pct_of(v):
@@ -1326,8 +1642,21 @@ for acct in manifest.get('accounts', []):
     session = [b['percent'] for b in buckets if b['group'] == 'session']
     weeklyp = max(weekly) if weekly else maxp
     sessionp = max(session) if session else 0
+    # How long weekly_percent keeps meaning something. A weekly bucket only ever RISES
+    # until its reset, so before that moment a stale percent is still a valid lower
+    # bound and the shim can rank on it when nothing fresher exists; after it, the
+    # number describes a week that is over and says nothing at all. Recording the
+    # horizon here keeps the shim from having to parse buckets[] on every invocation.
+    # It must come from the bucket weekly_percent actually CAME FROM: a low monthly
+    # bucket resetting in an hour says nothing about an 80% weekly one that resets in
+    # five days, and taking the minimum over all of them would throw the 80% away.
+    wresets = [int(b['resets_epoch']) for b in buckets
+               if b['group'] != 'session' and b['percent'] == weeklyp
+               and isinstance(b.get('resets_epoch'), int)]
     out = {'fetched_at': int(now), 'source': source, 'max_percent': maxp,
-           'weekly_percent': weeklyp, 'session_percent': sessionp, 'buckets': buckets}
+           'weekly_percent': weeklyp, 'session_percent': sessionp,
+           'weekly_resets_epoch': min(wresets) if wresets else 0,
+           'buckets': buckets}
     tmp = lpath + '.tmp'
     with open(tmp, 'w') as f:
         json.dump(out, f, indent=1)
@@ -1350,13 +1679,21 @@ for acct in manifest.get('accounts', []):
         say(f"{aid}: LIMITED {worst['name']} at {worst['percent']}% (resets {worst['resets_at']})")
     else:
         if os.path.exists(mpath):
-            # A shim-written error-cooldown marker outlives a clean limits pass:
-            # the account failed a real call moments ago; give the cooldown its window.
+            # A shim-written marker outlives a clean limits pass while its own window
+            # is still open:
+            #   error-cooldown     — the account failed a real call moments ago.
+            #   client-rate-limit  — Claude Code itself was REJECTED on this account and
+            #                        recorded the reset the API handed it. That is
+            #                        first-hand evidence; a usage payload that disagrees
+            #                        (different bucket set, cached edge) must not unpark
+            #                        the account early and send work straight back into
+            #                        the 429.
             keep = False
             try:
                 txt = open(mpath).read()
                 first = txt.splitlines()[0] if txt else ''
-                if 'reason=error-cooldown' in txt and first.isdigit() and int(first) > now:
+                if ('reason=error-cooldown' in txt or 'reason=client-rate-limit' in txt) \
+                        and first.isdigit() and int(first) > now:
                     keep = True
             except Exception:
                 pass
@@ -1367,6 +1704,18 @@ for acct in manifest.get('accounts', []):
             detail = '  '.join(f"{b['name']}={b['percent']}%" for b in buckets)
             print(f'{aid}: ok  {detail}')
 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
+  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
+  # beats silence — but hand the caller the failure, exactly as before --json existed.
+  if [ "$json" = "1" ]; then
+    emit_report_json limits || return $?
+  fi
+  return "$refresh_rc"
 }
 
 cmd_verify() {
@@ -1402,6 +1751,14 @@ def mark_expired(d, slug, detail=''):
     """Park an account the shim must stop selecting. Verify is the strongest signal
     there is — a real inference call that came back 'not authenticated'."""
     mpath = os.path.join(d, '.expired')
+    # Same rule as the limits path: an org block outranks every other reason and only
+    # a PASSING verify or a re-login may lift it. Rewriting its reason with a weaker
+    # one is how it gets lifted by accident later.
+    try:
+        if 'reason=org-blocked' in open(mpath, errors='replace').read():
+            return
+    except OSError:
+        pass
     try:
         with open(mpath + '.tmp', 'w') as f:
             f.write(f'{int(time.time())}\n')
@@ -1606,17 +1963,45 @@ sync_is_replica() {
 
 cmd_sync() {
   require_manifest
+  local allow_empty=0 no_server=0
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --allow-empty) allow_empty=1; shift ;;
+      --no-server) no_server=1; shift ;;   # this run pushes nowhere, whatever the manifest says
+      *) die "unknown option: $1 (usage: claude-accounts sync [--no-server] [--allow-empty])" ;;
+    esac
+  done
+  local server sroot srepo
+  server="$(sync_target)"
+  sroot="$(sync_target_root)"
+  srepo="$(sync_target_repo)"
+  # LOCAL-ONLY: no ssh target at all, because a panel/runner daemon distributes this
+  # pool. Validate + fix up locally and stop — the same verb keeps working, it simply
+  # has nowhere to push. (Not Mac-gated: a local pool is legitimate on any host.)
+  # This mode NARROWS the replica rule, it never widens it: a replica pushes nothing,
+  # and a local-only pool pushes nothing whether or not it is a replica. The marker is
+  # still honored and still reported, so a replica can never start pushing by having
+  # its sync target changed.
+  if [ "$no_server" = "1" ] || sync_target_is_local "$server"; then
+    rotate_log sync.log
+    manifest_well_formed || { log_to sync.log "FAIL: manifest malformed (local sync)"; \
+      die "manifest is not valid JSON or has no well-formed accounts — fix $MANIFEST"; }
+    local role="source"
+    sync_is_replica && role="replica"
+    log_to sync.log "sync (local-only, role=$role): no server target${no_server:+ (--no-server)}"
+    local_pool_fixup
+    if [ "$role" = "replica" ]; then
+      echo "sync ok (local-only, and this pool is a sync replica — nothing pushed either way)"
+    else
+      echo "sync ok (local-only: pool at $ACC_ROOT validated and re-seeded; nothing pushed)"
+    fi
+    return 0
+  fi
   [ "$(machine_kind)" = "mac" ] || die "sync runs on the Mac (source of truth), not the server"
   if sync_is_replica; then
     echo "this pool is a sync replica — the source machine pushes here; nothing sent"
     return 0
   fi
-  local allow_empty=0
-  [ "${1:-}" = "--allow-empty" ] && allow_empty=1
-  local server sroot srepo
-  server="$(manifest_get server "$DEFAULT_SERVER")"
-  sroot="$(manifest_get server_root "$DEFAULT_SERVER_ROOT")"
-  srepo="$(manifest_get server_repo "$DEFAULT_SERVER_REPO")"
   # These land inside remote shell commands — anything but a plain target/path is a
   # command-injection vector from a corrupted or hand-edited manifest. EVERY target
   # (primary and peers) is validated before anything is pushed anywhere.
@@ -1648,17 +2033,8 @@ EOF
   # never be pushed (it would blank the target pools), and must never make the removal
   # propagation wipe a target's credentials. Emptying the pool on purpose is possible
   # via `sync --allow-empty`, so this can never happen by accident.
-  "$PYBIN" - "$MANIFEST" <<'PYEOF' 2>/dev/null || fail "manifest is not valid JSON or has no well-formed accounts — refusing to sync"
-import json, re, sys
-doc = json.load(open(sys.argv[1]))
-accounts = doc.get('accounts')
-if not isinstance(accounts, list):
-    sys.exit(1)
-for a in accounts:
-    if not isinstance(a, dict) or not re.fullmatch(r'acct-\d{2}', str(a.get('id', ''))) \
-       or not str(a.get('email', '')).strip():
-        sys.exit(1)
-PYEOF
+  manifest_well_formed \
+    || fail "manifest is not valid JSON or has no well-formed accounts — refusing to sync"
   if [ -z "$(account_ids)" ] && [ "$allow_empty" != "1" ]; then
     fail "manifest has zero accounts — refusing to blank the target pools (use 'sync --allow-empty' if that is really intended)"
   fi
@@ -1685,13 +2061,7 @@ EOF
 
 cmd_post_sync() {
   require_manifest
-  local id d
-  for id in $(account_ids); do
-    d="$ACC_ROOT/$id"
-    seed_account_dir "$d"
-    [ -f "$d/server.token" ] && chmod 600 "$d/server.token" 2>/dev/null
-    [ -f "$d/.credentials.json" ] && chmod 600 "$d/.credentials.json" 2>/dev/null
-  done
+  local_pool_fixup
   log_to sync.log "post-sync: seeded $(account_ids | wc -l | tr -d ' ') account dirs"
   ( cmd_limits --quiet ) || true   # subshell: release the limits lock before verify
   cmd_verify --quick
@@ -1761,6 +2131,8 @@ case "${1:-help}" in
   status) shift; cmd_status "$@" ;;
   add) shift; cmd_add "$@" ;;
   import) shift; cmd_import "$@" ;;
+  export-credential|export-cred) shift; cmd_export_credential "$@" ;;
+  import-credential|import-cred) shift; cmd_import_credential "$@" ;;
   adopt) shift; cmd_adopt "$@" ;;
   dedupe) shift; cmd_dedupe "$@" ;;
   remove) shift; cmd_remove "$@" ;;