claude-multiacc 2.0.26 → 2.0.28

package/README.md

@@ -16,8 +16,8 @@ completely independent — separate manifests, credentials, telemetry, and logs
 either provider can be used, re-authenticated, or emptied without touching the other.
 
 Tested on: macOS (bash 3.2, zsh, Claude Code 2.1.207+, Codex CLI 0.147) and Ubuntu 24.04
-(bash 5.2). The compatibility suite currently covers 918 sandboxed cases with no
-network/quota use; the unified selector has its own adversarial contract suite.
+(bash 5.2). The compatibility suite exercises both providers with no network/quota
+use; the unified selector and packed npm commands have their own contract suites.
 
 ## Unified selector for app-robot
 
@@ -315,6 +315,45 @@ same ownership rule. Note that the **installed layout deliberately shares that t
 default codex pool this scan stays off and the usage endpoint remains codex's only limit
 signal. Claude accounts keep a private `sessions/` registry, so it is fully active there.
 
+A shared tree also gets **one shared rollout index**. codex refuses to start until its
+`state_<schema>.sqlite` has indexed every rollout under `$CODEX_HOME/sessions` (each file
+read whole), so a private index per account meant one full scan of the shared tree per
+account — 10 GB × 12 on a busy Mac — and any launch that met another process's unfinished
+scan died after 30 s with "timed out waiting for state db backfill … (status: running)",
+surfaced as the CLI's "local database appears to be damaged". A scan cut short (a probe with
+a timeout, Ctrl-C) also left its 15-minute worker lease behind, keeping the account
+unstartable long after its killer was gone. Since 2.0.27 `<acct>/state_N.sqlite` is a symlink
+to `~/.codex/state_N.sqlite`, exactly like the tree it describes: SQLite resolves the link
+before naming its `-wal`/`-shm` companions, so every process shares one lock set — the same
+multi-process mode a single `CODEX_HOME` already runs in. The shim applies this at every
+launch, and the index name the installed binary carries is linked ahead of time, so a codex
+schema bump still costs one backfill per machine rather than one per account.
+
+An account with **no index of its own** — every newly added one, and the case the change
+exists for — is simply linked. Nothing is renamed and nothing about the shared index's state
+can block it. An account that already has one is only ever moved while **nothing can open
+it** (no `-wal` and no `-shm` beside it). codex holds the state database through an sqlx pool
+whose connections are opened lazily and *by path* (`max_connections(5)`,
+`create_if_missing(true)`), so renaming an index under a live holder would leave its first
+connection on the old inode while every later one follows the new link — one process, two
+databases. A codex killed mid-write leaves the pair behind too, and the next clean session on
+that account removes it, so an account excluded this way rejoins on its own. Once it is
+closed, the account's index is either **retired** beside the link as `*.private` (never
+deleted, never overwritten — a second retirement gets its own suffix) when the home already
+has one, or **promoted** into the home when it does not. The promote goes through `link(2)`,
+which refuses an existing target: two shims racing to be the first to promote could otherwise
+rename one's fresh symlink onto the file the other had just promoted, leaving the shared index
+pointing at itself — `ELOOP`, every account on the machine unable to start, and repaired by
+neither codex nor the shim.
+
+Two things stop the sharing entirely. An account whose `sessions/` is a real directory keeps a
+private index — the rule is structural, not a heuristic. And codex's own corruption recovery
+has the last word: when it judges a database damaged it renames it (with its `-wal`/`-shm`)
+into `<CODEX_HOME>/db-backups/sqlite-<ts>-<n>/` and rebuilds, which under a link renames the
+*link*. A link sitting in that folder pointing at the shared file is codex's verdict on that
+file, so the account keeps the index codex rebuilt for it and that name is left alone —
+handing the link back would hand the damage back.
+
 **Auto-retry** (`-p`/`--print` only, default on, `CLAUDE_SHIM_RETRY=0` disables): on an
 auth- or rate-limit-looking failure the shim retries once on a different account and
 marks the failed one — a **10-minute cooldown** for a rate limit (it heals on its own),
@@ -327,149 +366,22 @@ and ≥2 accounts are eligible; service-spawned pipes take the plain exec path u
 
 ## Codex support (OpenAI Codex CLI)
 
