claude-multiacc 1.0.7 → 1.0.8

package/bin/codex-accounts

@@ -0,0 +1,1663 @@
+#!/usr/bin/env bash
+# codex-accounts — manage the codex-multiacc account pool (OpenAI Codex CLI).
+# Subcommands: list status add import adopt dedupe remove login expired relogin
+#              sync verify limits post-sync health self-update
+set -u
+# lib/codex_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).
+export PYTHONDONTWRITEBYTECODE=1
+
+_self="$0"
+while [ -L "$_self" ]; do
+  _t="$(readlink "$_self")"
+  case "$_t" in /*) _self="$_t" ;; *) _self="$(dirname "$_self")/$_t" ;; esac
+done
+BIN_DIR="$(cd "$(dirname "$_self")" && pwd -P)"
+REPO_DIR="$(dirname "$BIN_DIR")"
+# Selects the codex pool (~/.codex-accounts, codex_audit.py, the ChatGPT usage
+# endpoint) in everything lib/common.sh defines. Exported so subshells agree.
+export MULTIACC_PROVIDER=codex
+# shellcheck source=lib/common.sh
+. "$REPO_DIR/lib/common.sh"
+
+usage() {
+  cat <<'EOF'
+codex-accounts — multi-account pool manager for codex-multiacc (OpenAI Codex CLI)
+
+USAGE
+  codex-accounts list                       brief account list
+  codex-accounts status                     full health: auth, per-window limits, markers
+  codex-accounts add [email] [--browser] [--force]
+      login-FIRST: runs the Codex DEVICE-CODE sign-in by default — it prints a URL
+      + one-time code you can open in ANY browser (this machine, your laptop, a
+      phone), so it works identically on a local Mac, over SSH, and on servers.
+      Registers only after the signed-in email is read back. Email is OPTIONAL
+      (derived from the sign-in). Stores an auto-refreshing auth.json valid on
+      THIS machine. Duplicates refused.
+      --browser uses the localhost browser-callback flow instead (only works when
+      the browser runs on THIS machine — the callback goes to localhost:1455).
+  codex-accounts login <acct-NN> [--browser] [--force]
+      complete/refresh auth for an existing account (device-code flow, or --browser)
+  codex-accounts expired [--quiet]
+      which accounts CANNOT authenticate (dead refresh grant, no login on this
+      machine) and why. These are excluded from selection — `codex` never runs
+      under them. Exits 1 when any account needs a human. --quiet prints bare ids.
+  codex-accounts relogin [acct-NN ...] [--all] [--browser] [--yes]
+      sign in again, one account at a time (device-code flow by default). With no
+      arguments it re-authenticates exactly what `expired` lists; --all covers
+      every account. Syncs once at the end.
+  codex-accounts import <email> [opts]      register an account, optionally with auth
+      --id acct-NN          explicit id (default: next free)
+      --home mac|server     which machine owns the login (default: this one)
+      --auth PATH           existing auth.json to adopt
+      --mode copy|move|link how to adopt --auth (default copy)
+      --no-sync             skip the automatic server sync
+  codex-accounts adopt <acct-NN>            make acct-NN THIS machine's existing
+                                            default ~/.codex login (dir symlink —
+                                            single credential file, no grant fork)
+  codex-accounts remove <acct-NN> [--yes]   delete account (propagates to server)
+  codex-accounts dedupe [--yes]             remove any account registered twice
+                                            (same email), keeping one per email
+  codex-accounts sync                       push manifest+seeds to the server (Mac only;
+                                            auth.json is machine-local, NEVER synced)
+  codex-accounts verify [--quick]           auth matrix; full mode runs a real
+                                            `codex exec` per account
+  codex-accounts limits [--quiet] [--force]
+      refresh usage windows from the ChatGPT usage endpoint, apply >=90% markers.
+      Auto-refreshes long-expired access tokens via the OAuth 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.
+  codex-accounts health                     limits + full verify; logs to health.log
+  codex-accounts self-update                update the addon (npm i -g @latest, or git
+                                            pull + reinstall); logs to update.log
+  codex-accounts post-sync                  (server side) seed dirs, fix perms, quick verify
+
+ENV
+  CODEX_ACCOUNTS_DIR    override ~/.codex-accounts
+  CODEX_ACCOUNT         pin the shim to one account
+  CODEX_SHIM_RETRY=0    disable the `codex exec` auto-retry
+  CODEX_MULTIACC_DISABLE=1  bypass the shim entirely
+EOF
+}
+
+require_manifest() { [ -f "$MANIFEST" ] || die "no manifest at $MANIFEST — run install.sh first"; }
+
+next_id() {
+  local n=1 id
+  while :; do
+    id="$(printf 'acct-%02d' "$n")"
+    if [ ! -d "$ACC_ROOT/$id" ] && ! account_ids | grep -qx "$id"; then
+      printf '%s\n' "$id"
+      return 0
+    fi
+    n=$((n+1))
+    [ "$n" -gt 99 ] && die "no free account slot"
+  done
+}
+
+manifest_add_account() { # id email home
+  "$PYBIN" - "$MANIFEST" "$1" "$2" "$3" <<'PYEOF'
+import json, sys, time
+path, aid, email, home = sys.argv[1:5]
+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()),
+})
+accounts.sort(key=lambda a: a['id'])
+doc['accounts'] = accounts
+import os
+with open(path + '.tmp', 'w') as f:
+    json.dump(doc, f, indent=2)
+    f.write('\n')
+os.replace(path + '.tmp', path)
+PYEOF
+}
+
+email_owner() { # prints the id that owns <email>, empty if unregistered
+  [ -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 a.get('email', '').lower() == sys.argv[2].lower():
+        print(a['id'])
+        break
+PYEOF
+}
+
+manifest_del_account() { # id
+  "$PYBIN" - "$MANIFEST" "$1" <<'PYEOF'
+import json, sys
+path, aid = sys.argv[1:3]
+doc = json.load(open(path))
+doc['accounts'] = [a for a in doc.get('accounts', []) if a['id'] != aid]
+import os
+with open(path + '.tmp', 'w') as f:
+    json.dump(doc, f, indent=2)
+    f.write('\n')
+os.replace(path + '.tmp', path)
+PYEOF
+}
+
+auto_sync() { # best effort after mutations, Mac only, loud on failure
+  [ "$(machine_kind)" = "mac" ] || return 0
+  [ "${CODEX_MULTIACC_NO_SYNC:-0}" = "1" ] && return 0
+  # subshell: cmd_sync exits on failure and must not take the CLI down with it
+  ( cmd_sync ) || warn "server sync failed — run 'codex-accounts sync' manually"
+}
+
+cmd_list() {
+  require_manifest
+  "$PYBIN" - "$MANIFEST" "$ACC_ROOT" "$LIB_DIR" "$(machine_kind)" <<'PYEOF'
+import json, os, re, sys
+doc = json.load(open(sys.argv[1]))
+root = sys.argv[2]
+sys.path = [sys.argv[3]] + [p for p in sys.path if p not in ('', '.')]
+from codex_audit import audit_account   # noqa: E402  (shared with the shim's rule)
+machine = sys.argv[4]
+# Only render well-formed ids — a hand-edited manifest must not surface a traversal id.
+accounts = [a for a in doc.get('accounts', [])
+            if isinstance(a, dict) and re.fullmatch(r'acct-\d{2}', str(a.get('id', '')))]
+if not accounts:
+    print('(no accounts yet)')
+for a in accounts:
+    d = os.path.join(root, a['id'])
+    apath = os.path.join(d, 'auth.json')
+    auth = 'chatgpt' if (os.path.isfile(apath) and os.path.getsize(apath) > 0) else 'NONE'
+    limited = os.path.isfile(os.path.join(d, '.limited'))
+    st = audit_account(root, a, machine=machine)
+    flags = []
+    if st['state'] == 'expired':
+        flags.append('EXPIRED-LOGIN')
+    elif st['state'] == 'blocked':
+        flags.append('ORG-BLOCKED')
+    elif st['state'] == 'missing':
+        flags.append('NO-LOGIN')
+    if limited:
+        flags.append('LIMITED')
+    print(f"{a['id']}  {a['email']:<28} home={a.get('home','?'):<7} "
+          f"auth={auth:<11} {' '.join(flags)}")
+bad = [a for a in accounts
+       if audit_account(root, a, machine=machine)['state']
+       in ('expired', 'blocked', 'missing')]
+if bad:
+    print()
+    print(f"{len(bad)} account(s) are NOT usable — details: codex-accounts expired")
+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 'codex-accounts dedupe'")
+PYEOF
+}
+
+cmd_status() {
+  require_manifest
+  "$PYBIN" - "$MANIFEST" "$ACC_ROOT" "$LIB_DIR" "$(machine_kind)" <<'PYEOF'
+import json, os, sys, time
+doc = json.load(open(sys.argv[1]))
+root = sys.argv[2]
+sys.path = [sys.argv[3]] + [p for p in sys.path if p not in ('', '.')]
+from codex_audit import audit_account, jwt_claims   # noqa: E402
+machine = sys.argv[4]
+now = time.time()
+
+def last_pick(aid):
+    path = os.path.join(root, 'selection.log')
+    if not os.path.isfile(path):
+        return '-'
+    last = '-'
+    try:
+        with open(path, errors='replace') as f:
+            for line in f:
+                parts = line.split()
+                if len(parts) >= 2 and parts[1] == aid:
+                    last = parts[0]
+    except Exception:
+        pass
+    return last
+
+print(f"pool root : {root}")
+print(f"server    : {doc.get('server','-')}  (root: {doc.get('server_root','-')})")
+print(f"threshold : {doc.get('threshold', 90)}% (any window at/above => account excluded)")
+print()
+needs_login = []
+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)
+    banner = {'ok': '', 'remote': '  [not logged in here — login lives elsewhere]',
+              'missing': '  ** NO LOGIN — codex-accounts relogin %s **' % aid,
+              'expired': '  ** LOGIN EXPIRED — codex-accounts relogin %s **' % aid,
+              'blocked': '  ** ORG BLOCKED — Codex disabled for this account by an admin **',
+              }[st['state']]
+    print(f"{aid}  {a['email']}  [home={a.get('home','?')}]{banner}")
+    print(f"  selectable  : {'yes' if st['state'] == 'ok' else 'NO — ' + st['reason']}")
+    cpath = os.path.join(d, 'auth.json')
+    if os.path.isfile(cpath):
+        try:
+            c = json.load(open(cpath))
+            tokens = c.get('tokens') or {}
+            claims = jwt_claims(tokens.get('access_token'))
+            exp = float(claims.get('exp') or 0)
+            plan = ((jwt_claims(tokens.get('id_token'))
+                     .get('https://api.openai.com/auth') or {})
+                    .get('chatgpt_plan_type') or '?')
+            state = 'fresh' if exp > now else 'stale (auto-refreshes on use)'
+            rstate = 'present' if tokens.get('refresh_token') else 'MISSING — re-login needed'
+            when = time.strftime('%Y-%m-%d', time.gmtime(exp)) if exp else '?'
+            print(f"  chatgpt auth: {state} (access token until {when}); "
+                  f"refresh token {rstate}; plan {plan}")
+        except Exception as e:
+            print(f"  chatgpt auth: unreadable ({e})")
+    else:
+        print("  chatgpt auth: none on this machine")
+    lpath = os.path.join(d, 'limits.json')
+    if os.path.isfile(lpath):
+        try:
+            lim = json.load(open(lpath))
+            age = int(now - lim.get('fetched_at', 0))
+            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')}%]")
+        except Exception as e:
+            print(f"  limits      : unreadable ({e})")
+    else:
+        print("  limits      : never fetched")
+    mpath = os.path.join(d, '.limited')
+    if os.path.isfile(mpath):
+        try:
+            lines = open(mpath).read().splitlines()
+            reset = int(lines[0]) if lines and lines[0].isdigit() else 0
+            detail = lines[1] if len(lines) > 1 else ''
+            mins = max(0, int((reset - now) / 60))
+            print(f"  marker      : LIMITED ({detail}) — clears in ~{mins}m")
+        except Exception:
+            print("  marker      : LIMITED (unreadable marker)")
+    else:
+        print("  marker      : none (eligible)")
+    print(f"  last picked : {last_pick(aid)}")
+    print()
+if needs_login:
+    print(f"{len(needs_login)} account(s) are EXCLUDED from selection: {', '.join(needs_login)}")
+    print("What each one needs: codex-accounts expired")
+PYEOF
+}
+
+# The signed-in identity of a codex config dir, read OFFLINE from the id_token in
+# auth.json (no network, no real binary needed). Prints '' when unknown.
+codex_dir_email() { # $1 = config dir
+  "$PYBIN" - "$LIB_DIR" "$1/auth.json" <<'PYEOF' 2>/dev/null || echo ""
+import sys
+sys.path = [sys.argv[1]] + [p for p in sys.path if p not in ('', '.')]
+from codex_audit import auth_email   # noqa: E402
+print(auth_email(sys.argv[2]))
+PYEOF
+}
+
+# Interactive sign-in ceremony with CODEX_HOME pointed at the account dir, so the
+# resulting auth.json lands exactly there. DEFAULT is the device-code flow
+# (`codex login --device-auth`): it prints a URL + one-time code that can be opened
+# in ANY browser, so it behaves the same on a local Mac, over SSH, and on servers —
+# the browser-callback flow only works when the browser runs on this machine
+# (localhost:1455), which is why it is the opt-in (--browser), not the default.
+# Success is a credential that can AUTHENTICATE (codex_audit's rule), not merely a
+# file that exists.
+run_codex_login_ceremony() { # $1 = config dir, $2 = email hint, $3 = mode (device|browser)
+  local d="$1" hint="${2:-}" mode="${3:-device}" real
+  real="$(find_real_codex "$_self")" || { warn "real codex binary not found"; return 1; }
+  if [ "$mode" = "browser" ]; then
+    cat <<'TIP'
+A browser will open (or a sign-in link will be printed) for the Codex ChatGPT
+login. The sign-in must finish in a browser running on THIS machine (the
+callback goes to localhost:1455) — from SSH/remote sessions use the default
+device-code flow instead (drop --browser). Sign in as the account you're
+adding; if the browser is already signed into a different ChatGPT account, use
+"Sign in with a different account" (or a private window). This draws on the
+ChatGPT subscription — no API keys.
+TIP
+  else
+    cat <<'TIP'
+Device sign-in (works from anywhere): a URL and a one-time code will appear
+below. Open the URL in ANY browser — this machine, your laptop, even a phone —
+sign in to the ChatGPT account you're adding (use a private window if that
+browser is already signed into a different ChatGPT account), and enter the code.
+TIP
+  fi
+  [ -n "$hint" ] && printf 'Sign in as: %s\n' "$hint"
+  # Run codex login DIRECTLY on the user's terminal (no PTY wrapper): the credential
+  # is written to <dir>/auth.json, we capture nothing.
+  if [ "$mode" = "browser" ]; then
+    CODEX_HOME="$d" CODEX_SHIM_ACTIVE=1 "$real" login || true
+  else
+    CODEX_HOME="$d" CODEX_SHIM_ACTIVE=1 "$real" login --device-auth || true
+  fi
+  # Re-login targets already have a (dead) auth.json on disk, so a bare existence
+  # test would call an aborted sign-in a success, clear the dead-auth marker, and
+  # hand the account straight back to the pool.
+  [ -s "$d/auth.json" ] || return 1
+  chmod 600 "$d/auth.json" 2>/dev/null || true
+  creds_alive "$d"
+}
+
+cmd_add() {
+  # Login-FIRST: the account is registered (and synced) only after sign-in succeeds
+  # and the authenticated email is read back from the account itself. The email
+  # argument is OPTIONAL — omit it and it's derived from whoever you sign in as.
+  # An aborted or failed sign-in leaves zero traces.
+  require_manifest
+  local email="" force=0 mode="device"
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --force) force=1; shift ;;
+      --browser) mode="browser"; shift ;;  # localhost callback flow (browser on THIS machine)
+      --device) mode="device"; shift ;;    # accepted for compatibility; device is the default
+      --*) die "unknown option: $1" ;;
+      *)
+        if [ -z "$email" ]; then email="$1"; shift
+        else die "unexpected argument: $1 (usage: codex-accounts add [email] [--browser] [--force])"; fi ;;
+    esac
+  done
+  # 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")"
+    if [ -n "$owner" ]; then
+      echo "$email is already added as $owner — skipping (nothing to do; run 'codex-accounts login $owner' to re-authenticate it)."
+      return 0
+    fi
+  fi
+  if [ ! -t 0 ] && [ -z "${CODEX_MULTIACC_FORCE_TTY:-}" ]; then
+    die "add is interactive (it completes sign-in before registering) — run it from a terminal"
+  fi
+  find_real_codex "$_self" >/dev/null || die "real codex 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.
+  # 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
+
+  echo "Preparing $id for $elabel — NOTHING is registered until login completes."
+  run_codex_login_ceremony "$d" "$email" "$mode" || die "login failed or aborted — nothing was created"
+  got="$(codex_dir_email "$d")"
+  if [ -z "$got" ]; then
+    if [ -n "$email" ] && [ "$force" = "1" ]; then
+      warn "identity unverified — registering as $email because --force was given"
+      got="$email"
+    else
+      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
+  # 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 sign-in to 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
+    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
+  manifest_add_account "$id" "$got" "$(machine_kind)"
+  clear_auth_markers "$d"
+  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 $got (sign-in verified) — usable immediately.
+Optional:
+  codex-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:-}"
+  [ -n "$email" ] || die "usage: codex-accounts import <email> [--id acct-NN] [--home mac|server] [--auth PATH] [--mode copy|move|link] [--no-sync]"
+  shift
+  local id="" home="" auth="" mode="copy" no_sync=0 force=0
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --id) id="$2"; shift 2 ;;
+      --home) home="$2"; shift 2 ;;
+      --auth) auth="$2"; shift 2 ;;
+      --mode) mode="$2"; shift 2 ;;
+      --no-sync) no_sync=1; shift ;;
+      --force) force=1; shift ;;
+      *) die "unknown option: $1" ;;
+    esac
+  done
+  [ -n "$home" ] || home="$(machine_kind)"
+  # Validate ALL inputs before creating anything, so a bad auth path leaves no
+  # half-made account dir behind.
+  [ -n "$auth" ] && { [ -f "$auth" ] || die "auth file not found: $auth"; }
+  case "$mode" in copy|move|link) ;; *) die "mode must be copy|move|link" ;; esac
+  # STAGE the auth payload BEFORE taking the lock: the lock's stale-reclaim window
+  # is 30s, so the critical section below must stay milliseconds-fast (renames and
+  # a manifest write) — never a copy of caller-sized data.
+  local stage="" link_target=""
+  if [ -n "$auth" ]; then
+    case "$mode" in
+      link) link_target="$(canon_path "$auth")" ;;
+      *)
+        mkdir -p "$ACC_ROOT/tmp"
+        stage="$ACC_ROOT/tmp/import-auth.$$"
+        case "$mode" in
+          copy) ( umask 077; cp "$auth" "$stage" ) ;;
+          move) mv "$auth" "$stage" ;;
+        esac || { rm -f "$stage" 2>/dev/null; die "could not stage $auth (mode=$mode) — nothing registered"; }
+        ;;
+    esac
+  fi
+  # Id allocation + duplicate check + manifest write run under the mutation lock, so
+  # two parallel imports can never claim the same slot or drop each other's entry.
+  mutate_lock || { rm -f "$stage" 2>/dev/null; die "could not acquire the account lock (another op is stuck?) — try again"; }
+  # shellcheck disable=SC2064
+  trap "mutate_unlock 2>/dev/null || true; rm -f '$stage' 2>/dev/null || true" EXIT
+  fail_locked() { mutate_unlock; rm -f "$stage" 2>/dev/null; die "$@"; }
+  [ -n "$id" ] || id="$(next_id)"
+  case "$id" in acct-[0-9][0-9]) ;; *) fail_locked "id must look like acct-NN" ;; esac
+  local owner
+  owner="$(email_owner "$email")"
+  if [ -n "$owner" ] && [ "$owner" != "$id" ] && [ "$force" != "1" ]; then
+    fail_locked "$email is already registered as $owner — use --id $owner to update it, or --force to register a duplicate"
+  fi
+  local d="$ACC_ROOT/$id"
+  seed_account_dir "$d"
+  if [ -n "$stage" ]; then
+    # A failed adopt must not register an account that claims auth it does not have.
+    mv -f "$stage" "$d/auth.json" \
+      || fail_locked "could not adopt $auth into $d (mode=$mode) — nothing registered"
+    stage=""
+    chmod 600 "$d/auth.json" 2>/dev/null || true
+  elif [ -n "$link_target" ]; then
+    ln -sf "$link_target" "$d/auth.json" \
+      || fail_locked "could not link $auth into $d — nothing registered"
+  fi
+  manifest_add_account "$id" "$email" "$home" \
+    || fail_locked "manifest update failed — $id was seeded but NOT registered (re-run import)"
+  mutate_unlock
+  trap - EXIT
+  log_to ops.log "import $id $email home=$home auth=${auth:+yes} mode=$mode"
+  echo "Imported $id ($email, home=$home)."
+  [ "$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):
+    p = os.path.join(root, aid, 'auth.json')
+    return os.path.isfile(p) and os.path.getsize(p) > 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 (~/.codex) without
+  # forking its OAuth grant: the account dir becomes a symlink to ~/.codex, so
+  # there is exactly one auth.json no matter which path refreshes it.
+  require_manifest
+  local id="${1:-}"
+  [ -n "$id" ] || die "usage: codex-accounts adopt <acct-NN>"
+  valid_acct_id "$id" || die "not a valid account id: $id"
+  account_ids | grep -qx "$id" || die "unknown account: $id (import it first)"
+  local d="$ACC_ROOT/$id" default="$HOME/.codex"
+  [ -s "$default/auth.json" ] || die "no default login at $default to adopt"
+  if [ -L "$d" ]; then
+    echo "$id already adopted ($(readlink "$d"))"
+    return 0
+  fi
+  if [ -d "$d" ]; then
+    [ -s "$d/auth.json" ] && die "$id already has its own credentials — refusing to replace with adopt"
+    rm -rf "${ACC_ROOT:?}/${id:?}"
+  fi
+  ln -s "$default" "$d"
+  log_to ops.log "adopt $id -> $default"
+  echo "$id now runs the default $default login (symlinked, single credential file)."
+}
+
+cmd_remove() {
+  require_manifest
+  local id="${1:-}" yes="${2:-}"
+  [ -n "$id" ] || die "usage: codex-accounts remove <acct-NN> [--yes]"
+  valid_acct_id "$id" || die "not a valid account id: $id"
+  account_ids | grep -qx "$id" || die "unknown account: $id"
+  if [ "$yes" != "--yes" ]; then
+    printf 'Remove %s and propagate deletion to the server? [y/N] ' "$id"
+    read -r ans
+    case "$ans" in y|Y|yes) ;; *) echo "aborted"; return 1 ;; esac
+  fi
+  if [ -L "$ACC_ROOT/$id" ]; then
+    rm -f "${ACC_ROOT:?}/${id:?}"   # adopted account: remove the symlink, never the target
+  else
+    rm -rf "${ACC_ROOT:?}/${id:?}"
+  fi
+  manifest_del_account "$id"
+  log_to ops.log "remove $id"
+  auto_sync
+  echo "Removed $id."
+}
+
+cmd_login() {
+  # Complete (or refresh) auth for an EXISTING account: the device-code flow by
+  # default (works locally and over SSH), or --browser for the localhost callback
+  # flow. Verifies the signed-in email matches the manifest.
+  require_manifest
+  local id="" force=0 mode="device"
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --force) force=1; shift ;;
+      --browser) mode="browser"; shift ;;
+      --device) mode="device"; shift ;;   # accepted for compatibility; device is the default
+      --*) die "unknown option: $1" ;;
+      *) if [ -z "$id" ]; then id="$1"; shift; else die "unexpected argument: $1"; fi ;;
+    esac
+  done
+  [ -n "$id" ] || die "usage: codex-accounts login <acct-NN> [--browser] [--force]"
+  valid_acct_id "$id" || die "not a valid account id: $id"
+  account_ids | grep -qx "$id" || die "unknown account: $id"
+  local d="$ACC_ROOT/$id" email got
+  seed_account_dir "$d"
+  email="$("$PYBIN" - "$MANIFEST" "$id" <<'PYEOF'
+import json, sys
+for a in json.load(open(sys.argv[1])).get('accounts', []):
+    if a['id'] == sys.argv[2]:
+        print(a.get('email', ''))
+        break
+PYEOF
+)"
+  echo "Sign in as $email for $id."
+  # Snapshot the credential BEFORE the ceremony: `codex login` writes auth.json into
+  # the dir directly, so a sign-in to the WRONG account would otherwise leave that
+  # account's credential installed under $id — selectable, and burning the wrong
+  # subscription. On any refused/aborted outcome the prior state is restored exactly;
+  # a snapshot that cannot be taken ABORTS (never risk destroying the only copy).
+  LOGIN_SNAP=""
+  LOGIN_HAD_CRED=0
+  LOGIN_TARGET="$d"
+  if [ -f "$d/auth.json" ]; then
+    LOGIN_HAD_CRED=1
+    LOGIN_SNAP="$ACC_ROOT/tmp/login-snap.$$.json"
+    mkdir -p "$ACC_ROOT/tmp"
+    ( umask 077; cp "$d/auth.json" "$LOGIN_SNAP" 2>/dev/null ) \
+      || die "cannot snapshot the current credential ($d/auth.json) — aborting before any sign-in"
+  fi
+  restore_snap() { # put the pre-ceremony credential state back, exactly
+    if [ "$LOGIN_HAD_CRED" = "1" ]; then
+      [ -f "$LOGIN_SNAP" ] && mv -f "$LOGIN_SNAP" "$LOGIN_TARGET/auth.json" 2>/dev/null
+    else
+      rm -f "$LOGIN_TARGET/auth.json" 2>/dev/null
+    fi
+    rm -f "$LOGIN_SNAP" 2>/dev/null
+  }
+  # The transaction window (ceremony -> identity check) must not leave a wrong
+  # credential behind on Ctrl-C/kill either.
+  trap 'restore_snap; exit 130' INT TERM
+  run_codex_login_ceremony "$d" "$email" "$mode" \
+    || { restore_snap; trap - INT TERM; die "login failed or aborted (no working credential landed) — nothing changed"; }
+  got="$(codex_dir_email "$d")"
+  # Case-insensitive identity match (same rule the duplicate check applies).
+  got_lc="$(printf '%s' "$got" | tr '[:upper:]' '[:lower:]')"
+  email_lc="$(printf '%s' "$email" | tr '[:upper:]' '[:lower:]')"
+  if [ -n "$got" ] && [ "$got_lc" != "$email_lc" ] && [ "$force" != "1" ]; then
+    restore_snap
+    trap - INT TERM
+    die "you signed in as $got but $id is $email — nothing saved, previous credential restored (use --force to override)"
+  fi
+  if [ -z "$got" ] && [ "$force" != "1" ]; then
+    restore_snap
+    trap - INT TERM
+    die "signed in, but the account identity could not be read back — refusing to call $id fixed (retry, or pass --force)"
+  fi
+  trap - INT TERM
+  rm -f "$LOGIN_SNAP" 2>/dev/null
+  clear_auth_markers "$d"
+  echo "$id login saved (auth.json, this machine, auto-refreshing)."
+  log_to ops.log "login $id verified=${got:-unverified} mode=$mode"
+  auto_sync
+}
+
+cmd_expired() {
+  # Which accounts CANNOT authenticate right now — the pool's re-login worklist.
+  # Same rule the shim selects by (lib/codex_audit.py), so what is listed here is
+  # exactly what is excluded from selection.
+  require_manifest
+  local quiet=0
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --quiet|--ids) quiet=1; shift ;;   # ids only, for scripts
+      *) die "unknown option: $1 (usage: codex-accounts expired [--quiet])" ;;
+    esac
+  done
+  local rows bad
+  rows="$(account_audit)" || 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".
+    if [ -z "$(account_ids)" ]; then
+      echo "No accounts registered yet — add one with: codex-accounts add"
+      return 0
+    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 }')"
+  if [ "$quiet" = "1" ]; then
+    [ -n "$bad" ] || return 0
+    printf '%s\n' "$bad"
+    return 1
+  fi
+  printf '%s\n' "$rows" | awk -F'\t' '
+    BEGIN { bad = 0; ok = 0; remote = 0; relogin = 0 }
+    NF < 4 || $1 == "" { next }          # never invent an account from a blank line
+    $4 == "ok"     { ok++; next }
+    $4 == "remote" { remote++; rem = rem sprintf("  %-9s %-28s %s\n", $1, $2, $6); next }
+    {
+      bad++
+      relogin++
+      printf "  %-9s %-28s %-9s %s\n", $1, $2, $5, $6
+      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 (remote > 0) {
+        printf "\nNot logged in here on purpose (another machine owns the login):\n"
+        printf "%s", rem
+      }
+      if (relogin > 0) {
+        printf "\nRe-authenticate them:\n"
+        printf "  codex-accounts relogin             # every account that needs it\n"
+        printf "  codex-accounts relogin acct-NN     # just one\n"
+      }
+    }'
+  # Exit 1 when something needs a human, so cron/health checks can alert on it.
+  [ -z "$bad" ]
+}
+
+cmd_relogin() {
+  # Re-authenticate accounts whose login died. With no arguments it targets exactly
+  # what `expired` lists; ids (or --all) override that. Runs the same verified login
+  # ceremony as `login`, one account at a time, and syncs ONCE at the end.
+  require_manifest
+  local all=0 yes=0 browser=0 ids=""
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --all) all=1; shift ;;
+      --yes|-y) yes=1; shift ;;
+      --browser) browser=1; shift ;;
+      --device) browser=0; shift ;;   # accepted for compatibility; device is the default
+      --*) die "unknown option: $1" ;;
+      *)
+        valid_acct_id "$1" || die "not a valid account id: $1"
+        account_ids | grep -qx "$1" || die "unknown account: $1"
+        ids="$ids $1"; shift ;;
+    esac
+  done
+  if [ -n "$ids" ] && [ "$all" = "1" ]; then
+    die "give account ids OR --all, not both"
+  fi
+  if [ -z "$ids" ]; then
+    if [ "$all" = "1" ]; then
+      ids="$(account_ids | tr '\n' ' ')"
+    else
+      # A FAILED audit must not read as "nothing to do".
+      account_audit >/dev/null || die "the account audit failed — refusing to guess what needs a re-login"
+      ids="$(accounts_needing_login | tr '\n' ' ')"
+    fi
+  fi
+  ids="$(printf '%s' "$ids" | tr -s ' ' | sed 's/^ //; s/ $//')"
+  if [ -z "$ids" ]; then
+    echo "Nothing to re-authenticate — every account on this machine can be used."
+    return 0
+  fi
+  local count rows
+  count="$(printf '%s\n' "$ids" | tr ' ' '\n' | grep -c .)"
+  rows="$(account_audit)"
+  echo "Accounts to re-authenticate ($count):"
+  local id
+  for id in $ids; do
+    printf '  %s  %s\n' "$id" \
+      "$(printf '%s\n' "$rows" | awk -F'\t' -v i="$id" '$1 == i { print $2 "  (" $5 ")" }')"
+  done
+  if [ "$yes" != "1" ]; then
+    if [ ! -t 0 ]; then
+      die "relogin is interactive (each account needs a sign-in) — run it from a terminal, or pass --yes"
+    fi
+    printf 'Sign in to each of them now? [y/N] '
+    read -r ans
+    case "$ans" in y|Y|yes) ;; *) echo "aborted"; return 1 ;; esac
+  fi
+  # One sync at the end instead of one per account: each auto_sync is an ssh round trip.
+  local prev_no_sync="${CODEX_MULTIACC_NO_SYNC:-0}" failed="" done_ok=0
+  export CODEX_MULTIACC_NO_SYNC=1
+  for id in $ids; do
+    echo
+    echo "=== $id ==============================================================="
+    if [ "$browser" = "1" ]; then
+      ( cmd_login "$id" --browser ) && done_ok=$((done_ok + 1)) || failed="$failed $id"
+    else
+      ( cmd_login "$id" ) && done_ok=$((done_ok + 1)) || failed="$failed $id"
+    fi
+  done
+  export CODEX_MULTIACC_NO_SYNC="$prev_no_sync"
+  [ "$prev_no_sync" = "0" ] && unset CODEX_MULTIACC_NO_SYNC
+  echo
+  echo "re-authenticated $done_ok of $count account(s)."
+  if [ -n "$failed" ]; then
+    warn "still failing:$failed (re-run: codex-accounts relogin$failed)"
+  fi
+  [ "$done_ok" -gt 0 ] && auto_sync
+  [ -z "$failed" ]
+}
+
+cmd_limits() {
+  require_manifest
+  local quiet=0 force=0
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --quiet) quiet=1; shift ;;
+      --force) force=1; shift ;;   # ignore freshness/backoff (manual override)
+      *) die "unknown option: $1" ;;
+    esac
+  done
+  local lock="$ACC_ROOT/.locks/limits"
+  mkdir -p "$ACC_ROOT/.locks"
+  if ! mkdir "$lock" 2>/dev/null; then
+    local age=$(( $(epoch_now) - $(file_mtime "$lock") ))
+    if [ "$age" -lt 120 ]; then
+      [ "$quiet" = "1" ] || echo "another limits refresh is running; skipping"
+      return 0
+    fi
+    rm -rf "$lock"
+    mkdir "$lock" 2>/dev/null || return 0
+  fi
+  # shellcheck disable=SC2064
+  trap "rm -rf '$lock'" EXIT
+  rotate_log limits.log
+  # The >=90% exclusion rule is a hard requirement: the manifest may tighten it but
+  # never loosen it, or an account could sit at 95% and still be selected.
+  local threshold
+  threshold="$(manifest_get threshold 90)"
+  case "$threshold" in ''|*[!0-9]*) threshold=90 ;; esac
+  [ "$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 base64, datetime, 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('CODEX_MULTIACC_MIN_FETCH', '45'))
+
+# OAuth refresh-token grant — the same endpoint + public client id the Codex CLI
+# itself uses to keep auth.json alive. An account that sits idle past its
+# access-token TTL would otherwise drop out of telemetry (stale data ranks
+# neutral, so truly-idle accounts lose selection to busy-but-fresh ones).
+TOKEN_URL = os.environ.get('CODEX_MULTIACC_TOKEN_URL',
+                           'https://auth.openai.com/oauth/token')
+CLIENT_ID = os.environ.get('CODEX_MULTIACC_CLIENT_ID',
+                           'app_EMoamEEZ73f0CkXaXp7hrann')
+# 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)
+    with open(os.path.join(root, 'limits.log'), 'a') as f:
+        f.write(time.strftime('%Y-%m-%dT%H:%M:%SZ ', time.gmtime()) + msg + '\n')
+
+def jwt_claims(token):
+    try:
+        payload = str(token).split('.')[1]
+        payload += '=' * (-len(payload) % 4)
+        claims = json.loads(base64.urlsafe_b64decode(payload))
+        return claims if isinstance(claims, dict) else {}
+    except Exception:
+        return {}
+
+def jwt_exp(token):
+    try:
+        return float(jwt_claims(token).get('exp') or 0)
+    except (TypeError, ValueError):
+        return 0.0
+
+# `.expired` — the persistent "this account cannot authenticate" marker the shim
+# honors. Written only for a PROVEN dead grant (no refresh token, or an
+# invalid_grant from the token endpoint), never for a transient hiccup.
+def mark_expired(d, slug, detail=''):
+    mpath = os.path.join(d, '.expired')
+    try:
+        with open(mpath + '.tmp', 'w') as f:
+            f.write(f'{int(now)}\n')
+            f.write(f"reason={slug} marked_at="
+                    f"{time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime())} detail={detail}\n")
+        os.replace(mpath + '.tmp', mpath)
+    except Exception:
+        pass
+
+def clear_expired(d):
+    """A usage fetch that succeeded PROVES the bearer works — drop any dead-auth mark.
+    EXCEPT an org-blocked one: those accounts authenticate perfectly (telemetry works),
+    they are just barred from Codex inference, so telemetry says nothing about them.
+    Only a passing `verify` (a real call) or a re-login lifts that."""
+    mpath = os.path.join(d, '.expired')
+    try:
+        if 'reason=org-blocked' in open(mpath, errors='replace').read():
+            return False
+    except OSError:
+        return False
+    try:
+        os.remove(mpath)
+        return True
+    except OSError:
+        return False
+
+try:
+    manifest = json.load(open(os.path.join(root, 'accounts.json')))
+except Exception as e:
+    sys.exit(f'cannot read manifest: {e}')
+
+def refresh_oauth(aid, d, cpath):
+    """Refresh a long-expired access token via the OAuth 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))
+        tokens = doc.get('tokens')
+        # Present-but-null/non-object tokens (interrupted or reset credential
+        # write) must degrade THIS account only, like every other malformed input.
+        if not isinstance(doc, dict) or not isinstance(tokens, dict):
+            return None
+    except Exception:
+        return None
+    if not tokens.get('access_token'):
+        return None
+    if not tokens.get('refresh_token'):
+        mark_expired(d, 'no-refresh-token',
+                     'credential has no refresh token and its access token expired')
+        return None
+    if jwt_exp(tokens['access_token']) > now - REFRESH_MIN_EXPIRED:
+        return None  # not expired long enough to prove no live session owns it
+    if not force:
+        try:
+            if json.load(open(spath)).get('retry_after', 0) > now:
+                return None  # earlier refresh failure still backing off
+        except Exception:
+            pass
+
+    def back_off(wait, why, denials=0):
+        try:
+            with open(spath + '.tmp', 'w') as f:
+                json.dump({'retry_after': int(now + wait), 'error': why,
+                           'denials': denials,
+                           'at': time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime())}, f)
+            os.replace(spath + '.tmp', spath)
+        except Exception:
+            pass
+        say(f'{aid}: oauth refresh failed ({why}); backing off {wait}s; limits left as-is')
+
+    # The grant ROTATES the refresh token, so it must not be consumed unless the
+    # rotated credential can actually be persisted afterwards: probe that the
+    # atomic-write path works (0600 temp file in the same dir) BEFORE the request.
+    # The probe uses its OWN pid-scoped name — never the real .tmp staging path,
+    # which a concurrent writer could be mid-flight on.
+    probe = f'{cpath}.probe.{os.getpid()}'
+    try:
+        fd = os.open(probe, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        os.close(fd)
+        os.remove(probe)
+    except Exception as e:
+        back_off(REFRESH_FAIL_BACKOFF, f'cannot persist a rotated credential ({str(e)[:120]}); refresh not attempted')
+        return None
+    body = json.dumps({'client_id': CLIENT_ID,
+                       'grant_type': 'refresh_token',
+                       'refresh_token': tokens['refresh_token'],
+                       'scope': 'openid profile email'}).encode()
+    req = urllib.request.Request(TOKEN_URL, data=body, headers={
+        'Content-Type': 'application/json',
+        'User-Agent': 'codex-multiacc/1.0',
+    })
+    try:
+        data = json.loads(urllib.request.urlopen(req, timeout=30).read().decode())
+    except urllib.error.HTTPError as e:
+        if e.code in (400, 401, 403):
+            # A 4xx from the TOKEN endpoint is only proof of a dead grant when the
+            # server says so (OAuth's invalid_grant). Everything else 4xx — a bad
+            # client_id, an endpoint change, a WAF page, a provider incident — would
+            # hit EVERY account at once, so it must never park the whole pool on the
+            # first try: back off, and only park after this account has been refused
+            # repeatedly.
+            resp_body = ''
+            try:
+                resp_body = e.read().decode('utf-8', 'replace')[:400]
+            except Exception:
+                pass
+            denials = 1
+            try:
+                denials = int(json.load(open(spath)).get('denials', 0)) + 1
+            except Exception:
+                pass
+            if 'invalid_grant' in resp_body:
+                mark_expired(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')
+            back_off(REFRESH_DENIED_BACKOFF,
+                     f'HTTP {e.code} — refresh token may be revoked; re-login needed',
+                     denials=denials)
+        else:
+            back_off(REFRESH_FAIL_BACKOFF, f'HTTP {e.code}')
+        return None
+    except Exception as e:
+        back_off(REFRESH_FAIL_BACKOFF, str(e)[:200])
+        return None
+    tok = data.get('access_token') if isinstance(data, dict) else None
+    if not tok:
+        back_off(REFRESH_DENIED_BACKOFF, 'no access_token in response')
+        return None
+    tokens['access_token'] = tok
+    # The grant ROTATES the refresh token: persist it (and the fresh id_token) or
+    # the account is stranded — hence atomic write, and a loud message if it fails.
+    if data.get('refresh_token'):
+        tokens['refresh_token'] = data['refresh_token']
+    if data.get('id_token'):
+        tokens['id_token'] = data['id_token']
+    doc['tokens'] = tokens
+    doc['last_refresh'] = datetime.datetime.now(datetime.timezone.utc) \
+        .isoformat().replace('+00:00', 'Z')
+    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, indent=2)
+        os.replace(cpath + '.tmp', cpath)
+    except Exception as e:
+        say(f'{aid}: token refreshed but auth.json NOT persisted ({e}) — re-login may be needed')
+        return None
+    try:
+        os.remove(spath)
+    except OSError:
+        pass
+    # The grant answered: whatever parked this account before, it authenticates now.
+    if clear_expired(d):
+        say(f'{aid}: dead-auth marker cleared (refresh grant works again)')
+    say(f'{aid}: 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
+
+    # 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):
+        try:
+            prev = json.load(open(lpath))
+        except Exception:
+            prev = {}
+    if not force:
+        age = now - prev.get('fetched_at', 0)
+        if age < MIN_FETCH_INTERVAL:
+            continue
+        retry_at = prev.get('retry_after', 0)
+        if retry_at > now:
+            say(f'{aid}: backing off after 429 ({int(retry_at - now)}s left); limits left as-is')
+            continue
+
+    bearer = None
+    account_id = ''
+    cpath = os.path.join(d, 'auth.json')
+    if os.path.isfile(cpath):
+        try:
+            c = json.load(open(cpath))
+            tokens = c.get('tokens') or {}
+            if isinstance(tokens, dict) and tokens.get('access_token') \
+               and jwt_exp(tokens['access_token']) > now + 60:
+                bearer = tokens['access_token']
+            if isinstance(tokens, dict):
+                account_id = str(tokens.get('account_id') or '')
+        except Exception:
+            pass
+        if not bearer:
+            # 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 = tok
+    if not bearer:
+        # Fail OPEN: no usable bearer => leave existing state; never block work on telemetry.
+        say(f'{aid}: no fresh bearer (expired or missing chatgpt auth); limits left as-is')
+        continue
+    if not account_id:
+        account_id = str((jwt_claims(bearer).get('https://api.openai.com/auth') or {})
+                         .get('chatgpt_account_id') or '')
+
+    headers = {
+        'Authorization': 'Bearer ' + bearer,
+        'Content-Type': 'application/json',
+        'User-Agent': 'codex_cli_rs (codex-multiacc)',
+        'originator': 'codex_cli_rs',
+    }
+    if account_id:
+        headers['chatgpt-account-id'] = account_id
+    req = urllib.request.Request(url, headers=headers)
+    try:
+        resp = urllib.request.urlopen(req, timeout=15)
+        data = json.loads(resp.read().decode())
+    except urllib.error.HTTPError as e:
+        if e.code == 429:
+            # Respect Retry-After; otherwise exponential backoff capped at 30 min.
+            try:
+                wait = int(e.headers.get('Retry-After') or 0)
+            except (TypeError, ValueError):
+                wait = 0
+            if wait <= 0:
+                wait = min(1800, max(120, int(prev.get('backoff', 60)) * 2))
+            prev['retry_after'] = int(now + wait)
+            prev['backoff'] = wait
+            tmp = lpath + '.tmp'
+            with open(tmp, 'w') as f:
+                json.dump(prev, f, indent=1)
+            os.replace(tmp, lpath)
+            say(f'{aid}: rate limited (429); backing off {wait}s; failing open')
+        else:
+            say(f'{aid}: usage fetch failed (HTTP {e.code}); failing open')
+        continue
+    except Exception as e:
+        say(f'{aid}: usage fetch failed ({e}); failing open')
+        continue
+
+    def pct_of(v):
+        try:
+            return max(0, min(100, int(round(float(v)))))
+        except (TypeError, ValueError):
+            return None
+
+    # Shape-agnostic bucket extraction. The payload nests rate-limit WINDOWS
+    # (used_percent + limit_window_seconds + reset_at) under several scopes:
+    # the overall rate_limit, code_review_rate_limit, and one per model family in
+    # additional_rate_limits[] (each model tracked as its own bucket — the codex
+    # analog of the per-model Fable bucket requirement). Window length classifies
+    # session (~5h, self-healing) vs weekly (multi-day, expensive): <=6h => session.
+    # If the payload reshapes, whatever windows remain are still found (recursive
+    # fallback), unparseable entries are skipped, and a payload the code cannot
+    # read at all degrades that one account (fail open), never the run.
+    def win_bucket(scope, which, win):
+        if not isinstance(win, dict):
+            return None
+        pct = pct_of(win.get('used_percent'))
+        if pct is None:
+            return None
+        try:
+            secs = int(win.get('limit_window_seconds') or 0)
+        except (TypeError, ValueError):
+            secs = 0
+        if secs and secs <= 21600:
+            dur, group = f'{max(1, secs // 3600)}h', 'session'
+        elif secs:
+            dur, group = f'{max(1, secs // 86400)}d', 'weekly'
+        else:
+            # Unknown durable windows default to 'weekly' so they are never under-weighted.
+            dur, group = which, 'weekly'
+        name = f'{scope}:{dur}' if scope else dur
+        try:
+            reset_epoch = int(float(win.get('reset_at')))
+        except (TypeError, ValueError):
+            reset_epoch = int(now + (secs or 3600))
+        return {
+            'name': name,
+            'kind': which,
+            'group': group,
+            'percent': pct,
+            'resets_at': time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime(reset_epoch)),
+            'resets_epoch': reset_epoch,
+        }
+
+    def scope_buckets(scope, rl):
+        out = []
+        if not isinstance(rl, dict):
+            return out
+        for which in ('primary_window', 'secondary_window'):
+            b = win_bucket(scope, which, rl.get(which))
+            if b:
+                out.append(b)
+        # A hard "limit reached / not allowed" verdict without a >=threshold window
+        # (payload skew) must still exclude: synthesize a 100% bucket that resets
+        # with the scope's furthest-out window (or in 1h if none is readable).
+        if (rl.get('limit_reached') is True or rl.get('allowed') is False) \
+           and not any(b['percent'] >= threshold for b in out):
+            reset_epoch = max([b['resets_epoch'] for b in out] or [int(now + 3600)])
+            out.append({
+                'name': f'{scope}:limit_reached' if scope else 'limit_reached',
+                'kind': 'limit_reached', 'group': 'weekly', 'percent': 100,
+                'resets_at': time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime(reset_epoch)),
+                'resets_epoch': reset_epoch,
+            })
+        return out
+
+    buckets = []
+    try:
+        buckets += scope_buckets('', data.get('rate_limit'))
+        buckets += scope_buckets('code_review', data.get('code_review_rate_limit'))
+        for extra in (data.get('additional_rate_limits') or []):
+            if not isinstance(extra, dict):
+                continue
+            scope = str(extra.get('limit_name') or extra.get('metered_feature') or 'model')
+            buckets += scope_buckets(scope, extra.get('rate_limit'))
+        if not buckets:
+            # Fallback for a reshaped payload: find ANY window-shaped object (carries
+            # used_percent) anywhere in the document, naming it by its path. Missing
+            # one would let an exhausted bucket go unnoticed.
+            def walk(node, path):
+                if isinstance(node, dict):
+                    if 'used_percent' in node:
+                        b = win_bucket(':'.join(path[:-1]), path[-1] if path else 'window', node)
+                        if b:
+                            buckets.append(b)
+                        return
+                    for k in sorted(node):
+                        walk(node[k], path + [str(k)])
+                elif isinstance(node, list):
+                    for i, item in enumerate(node):
+                        walk(item, path + [str(i)])
+            walk(data, [])
+    except Exception as e:
+        say(f'{aid}: unexpected usage payload shape ({e}); failing open')
+        continue
+    # Successful fetch: fresh buckets replace everything, backoff state is dropped.
+    # THREE selection signals, same reset asymmetry as the claude pool:
+    #   max_percent    — peak of ALL buckets; drives >=90% EXCLUSION.
+    #   weekly_percent — peak of the durable buckets; the PRIMARY ranking signal.
+    #   session_percent— peak of the self-healing ~5h buckets; a soft tiebreaker.
+    maxp = max([b['percent'] for b in buckets] or [0])
+    weekly = [b['percent'] for b in buckets if b['group'] != 'session']
+    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
+    out = {'fetched_at': int(now), 'source': 'chatgpt', 'max_percent': maxp,
+           'weekly_percent': weeklyp, 'session_percent': sessionp,
+           'plan': str(data.get('plan_type') or ''), 'buckets': buckets}
+    tmp = lpath + '.tmp'
+    with open(tmp, 'w') as f:
+        json.dump(out, f, indent=1)
+    os.replace(tmp, lpath)
+    # The fetch went through with this account's own bearer => its auth is alive.
+    if clear_expired(d):
+        say(f'{aid}: dead-auth marker cleared (authenticated successfully)')
+    offenders = [b for b in buckets if b['percent'] >= threshold]
+    mpath = os.path.join(d, '.limited')
+    if offenders:
+        worst = max(offenders, key=lambda b: b['percent'])
+        reset_epoch = max(int(b['resets_epoch']) for b in offenders)
+        # Atomic: a concurrent shim must never read a half-written marker.
+        with open(mpath + '.tmp', 'w') as f:
+            f.write(f'{reset_epoch}\n')
+            f.write(f"bucket={worst['name']} percent={worst['percent']} "
+                    f"marked_at={time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime())} "
+                    f"reason=limits resets_at={worst['resets_at']}\n")
+        os.replace(mpath + '.tmp', mpath)
+        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.
+            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:
+                    keep = True
+            except Exception:
+                pass
+            if not keep:
+                os.remove(mpath)
+                say(f'{aid}: marker cleared (max {maxp}%)')
+        if not quiet:
+            detail = '  '.join(f"{b['name']}={b['percent']}%" for b in buckets)
+            print(f'{aid}: ok  {detail}')
+PYEOF
+}
+
+cmd_verify() {
+  require_manifest
+  local quick=0
+  [ "${1:-}" = "--quick" ] && quick=1
+  local real=""
+  if [ "$quick" = "0" ]; then
+    real="$(find_real_codex "$_self")" || die "real codex binary not found"
+  fi
+  "$PYBIN" - "$ACC_ROOT" "$quick" "$real" "$LIB_DIR" "$(machine_kind)" <<'PYEOF'
+import json, os, re, subprocess, sys, tempfile, 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 ('', '.')]
+from codex_audit import audit_account   # noqa: E402  (shared with the shim's rule)
+machine = sys.argv[5]
+now = time.time()
+manifest = json.load(open(os.path.join(root, 'accounts.json')))
+os.makedirs(os.path.join(root, 'tmp'), exist_ok=True)
+failures = 0
+tested = 0
+
+# Same failure vocabulary the shim retries on (bin/codex: PARK_AUTH / PARK_ORG).
+AUTH_ERR = re.compile(
+    r'not (logged|signed) in|authentication (required|failed|error)'
+    r'|please run `?codex login|run `?codex login`? to|401|unauthorized'
+    r'|token .{0,12}(expired|revoked|invalid)|refresh token.{0,20}(expired|invalid|revoked)'
+    r'|invalid_grant|could not refresh|re-?authenticate', re.I)
+ORG_ERR = re.compile(
+    r'disabled by (your )?(workspace )?admin|admin (has )?disabled'
+    r'|(workspace|organization) has disabled (codex|chatgpt)'
+    r'|codex.{0,20}disabled for (your|this) (workspace|organization)', re.I)
+
+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')
+    try:
+        with open(mpath + '.tmp', 'w') as f:
+            f.write(f'{int(time.time())}\n')
+            f.write(f"reason={slug} marked_at="
+                    f"{time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime())} detail={detail}\n")
+        os.replace(mpath + '.tmp', mpath)
+    except Exception:
+        pass
+
+for acct in manifest.get('accounts', []):
+    aid = acct['id']
+    d = os.path.join(root, aid)
+    cpath = os.path.join(d, 'auth.json')
+    has_creds = os.path.isfile(cpath) and os.path.getsize(cpath) > 0
+    if not has_creds:
+        print(f'{aid} {acct["email"]}: SKIP (no auth on this machine)')
+        continue
+    tested += 1
+    if quick:
+        # Quick mode must agree with what the shim will actually do — presence of a
+        # credential file is not proof it can authenticate.
+        st = audit_account(root, acct, machine=machine)
+        if st['state'] == 'ok':
+            print(f'{aid} {acct["email"]}: OK (quick, chatgpt auth present)')
+        else:
+            print(f'{aid} {acct["email"]}: FAIL ({st["label"]} — {st["reason"]})'
+                  + (f'; fix: {st["fix"]}' if st['fix'] else ''))
+            failures += 1
+        continue
+    env = dict(os.environ)
+    env['CODEX_HOME'] = d
+    env.pop('OPENAI_API_KEY', None)
+    env.pop('CODEX_ACCOUNT', None)
+    env['CODEX_SHIM_ACTIVE'] = '1'
+    # --output-last-message: codex exec prints progress/log lines around the answer,
+    # so the agent's final message is read from a file instead of scraping stdout.
+    outfile = tempfile.NamedTemporaryFile(prefix='verify.', suffix='.txt',
+                                          dir=os.path.join(root, 'tmp'), delete=False)
+    outfile.close()
+    t0 = time.time()
+    try:
+        r = subprocess.run([real, 'exec', '--skip-git-repo-check',
+                            '--sandbox', 'read-only', '--color', 'never',
+                            '-o', outfile.name, 'Reply with exactly: OK'],
+                           env=env, capture_output=True, text=True, timeout=240,
+                           stdin=subprocess.DEVNULL, cwd=root)
+    except subprocess.TimeoutExpired:
+        print(f'{aid} {acct["email"]}: FAIL (timeout after 240s)')
+        failures += 1
+        try:
+            os.remove(outfile.name)
+        except OSError:
+            pass
+        continue
+    dt = time.time() - t0
+    try:
+        last = open(outfile.name, errors='replace').read().strip()
+    except OSError:
+        last = ''
+    try:
+        os.remove(outfile.name)
+    except OSError:
+        pass
+    out = (r.stdout or '').strip()
+    if r.returncode == 0 and ('ok' in last.lower() or 'ok' in out.lower()):
+        # A real call succeeded: this account is definitively alive.
+        try:
+            os.remove(os.path.join(d, '.expired'))
+        except OSError:
+            pass
+        print(f'{aid} {acct["email"]}: PASS ({dt:.1f}s) -> {(last or out)[:60]!r}')
+    else:
+        err = (r.stderr or '').strip()[:200]
+        hint = ''
+        if ORG_ERR.search(out) or ORG_ERR.search(err):
+            # Not an auth problem: the account authenticates fine, a workspace admin
+            # has simply turned Codex access off. Park it — a re-login changes
+            # nothing — and say what actually helps.
+            mark_expired(d, 'org-blocked',
+                         'Codex access is disabled for the account by a workspace admin')
+            hint = (f' — ORG BLOCKED, excluded from the pool; '
+                    f'try: codex-accounts relogin {aid}')
+        elif AUTH_ERR.search(out) or AUTH_ERR.search(err):
+            mark_expired(d, 'auth-error', 'a real call came back not-authenticated')
+            hint = f' — login is dead, run: codex-accounts relogin {aid}'
+        print(f'{aid} {acct["email"]}: FAIL rc={r.returncode} '
+              f'out={(last or out)[:120]!r} err={err!r}{hint}')
+        failures += 1
+
+print()
+print(f'verified {tested} account(s), {failures} failure(s)')
+sys.exit(1 if failures else 0)
+PYEOF
+}
+
+cmd_sync() {
+  require_manifest
+  [ "$(machine_kind)" = "mac" ] || die "sync runs on the Mac (source of truth), not the server"
+  local allow_empty=0
+  [ "${1:-}" = "--allow-empty" ] && allow_empty=1
+  local server sroot srepo rc=0
+  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 a remote shell command — anything but a plain target/path is a
+  # command-injection vector from a corrupted or hand-edited manifest.
+  valid_ssh_target "$server" || die "manifest 'server' is not a plain user@host: $server"
+  valid_remote_path "$sroot" || die "manifest 'server_root' is not a plain absolute path: $sroot"
+  valid_remote_path "$srepo" || die "manifest 'server_repo' is not a plain absolute path: $srepo"
+  rotate_log sync.log
+  slog() { log_to sync.log "$*"; }
+  fail() { slog "FAIL: $*"; printf 'codex-accounts sync: FAILED: %s\n' "$*" >&2; exit 1; }
+  slog "sync start -> $server:$sroot"
+
+  # Hard validation before anything destructive: a corrupt or accountless manifest must
+  # never be pushed (it would blank the server's pool), and must never make the removal
+  # loop below wipe the server's account dirs. 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
+  if [ -z "$(account_ids)" ] && [ "$allow_empty" != "1" ]; then
+    fail "manifest has zero accounts — refusing to blank the server pool (use 'sync --allow-empty' if that is really intended)"
+  fi
+
+  ssh -o BatchMode=yes -o ConnectTimeout=10 "$server" "mkdir -p '$sroot'" >>"$ACC_ROOT/sync.log" 2>&1 \
+    || fail "cannot reach $server"
+  rsync -az "$MANIFEST" "$server:$sroot/accounts.json" >>"$ACC_ROOT/sync.log" 2>&1 \
+    || fail "manifest push failed"
+
+  # NB: auth.json is deliberately NEVER pushed (in either direction): the refresh
+  # token inside it rotates, and two machines refreshing one grant invalidate each
+  # other. A codex account that should run on the server is signed in THERE
+  # (codex-accounts add --device over SSH).
+  local id d
+  for id in $(account_ids); do
+    d="$ACC_ROOT/$id"
+    [ -d "$d" ] || continue
+    ssh -o BatchMode=yes "$server" "mkdir -p '$sroot/$id'" >>"$ACC_ROOT/sync.log" 2>&1 \
+      || fail "mkdir $id failed"
+    local seed
+    for seed in config.toml; do
+      if [ -f "$d/$seed" ]; then
+        rsync -az --ignore-existing "$d/$seed" "$server:$sroot/$id/" >>"$ACC_ROOT/sync.log" 2>&1 \
+          || fail "seed push for $id/$seed failed"
+      fi
+    done
+    # Advisory limit state for accounts the server may lack a bearer for.
+    local extra
+    for extra in limits.json .limited; do
+      if [ -f "$d/$extra" ]; then
+        rsync -az "$d/$extra" "$server:$sroot/$id/" >>"$ACC_ROOT/sync.log" 2>&1 || true
+      fi
+    done
+  done
+
+  # Removal propagation: any server acct dir not in the manifest gets deleted.
+  # Safety: an EMPTY id list (parse error, or a truly emptied pool) never deletes —
+  # wiping every server credential must be an explicit manual act, not a side effect.
+  local ids_list ids_spaced
+  ids_list="$(account_ids)"
+  if [ -z "$ids_list" ]; then
+    slog "removal propagation skipped: empty account list (safety guard)"
+  else
+    ids_spaced=" $(printf '%s' "$ids_list" | tr '\n' ' ') "
+    ssh -o BatchMode=yes "$server" "cd '$sroot' 2>/dev/null || exit 0
+for dd in acct-*; do
+  [ -d \"\$dd\" ] || continue
+  case '$ids_spaced' in
+    *\" \$dd \"*) ;;
+    *) rm -rf -- \"\$dd\" ;;
+  esac
+done" >>"$ACC_ROOT/sync.log" 2>&1 || fail "removal propagation failed"
+  fi
+
+  # Post-sync hook: server seeds dirs and re-runs its quick verification matrix.
+  ssh -o BatchMode=yes "$server" "[ -x '$srepo/bin/codex-accounts' ] && '$srepo/bin/codex-accounts' post-sync" \
+    >>"$ACC_ROOT/sync.log" 2>&1 || slog "post-sync hook not available yet (server not bootstrapped?)"
+
+  slog "sync ok"
+  echo "sync ok -> $server:$sroot"
+  return $rc
+}
+
+cmd_post_sync() {
+  require_manifest
+  local id d
+  for id in $(account_ids); do
+    d="$ACC_ROOT/$id"
+    seed_account_dir "$d"
+    [ -f "$d/auth.json" ] && chmod 600 "$d/auth.json" 2>/dev/null
+  done
+  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
+}
+
+cmd_self_update() {
+  # Update the addon in place. npm global install => npm i -g @latest (its postinstall
+  # re-runs install.sh). git checkout => git pull + ./install.sh. Anything else is a
+  # no-op with a hint. Best-effort and fully logged; never disrupts a running codex.
+  local quiet=0
+  [ "${1:-}" = "--quiet" ] && quiet=1
+  rotate_log update.log
+  ulog() { log_to update.log "$*"; [ "$quiet" = "1" ] || echo "$*"; }
+  case "$REPO_DIR" in
+    */node_modules/claude-multiacc|*/node_modules/claude-multiacc/*)
+      command -v npm >/dev/null 2>&1 || { ulog "self-update: npm not found; skipping"; return 0; }
+      local cur lat
+      cur="$(npm ls -g --depth=0 claude-multiacc 2>/dev/null | sed -n 's/.*claude-multiacc@//p' | head -1)"
+      lat="$(npm view claude-multiacc version 2>/dev/null)"
+      if [ -n "$lat" ] && [ "$cur" = "$lat" ]; then
+        ulog "self-update: already latest ($cur)"
+        return 0
+      fi
+      ulog "self-update: npm $cur -> ${lat:-latest}"
+      if npm install -g claude-multiacc@latest >>"$ACC_ROOT/update.log" 2>&1; then
+        ulog "self-update: npm update ok"
+      else
+        ulog "self-update: npm update FAILED (see update.log)"
+        return 1
+      fi
+      ;;
+    *)
+      if [ -d "$REPO_DIR/.git" ] && command -v git >/dev/null 2>&1; then
+        ulog "self-update: git pull in $REPO_DIR"
+        if git -C "$REPO_DIR" pull --ff-only >>"$ACC_ROOT/update.log" 2>&1; then
+          "$REPO_DIR/install.sh" >>"$ACC_ROOT/update.log" 2>&1 \
+            && ulog "self-update: git update + reinstall ok" \
+            || { ulog "self-update: reinstall FAILED"; return 1; }
+        else
+          ulog "self-update: git pull FAILED (local changes? see update.log)"
+          return 1
+        fi
+      else
+        ulog "self-update: not an npm or git install ($REPO_DIR) — update manually"
+      fi
+      ;;
+  esac
+}
+
+cmd_health() {
+  require_manifest
+  rotate_log health.log
+  local out rc=0
+  # verify first: its real codex runs refresh any expired tokens, so the
+  # limits pass that follows always has fresh bearers.
+  out="$( { echo "== verify =="; cmd_verify; echo; echo "== limits =="; cmd_limits; } 2>&1 )" || rc=1
+  printf '%s\n' "$out"
+  printf '%s health rc=%s\n%s\n' "$(ts_utc)" "$rc" "$out" >> "$ACC_ROOT/health.log"
+  if [ "$rc" -ne 0 ] && [ "$(machine_kind)" = "mac" ]; then
+    osascript -e 'display notification "codex-multiacc health check FAILED — run codex-accounts status" with title "claude-multiacc"' 2>/dev/null || true
+  fi
+  return $rc
+}
+
+cmd_init_pool() {
+  # Called by install.sh: create the codex pool skeleton + manifest (idempotent).
+  # An explicit server override updates an existing manifest too (same behavior
+  # install.sh applies to the claude manifest).
+  manifest_init "${1:-}"
+  if [ -n "${1:-}" ]; then
+    "$PYBIN" - "$MANIFEST" "$1" <<'PYEOF'
+import json, os, sys
+doc = json.load(open(sys.argv[1]))
+doc['server'] = sys.argv[2]
+with open(sys.argv[1] + '.tmp', 'w') as f:
+    json.dump(doc, f, indent=2)
+    f.write('\n')
+os.replace(sys.argv[1] + '.tmp', sys.argv[1])
+PYEOF
+  fi
+  echo "codex account pool: $ACC_ROOT (manifest ready)"
+}
+
+case "${1:-help}" in
+  list) shift; cmd_list "$@" ;;
+  status) shift; cmd_status "$@" ;;
+  add) shift; cmd_add "$@" ;;
+  import) shift; cmd_import "$@" ;;
+  adopt) shift; cmd_adopt "$@" ;;
+  dedupe) shift; cmd_dedupe "$@" ;;
+  remove) shift; cmd_remove "$@" ;;
+  login) shift; cmd_login "$@" ;;
+  expired) shift; cmd_expired "$@" ;;
+  relogin|re-login) shift; cmd_relogin "$@" ;;
+  sync) shift; cmd_sync "$@" ;;
+  verify) shift; cmd_verify "$@" ;;
+  limits) shift; cmd_limits "$@" ;;
+  post-sync) shift; cmd_post_sync "$@" ;;
+  health) shift; cmd_health "$@" ;;
+  self-update) shift; cmd_self_update "$@" ;;
+  init-pool) shift; cmd_init_pool "$@" ;;
+  help|--help|-h) usage ;;
+  *) usage; exit 1 ;;
+esac