claude-multiacc 1.0.21 → 2.0.0

package/docs/ACCOUNT_OPERATIONS.md

@@ -0,0 +1,396 @@
+# Account and fleet operations
+
+## 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` | **portable** | **Yes**; the fleet-distributed credential |
+| claude OAuth login | `<acct>/.credentials.json` | machine-local | **No**; refresh tokens rotate |
+| codex ChatGPT login | `<acct>/auth.json` | machine-local | **No**; Codex has no portable credential |
+
+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` | ignore the client's own rate-limit records |
+| `CLAUDE_MULTIACC_CLIENT_SCAN_TTL=<s>` | clean client-limit scan cache; default 20s |
+| `CLAUDE_SHIM_RETRY=0` | disable the `-p` auto-retry |
+| `CLAUDE_ACCOUNTS_ROOT=...` | relocate the pool; legacy spelling is `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            # 644 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`.
+- **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).

package/docs/UNIFIED_SELECTOR.md

@@ -0,0 +1,42 @@
+# Unified Claude + Codex selector
+
+`multiacc-select` is the canonical policy engine for app-robot's
+`DEFAULT_ENGINE=both` mode. It ranks a database-locked snapshot of both subscription
+pools and returns one concrete provider/account identity. It is deliberately pure: the
+caller owns telemetry collection, row locks, durable reservation, retries and launch.
+
+## Invocation
+
+```sh
+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.
+
+The request schema is `claude-multiacc/pool-selection.v2` and contains:
+
+- a canonical database timestamp and reservation key;
+- the policy (`default_claude`, `default_codex`, `default_both`, `explicit`,
+  `producer_retry`, or `reviewer`);
+- any required provider, producer identity and explicit exclusions;
+- the runner generation's candidate telemetry plus exact reservation history.
+
+Candidates must be active, fresh, provider-capable, not currently limited, and not
+covered by a live reservation. Percentages are finite decimals clamped to 0–100.
+Canonical account IDs are NFC-normalized and trimmed with case preserved; an
+NFC/case-folded key rejects case-only duplicate identities before ranking.
+Known quota ranks ahead of unknown quota; higher minimum weekly/session headroom
+wins; equal capacity goes to the least-recently-selected account, then a stable
+Claude-before-Codex/account-id tie order.
+
+Success returns the concrete engine/account/runner generation, normalized score basis,
+an RFC 8785/SHA-256 candidate-snapshot digest and a selection digest. Stable failures
+are `invalid_request`, `unsupported_schema`, `duplicate_candidate_identity`, and
+`no_candidate`. A reviewer stays on the producer's provider and avoids its account when
+another eligible account exists.
+
+The selector does not read `~/.claude-accounts` or `~/.codex-accounts`. That would race
+the panel's transaction and make the returned digest unprovable. The individual
+`claude` and `codex` shims continue selecting directly inside their own pools for
+ordinary interactive use.

package/lib/selector_policy.py

@@ -0,0 +1,174 @@
+"""Canonical unified Claude/Codex account selection policy."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from decimal import Decimal, localcontext
+
+from selector_primitives import (
+    SCHEMA,
+    SELECTOR_VERSION,
+    canonical_sha256,
+    collision_key,
+    decimal_value,
+    identity,
+    request_error,
+    timestamp,
+)
+
+
+def _parse_times(raw: dict) -> tuple[dict, set[str]]:
+    parsed: dict[str, tuple[datetime, str] | None] = {}
+    invalid: set[str] = set()
+    for field in ("seen_at", "limited_until", "last_selected_at", "resets_at"):
+        try:
+            parsed[field] = timestamp(raw[field]) if raw.get(field) is not None else None
+        except ValueError:
+            parsed[field] = None
+            invalid.add(field)
+    return parsed, invalid
+
+
+def _reservation_state(history: dict, now: datetime) -> tuple[str | None, bool]:
+    value = history.get("active_expires_at")
+    if value is None:
+        return None, False
+    parsed, canonical = timestamp(value)
+    return canonical, parsed > now
+
+
+def normalize_candidate(raw: dict, now: datetime, ordinal: int) -> dict:
+    runner, generation, engine, account, valid_identity = identity(raw)
+    weekly, weekly_text = decimal_value(raw.get("weekly_pct"))
+    session, session_text = decimal_value(raw.get("session_pct"))
+    quota_known = weekly is not None and session is not None
+    decimals = [value for value in (weekly, session) if value is not None]
+    precision = max([6] + [len(value.as_tuple().digits)
+                           + max(0, -value.as_tuple().exponent) for value in decimals])
+    with localcontext() as context:
+        context.prec = precision + 3
+        weekly_left = Decimal(100) - weekly if weekly is not None else None
+        session_left = Decimal(100) - session if session is not None else None
+        effective = min(weekly_left, session_left) if quota_known else None
+    history = raw["reservation_history"]
+    timed = {**raw, "last_selected_at": history["last_selected_at"]}
+    parsed, invalid = _parse_times(timed)
+    active_expiry, reserved = _reservation_state(history, now)
+    seen, limited, last = parsed["seen_at"], parsed["limited_until"], parsed["last_selected_at"]
+    status = str(raw.get("status") or "").strip().lower()
+    conditions = [
+        ("invalid_identity", not valid_identity), ("status_not_active", status != "active"),
+        ("invalid_seen_at", "seen_at" in invalid),
+        ("future_telemetry", bool(seen and (seen[0] - now).total_seconds() > 30)),
+        ("stale_telemetry", bool(seen and (now - seen[0]).total_seconds() > 300)),
+        ("invalid_limited_until", "limited_until" in invalid),
+        ("account_limited", bool(limited and limited[0] > now)),
+        ("invalid_last_selected_at", "last_selected_at" in invalid),
+        ("future_last_selected_at", bool(last and (last[0] - now).total_seconds() > 30)),
+        ("provider_incapable", raw.get("provider_capable") is not True),
+        ("active_reservation", reserved)]
+    exclusion = next((code for code, applies in conditions if applies), None)
+    canon = lambda value: decimal_value(value)[1] if value is not None else None
+    return {
+        "input_ordinal": ordinal, "identity_valid": valid_identity, "runner_id": runner,
+        "runner_generation": generation, "engine": engine, "account_id": account, "status": status,
+        "weekly_pct": weekly_text, "session_pct": session_text, "quota_known": quota_known,
+        "effective_headroom": canon(effective), "weekly_remaining": canon(weekly_left),
+        "session_remaining": canon(session_left),
+        "resets_at": parsed["resets_at"][1] if parsed["resets_at"] else None,
+        "limited_until": limited[1] if limited else None, "seen_at": seen[1] if seen else None,
+        "provider_capable": raw.get("provider_capable") is True,
+        "reservation_history": {"active_expires_at": active_expiry,
+                                "last_selected_at": last[1] if last else None},
+        "last_selected_at": last[1] if last else None, "eligible": exclusion is None,
+        "exclusion_code": exclusion}
+
+
+def _policy_context(request: dict, rows: list[dict]) -> tuple[str | None, tuple, set[tuple], int]:
+    policy, required = request["policy"], request.get("required_engine")
+    if policy == "default_claude":
+        required = "claude"
+    elif policy == "default_codex":
+        required = "codex"
+    elif policy not in {"explicit", "producer_retry", "reviewer"}:
+        required = None
+    producer = identity(request.get("producer_identity") or {})[:4]
+    excluded = {identity(value)[:4] for value in request.get("excluded_identities", [])}
+    alternatives = sum(
+        row["eligible"] and (required is None or row["engine"] == required)
+        and _row_identity(row) != producer and _row_identity(row) not in excluded for row in rows)
+    return required, producer, excluded, alternatives
+
+
+def _row_identity(row: dict) -> tuple:
+    return tuple(row[name] for name in ("runner_id", "runner_generation", "engine", "account_id"))
+
+
+def _apply_policy(request: dict, rows: list[dict]) -> tuple[tuple, int]:
+    required, producer, excluded, alternatives = _policy_context(request, rows)
+    for row in rows:
+        key = _row_identity(row)
+        policy_excluded = required is not None and row["engine"] != required
+        policy_excluded |= key in excluded
+        policy_excluded |= request["policy"] == "reviewer" and alternatives > 0 and key == producer
+        if row["eligible"] and policy_excluded:
+            row["eligible"] = False
+            row["exclusion_code"] = "policy_excluded"
+    return producer, alternatives
+
+
+def _winner_key(row: dict) -> tuple:
+    descending_headroom = Decimal(row["effective_headroom"] or "-1").copy_negate()
+    return (
+        not row["quota_known"], descending_headroom,
+        row["last_selected_at"] is not None, row["last_selected_at"] or "",
+        row["engine"], row["account_id"], row["runner_id"], row["runner_generation"])
+
+
+def _snapshot_key(row: dict) -> tuple:
+    if row["identity_valid"]:
+        return 0, row["runner_id"], row["runner_generation"], row["engine"], row["account_id"]
+    return 1, row["input_ordinal"], 0, "", ""
+
+
+def _error(code: str, detail: dict) -> dict:
+    return {"schema": SCHEMA, "selector_version": SELECTOR_VERSION, "ok": False,
+            "error_code": code, "error_detail": detail}
+
+
+def select(request: object) -> dict:
+    if error := request_error(request):
+        return _error(error[0], error[1])
+    assert isinstance(request, dict)
+    now, canonical_now = timestamp(request["database_now"])
+    rows = [normalize_candidate(item, now, index)
+            for index, item in enumerate(request["candidates"])]
+    identities: dict[tuple, list[int]] = {}
+    for row in rows:
+        if row["identity_valid"]:
+            identities.setdefault(collision_key(_row_identity(row)), []).append(row["input_ordinal"])
+    duplicate = next((items for items in identities.values() if len(items) > 1), None)
+    if duplicate:
+        return _error("duplicate_candidate_identity", {"input_ordinals": duplicate})
+    producer, alternatives = _apply_policy(request, rows)
+    eligible = [row for row in rows if row["eligible"]]
+    if not eligible:
+        return _error("no_candidate", {"eligible_count": 0})
+    winner = min(eligible, key=_winner_key)
+    rows.sort(key=_snapshot_key)
+    snapshot = canonical_sha256(rows)
+    chosen = dict(zip(("runner_id", "runner_generation", "engine", "account_id"), _row_identity(winner)))
+    digest_input = {
+        "schema": SCHEMA, "selector_version": SELECTOR_VERSION,
+        "database_now": canonical_now, "policy": request["policy"],
+        "required_engine": request.get("required_engine"), "reservation_key": request["reservation_key"],
+        "candidate_snapshot_digest": snapshot, "selected_identity": chosen}
+    score_fields = ("quota_known", "weekly_pct", "session_pct", "weekly_remaining",
+                    "session_remaining", "effective_headroom", "last_selected_at")
+    response = {"schema": SCHEMA, "selector_version": SELECTOR_VERSION, "ok": True, **chosen,
+                "score_basis": {name: winner[name] for name in score_fields},
+                "candidate_snapshot_digest": snapshot,
+                "selection_digest": canonical_sha256(digest_input)}
+    if request["policy"] == "reviewer" and not alternatives and _row_identity(winner) == producer:
+        response["fallback_reason"] = "sole_eligible_account"
+    return response