-The exact same machinery, instantiated a second time for Codex. Everything documented
-above about the claude pool holds for the codex pool with these translations:
-
-| Claude side | Codex side |
-| --- | --- |
-| `bin/claude` shim, `claude-accounts` CLI | `bin/codex` shim, `codex-accounts` CLI |
-| pool `~/.claude-accounts` | pool `~/.codex-accounts` |
-| `CLAUDE_CONFIG_DIR` per-account dirs | `CODEX_HOME` per-account dirs |
-| `.credentials.json` / macOS Keychain item (OAuth, machine-local) | `auth.json` (ChatGPT OAuth, machine-local) |
-| `claude -p` auto-retry | `codex exec` auto-retry |
-| Anthropic OAuth usage and Fable buckets | Codex usage endpoint and per-model buckets |
-| `CLAUDE_*` pool controls | equivalent `CODEX_*` controls |
-
-Same selection rule (session gate first — `CODEX_MULTIACC_SESSION_GATE`, default 50 —
-then the 30-point weekly-headroom band with random spread, ≥90% any-bucket
-exclusion, peers rotate), same marker semantics (`.limited` cooldowns, `.expired` parks with
-credential/policy scoping and soft expiry), same fail-open guarantees, same sync
-safety guards. The `codex` shim engages the buffered auto-retry only for
-`codex exec` runs with finite stdin, exactly like `-p` on the claude side.
-
-Codex-specific notes:
-
-- **Auth is the Codex device-code sign-in by default**: `codex-accounts add` 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 — there
-  is no portable setup-token equivalent for Codex, so a server account is signed in
-  ON the server the same way. `--browser` opts into the localhost browser-callback
-  flow instead (only works when the browser runs on the same machine — the callback
-  goes to `localhost:1455`). Either way the login runs with `CODEX_HOME` pointed at
-  the account dir, and identity is verified offline from the id-token before
-  anything is registered.
-- **`auth.json` is never synced** in either direction, for the same reason
-  `.credentials.json` never is: the refresh token rotates, and two machines
-  refreshing one grant strand each other. Sync pushes manifest + `config.toml`
-  seeds + advisory limit state only.
-- **Windows are classified by length**, not by name: any window ≤6h counts as the
-  self-healing session signal, anything longer as durable/weekly. A hard
-  `limit_reached`/`allowed:false` verdict marks the account even if no window shows
-  ≥90%, and a reshaped payload is still scanned recursively for window-shaped
-  objects (fail open if nothing parses).
-- **Idle-account telemetry** stays fresh the same way: a long-expired access token is
-  renewed via the OAuth refresh-token grant (`auth.openai.com/oauth/token`, the CLI's
-  own public client id) and the rotated credential is persisted 0600. Overrides for
-  tests: `CODEX_MULTIACC_TOKEN_URL`, `CODEX_MULTIACC_CLIENT_ID`,
-  `CODEX_MULTIACC_USAGE_URL`.
-- **Earned usage resets are redeemed automatically at 95% used** (5% remaining) or
-  when the backend reports the limit finished. The limits refresher checks the reset
-  credits belonging to that same account, uses the soonest-expiring available credit,
-  and writes a per-account/window idempotency key before redemption so a lost response
-  or simultaneous fleet poll cannot spend a second reset. Set
-  `CODEX_MULTIACC_AUTO_RESET=0` only for emergency rollback/testing.
-  A finished-limit verdict takes precedence over a conflicting percentage. The
-  redemption key excludes unused model windows whose reset clocks move between reads.
-  Eligible accounts, including spent ones, check the credit endpoint every five
-  minutes even if the usage summary still says zero credits. A newly granted reset
-  is redeemed during that pass and clears the old limit; no-credit results are
-  checked again next pass, without waiting for the weekly reset date.
-  All authenticated accounts also report `usage.reset_credits_available` and
-  `usage.reset_credits_fetched_at` (ISO 8601) in `list/status/limits --json`.
-  The count comes from the credit endpoint, including below 95% used and with
-  automatic redemption disabled. The scheduled usage cadence bounds these reads.
-  Redemption shares that read, then reads back the remaining count after a POST;
-  no subtraction or embedded usage summary substitutes for provider evidence.
-  Zero means no available resets; missing fields mean the read was unavailable.
-  Credit identifiers remain local and selection does not use these fields.
-- **API-key logins are rejected** — ChatGPT subscription accounts only, matching the
-  addon's no-API-keys rule.
-
-```bash
-codex-accounts add                    # sign in a new ChatGPT account (device code —
-                                      # open the URL in any browser, enter the code)
-codex-accounts add --browser          # localhost browser-callback flow instead
-codex-accounts import <email> --id acct-01 && codex-accounts adopt acct-01
-                                      # adopt this machine's existing ~/.codex login
-codex-accounts list | status | expired | relogin | verify | limits | health | sync
-claude-multiacc codex <cmd>           # same commands via the npm wrapper
-```
+Both pools use the same selection policy. See [Codex account commands and behavior](docs/CODEX.md).
 
 ## Install / update / uninstall
 
