claude-multiacc 1.0.3 → 1.0.5

package/README.md

@@ -74,9 +74,16 @@ code cannot read at all degrades that one account (fail open), never the run.
 Telemetry failures never block work: no fresh data ⇒ account treated as available. The
 endpoint rate-limits per account, so the refresher skips accounts fetched in the last 45s
 and backs off exponentially (honoring `Retry-After`) on a 429 — `limits --force` overrides
-both. If an account's OAuth access token has expired (quiet machine, nothing ran claude for
-hours), the refresher first runs a zero-cost `claude auth status` under that account to let
-the app refresh its own credentials, then fetches; if that fails it logs and fails open.
+both. If an account's OAuth access token has been expired for a while (idle account,
+nothing ran claude under it for hours), the refresher renews it directly via the OAuth
+**refresh-token grant** — the same endpoint and public client id Claude Code itself uses —
+and atomically persists the rotated credential (0600) back to that account's
+`.credentials.json`. This is what keeps idle accounts' telemetry fresh so they win
+selection over busy accounts; without it, stale telemetry ranks neutral and a truly-idle
+account would lose to a busy-but-fresh one. Refresh failures fail open and back off via
+`<acct>/.oauth-refresh.json` (10 min transient, 6 h when the grant looks revoked — the log
+then says re-login is needed). Overrides: `CLAUDE_MULTIACC_TOKEN_URL`,
+`CLAUDE_MULTIACC_CLIENT_ID` (used by the sandboxed tests; defaults are correct for real use).
 
 **Auto-retry** (`-p`/`--print` only, default on, `CLAUDE_SHIM_RETRY=0` disables): on an
 auth/rate-limit-looking failure the shim marks the account with a 10-minute error

package/bin/claude-accounts

@@ -40,13 +40,18 @@ USAGE
                                             default ~/.claude login (dir symlink —
                                             single credential file, no grant fork)
   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 (Mac only)
   claude-accounts verify [--quick]          auth matrix; full mode runs `-p "reply OK"` per account
   claude-accounts limits [--quiet] [--force]
-      refresh usage buckets, apply >=90% markers. Skips accounts fetched in the
-      last 45s and honors 429 backoff; --force ignores both.
+      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.
+      Skips accounts fetched in the last 45s and honors 429/refresh backoff;
+      --force ignores all three.
   claude-accounts health                    limits + full verify; logs to health.log
   claude-accounts self-update               update the addon (npm i -g @latest, or git
                                             pull + reinstall); logs to update.log
@@ -149,6 +154,14 @@ for a in accounts:
         auth.append('token')
     limited = os.path.isfile(os.path.join(d, '.limited'))
     print(f"{a['id']}  {a['email']:<28} home={a.get('home','?'):<7} auth={'+'.join(auth) or 'NONE':<11} {'LIMITED' if limited else ''}")
+seen = {}
+for a in accounts:
+    seen.setdefault(a.get('email', '').lower(), []).append(a['id'])
+dups = {e: ids for e, ids in seen.items() if len(ids) > 1}
+if dups:
+    print()
+    for e, ids in dups.items():
+        print(f"WARNING: {e} is registered {len(ids)}x ({', '.join(ids)}) — run 'claude-accounts dedupe'")
 PYEOF
 }
 
