claude-multiacc 1.0.20 → 2.0.0

package/README.md

@@ -16,8 +16,31 @@ 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). Test suite: `tests/run-tests.sh` (525 sandboxed tests, no network / no
-quota — passes on both platforms).
+(bash 5.2). The compatibility suite currently covers 644 sandboxed cases with no
+network/quota use; the unified selector has its own adversarial contract suite.
+
+## Unified selector for app-robot
+
+`DEFAULT_ENGINE=both` uses one pure selector across the Claude and Codex pools. It
+does not change either interactive shim and never launches an agent itself:
+
+```bash
+multiacc-select --request-json - --response-json -
+# equivalent npm dispatcher:
+claude-multiacc select --request-json - --response-json -
+```
+
+The command reads one strict UTF-8 JSON request and emits one JSON response using
+the versioned `claude-multiacc/pool-selection.v2` protocol. It ranks the caller's
+locked candidate snapshot by usable weekly/session headroom and returns one concrete
+provider/account plus canonical snapshot and selection digests. `both` is a policy,
+never an execution engine. The caller remains responsible for durable reservations,
+database locks, retries, and launching the selected CLI.
+
+Run `multiacc-select --version` for the selector protocol version. The npm package
+version is independent and remains available through `claude-multiacc --version`.
+See [the complete selector contract](docs/UNIFIED_SELECTOR.md) for the request fields,
+ranking rules, stable errors, and caller boundary.
 
 ---
 
@@ -122,7 +145,7 @@ and backs off on **every** non-2xx, not just a 429 — honoring `Retry-After`, a
 for 6 h on a refusal the server marks `x-should-retry: false`. `limits --force` overrides
 all of it. The cadence is deliberately unhurried: several machines polling the same
 accounts every minute earns a 429 with `Retry-After: 3600`, and telemetry then goes stale
-for an hour at a time — which is exactly when every account starts scoring *neutral* and
+for an hour at a time — which is exactly when every account starts scoring *unknown* and
 the picker loses its ability to tell them apart.
 
 > **The usage endpoint needs an OAuth login, not a setup token.** A portable
@@ -131,7 +154,7 @@ the picker loses its ability to tell them apart.
 > user:profile`: setup tokens are minted without that scope. So an account whose
 > `.credentials.json` grant has lapsed keeps working perfectly while going **permanently
 > dark for telemetry**, and a pool where that happens to every account ranks everything
-> neutral and picks at random. `claude-accounts status` says `RANKING IS BLIND` when the
+> unknown and picks at random. `claude-accounts status` says `RANKING IS BLIND` when the
 > pool is in that state, and the shim prints an hourly warning on a terminal. The fix is
 > a real sign-in on the machine that polls (`claude-accounts login <acct-NN>`); since
 > `limits.json` is one of the things `sync` pushes, only the **source** machine needs it —
@@ -145,7 +168,7 @@ working accounts, while the cutoff declares one unusable, and an account reading
 hour ago may be well past 90% now. When nothing is in-window at all, a stale weekly
 reading is still used **if its bucket has not reset yet** (a weekly bucket only rises
 until then, so the number remains a true lower bound) — logged as `ranking=DEGRADED`.
-Only when even that is unavailable does selection fall back to neutral, logged as
+Only when even that is unavailable does selection rank the account last, logged as
 `ranking=BLIND`.
 
 If an account's OAuth access token has been expired for a while (idle account,
@@ -232,12 +255,12 @@ 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`, server `/root/.claude-accounts` | pool `~/.codex-accounts`, server `/root/.codex-accounts` |
+| pool `~/.claude-accounts` | pool `~/.codex-accounts` |
 | `CLAUDE_CONFIG_DIR` per-account dirs | `CODEX_HOME` per-account dirs |
 | `.credentials.json` (OAuth, machine-local) | `auth.json` (ChatGPT OAuth, machine-local) |
 | `claude -p` auto-retry | `codex exec` auto-retry |