-### npm (recommended)
-
-```bash
-npm install -g claude-multiacc     # postinstall wires up the shim, CLI, and scheduled jobs
-# or run it once without installing globally:
-npx claude-multiacc
-```
-
-`claude-multiacc` then wraps everything:
-
 ```bash
-claude-multiacc                    # install or update the addon (idempotent)
-claude-multiacc self-update        # npm i -g @latest + re-install
-claude-multiacc uninstall [--purge-data]
-claude-multiacc list | status | add <email> | ...   # passthrough to claude-accounts
+npm install -g claude-multiacc@latest
+codex-accounts verify
 ```
 
-**Automatic updates:** a globally-installed package re-runs `install.sh` from its own
-postinstall, so `npm i -g claude-multiacc@latest` fully updates the shim, CLI, and jobs.
-A daily job (launchd on macOS, cron on Linux, 04:07) runs `claude-accounts self-update`
-to pull the latest release on its own — `npm i -g @latest` for npm installs, `git pull +
-reinstall` for git checkouts; set `CLAUDE_MULTIACC_AUTOUPDATE=0` before install to
-opt out. `update-notifier` also prints a one-line nudge when a newer version is on npm.
-(Note: newer npm versions gate install scripts; if postinstall is blocked, just run
-`claude-multiacc install` once.)
-
-New versions publish to npm automatically from `main` via GitHub Actions
-(`.github/workflows/publish.yml`, OIDC Trusted Publishing — no long-lived token after the
-first bootstrap publish; `scripts/auto-version.mjs` bumps the patch above the last release).
-
-### From a git checkout
-
-```bash
-git clone <repo> && cd claude-multiacc && ./install.sh    # macOS or Linux, idempotent
-./install.sh --server root@1.2.3.4                        # override sync target
-git pull && ./install.sh                                  # update (data untouched)
-./install.sh --uninstall                # restores stock behavior, keeps account data
-./install.sh --uninstall --purge-data   # also deletes ~/.claude-accounts
-```
+npm installs `claude-multiacc`, `claude-accounts`, `codex-accounts`, and `multiacc-select`
+into its global bin directory, so account commands work in the current shell. Open a
+new shell for the `claude` and `codex` shims. If auto-setup was skipped, run
+`claude-multiacc install` to initialize the pools and shell setup.
 
-`self-update` auto-detects which of these you used (npm global vs git checkout).
-
-**Servers / machines without repo access:** install via **npm** — the registry is
-public, so the daily self-update needs no credentials at all (no rsync, no keys).
-A git checkout self-updates too, but only if `git pull` can authenticate; for a
-private repo on a server that means a read-only deploy key (the 138 server runs
-this way: `core.sshCommand` pinned to its deploy key). A plain copied tree is the
-one layout that can NOT self-update — don't ship the addon that way.
-
-What install does (all reversible, nothing else):
-
-- **macOS:** marked PATH block at the END of `~/.zshenv`, `~/.zprofile`, `~/.zshrc`
-  (+ bash rc files if present) — end-of-file placement matters because those files
-  re-prepend `~/.local/bin`; launchd agents `com.claude-multiacc.limits` +
-  `.codex-limits` (5m), `.health` + `.codex-health` (weekly Mon morning), and
-  `.update` (daily 04:07). Notes when this Mac keeps Claude Code logins in the
-  Keychain (the pool reads them; ssh sessions cannot — mint portable tokens for
-  accounts that must work from everywhere).
-- **Linux (root):** PATH block in `~/.bashrc` + `/etc/profile.d/claude-multiacc.sh`,
-  shim symlinks at `/usr/local/bin/claude` and `/usr/local/bin/codex` (shadow via
-  PATH order — on the systemd default PATH too; the original binaries are untouched),
-  cron entries for limits/health (both providers) + the daily auto-update.
-- Both: `~/.claude-accounts/` skeleton + `accounts.json` manifest.
+See [installation, updates, removal, and command-not-found recovery](docs/INSTALLATION.md)
+for npm, npx, git checkout, and server instructions.
 
 Account lifecycle, synchronization, fleet integration, environment switches,
 verification, troubleshooting, and security guidance continue in

package/bin/claude-accounts

@@ -86,8 +86,7 @@ USAGE
       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
+  claude-accounts self-update               update this npm/git install; logs to update.log
   claude-accounts post-sync                 (server side) seed dirs, fix perms, quick verify
 
 ENV
@@ -103,7 +102,7 @@ ENV
 EOF
 }
 