@@ -249,89 +262,94 @@ cmd_add() {
         else die "unexpected argument: $1 (usage: claude-accounts add [email] [--token] [--force])"; fi ;;
     esac
   done
-  # If an email was named, fast-fail on a duplicate now. If not, we learn (and dedup)
-  # the real email from the sign-in below — one account per email either way.
+  # If an email was named and it's already in the pool, SKIP before any sign-in — no
+  # duplicate is ever created. (A graceful skip, exit 0: adding an existing account is
+  # a no-op, not an error. Re-auth an existing account with 'login'.)
   local owner
   if [ -n "$email" ]; then
     owner="$(email_owner "$email")"
-    [ -n "$owner" ] && die "$email is already registered as $owner — nothing created (run 'claude-accounts login $owner' to re-authenticate it)"
+    if [ -n "$owner" ]; then
+      echo "$email is already added as $owner — skipping (nothing to do; run 'claude-accounts login $owner' to re-authenticate it)."
+      return 0
+    fi
   fi
   if [ ! -t 0 ] && [ -z "${CLAUDE_MULTIACC_FORCE_TTY:-}" ]; then
     die "add is interactive (it completes sign-in before registering) — run it from a terminal"
   fi
-  # Serialize the whole check->allocate->authenticate->register sequence: two concurrent
-  # adds must not race the duplicate check, collide on an id, or clobber the manifest.
-  local lock="$ACC_ROOT/.locks/mutate"
-  mkdir -p "$ACC_ROOT/.locks"
-  if ! mkdir "$lock" 2>/dev/null; then
-    if [ $(( $(epoch_now) - $(file_mtime "$lock") )) -gt 900 ]; then
-      rm -rf "$lock"; mkdir "$lock" 2>/dev/null || die "cannot acquire the account lock"
-    else
-      die "another claude-accounts add/login is in progress — try again when it finishes"
-    fi
-  fi
-  # shellcheck disable=SC2064
-  trap "rm -rf '$lock'" EXIT
   local real
   real="$(find_real_claude "$_self")" || die "real claude binary not found"
+
+  # Reserve a unique id under a BRIEF lock (creating the dir claims the id, so a parallel
+  # add gets the next one). The long browser sign-in below runs WITHOUT the lock, so
+  # several `add` in different terminals proceed in parallel. RESERVED_DIR drives a trap
+  # that removes the half-made dir on any failure/abort BEFORE registration.
   local id d got elabel
   elabel="${email:-the account you sign in as}"
+  RESERVED_DIR=""
+  trap 'add_cleanup_reserved; exit 130' INT TERM
+  trap 'add_cleanup_reserved' EXIT
+  mutate_lock || die "could not acquire the account lock (another op is stuck?) — try again"
   id="$(next_id)"
   d="$ACC_ROOT/$id"
   seed_account_dir "$d"
+  RESERVED_DIR="$d"
+  mutate_unlock
+
   if [ "$token" = "1" ]; then
     # Portable setup-token variant (works on Mac AND server; needs a recent sign-in).
     echo "Preparing $id for $elabel (portable token) — NOTHING is registered until sign-in completes."
-    if ! run_token_ceremony "$d"; then
-      rm -rf "${ACC_ROOT:?}/${id:?}"
-      die "sign-in failed or aborted — nothing was created"
-    fi
+    run_token_ceremony "$d" || die "sign-in failed or aborted — nothing was created"
     ( umask 077; printf '%s' "$CEREMONY_TOKEN" > "$d/server.token" )
     chmod 600 "$d/server.token"
     got="$(token_email "$CEREMONY_TOKEN")"
   else
-    # Default: full Claude Code login (the flow that just works — full scopes, no
-    # long-lived-token step-up). Writes auto-refreshing .credentials.json, valid on
-    # THIS machine (creds are never synced, so no cross-machine refresh races).
+    # Default: full Claude Code login (full scopes, no long-lived-token step-up).
+    # Writes auto-refreshing .credentials.json, valid on THIS machine.
     echo "Preparing $id for $elabel — NOTHING is registered until login completes."
-    if ! run_login_ceremony "$d" "$email"; then
-      rm -rf "${ACC_ROOT:?}/${id:?}"
-      die "login failed or aborted — nothing was created"
-    fi
+    run_login_ceremony "$d" "$email" || die "login failed or aborted — nothing was created"
     got="$(config_dir_email "$d")"
   fi
   if [ -z "$got" ]; then
-    # Signed in, but we could not read back WHICH account. Without a verified email we
-    # cannot label or dedup the account, so refuse — unless an email was named AND
-    # --force was given (then we trust the named email).
     if [ -n "$email" ] && [ "$force" = "1" ]; then
       warn "identity unverified — registering as $email because --force was given"
       got="$email"
     else
-      rm -rf "${ACC_ROOT:?}/${id:?}"
       die "signed in, but the account identity could not be read back — nothing was created (retry; or 'add <email> --force' to trust a named email)"
     fi
   fi
-  # `got` is now the authoritative signed-in email. Dedup against it, warn on mismatch.
+  # Dedup + register under a BRIEF lock, re-reading the manifest (a parallel add may have
+  # registered the same email meanwhile — the loser skips gracefully). This is the
+  # guarantee that a code pasted for an already-added account never yields a second entry.
+  mutate_lock || die "could not acquire the account lock — try again"
   owner="$(email_owner "$got")"
   if [ -n "$owner" ]; then
-    rm -rf "${ACC_ROOT:?}/${id:?}"
-    die "you signed in as $got, which is already registered as $owner — nothing was created"
+    mutate_unlock
+    echo "$got is already added as $owner — skipping (nothing added)."
+    return 0   # RESERVED_DIR still set -> trap removes the temp dir
   fi
   if [ -n "$email" ] && [ "$got" != "$email" ]; then
     warn "signed in as $got (you named $email) — registering the account that actually authenticated"
   fi
-  email="$got"
-  manifest_add_account "$id" "$email" "$(machine_kind)"
-  log_to ops.log "add $id $email (auth-verified)"
+  manifest_add_account "$id" "$got" "$(machine_kind)"
+  mutate_unlock
+  RESERVED_DIR=""            # committed — the trap must not delete it now
+  trap - EXIT INT TERM
+  log_to ops.log "add $id $got (auth-verified)"
   auto_sync
   cat <<EOF
-Registered $id for $email (sign-in verified) — usable immediately.
+Registered $id for $got (sign-in verified) — usable immediately.
 Optional:
   claude-accounts verify       # confirm the 100% matrix
 EOF
 }
 