-| Anthropic OAuth usage endpoint, per-model Fable bucket | `chatgpt.com/backend-api/codex/usage`, per-model buckets (e.g. `GPT-5.3-Codex-Spark:5h/7d`) |
-| `CLAUDE_ACCOUNT` / `CLAUDE_SHIM_RETRY` / `CLAUDE_MULTIACC_DISABLE` / … | `CODEX_ACCOUNT` / `CODEX_SHIM_RETRY` / `CODEX_MULTIACC_DISABLE` / … |
+| Anthropic OAuth usage and Fable buckets | Codex usage endpoint and per-model buckets |
+| `CLAUDE_*` pool controls | equivalent `CODEX_*` controls |
 
 Same selection rule (weekly headroom primary, session tiebreak, ≥90% any-bucket
 exclusion, equal scores rotate), same marker semantics (`.limited` cooldowns, `.expired` parks with
@@ -348,397 +371,6 @@ What install does (all reversible, nothing else):
   cron entries for limits/health (both providers) + the daily auto-update.
 - Both: `~/.claude-accounts/` skeleton + `accounts.json` manifest.
 
-## Accounts
-
-```bash
-claude-accounts list      # pool at a glance
-claude-accounts status    # per-account auth health, per-bucket limits incl. Fable, markers, last pick
-claude-accounts expired   # ONLY the accounts that cannot authenticate, and why (exit 1 if any)
-claude-accounts relogin   # sign those back in, one at a time (ids or --all to pick your own)
-```
-
-Every account in the pool is authenticated — `add` cannot register one otherwise.
-
-### When an account stops working
-
-Subscription logins expire (the refresh token has a finite life), can be revoked from
-claude.ai, and an organization can disable Claude Code for one of its accounts entirely.
-Such an account is **never selected** — `claude` keeps working on the healthy ones — and
-shows up here:
-
-```bash
-claude-accounts expired
-#   acct-01   support@example.com   EXPIRED   refresh token expired 2026-08-05 (2d ago)
-#                                             fix: claude-accounts relogin acct-01
-#   acct-08   dev@example.com       BLOCKED   this account's organization has disabled
-#                                             Claude Code subscription access
-#                                             fix: claude-accounts relogin acct-08
-
-claude-accounts relogin              # re-authenticate everything a sign-in can fix
-claude-accounts relogin acct-01      # or just one
-claude-accounts relogin acct-01 --token   # portable token instead (Mac + server)
-```
-
-`relogin` covers `BLOCKED` accounts too — a fresh sign-in re-issues the grant and usually
-clears the block. Use `claude-accounts verify` (a real `-p` call per account) to re-test
-one at any time; a PASS clears the park automatically.
-
-`relogin` runs the same verified sign-in as `login` (it refuses to save a credential for
-the wrong email), one account at a time, and syncs to the server once at the end.
-`expired` exits **1** when anything needs a human, so it drops straight into a cron or
-monitoring check. `list` tags such accounts `EXPIRED-LOGIN`, and `status` says
-`selectable: NO` with the reason.
-
-### Adopt this machine's existing login (no browser needed)
-
-```bash
-claude-accounts import you@example.com --id acct-01 --home mac
-claude-accounts adopt acct-01
-```
-
-`adopt` makes the account dir a **symlink to `~/.claude`** — the machine's existing
-login joins the pool with a single credential file (no copy of the OAuth grant exists
-anywhere else, so refreshes can never race). This is how the two current accounts run:
-acct-01 = the Mac's login, acct-02 = the server's login (adopted server-side).
-
-### Add a fresh account (~1 min, one browser sign-in)
-
-```bash
-claude-accounts add               # no email needed — read back from the sign-in
-# or name it explicitly (fast-fails on a duplicate, and pre-fills the login page):
-claude-accounts add new@example.com
-```
-
-This runs the **normal full Claude Code login** — the exact same
-`claude auth login` flow the app itself uses (`claude.com/cai/oauth/authorize`, full
-Claude Code scopes). A browser opens (or a sign-in link is printed); sign in to the
-account you're adding, approve, and if a code is shown, paste it back. It draws on the
-subscription — never API keys.
-
-Using the full login on purpose: it does **not** hit the *"Sign in again to continue"*
-step-up wall that the narrow long-lived-token grant triggers, and it stores an
-auto-refreshing `.credentials.json`. That credential is **machine-local** (never synced),
-which is what keeps two machines from invalidating each other's refresh token — so an
-account you `add` on the Mac runs on the Mac, and you `add` it on the server (over SSH) if
-you want it there too. The account is registered **only after the signed-in email is read
-back**; an aborted login leaves nothing behind, and duplicate emails are refused.
-
-```bash
-claude-accounts login acct-NN         # complete/refresh an existing account (full login)
-claude-accounts add new@example.com --token   # portable setup-token instead: works on BOTH
-                                              # machines and syncs to the server, but needs a
-                                              # recent sign-in (may show the step-up screen)
-claude-accounts login acct-NN --token         # same, for an existing account
-```
-
-Use `--token` when you specifically want one account usable on the server via the Mac's
-sync (the ~1-year inference-only token that mirrors over). For everyday adds, the default
-full login is smoother. `status` warns when a token nears end of life; re-run `login`.
-
-### A setup token has no identity — name the account yourself
-
-A setup token is minted with scope `user:inference` **alone**, so `claude auth status`
-answers `{loggedIn, authMethod, apiProvider}` and no email — only an OAuth login reports
-`email`/`orgId`/`subscriptionType`. Nothing on this side can therefore learn which account
-approved a `setup-token` grant, and no future check will change that.
-
-What follows, and what the CLI does about it:
-
-- **`add <email> --token` requires the email** — there is nothing to read the account back
-  from. It registers under the name you gave and says so; naming no email is refused
-  outright rather than registering an anonymous slot.
-- **`mint <acct-NN>` names the account in its prompt** (`approve in a browser signed in as
-  …`) and warns afterwards that the identity is unverifiable. Approving in a window signed
-  into a *different* account silently binds that account's subscription to the slot —
-  every machine then runs it under the wrong name. Sign in to the right account **first**,
-  in a fresh private window, then paste the link.
-- `login <acct-NN> --token` compares against the manifest when an identity is readable
-  (it is not, today) and otherwise says what it is trusting.
-
-Both accounts currently in the pool are live and verified: acct-01 (support@gowalkae.com,
-Mac) and acct-02 (hasan@gowalkqa.com, server) — each adopted from its machine's existing
-login, so each runs on the machine that holds its credential.
-
-### Remove
-
-```bash
-claude-accounts remove acct-NN          # deletes locally, propagates to the server
-```
-
-## Sync (multi-machine)
-
-One machine is the **source of truth**; every other machine is a **target**. Sync is
-one-way, fired automatically by `add`/`import`/`remove`/`mint` on the source and
-manually via:
-
-```bash
-claude-accounts sync      # and codex-accounts sync for the codex pool
-```
-
-Targets are the resolved sync target — env override, else the manifest's
-`server`/`server_root`/`server_repo` (the Linux box), see *Pointing sync somewhere else*
-below — plus an optional `peers` array for additional machines (e.g. a second Mac):
-
-```json
-"peers": [{"target": "gas@gas-mini", "root": "/Users/gas/.claude-accounts",
-           "repo": "/Users/gas/claude-multiacc"}]
-```
-
-Every target gets the manifest + per-account `server.token` (0600, claude pool) +
-one-time seeds + advisory limit state; **never** `.credentials.json` or codex
-`auth.json` in either direction (their refresh tokens rotate — two machines
-refreshing one grant invalidate each other; codex accounts are signed in per
-machine with the device-code flow instead). Removals propagate to every target; an
-empty/corrupt manifest — or one with an invalid target/peer shape — refuses to sync
-before anything is pushed anywhere. After every push each target re-seeds dirs and
-re-runs its quick verification matrix (`post-sync` hook). Everything logs to
-`sync.log`; failures are loud and non-zero.
-
-A target machine's pool carries a `sync-role` file containing `replica`: such a pool
-**never pushes** (manually or via auto-sync) — the source machine owns the account
-set, which is what prevents two machines from overwriting each other's manifests.
-Make account changes on the source; sign-ins (`login`/`relogin`) still happen on
-whichever machine needs the credential.
-
-### Pointing sync somewhere else (or nowhere)
-
-The target is no longer baked in. In precedence order:
-
-1. `CLAUDE_MULTIACC_SYNC_TARGET` / `CODEX_MULTIACC_SYNC_TARGET` (or the provider-neutral
-   `MULTIACC_SYNC_TARGET`), plus `…_SYNC_ROOT` and `…_SYNC_REPO` — env, so a daemon can
-   point one instance at its own target without rewriting a manifest it does not own;
-2. the manifest's `server` / `server_root` / `server_repo` (what `install.sh --server`
-   wrote);
-3. the historical default — unchanged, so existing installs keep pushing where they did.
-
-A pool whose `sync-role` file says `replica` still never pushes, in any mode — the
-marker is honored and reported before anything else, and local-only mode below only
-narrows it further (a local pool pushes nothing whether or not it is a replica).
-
-The value **`none`** (also `local`, `off`, `disabled`, empty) selects **local-only** mode:
-there is no ssh target at all because something else — the app-robot panel and its runner
-daemon — distributes the pool. `sync` then validates the manifest, re-seeds account dirs,
-fixes permissions and pushes nowhere; mutations stop auto-pushing (and stop warning about
-a server they are not supposed to reach). One run can force it with `sync --no-server`,
-and a whole install can start that way:
-
-```bash
-./install.sh --no-server          # manifest server = none
-claude-accounts sync              # "sync ok (local-only: … nothing pushed)"
-claude-accounts sync --no-server  # same, whatever the manifest says
-```
-
-## Fleet integration (panels, daemons, multiple instances)
-
-Everything below is non-interactive and machine-readable: it is what a supervising panel
-(app-robot) or any other daemon needs to run a pool across a fleet of Macs.
-
-### `--json` on `list`, `status` and `limits`
-
-```bash
-claude-accounts list --json      # pool + accounts, no refresh
-claude-accounts status --json    # the same, plus last_picked and credential detail
-claude-accounts limits --json    # refresh usage first, then emit the same document
-codex-accounts  list --json      # identical schema, provider: "codex"
-```
-
-Stdout is the JSON document and nothing else. One shape for every verb and both
-providers (`lib/report.py`), so a consumer writes one parser:
-
-```jsonc
-{
-  "schema": "claude-multiacc/pool.v1",   // bumped only on a breaking change
-  "provider": "claude", "kind": "list", "generated_at": "…Z",
-  "machine": "mac", "host": "my-mini",
-  "pool": {
-    "root": "/Users/gas/.claude-accounts", "manifest": "…/accounts.json",
-    "threshold": 90,
-    "sync": {"mode": "server|local", "target": "root@…", "root": "…", "repo": "…",
-             "role": "source|replica", "peers": [...]}
-  },
-  "accounts": [{
-    "id": "acct-05", "email": "…", "home": "mac", "added_at": "…Z",
-    "home_dir": "/Users/gas/.claude-accounts/acct-05", "adopted": false,
-    "status": "active",            // active|limited|expired|blocked|missing|remote
-    "state": "ok", "label": "OK", "reason": "…", "fix": "…",
-    "selectable": true, "needs_login": false,
-    "credential_class": "portable", // portable|machine-local|none
-    "portable": true,
-    "credentials": {"oauth": true, "token": true, "oauth_expires_at": "…Z",
-                    "oauth_refresh_expires_at": "…Z", "token_minted_at": "…Z",
-                    "token_age_days": 39},
-    "limited": false, "limit_reset_at": null, "limit_detail": null,
-    "usage": {"fetched_at": "…Z", "age_seconds": 41, "source": "oauth",
-              "max_percent": 62, "weekly_percent": 62, "session_percent": 18,
-              "buckets": [{"name": "weekly_scoped:Fable", "group": "weekly",
-                           "percent": 62, "resets_at": "…Z"}]}
-  }],
-  "summary": {"total": 3, "active": 2, "limited": 1, "needs_login": 0,
-              "portable": 3, "selectable": 2},
-  "warnings": []
-}
-```
-
-`status` values mean exactly what the shim does: only `active` accounts are selected;
-`limited` authenticates but is parked until `limit_reset_at`; `expired`/`blocked`/
-`missing` need a human (`fix` says what); `remote` is not logged in here on purpose.
-A consumer that only distinguishes *usable / parked / needs-a-human* can read
-`selectable` and `needs_login` and ignore the rest; `state` keeps the raw audit verdict
-without the limit overlay. `limited` follows the shim's marker rule exactly — a marker
-whose reset time has passed does not count, an unreadable one does.
-
-### Which accounts are portable
-
-| Credential | Where it lives | Class | Can it be copied to another machine? |
-| --- | --- | --- | --- |
-| claude setup-token | `<acct>/server.token` (`sk-ant-oat…`, ~1 year, inference-only) | **portable** | **Yes** — this is the only credential the fleet distributes |
-| claude OAuth login | `<acct>/.credentials.json` | machine-local | **No.** Its refresh token rotates on every refresh; a second machine refreshing the same grant strands the first |
-| codex ChatGPT login | `<acct>/auth.json` | machine-local | **No** — same rotating-refresh-token reason. Codex has **no** portable credential type |
-
-Non-portable accounts are not a dead end: they show up as `credential_class:
-"machine-local"`, and the way to run one somewhere else is one interactive sign-in there
-(`claude-accounts login <id>`, `codex-accounts login <id>` — the codex device-code flow
-works over SSH). A claude account can be *converted* to the portable class with one
-`claude-accounts mint <id>` on a machine that is already signed in.
-
-### `export-credential` / `import-credential`
-
-```bash
-claude-accounts export-credential acct-05                 # blob to stdout
-claude-accounts export-credential acct-05 --out cred.json # …or to a 0600 file
-claude-accounts export-credential acct-05 --identity-only # registry entry, no secret
-cat cred.json | claude-accounts import-credential         # install it here
-claude-accounts import-credential --in cred.json --home mac --no-sync
-```
-
-`export-credential` is **read-only on the source pool** — nothing is refreshed, re-minted
-or marked, so exporting a live account cannot disturb it. It refuses anything that is not
-portable, with the reason and the fix, and its exit code is the contract a daemon branches
-on:
-
-| Exit | Meaning |
-| --- | --- |
-| 0 | blob written |
-| 2 | usage error / unknown account / malformed blob |
-| 3 | the credential is machine-local — copying it would break both machines |
-| 4 | the account has no credential material here |
-| 5 | credential present but unusable (corrupt, or an API key rather than a setup-token) |
-
-The blob is self-contained JSON (`format: "claude-multiacc/credential"`, version 1):
-identity metadata (`id`, `email`, `home`, `added_at`), where it came from, and — for
-class `portable` — the credential itself. **Treat a `portable` blob exactly like the
-credential it contains.**
-
-`import-credential` reads it on stdin (or `--in PATH`), creates the account dir and the
-manifest entry as needed, writes the credential 0600, and clears any dead-auth marker.
-It is idempotent **by email**: re-importing an account that is already in the pool
-refreshes it in place rather than adding a second entry, so a daemon can push the same
-pool to a machine over and over. It refuses a blob from the other provider and refuses an
-API key. It also refuses to land an email in a second slot, or to write into a slot that
-belongs to a different account — `--force` settles exactly those identity conflicts, and
-nothing else: an **adopted** (symlinked) account is refused unconditionally, `--force`
-included, because writing a credential through that link would put it outside the pool.
-An `identity` blob registers the account and says which sign-in it still needs. The
-imported account keeps the `added_at` it had on the source machine, so the same account
-reads identically everywhere.
-
-For codex, `export-credential` always refuses with exit 3 (there is nothing portable to
-export) and points at the device-code login; `--identity-only` is how a codex account list
-reaches another machine.
-
-### Instance-scoped pools
-
-`CLAUDE_ACCOUNTS_ROOT` / `CODEX_ACCOUNTS_ROOT` relocate a pool, so several app-robot
-instances can share one machine and user account without ever seeing each other's
-accounts. Both the CLIs **and the shims** resolve the same root, so a task launched with
-the env set runs under that instance's pool. (The older `…_ACCOUNTS_DIR` spelling still
-works; `…_ROOT` wins when both are set.)
-
-```bash
-export CLAUDE_ACCOUNTS_ROOT=/opt/app-robot/teamA/claude-accounts
-export CODEX_ACCOUNTS_ROOT=/opt/app-robot/teamA/codex-accounts
-./install.sh --no-server --instance teamA
-```
-
-An install whose roots are not the defaults is an **instance install**: its LaunchAgents
-(and cron lines on Linux) are labelled `com.claude-multiacc.<instance>.*` so instances
-never overwrite each other's agents, and they carry the pool roots in their environment.
-It deliberately does **not** touch the shell rc PATH block, `/etc/profile.d`, or the
-`/usr/local/bin` shims — one interactive PATH cannot serve two pools, and those belong to
-the default install. `--instance NAME` labels it explicitly; otherwise the label is
-derived from the pool root. Uninstalling an instance removes only that instance's agents.
-
-## Pinning & env switches
-
-| Env | Effect |
-| --- | --- |
-| `CLAUDE_ACCOUNT=acct-03` | pin this invocation to one account (wins over markers) |
-| `CLAUDE_CONFIG_DIR=...` | shim passes straight through (scripts can pin the old way) |
-| `CLAUDE_MULTIACC_DISABLE=1` | bypass selection entirely |
-| `CLAUDE_MULTIACC_CLIENT_LIMITS=0` | do not read the client's own rate-limit records (same for `CODEX_MULTIACC_CLIENT_LIMITS`) |
-| `CLAUDE_MULTIACC_CLIENT_SCAN_TTL=<s>` | how long a clean client-limit scan is memoized (default 20s; same for `CODEX_MULTIACC_CLIENT_SCAN_TTL`) |
-| `CLAUDE_SHIM_RETRY=0` | disable the `-p` auto-retry |
-| `CLAUDE_ACCOUNTS_ROOT=...` | relocate the pool — one isolated pool per app-robot instance (legacy spelling: `CLAUDE_ACCOUNTS_DIR`) |
-| `CLAUDE_MULTIACC_SYNC_TARGET=...` | sync target, overriding the manifest; `none` = local-only |
-| `CLAUDE_MULTIACC_SYNC_ROOT=... / _SYNC_REPO=...` | remote pool root / addon repo that goes with it |
-
-The codex shim honors the same switches spelled `CODEX_*`: `CODEX_ACCOUNT`,
-`CODEX_HOME` (passthrough), `CODEX_MULTIACC_DISABLE`, `CODEX_SHIM_RETRY`,
-`CODEX_SHIM_SELECT`, `CODEX_ACCOUNTS_ROOT` (legacy `CODEX_ACCOUNTS_DIR`),
-`CODEX_MULTIACC_SYNC_TARGET`, `CODEX_MULTIACC_THRESHOLD`.
-
-## Verification
-
-```bash
-tests/run-tests.sh            # 525 sandboxed 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`.
-- **Everything marked limited** — the shim still runs (least-utilized fallback);
-  check `selection.log` for `all-limited` 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).
+Account lifecycle, synchronization, fleet integration, environment switches,
+verification, troubleshooting, and security guidance continue in
+[Account and fleet operations](docs/ACCOUNT_OPERATIONS.md).