-require_manifest() { [ -f "$MANIFEST" ] || die "no manifest at $MANIFEST — run install.sh first"; }
+require_manifest() { [ -f "$MANIFEST" ] || die "no manifest at $MANIFEST — run claude-multiacc install first"; }
 
 next_id() {
   local n=1 id

package/bin/claude-multiacc

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+// The installer adds bin/ to PATH for git and npx installs too.
+import './cli.mjs';

package/bin/cli.mjs

@@ -2,7 +2,7 @@
 // claude-multiacc npm entrypoint. Thin dispatcher over the bash addon:
 //   claude-multiacc [install]      run install.sh (install or update, idempotent)
 //   claude-multiacc uninstall [--purge-data]
-//   claude-multiacc self-update    npm i -g claude-multiacc@latest, then re-install
+//   claude-multiacc self-update    update the running npm/git installation
 //   claude-multiacc doctor         environment + auth summary
 //   claude-multiacc <accounts...>  passthrough to claude-accounts (list/status/add/...)
 // A globally-installed package auto-runs install.sh on (re)install via postinstall, so
@@ -59,10 +59,10 @@ mirror to a deploy server. No API keys — Claude and ChatGPT subscription login
 USAGE
   claude-multiacc [install]            install or update the addon (idempotent)
   claude-multiacc uninstall [--purge-data]
-  claude-multiacc self-update          update to the latest npm release + re-install
+  claude-multiacc self-update          update this npm/git installation + re-install
   claude-multiacc doctor               show environment + account health (both pools)
   claude-multiacc <cmd> [args...]      run a claude-accounts command, e.g.
-                                       list | status | add <email> | login <acct-NN> |
+                                       list | status | add [email] | login <acct-NN> |
                                        remove <acct-NN> | sync | verify | limits | health
   claude-multiacc codex <cmd> [args...]  same commands for the Codex pool
                                        (runs codex-accounts <cmd>)
@@ -71,6 +71,12 @@ USAGE
   claude-multiacc -v | --version
   claude-multiacc -h | --help
 
+ACCOUNT COMMANDS (also installed directly by npm)
+  claude-accounts verify              verify the Claude pool
+  codex-accounts verify               verify the Codex pool
+  claude-accounts --help              all Claude account commands and options
+  codex-accounts --help               all Codex account commands and options
+
 INSTALL
   npm install -g claude-multiacc       # postinstall wires up the PATH shims + schedules
   # or, no global install:
@@ -91,23 +97,14 @@ switch (cmd) {
   case 'uninstall':
     status = runInstall(['--uninstall', ...argv.slice(1)]);
     break;
-  case 'self-update': {
-    console.log('Updating claude-multiacc from npm…');
-    const up = sh('npm', ['install', '-g', `${pkg.name}@latest`]);
-    if (up !== 0) {
-      console.error(
-        'npm update failed — is this a global npm install? '
-        + '(git checkouts update with: git pull && ./install.sh)',
-      );
-      status = up;
-      break;
-    }
-    // The freshly-installed global package re-runs its own postinstall, so the addon
-    // is already reconciled; nothing else to do here.
-    console.log('Updated. Open a new shell to pick up any PATH changes.');
+  case 'self-update':
+    status = runAccounts(argv);
     break;
-  }
   case 'doctor': {
+    if (argv.slice(1).some(arg => arg === '--help' || arg === '-h')) {
+      console.log(HELP);
+      break;
+    }
     console.log('== claude pool ==');
     const claudeStatus = runAccounts(['status']);
     console.log('\n== codex pool ==');
@@ -128,6 +125,7 @@ switch (cmd) {
     break;
   case '-h':
   case '--help':
+  case 'help':
     console.log(HELP);
     break;
   default:

package/bin/codex

@@ -122,6 +122,127 @@ sel_log() {
   printf '%s %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$*" 2>/dev/null >> "$ACC_ROOT/selection.log" || true
 }
 
+# ---- one index for the shared session tree -----------------------------------------
+# codex keeps a SQLite index of the rollout tree beside it (state_<schema>.sqlite) and
+# refuses to start until that index has been BACKFILLED from every rollout under
+# $CODEX_HOME/sessions — each file read whole. The installed layout shares one tree
+# across every account (<acct>/sessions -> ~/.codex/sessions), so a private index per
+# account meant one full scan of the whole tree per account: 10 GB × 12 on a busy Mac,
+# minutes each, and a launch that met another process's unfinished scan died after 30 s
+# with "timed out waiting for state db backfill … (status: running)" — surfaced as the
+# CLI's damaged-database message. A scan cut short (a probe with a timeout, Ctrl-C) also
+# left its 15-minute worker lease behind, so the account stayed unstartable long after
+# its killer was gone (my-mini 2026-09-09: six fresh accounts, every launch refused).
+#
+# A shared tree gets ONE shared index: <acct>/state_N.sqlite is a symlink to the same
+# file under ~/.codex, exactly like the tree it describes. SQLite resolves that symlink
+# before naming its -wal/-shm companions, so every process shares one lock set — the
+# multi-process mode a single CODEX_HOME already runs in. A private index that already
+# exists and nothing holds open is retired beside the link (never deleted), or promoted
+# into the home when the home has none yet; and the index the installed binary will
+# create next is linked ahead of time, so a schema bump still costs one backfill, not one
+# per account. Structural on purpose: a real (private) session tree keeps a private index.
+# lib/common.sh carries the same function for seeding — keep the two in step.
+# CORE — byte-identical in lib/common.sh; tests diff them.
+state_index_names() { # $1 acct dir, $2 home dir -> the index file names either side holds
+  local f name seen=" "
+  for f in "$2"/state_[0-9]*.sqlite "$1"/state_[0-9]*.sqlite; do
+    [ -e "$f" ] || [ -L "$f" ] || continue          # an unmatched glob is the pattern itself
+    name="${f##*/}"
+    case "$seen" in *" $name "*) continue ;; esac
+    seen="$seen$name "
+    printf '%s\n' "$name"
+  done
+}
+
+installed_state_index_name() { # the index file the installed binary creates; memoized per binary
+  local cache="$ACC_ROOT/.state-index" bin="$REAL" real id line name="" nat
+  # macOS `stat` reports a SYMLINK's own mtime, and codex is usually installed behind a
+  # stable launcher symlink — so the memo has to key on the file the link resolves to.
+  real="$(canon_path "$bin")"
+  id="$real:$(file_mtime "$real")"
+  if [ -f "$cache" ]; then
+    IFS= read -r line < "$cache" 2>/dev/null || line=""
+    case "$line" in "$id "*) printf '%s\n' "${line#"$id "}"; return 0 ;; esac
+  fi
+  # The npm launcher is a script; the schema name lives in the native binary vendored
+  # beside it. Try the launcher first (a bare binary answers directly), then the vendor.
+  for nat in "$bin" "$(dirname "$(canon_path "$bin")")"/../node_modules/@openai/codex-*/vendor/*/bin/codex; do
+    [ -f "$nat" ] || continue
+    name="$(LC_ALL=C grep -a -o -m1 'state_[0-9][0-9]*\.sqlite' "$nat" 2>/dev/null | head -1)"
+    [ -n "$name" ] && break
+  done
+  case "$name" in *[!A-Za-z0-9_.]*) name="" ;; esac
+  { printf '%s %s\n' "$id" "$name" > "$cache.$$" && mv -f "$cache.$$" "$cache"; } 2>/dev/null \
+    || rm -f "$cache.$$" 2>/dev/null
+  printf '%s\n' "$name"
+}
+
+# CORE — byte-identical in lib/common.sh; tests diff them.
+shared_index_rejected() { # $1 acct dir, $2 index name, $3 shared target
+  # True when codex's own corruption recovery moved THIS account's link out of the way:
+  # it renames the database it judged damaged (and its -wal/-shm) into
+  # <CODEX_HOME>/db-backups/sqlite-<ts>-<n>/ and rebuilds, and under a link that renames
+  # the LINK. A link sitting in there pointing at the shared file is codex's verdict on
+  # that file, so this account keeps the index codex rebuilt for it and this name is
+  # left alone — handing the link back would hand the damage back.
+  local marker
+  for marker in "$1"/db-backups/*/"$2"; do
+    [ -L "$marker" ] || continue
+    [ "$(readlink "$marker" 2>/dev/null)" = "$3" ] && return 0
+  done
+  return 1
+}
+
+# CORE — byte-identical in lib/common.sh; tests diff them.
+share_state_index_links() { # $1 acct dir, $2 home dir, $3 extra index name ('' for none)
+  local d="$1" home="$2" name names target link retired n
+  [ -L "$d" ] && return 0                              # adopted: the dir IS the home
+  [ -L "$d/sessions" ] || return 0                     # a private tree keeps its private index
+  [ "$(readlink "$d/sessions" 2>/dev/null)" = "$home/sessions" ] || return 0
+  [ -d "$home" ] || return 0
+  names="$(state_index_names "$d" "$home")"
+  case "${3:-}" in ''|*[!A-Za-z0-9_.]*) ;; *) names="$names $3" ;; esac
+  for name in $names; do
+    target="$home/$name"; link="$d/$name"
+    [ -L "$link" ] && continue                         # already shared (or pointed elsewhere on purpose)
+    shared_index_rejected "$d" "$name" "$target" && continue
+    if [ ! -e "$link" ]; then
+      ln -s "$target" "$link" 2>/dev/null || true      # a new account: the whole point
+      continue
+    fi
+    # This account has an index of its own, and MOVING one that a process can still open
+    # is unsafe. codex holds the state database through an sqlx pool that opens its
+    # connections lazily and BY PATH (max_connections(5), create_if_missing(true) —
+    # codex-rs/state/src/sqlite.rs open_read_write_pool), so a rename under a live holder
+    # leaves connection 1 on the old inode while every connection the pool opens
+    # afterwards follows the new link: one process, two databases. A -wal or a -shm beside
+    # the file is that proof. A codex killed mid-write leaves them behind too, and the
+    # next clean session on the account removes them, so this heals itself in time.
+    { [ -e "$link-wal" ] || [ -e "$link-shm" ]; } && continue
+    if [ -e "$target" ]; then
+      retired="$link.private"; n=0                     # never overwrite an earlier copy
+      while [ -e "$retired" ] && [ "$n" -lt 100 ]; do n=$((n+1)); retired="$link.private.$n"; done
+      [ -e "$retired" ] && continue
+      mv "$link" "$retired" 2>/dev/null || continue
+    else
+      # Atomic or nothing: link(2) refuses an existing target, so two shims racing to be
+      # the first to promote cannot rename one's fresh symlink onto the file the other
+      # just promoted — which is how a self-referential shared index (ELOOP, and every
+      # account on the Mac unable to start) could appear. A cross-device link simply
+      # fails and this account keeps its own index.
+      ln "$link" "$target" 2>/dev/null || continue
+      [ -L "$link" ] || rm -f "$link"
+    fi
+    ln -s "$target" "$link" 2>/dev/null || true
+  done
+  return 0
+}
+
+share_state_index() { # $1 acct dir — at launch: the home's index, plus the one this binary will create
+  share_state_index_links "$1" "${HOME:-/nonexistent}/.codex" "$(installed_state_index_name)"
+}
+
 marker_active() { # true if $1/.limited is still in force; clears cleanly-expired markers
   # Parity with bin/claude's client_marker_recovered, by construction: this shim has NO
   # telemetry-based clearing path. A marker leaves here only when its OWN reset epoch has
@@ -521,6 +642,7 @@ if [ -n "${CODEX_ACCOUNT:-}" ]; then
   d="$ACC_ROOT/$CODEX_ACCOUNT"
   if [ -d "$d" ]; then
     sel_log "$CODEX_ACCOUNT pinned pwd=$PWD"
+    share_state_index "$d"
     export CODEX_HOME="$d"
     export CODEX_SHIM_ACTIVE=1
     exec "$REAL" "$@"
@@ -805,6 +927,7 @@ if [ "${CODEX_SHIM_RETRY:-1}" != "0" ] && [ "${#eligible[@]}" -ge 2 ]; then
   fi
 fi
 
+share_state_index "$pick"
 if [ "$wants_retry" = "0" ]; then
   export CODEX_HOME="$pick"
   exec "$REAL" "$@"
@@ -906,6 +1029,7 @@ while :; do
     if [ -n "$next" ]; then
       sel_log "retry from=$(basename "$cur") to=$(basename "$next") rc=$rc"
       cur="$next"
+      share_state_index "$cur"
       # The account that actually serves the work is the one the next run should rotate
       # away from — not the one that bounced.
       remember_pick "$cur"

package/bin/codex-accounts

@@ -90,8 +90,7 @@ USAGE
       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 self-update                update this npm/git install; logs to update.log
   codex-accounts post-sync                  (server side) seed dirs, fix perms, quick verify
 
 ENV
@@ -108,7 +107,7 @@ ENV
 EOF
 }
 