+add_cleanup_reserved() {
+  # EXIT trap for cmd_add: remove a reserved-but-uncommitted account dir (and, in case
+  # we died mid-critical-section, release the lock).
+  [ -n "${RESERVED_DIR:-}" ] && rm -rf "$RESERVED_DIR" 2>/dev/null
+  mutate_unlock 2>/dev/null || true
+}
+
 cmd_import() {
   require_manifest
   local email="${1:-}"
@@ -393,6 +411,70 @@ cmd_import() {
   [ "$no_sync" = "1" ] || auto_sync
 }
 
+# Prints duplicate account ids to REMOVE, one per line: for every email that appears
+# more than once, keep exactly one (prefer an account that has auth on this machine,
+# then the lowest id) and list the rest. Empty output => pool is already clean.
+dup_ids_to_remove() {
+  [ -f "$MANIFEST" ] || return 0
+  "$PYBIN" - "$MANIFEST" "$ACC_ROOT" <<'PYEOF' 2>/dev/null
+import json, os, re, sys
+manifest, root = sys.argv[1], sys.argv[2]
+accts = [a for a in json.load(open(manifest)).get('accounts', [])
+         if isinstance(a, dict) and re.fullmatch(r'acct-\d{2}', str(a.get('id', '')))]
+def has_auth(aid):
+    d = os.path.join(root, aid)
+    c = os.path.join(d, '.credentials.json')
+    t = os.path.join(d, 'server.token')
+    return (os.path.isfile(c) and os.path.getsize(c) > 0) or (os.path.isfile(t) and os.path.getsize(t) > 0)
+by_email = {}
+for a in accts:
+    by_email.setdefault(a.get('email', '').lower(), []).append(a['id'])
+for email, ids in by_email.items():
+    if len(ids) < 2:
+        continue
+    # keep: authed first, then lowest id
+    keep = sorted(ids, key=lambda i: (not has_auth(i), i))[0]
+    for i in ids:
+        if i != keep:
+            print(i)
+PYEOF
+}
+
+cmd_dedupe() {
+  require_manifest
+  local yes=0
+  [ "${1:-}" = "--yes" ] && yes=1
+  local dups
+  dups="$(dup_ids_to_remove)"
+  if [ -z "$dups" ]; then
+    echo "No duplicate accounts — every email appears once."
+    return 0
+  fi
+  echo "Duplicate accounts (same email registered more than once):"
+  local id email
+  for id in $dups; do
+    email="$("$PYBIN" - "$MANIFEST" "$id" <<'PYEOF'
+import json, sys
+for a in json.load(open(sys.argv[1])).get('accounts', []):
+    if a.get('id') == sys.argv[2]: print(a.get('email', '')); break
+PYEOF
+)"
+    echo "  will remove $id ($email)"
+  done
+  if [ "$yes" != "1" ]; then
+    printf 'Remove these duplicates (keeps one per email)? [y/N] '
+    read -r ans
+    case "$ans" in y|Y|yes) ;; *) echo "aborted"; return 1 ;; esac
+  fi
+  for id in $dups; do
+    if [ -L "$ACC_ROOT/$id" ]; then rm -f "${ACC_ROOT:?}/${id:?}"; else rm -rf "${ACC_ROOT:?}/${id:?}"; fi
+    manifest_del_account "$id"
+    log_to ops.log "dedupe removed $id"
+  done
+  echo "Removed $(printf '%s\n' "$dups" | grep -c .) duplicate account(s)."
+  auto_sync
+}
+
 cmd_adopt() {
   # Make <acct-NN> THIS machine's existing default login (~/.claude) without
   # forking its OAuth grant: the account dir becomes a symlink to ~/.claude, so
@@ -661,24 +743,9 @@ cmd_limits() {
   # shellcheck disable=SC2064
   trap "rm -rf '$lock'" EXIT
   rotate_log limits.log
-  # Expired-bearer self-heal: on a quiet machine nothing refreshes OAuth creds,
-  # which would silently stall limits telemetry (fail-open keeps selection working,
-  # but data goes stale). `claude auth status` refreshes creds without inference.
-  local real="" d
-  real="$(find_real_claude "$_self" 2>/dev/null)" || real=""
-  if [ -n "$real" ]; then
-    for d in "$ACC_ROOT"/acct-*; do
-      [ -d "$d" ] || continue
-      [ -f "$d/.credentials.json" ] || continue
-      [ -s "$d/server.token" ] && continue
-      if "$PYBIN" -c '
-import json, sys, time
-c = json.load(open(sys.argv[1])).get("claudeAiOauth", {})
-sys.exit(0 if c.get("expiresAt", 0) / 1000.0 <= time.time() + 60 else 1)' "$d/.credentials.json" 2>/dev/null; then
-        CLAUDE_CONFIG_DIR="$d" CLAUDE_SHIM_ACTIVE=1 "$real" auth status >/dev/null 2>&1 || true
-      fi
-    done
-  fi
+  # 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
+  # refresh credentials — it only reports the on-disk state.)
   # The >=90% exclusion rule is a hard requirement: the manifest may tighten it but
   # never loosen it, or an account could sit at 95% and still be selected.
   local threshold
@@ -694,6 +761,21 @@ 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'))
 
+# 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
+# access-token TTL would otherwise drop out of telemetry forever (stale data ranks
+# neutral, so truly-idle accounts lose selection to busy-but-fresh ones).
+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
+
 def say(msg):
     if not quiet:
         print(msg)
@@ -714,34 +796,108 @@ try:
 except Exception as e:
     sys.exit(f'cannot read manifest: {e}')
 
+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
+    None (fail open: the on-disk 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 = json.load(open(cpath))
+        o = doc.get('claudeAiOauth', {})
+        # Present-but-null/non-object claudeAiOauth (interrupted or reset credential
+        # write) must degrade THIS account only, like every other malformed input.
+        if not isinstance(doc, dict) or not isinstance(o, dict):
+            return None
+    except Exception:
+        return None
+    if not o.get('refreshToken') or not o.get('accessToken'):
+        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:
+        say(f'{aid}: refresh token expired — re-login needed (claude-accounts login {aid})')
+        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):
+        try:
+            with open(spath + '.tmp', 'w') as f:
+                json.dump({'retry_after': int(now + wait), 'error': why,
+                           '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')
+
+    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):
+            back_off(REFRESH_DENIED_BACKOFF,
+                     f'HTTP {e.code} — refresh token may be revoked; re-login needed')
+        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)
+    doc['claudeAiOauth'] = o
+    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)
+        os.replace(cpath + '.tmp', cpath)
+    except Exception as e:
+        say(f'{aid}: token refreshed but credentials NOT persisted ({e}) — re-login may be needed')
+        return None
+    try:
+        os.remove(spath)
+    except OSError:
+        pass
+    say(f'{aid}: oauth access token refreshed via refresh-token grant')
+    return tok
+
 for acct in manifest.get('accounts', []):
     aid = acct['id']
     d = os.path.join(root, aid)
     if not os.path.isdir(d):
         continue
