claude-multiacc 2.0.27 → 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
 
@@ -366,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
+npm install -g claude-multiacc@latest
+codex-accounts verify
 ```
 
-`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
-```
-
-**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-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
+```

package/docs/INSTALLATION.md

@@ -0,0 +1,91 @@
+# 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        # update the running installation + re-install
+claude-multiacc list               # Claude pool, via claude-accounts
+claude-multiacc codex list         # Codex pool, via codex-accounts
+claude-multiacc doctor             # status for both pools
+claude-multiacc install --help     # installer options
+claude-multiacc uninstall          # keep both account pools
+# To delete both pools as well: claude-multiacc uninstall --purge-data
+```
+
+After `claude-multiacc uninstall`, `npm uninstall -g claude-multiacc` also removes
+the npm package and its command links.
+
+npm links `claude-multiacc`, `claude-accounts`, `codex-accounts`, and `multiacc-select`
+into its global bin directory. If `claude-multiacc` works, both account commands work
+in that same shell, even when postinstall was skipped. The `claude` and `codex` shims
+still need the installer's PATH setup: open a new shell after installation.
+
+If an older installation says `codex-accounts: command not found`, update it:
+
+```bash
+npm install -g claude-multiacc@latest
+codex-accounts verify
+```
+
+Before updating, `claude-multiacc codex verify` runs the same verification through
+the existing npm wrapper. For git/npx installs, open a new shell or run the exact
+`export PATH=...` command printed by the installer. Run `claude-multiacc install`
+if auto-setup was skipped and the pool has no manifest yet.
+
+**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 claude-multiacc@latest` for npm installs,
+`git pull && ./install.sh` 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 https://github.com/gowalk-public/claude-multiacc.git
+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 both account pools
+```
+
+`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` (15m Claude / 5m Codex), `.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/` and `~/.codex-accounts/`, each with an `accounts.json` manifest.

package/docs/UNIFIED_SELECTOR.md

@@ -13,6 +13,8 @@ multiacc-select --request-json - --response-json -
 
 The command reads one UTF-8 JSON object from stdin and writes one JSON object to
 stdout. `multiacc-select --version` reports the selector contract version.
+`multiacc-select --help` (or `-h`) prints usage and exits successfully without
+reading stdin. All three forms also work through `claude-multiacc select`.
 
 The request schema is `claude-multiacc/pool-selection.v2` and contains:
 

package/docs/VERIFICATION.md

@@ -0,0 +1,68 @@
+# Verification and troubleshooting
+
+## Verification
+
+```bash
+tests/run-tests.sh            # sandboxed compatibility tests, no quota
+python3 tests/test_selector.py # unified selector contract
+npm run test:commands         # packed npm commands; run npm install --ignore-scripts first
+claude-accounts verify        # real matrix: `claude -p "reply OK"` per authed account
+claude-accounts verify --quick # auth presence/expiry only, no inference
+codex-accounts verify         # real codex exec call per account
+codex-accounts verify --quick  # local Codex auth check, 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).