-require_manifest() { [ -f "$MANIFEST" ] || die "no manifest at $MANIFEST — run install.sh first"; }
+require_manifest() { [ -f "$MANIFEST" ] || die "no manifest at $MANIFEST — run claude-multiacc install first"; }
 
 next_id() {
   local n=1 id

package/bin/multiacc-select

@@ -30,6 +30,10 @@ def _strict_object(pairs: list[tuple[str, object]]) -> dict:
 
 
 def main() -> int:
+    if sys.argv[1:] in (["--help"], ["-h"]):
+        print("usage: multiacc-select --request-json - --response-json -\n"
+              "       multiacc-select --version")
+        return 0
     if sys.argv[1:] == ["--version"]:
         print(SELECTOR_VERSION)
         return 0

package/docs/ACCOUNT_OPERATIONS.md

@@ -370,65 +370,7 @@ The codex shim honors the same switches spelled `CODEX_*`: `CODEX_ACCOUNT`,
 300s — weekly markers never clear early), `CODEX_ACCOUNTS_ROOT` (legacy
 `CODEX_ACCOUNTS_DIR`), `CODEX_MULTIACC_SYNC_TARGET`, `CODEX_MULTIACC_THRESHOLD`.
 
-## Verification
+## Verification and troubleshooting
 