-    bearer = None
-    source = None
-    cpath = os.path.join(d, '.credentials.json')
-    if os.path.isfile(cpath):
-        try:
-            c = json.load(open(cpath)).get('claudeAiOauth', {})
-            if c.get('accessToken') and c.get('expiresAt', 0) / 1000.0 > now + 60:
-                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:
-        # 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')
-        continue
 
     # The usage endpoint rate-limits per account. Several callers can fire at once
     # (60s cron + the shim's opportunistic kick + a manual run), so skip a fetch when
     # this account's data is already fresh, and honor any backoff a 429 set earlier.
+    # Checked FIRST so a skipped account never burns an oauth refresh for nothing.
     lpath = os.path.join(d, 'limits.json')
     prev = {}
     if os.path.isfile(lpath):
@@ -758,6 +914,36 @@ for acct in manifest.get('accounts', []):
             say(f'{aid}: backing off after 429 ({int(retry_at - now)}s left); limits left as-is')
             continue
 
+    bearer = None
+    source = None
+    cpath = os.path.join(d, '.credentials.json')
+    if os.path.isfile(cpath):
+        try:
+            c = json.load(open(cpath)).get('claudeAiOauth', {})
+            if c.get('accessToken') and c.get('expiresAt', 0) / 1000.0 > now + 60:
+                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.
+        try:
+            tok = refresh_oauth(aid, d, cpath)
+        except Exception as e:
+            say(f'{aid}: oauth refresh failed unexpectedly ({str(e)[:200]}); failing open')
+            tok = None
+        if tok:
+            bearer, source = tok, 'oauth'
+    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')
+        continue
+
     req = urllib.request.Request(url, headers={
         'Authorization': 'Bearer ' + bearer,
         'anthropic-beta': 'oauth-2025-04-20',
@@ -1165,6 +1351,7 @@ case "${1:-help}" in
   add) shift; cmd_add "$@" ;;
   import) shift; cmd_import "$@" ;;
   adopt) shift; cmd_adopt "$@" ;;
+  dedupe) shift; cmd_dedupe "$@" ;;
   remove) shift; cmd_remove "$@" ;;
   mint) shift; cmd_mint "$@" ;;
   login) shift; cmd_login "$@" ;;

package/lib/common.sh

@@ -188,6 +188,34 @@ PYEOF
   fi
 }
 