package/bin/claude

@@ -214,17 +214,17 @@ age_human() { # $1 = seconds
 # confirm this reset asymmetry — an account whose only near-full bucket is the cheap
 # session one must NOT rank behind one burning durable weekly headroom.)
 #   score = weekly%*1000 + session%      weekly,session in [0,100]
-# Stale/unreadable telemetry ranks NEUTRAL (weekly 50, session 50), never "free" —
+# Stale/unreadable telemetry ranks LAST (weekly 100, session 100), never "free" —
 # EXCEPT in a blind pool (SEL_DEGRADED=1), where a still-valid stale weekly reading is
-# used instead. Neutral is only the right answer while some other account HAS fresh
-# data to be neutral against; when no account does, neutral is just a coin flip.
+# used instead. Unknown data must never beat a truthful usage reading; when every
+# candidate is unknown, the equal worst-case scores still preserve fail-open selection.
 SEL_DEGRADED=0
 sel_score_of() { # $1 = acct dir
   local w s
   if ! w="$(fresh_field "$1" weekly_percent)" && ! w="$(fresh_field "$1" max_percent)"; then
-    if [ "$SEL_DEGRADED" = 1 ]; then w="$(stale_weekly "$1")" || w=50; else w=50; fi
+    if [ "$SEL_DEGRADED" = 1 ]; then w="$(stale_weekly "$1")" || w=100; else w=100; fi
   fi
-  s="$(fresh_field "$1" session_percent)" || s=50
+  s="$(fresh_field "$1" session_percent)" || s=100
   printf '%s\n' $((w * 1000 + s))
 }
 

package/bin/cli.mjs

@@ -46,6 +46,10 @@ function runCodexAccounts(args) {
   return sh('bash', [join(ROOT, 'bin', 'codex-accounts'), ...args]);
 }
 
+function runSelector(args) {
+  return sh(join(ROOT, 'bin', 'multiacc-select'), args);
+}
+
 const HELP = `claude-multiacc ${pkg.version}
 
 Every 'claude' / 'claude -p' AND every 'codex' / 'codex exec' runs under a
@@ -62,6 +66,8 @@ USAGE
                                        remove <acct-NN> | sync | verify | limits | health
   claude-multiacc codex <cmd> [args...]  same commands for the Codex pool
                                        (runs codex-accounts <cmd>)
+  claude-multiacc select <args...>      run the unified pool-selection.v2 selector
+                                       (JSON request/response over stdin/stdout)
   claude-multiacc -v | --version
   claude-multiacc -h | --help
 
@@ -89,7 +95,10 @@ switch (cmd) {
     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)');
+      console.error(
+        'npm update failed — is this a global npm install? '
+        + '(git checkouts update with: git pull && ./install.sh)',
+      );
       status = up;
       break;
     }
@@ -110,6 +119,9 @@ switch (cmd) {
     // Codex-pool passthrough: claude-multiacc codex list | status | add | ...
     status = argv.length > 1 ? runCodexAccounts(argv.slice(1)) : runCodexAccounts(['help']);
     break;
+  case 'select':
+    status = runSelector(argv.slice(1));
+    break;
   case '-v':
   case '--version':
     console.log(pkg.version);

package/bin/codex

@@ -144,11 +144,13 @@ fresh_field() { # fresh_field <acct dir> <json key> -> integer if telemetry fres
 # window only refills on its multi-day reset, while the ~5h window self-heals, so
 # session is a mild tiebreaker only (same reset asymmetry as the claude pool).
 #   score = weekly%*1000 + session%      weekly,session in [0,100]
-# Stale/unreadable telemetry ranks NEUTRAL (weekly 50, session 50), never "free".
+# Stale/unreadable telemetry ranks LAST (weekly 100, session 100), never "free".
+# Equal worst-case scores keep an entirely unknown pool selectable, but an unknown
+# account can never beat a candidate with truthful usage telemetry.
 sel_score_of() { # $1 = acct dir
   local w s
-  w="$(fresh_field "$1" weekly_percent)" || w="$(fresh_field "$1" max_percent)" || w=50
-  s="$(fresh_field "$1" session_percent)" || s=50
+  w="$(fresh_field "$1" weekly_percent)" || w="$(fresh_field "$1" max_percent)" || w=100
+  s="$(fresh_field "$1" session_percent)" || s=100
   printf '%s\n' $((w * 1000 + s))
 }
 

package/bin/multiacc-select

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""Strict JSON transport for the unified Claude/Codex pool selector."""
+
+from __future__ import annotations
+
+import json
+import sys
+from decimal import Decimal, DecimalException
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "lib"))
+
+from selector_policy import select  # noqa: E402
+from selector_primitives import SCHEMA, SELECTOR_VERSION  # noqa: E402
+
+
+def _invalid_json() -> dict:
+    return {"schema": SCHEMA, "selector_version": SELECTOR_VERSION, "ok": False,
+            "error_code": "invalid_request", "error_detail": {"field": "$"}}
+
+
+def _strict_object(pairs: list[tuple[str, object]]) -> dict:
+    result: dict = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError("duplicate JSON object key")
+        result[key] = value
+    return result
+
+
+def main() -> int:
+    if sys.argv[1:] == ["--version"]:
+        print(SELECTOR_VERSION)
+        return 0
+    if sys.argv[1:] != ["--request-json", "-", "--response-json", "-"]:
+        print("usage: multiacc-select --request-json - --response-json -", file=sys.stderr)
+        return 2
+    try:
+        raw = sys.stdin.buffer.read().decode("utf-8")
+        request = json.loads(
+            raw, object_pairs_hook=_strict_object, parse_float=Decimal,
+            parse_constant=lambda value: (_ for _ in ()).throw(ValueError(value)))
+        response = select(request)
+    except (UnicodeDecodeError, ValueError, json.JSONDecodeError, DecimalException):
+        response = _invalid_json()
+    print(json.dumps(response, ensure_ascii=False, allow_nan=False, separators=(",", ":")))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())