-```bash
-tests/run-tests.sh            # 645 sandboxed compatibility tests, no quota
-claude-accounts verify        # real matrix: `claude -p "reply OK"` per authed account
-claude-accounts verify --quick# auth presence/expiry only, no inference
-claude-accounts limits        # live per-bucket usage incl. the Fable bucket
-claude-accounts health        # limits + full verify, logs to health.log, notifies on failure (Mac)
-```
-
-Verified end-to-end on both machines (2026-07-13): full matrix PASS, 20-invocation shim
-spread clean, real project `-p` through the shim OK on Mac (`~/pipeline`) and server
-(`/opt/inapp-onboarding`), uninstall→stock→reinstall roundtrip byte-identical, three
-server systemd services (`vpn-server-management`, `inapp-onboarding`, `vpn-seo-panel`)
-repointed via `CLAUDE_BIN=/usr/local/bin/claude` and restarted healthy.
-
-## Troubleshooting
-
-- **`claude` resolves to the real binary, not the shim** — open a new shell, or check
-  that the marked block is the LAST PATH manipulation in your rc file
-  (`grep -A2 'claude-multiacc >>>' ~/.zshrc`).
-- **An account never gets picked** — `claude-accounts status`: no auth on this machine,
-  a dead login (`selectable: NO`, see `claude-accounts expired`), or an active `.limited`
-  marker (shows bucket + minutes to reset).
-- **"Failed to authenticate: OAuth session expired and could not be refreshed"** — the
-  login behind that run is dead. Run `claude-accounts expired` to see which, then
-  `claude-accounts relogin`. Accounts in that state are excluded from selection
-  automatically, so this only surfaces when *every* account needs a re-login (the shim
-  then falls back to the machine's own `~/.claude` login) or when it was pinned with
-  `CLAUDE_ACCOUNT`.
-- **"Please run /login · API Error: 401 OAuth access token is invalid"** — the portable
-  setup-token is rejected even though its presence and `claude auth status` look healthy.
-  The shim now runs a private first-use inference, parks a rejected token, and reselects
-  before direct, TUI, or `--resume` work sees the 401. Run `claude-accounts verify` to
-  check every token immediately; `claude-accounts expired` reports token-only accounts
-  as `UNVERIFIED` until that proof exists.
-- **Everything marked limited** — the shim still runs: the still-serving limited accounts
-  go through the same two cuts (session gate, then strict best-weekly) and one is handed
-  out anyway; check `selection.log` for `all-limited fallback=` lines.
-- **Sync fails** — `tail ~/.claude-accounts/sync.log`; it's ssh/rsync to the manifest's
-  `server` (BatchMode — needs key auth).
-- **A service bypasses the shim** — it spawns an absolute path. Point its env
-  (`CLAUDE_BIN` etc.) at `/usr/local/bin/claude`. Docker-internal `claude` installs
-  (e.g. openclaw live-test containers) are out of scope for a host shim.
-- **`add` sign-in says "Sign in again to continue"** — that's Claude's step-up
-  authentication, not a tool error: granting a long-lived token needs a *recent* sign-in.
-  Open a fresh incognito window, sign in to the target account at claude.ai **first**,
-  then paste the link and approve. The approval scope is `user:inference`
-  (*"Contribute to your Claude subscription usage"*) — that's correct and minimal.
-- **Limits look stale** — launchd: `launchctl list | grep claude-multiacc`;
-  cron: `crontab -l | grep claude-multiacc`. The shim also kicks a refresh when data
-  is >3 min old.
-
-## Security notes & known risks
-
-- Tokens and credentials live as 0600 files under `~/.claude-accounts` (and
-  `/root/.claude-accounts` on the server). Server compromise = account access.
-- `selection.log` records timestamps/account/cwd only — never prompt text.
-- Rotating multiple subscriptions to spread usage may be flagged by anti-abuse systems;
-  accounts can be banned for limit circumvention. Known and accepted by the operator.
-- The usage endpoint is the internal one `/usage` consumes; if it changes shape, limit
-  tracking fails open (accounts stay available, error-retry is the backstop).
+See [verification commands and troubleshooting](VERIFICATION.md), including the
+packed npm command checks, account health, shell PATH setup, and security notes.

package/docs/CODEX.md

@@ -0,0 +1,83 @@
+# Codex support (OpenAI Codex CLI)
+
+Codex uses the same machinery as the [Claude pool](../README.md), with these translations:
+
+| Claude side | Codex side |
+| --- | --- |
+| `bin/claude` shim, `claude-accounts` CLI | `bin/codex` shim, `codex-accounts` CLI |
+| pool `~/.claude-accounts` | pool `~/.codex-accounts` |
+| `CLAUDE_CONFIG_DIR` per-account dirs | `CODEX_HOME` per-account dirs |
+| `.credentials.json` / macOS Keychain item (OAuth, machine-local) | `auth.json` (ChatGPT OAuth, machine-local) |
+| `claude -p` auto-retry | `codex exec` auto-retry |
+| Anthropic OAuth usage and Fable buckets | Codex usage endpoint and per-model buckets |
+| `CLAUDE_*` pool controls | equivalent `CODEX_*` controls |
+
+Same selection rule (session gate first — `CODEX_MULTIACC_SESSION_GATE`, default 50 —
+then the 30-point weekly-headroom band with random spread, ≥90% any-bucket
+exclusion, peers rotate), same marker semantics (`.limited` cooldowns, `.expired` parks with
+credential/policy scoping and soft expiry), same fail-open guarantees, same sync
+safety guards. The `codex` shim engages the buffered auto-retry only for
+`codex exec` runs with finite stdin, exactly like `-p` on the claude side.
+
+Codex-specific notes:
+
+- **Auth is the Codex device-code sign-in by default**: `codex-accounts add` 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 — there
+  is no portable setup-token equivalent for Codex, so a server account is signed in
+  ON the server the same way. `--browser` opts into the localhost browser-callback
+  flow instead (only works when the browser runs on the same machine — the callback
+  goes to `localhost:1455`). Either way the login runs with `CODEX_HOME` pointed at
+  the account dir, and identity is verified offline from the id-token before
+  anything is registered.
+- **`auth.json` is never synced** in either direction, for the same reason
+  `.credentials.json` never is: the refresh token rotates, and two machines
+  refreshing one grant strand each other. Sync pushes manifest + `config.toml`
+  seeds + advisory limit state only.
+- **Windows are classified by length**, not by name: any window ≤6h counts as the
+  self-healing session signal, anything longer as durable/weekly. A hard
+  `limit_reached`/`allowed:false` verdict marks the account even if no window shows
+  ≥90%, and a reshaped payload is still scanned recursively for window-shaped
+  objects (fail open if nothing parses).
+- **Idle-account telemetry** stays fresh the same way: a long-expired access token is
+  renewed via the OAuth refresh-token grant (`auth.openai.com/oauth/token`, the CLI's
+  own public client id) and the rotated credential is persisted 0600. Overrides for
+  tests: `CODEX_MULTIACC_TOKEN_URL`, `CODEX_MULTIACC_CLIENT_ID`,
+  `CODEX_MULTIACC_USAGE_URL`.
+- **Earned usage resets are redeemed automatically at 95% used** (5% remaining) or
+  when the backend reports the limit finished. The limits refresher checks the reset
+  credits belonging to that same account, uses the soonest-expiring available credit,
+  and writes a per-account/window idempotency key before redemption so a lost response
+  or simultaneous fleet poll cannot spend a second reset. Set
+  `CODEX_MULTIACC_AUTO_RESET=0` only for emergency rollback/testing.
+  A finished-limit verdict takes precedence over a conflicting percentage. The
+  redemption key excludes unused model windows whose reset clocks move between reads.
+  Eligible accounts, including spent ones, check the credit endpoint every five
+  minutes even if the usage summary still says zero credits. A newly granted reset
+  is redeemed during that pass and clears the old limit; no-credit results are
+  checked again next pass, without waiting for the weekly reset date.
+  All authenticated accounts also report `usage.reset_credits_available` and
+  `usage.reset_credits_fetched_at` (ISO 8601) in `list/status/limits --json`.
+  The count comes from the credit endpoint, including below 95% used and with
+  automatic redemption disabled. The scheduled usage cadence bounds these reads.
+  Redemption shares that read, then reads back the remaining count after a POST;
+  no subtraction or embedded usage summary substitutes for provider evidence.
+  Zero means no available resets; missing fields mean the read was unavailable.
+  Credit identifiers remain local and selection does not use these fields.
+- **API-key logins are rejected** — ChatGPT subscription accounts only, matching the
+  addon's no-API-keys rule.
+
+```bash
+codex-accounts add                    # sign in a new ChatGPT account (device code —
+                                      # open the URL in any browser, enter the code)
+codex-accounts add --browser          # localhost browser-callback flow instead
+codex-accounts import you@example.com --id acct-01
+codex-accounts adopt acct-01
+                                      # adopt this machine's existing ~/.codex login
+codex-accounts list
+codex-accounts status
+codex-accounts verify --quick         # check local auth without inference
+codex-accounts verify                 # real codex exec call per account
+codex-accounts --help                 # all account commands and options
+claude-multiacc codex status          # same status command via the npm wrapper
+```