+# Short-lived mutation lock: serialize only the brief critical sections (id reservation,
+# manifest write), NOT long interactive work like a browser sign-in — so several
+# `add`/`login` in different terminals run in parallel and only briefly wait on each other.
+# Held for milliseconds; a lock older than 30s is assumed abandoned (holder died) and reclaimed.
+MUTATE_LOCK_HELD=0
+mutate_lock() {
+  local lock="$ACC_ROOT/.locks/mutate" tries=0
+  mkdir -p "$ACC_ROOT/.locks" 2>/dev/null
+  while ! mkdir "$lock" 2>/dev/null; do
+    if [ $(( $(epoch_now) - $(file_mtime "$lock") )) -gt 30 ]; then
+      rm -rf "$lock" 2>/dev/null
+      continue
+    fi
+    tries=$((tries + 1))
+    [ "$tries" -gt 600 ] && return 1   # ~60s ceiling; contention should clear in ms
+    sleep 0.1
+  done
+  MUTATE_LOCK_HELD=1
+  return 0
+}
+# Only removes the lock dir when THIS process holds it — so a normal release, or a
+# cleanup trap firing after release, can never delete a lock a parallel process just took.
+mutate_unlock() {
+  [ "${MUTATE_LOCK_HELD:-0}" = 1 ] || return 0
+  rm -rf "$ACC_ROOT/.locks/mutate" 2>/dev/null
+  MUTATE_LOCK_HELD=0
+}
+
 rotate_log() { # keep logs bounded: rotate_log <file-in-acc-root> (keeps last ~256KB)
   local f="$ACC_ROOT/$1"
   [ -f "$f" ] || return 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-multiacc",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Multi-account addon for Claude Code: every claude / claude -p runs under a randomly-picked subscription account with the most usage headroom. Mirrors to a deploy server. No API keys.",
   "type": "module",
   "bin": {

package/tests/run-tests.sh

@@ -75,6 +75,9 @@ export CLAUDE_MULTIACC_NO_SYNC=1
 # Fixtures are local file:// URLs with no rate limit, so the anti-429 fetch throttle
 # is off by default here; the throttle test re-enables it explicitly.
 export CLAUDE_MULTIACC_MIN_FETCH=0
+# The oauth token endpoint must NEVER be hit for real from tests: default to a missing
+# file:// fixture (refresh fails fast, offline); the refresh tests override per-case.
+export CLAUDE_MULTIACC_TOKEN_URL="file://$WORK/token-endpoint-missing.json"
 
 now="$(date +%s)"
 
@@ -353,11 +356,13 @@ check "remove account" "Removed acct-04" "$out"
 [ ! -d "$ACC/acct-04" ] && t_ok "remove deleted dir" || t_fail "remove deleted dir" "dir still there"
 
 # ---- 15b. duplicate-email guards ------------------------------------------------
+# add of a named, already-present email => graceful SKIP before any sign-in (exit 0)
 out="$(claude-accounts add a@test 2>&1)"
 rc=$?
-check "add refuses duplicate email" "already registered as acct-01" "$out"
-[ "$rc" != "0" ] && t_ok "duplicate add exits nonzero" || t_fail "duplicate add rc" "rc=0"
+check "add skips a duplicate email with a message" "already added as acct-01 — skipping" "$out"
+[ "$rc" = "0" ] && t_ok "duplicate add exits 0 (graceful skip)" || t_fail "duplicate add rc" "rc=$rc"
 [ ! -d "$ACC/acct-04" ] && t_ok "duplicate add created nothing" || t_fail "duplicate add" "dir created"
+# import stays strict (it's the lower-level command): refuses a duplicate
 out="$(claude-accounts import a@test --id acct-09 --no-sync 2>&1)"
 rc=$?
 check "import refuses duplicate email" "already registered as acct-01" "$out"
@@ -391,8 +396,8 @@ claude-accounts remove acct-04 --yes >/dev/null 2>&1
 # add with no email, but the signed-in email is already registered => refuse + clean up
 out="$(CLAUDE_MULTIACC_FORCE_TTY=1 FAKE_EMAIL=a@test claude-accounts add 2>&1)"
 rc=$?
-check "email-less add refuses a duplicate signed-in email" "already registered as acct-01" "$out"
-[ "$rc" != "0" ] && t_ok "email-less duplicate exits nonzero" || t_fail "email-less dup rc" "rc=0"
+check "email-less add skips a duplicate signed-in email" "a@test is already added as acct-01 — skipping" "$out"
+[ "$rc" = "0" ] && t_ok "email-less duplicate skip exits 0" || t_fail "email-less dup rc" "rc=$rc"
 [ ! -d "$ACC/acct-04" ] && t_ok "email-less duplicate cleaned up" || t_fail "email-less dup cleanup" "dir left"
 # add with no email but identity can't be read back => refuse (can't label the account)
 out="$(CLAUDE_MULTIACC_FORCE_TTY=1 FAKE_AUTH_FAIL=1 claude-accounts add 2>&1)"
@@ -422,7 +427,8 @@ check "aborted --token add detected" "sign-in failed or aborted" "$out"
 # ---- 15e. sign-in as an already-registered email is rejected + cleaned ---------------
 out="$(CLAUDE_MULTIACC_FORCE_TTY=1 FAKE_EMAIL=a@test claude-accounts add brand@test 2>&1)"
 rc=$?
-check "wrong-account sign-in rejected" "already registered as acct-01" "$out"
+check "wrong-account sign-in skips (already added)" "a@test is already added as acct-01 — skipping" "$out"
+[ "$rc" = "0" ] && t_ok "wrong-account skip exits 0" || t_fail "wrong-account rc" "rc=$rc"
 [ ! -d "$ACC/acct-04" ] && t_ok "wrong-account sign-in cleaned up" || t_fail "wrong-account cleanup" "dir left behind"
 
 # ---- 15f. login command completes auth for an existing auth-less account -------------
@@ -440,6 +446,62 @@ check "login --token saves a portable token" "acct-08 token saved" "$out"
 [ -s "$ACC/acct-08/server.token" ] && t_ok "login --token writes server.token" || t_fail "login token" "missing"
 claude-accounts remove acct-08 --yes >/dev/null 2>&1
 
+# ---- 15g. parallel adds (different terminals) get distinct ids, no lock-busy error ----
+( CLAUDE_MULTIACC_FORCE_TTY=1 FAKE_EMAIL=par1@test claude-accounts add >"$WORK/p1.out" 2>&1 ) &
+pA=$!
+( CLAUDE_MULTIACC_FORCE_TTY=1 FAKE_EMAIL=par2@test claude-accounts add >"$WORK/p2.out" 2>&1 ) &
+pB=$!
+wait "$pA"; wait "$pB"
+both="$(cat "$WORK/p1.out" "$WORK/p2.out" 2>/dev/null)"
+printf '%s' "$both" | grep -q "in progress" \
+  && t_fail "parallel add: no lock-busy error" "got the 'another add in progress' error" \
+  || t_ok "parallel add: neither reports 'another add in progress'"
+regA="$(claude-accounts list 2>&1 | grep par1@test | awk '{print $1}')"
+regB="$(claude-accounts list 2>&1 | grep par2@test | awk '{print $1}')"
+{ [ -n "$regA" ] && [ -n "$regB" ] && [ "$regA" != "$regB" ]; } \
+  && t_ok "parallel add: both registered on distinct ids ($regA, $regB)" \
+  || t_fail "parallel add ids" "regA=$regA regB=$regB"
+# and no duplicate/second entry crept in for either email
+{ [ "$(claude-accounts list 2>&1 | grep -c par1@test)" = "1" ] && [ "$(claude-accounts list 2>&1 | grep -c par2@test)" = "1" ]; } \
+  && t_ok "parallel add: exactly one entry per email" || t_fail "parallel add dup" "duplicate created"
+[ -n "$regA" ] && claude-accounts remove "$regA" --yes >/dev/null 2>&1
+[ -n "$regB" ] && claude-accounts remove "$regB" --yes >/dev/null 2>&1
+
+# ---- 15h. two parallel adds signing into the SAME email: exactly one wins ------------
+( CLAUDE_MULTIACC_FORCE_TTY=1 FAKE_EMAIL=same@test claude-accounts add >"$WORK/s1.out" 2>&1 ) &
+sA=$!
+( CLAUDE_MULTIACC_FORCE_TTY=1 FAKE_EMAIL=same@test claude-accounts add >"$WORK/s2.out" 2>&1 ) &
+sB=$!
+wait "$sA"; wait "$sB"
+n="$(claude-accounts list 2>&1 | grep -c same@test)"
+[ "$n" = "1" ] && t_ok "same-email parallel add: exactly one registered (other skipped)" \
+  || t_fail "same-email parallel add" "count=$n (expected 1)"
+cat "$WORK/s1.out" "$WORK/s2.out" 2>/dev/null | grep -q "already added as\|skipping" \
+  && t_ok "same-email parallel add: loser skipped gracefully" || t_fail "same-email skip msg" "no skip message"
+regS="$(claude-accounts list 2>&1 | grep same@test | awk '{print $1}')"
+[ -n "$regS" ] && claude-accounts remove "$regS" --yes >/dev/null 2>&1
+
+# ---- 15i. dedupe removes accounts registered twice (keeps one per email) --------------
+out="$(claude-accounts dedupe 2>&1)"
+check "dedupe on a clean pool is a no-op" "No duplicate accounts" "$out"
+# manufacture a duplicate directly in the manifest (a pre-fix leftover) + a dir for it
+claude-accounts import twin@test --id acct-06 --creds "$WORK/import-creds.json" --mode copy --no-sync >/dev/null 2>&1
+python3 - "$ACC/accounts.json" <<'EOF'
+import json, os, sys
+d = json.load(open(sys.argv[1]))
+d['accounts'].append({'id': 'acct-07', 'email': 'twin@test', 'home': 'mac'})
+json.dump(d, open(sys.argv[1] + '.tmp', 'w'), indent=2); os.replace(sys.argv[1] + '.tmp', sys.argv[1])
+EOF
+mkdir -p "$ACC/acct-07"
+out="$(claude-accounts list 2>&1)"
+check "list warns about a duplicate email" "twin@test is registered 2x" "$out"
+out="$(claude-accounts dedupe --yes 2>&1)"
+check "dedupe reports removal" "Removed 1 duplicate" "$out"
+[ "$(claude-accounts list 2>&1 | grep -c twin@test)" = "1" ] && t_ok "dedupe keeps exactly one per email" || t_fail "dedupe count" "not 1"
+# it kept the authed one (acct-06 has creds), removed the bare acct-07
+claude-accounts list 2>&1 | grep -q "acct-06.*twin@test" && t_ok "dedupe kept the authenticated account" || t_fail "dedupe keep-authed" "kept the wrong one"
+claude-accounts remove acct-06 --yes >/dev/null 2>&1
+
 # ---- 16. CLI: limits marking via fixture endpoint ------------------------------
 cat > "$WORK/usage-high.json" <<'EOF'
 {"limits":[
@@ -559,15 +621,107 @@ d = json.load(open('$ACC/acct-01/limits.json'))
 sys.exit(0 if 'retry_after' not in d and 'backoff' not in d else 1)" \
   && t_ok "successful fetch clears backoff state" || t_fail "backoff cleared" "retry_after/backoff persisted"
 
-# ---- 16b. expired-bearer account skipped gracefully (fail open) -----------------
+# ---- 16b. expired-bearer account: oauth refresh attempted; fail-open when it fails ----
 mkdir -p "$ACC/acct-05"
-printf '{"claudeAiOauth":{"accessToken":"sk-ant-oat01-old","refreshToken":"r","expiresAt":1000,"refreshTokenExpiresAt":9999999999999}}' > "$ACC/acct-05/.credentials.json"
+printf '{"claudeAiOauth":{"accessToken":"sk-ant-oat01-old","refreshToken":"sk-ant-ort01-oldrefresh","expiresAt":1000,"refreshTokenExpiresAt":9999999999999}}' > "$ACC/acct-05/.credentials.json"
 claude-accounts import e@test --id acct-05 --no-sync >/dev/null 2>&1
 out="$(CLAUDE_MULTIACC_USAGE_URL="file://$WORK/usage-low.json" claude-accounts limits 2>&1)"
 rc=$?
+check "failed oauth refresh logged with backoff" "acct-05: oauth refresh failed" "$out"
 check "expired bearer logged, not fatal" "acct-05: no fresh bearer" "$out"
 [ "$rc" = "0" ] && t_ok "limits exits 0 with expired-bearer account" || t_fail "limits exit code" "rc=$rc"
 [ ! -f "$ACC/acct-05/limits.json" ] && t_ok "no limits.json fabricated for expired account" || t_fail "expired acct limits.json" "unexpectedly written"
+[ -f "$ACC/acct-05/.oauth-refresh.json" ] && t_ok "refresh failure recorded in .oauth-refresh.json" || t_fail "refresh backoff file" "missing"
+
+# ---- 16b2. refresh backoff honored: even a now-working endpoint is not retried early --
+cat > "$WORK/token-ok.json" <<'EOF'
+{"access_token":"sk-ant-oat01-refreshednew","refresh_token":"sk-ant-ort01-rotatednew","expires_in":28800,"refresh_token_expires_in":2592000}
+EOF
+out="$(CLAUDE_MULTIACC_TOKEN_URL="file://$WORK/token-ok.json" CLAUDE_MULTIACC_USAGE_URL="file://$WORK/usage-low.json" claude-accounts limits 2>&1)"
+check "refresh backoff honored (no early retry)" "acct-05: no fresh bearer" "$out"
+grep -q "sk-ant-oat01-refreshednew" "$ACC/acct-05/.credentials.json" \
+  && t_fail "backoff prevented refresh" "credentials rewritten inside the backoff window" \
+  || t_ok "no refresh inside the backoff window"
+
+# ---- 16b3. --force bypasses refresh backoff: rotated credential persisted + fetch ok --
+out="$(CLAUDE_MULTIACC_TOKEN_URL="file://$WORK/token-ok.json" CLAUDE_MULTIACC_USAGE_URL="file://$WORK/usage-low.json" claude-accounts limits --force 2>&1)"
+check "--force refreshes the expired oauth token" "acct-05: oauth access token refreshed" "$out"
+check "refreshed account fetches telemetry" "acct-05: ok" "$out"
+python3 - "$ACC/acct-05/.credentials.json" <<'EOF'
+import json, os, stat, sys, time
+p = sys.argv[1]
+o = json.load(open(p))['claudeAiOauth']
+assert o['accessToken'] == 'sk-ant-oat01-refreshednew', o['accessToken']
+assert o['refreshToken'] == 'sk-ant-ort01-rotatednew', 'refresh token was not rotated'
+assert o['expiresAt'] / 1000.0 > time.time() + 3600, 'expiresAt not advanced'
+assert o['refreshTokenExpiresAt'] / 1000.0 > time.time() + 86400, 'refreshTokenExpiresAt not advanced'
+mode = stat.S_IMODE(os.stat(p).st_mode)
+assert mode == 0o600, oct(mode)
+EOF
+[ $? -eq 0 ] && t_ok "rotated credential persisted with 0600" || t_fail "credential rotation" "see assertions above"
+[ ! -f "$ACC/acct-05/.oauth-refresh.json" ] && t_ok "successful refresh clears the backoff file" || t_fail "refresh backoff clear" "file still present"
+[ -f "$ACC/acct-05/limits.json" ] && t_ok "telemetry written right after refresh" || t_fail "limits.json after refresh" "missing"
+grep -qE "sk-ant-ort01|sk-ant-oat01-refreshednew" "$ACC/limits.log" \
+  && t_fail "limits.log leaks no tokens" "a token leaked into limits.log" \
+  || t_ok "limits.log leaks no tokens"
+
+# ---- 16b4. steady state: fresh data means no refresh and no fetch (quiet skip) --------
+out="$(CLAUDE_MULTIACC_MIN_FETCH=45 CLAUDE_MULTIACC_USAGE_URL="file://$WORK/usage-low.json" claude-accounts limits 2>&1)"
+printf '%s' "$out" | grep -q "acct-05" \
+  && t_fail "fresh account skipped silently" "unexpected acct-05 output: $out" \
+  || t_ok "fresh account skipped silently (no refresh, no fetch)"
+
+# ---- 16b5. an EXPIRED refresh token is never sent: clear re-login message -------------
+printf '{"claudeAiOauth":{"accessToken":"sk-ant-oat01-old","refreshToken":"sk-ant-ort01-dead","expiresAt":1000,"refreshTokenExpiresAt":1000}}' > "$ACC/acct-05/.credentials.json"
+rm -f "$ACC/acct-05/limits.json" "$ACC/acct-05/.oauth-refresh.json"
+out="$(CLAUDE_MULTIACC_TOKEN_URL="file://$WORK/token-ok.json" CLAUDE_MULTIACC_USAGE_URL="file://$WORK/usage-low.json" claude-accounts limits 2>&1)"
+check "expired refresh token => re-login message" "re-login needed" "$out"
+grep -q "sk-ant-oat01-refreshednew" "$ACC/acct-05/.credentials.json" \
+  && t_fail "dead refresh token never used" "credentials rewritten from a dead refresh token" \
+  || t_ok "dead refresh token never used"
+
+# ---- 16b6. RECENTLY-expired token is left alone (a live session owns it) --------------
+# The 5-min REFRESH_MIN_EXPIRED gate is the rotation-safety core: a token that expired
+# moments ago may be mid-refresh by a live claude session; grants must not race it.
+# Not even --force may bypass this.
+recent_ms="$(python3 -c 'import time; print(int((time.time()-100)*1000))')"
+printf '{"claudeAiOauth":{"accessToken":"sk-ant-oat01-recent","refreshToken":"sk-ant-ort01-live","expiresAt":%s,"refreshTokenExpiresAt":9999999999999}}' "$recent_ms" > "$ACC/acct-05/.credentials.json"
+rm -f "$ACC/acct-05/limits.json" "$ACC/acct-05/.oauth-refresh.json"
+out="$(CLAUDE_MULTIACC_TOKEN_URL="file://$WORK/token-ok.json" CLAUDE_MULTIACC_USAGE_URL="file://$WORK/usage-low.json" claude-accounts limits --force 2>&1)"
+check "recently-expired token is not refreshed (even --force)" "acct-05: no fresh bearer" "$out"
+grep -q "sk-ant-oat01-recent" "$ACC/acct-05/.credentials.json" \
+  && t_ok "recently-expired credential left untouched" \
+  || t_fail "REFRESH_MIN_EXPIRED gate" "credential was rewritten within the 5-min grace window"
+[ ! -f "$ACC/acct-05/.oauth-refresh.json" ] && t_ok "no backoff recorded for a gated (skipped) refresh" \
+  || t_fail "gated refresh backoff" ".oauth-refresh.json written despite the gate"
+
+# ---- 16b7. server.token accounts are NEVER oauth-refreshed (token bearer wins) ---------
+printf '{"claudeAiOauth":{"accessToken":"sk-ant-oat01-old","refreshToken":"sk-ant-ort01-x","expiresAt":1000,"refreshTokenExpiresAt":9999999999999}}' > "$ACC/acct-05/.credentials.json"
+printf 'sk-ant-oat01-portable-token-05' > "$ACC/acct-05/server.token"
+rm -f "$ACC/acct-05/limits.json" "$ACC/acct-05/.oauth-refresh.json"
+out="$(CLAUDE_MULTIACC_TOKEN_URL="file://$WORK/token-ok.json" CLAUDE_MULTIACC_USAGE_URL="file://$WORK/usage-low.json" claude-accounts limits --force 2>&1)"
+check "token-bearer account fetches without refresh" "acct-05: ok" "$out"
+grep -q "sk-ant-oat01-refreshednew" "$ACC/acct-05/.credentials.json" \
+  && t_fail "server.token exempts oauth refresh" "oauth creds were rotated despite a portable token" \
+  || t_ok "server.token account never oauth-refreshed (grant not run)"
+python3 -c "import json,sys; sys.exit(0 if json.load(open('$ACC/acct-05/limits.json'))['source']=='token' else 1)" \
+  && t_ok "telemetry fetched via the portable token" || t_fail "token bearer source" "source != token"
+rm -f "$ACC/acct-05/server.token"
+
+# ---- 16b8. malformed claudeAiOauth (null) degrades that account ONLY (fail open) -------
+# {"claudeAiOauth": null} is valid JSON from an interrupted/reset credential write; it
+# must not abort the refresher — accounts AFTER it in the manifest must still be fetched.
+# acct-01 is first in the manifest, so corrupting it exercises the loop guarantee.
+cp "$ACC/acct-01/.credentials.json" "$WORK/acct01-creds.bak"
+printf '{"claudeAiOauth": null}' > "$ACC/acct-01/.credentials.json"
+rm -f "$ACC/acct-01/limits.json" "$ACC/acct-01/.oauth-refresh.json" "$ACC/acct-02/limits.json"
+out="$(CLAUDE_MULTIACC_TOKEN_URL="file://$WORK/token-ok.json" CLAUDE_MULTIACC_USAGE_URL="file://$WORK/usage-low.json" claude-accounts limits --force 2>&1)"
+rc=$?
+[ "$rc" = "0" ] && t_ok "null claudeAiOauth exits 0 (fail open)" || t_fail "null claudeAiOauth rc" "rc=$rc: $out"
+check "null claudeAiOauth degrades only that account" "acct-01: no fresh bearer" "$out"
+[ -f "$ACC/acct-02/limits.json" ] && t_ok "accounts after a malformed one still refresh" \
+  || t_fail "fail-open loop guarantee" "acct-02 was starved by acct-01's malformed creds"
+cp "$WORK/acct01-creds.bak" "$ACC/acct-01/.credentials.json"
 claude-accounts remove acct-05 --yes >/dev/null 2>&1
 
 # ---- 16c. codex-review: security hardening -----------------------------------------