feat: Grok Build SuperGrok pool (init --grok) — Claude-resolution greedy swap via billing?format=credits

[chasehuh]

Implements #1: a third tokenmaxxing pool for Grok Build SuperGrok OIDC logins at the same CLI resolution as Claude Code and Codex.

What's in

• Full CLI surface: init/add/switch/rm/rename --grok (flag accepted anywhere in argv, mutually exclusive with --codex), grok sections in ls/status/watch/doctor, grokBin in config, grok teardown in uninstall.
• Usage SoT: GET {base}/billing?format=credits with Authorization: Bearer <issuer.key> + X-XAI-Token-Auth: xai-grok-cli. config.creditUsagePercent = used%, config.currentPeriod.end = weekly reset, productUsage[GrokBuild] as fallback. The query is pinned in one place (billingUrl()), and the mapper throws on the legacy monthly-zeros body so a lost format=credits can never render as an empty weekly bar. Weekly window only — no 5h bar invented, status --force never pings grok.
• Swap = whole-map replace under grok's own auth.json.lock flock (held across harvest→install) plus tokenmaxxing's grok-lock. Harvest keys on the blob's user_id, never a label; an unpooled live identity refuses the swap. Live writes are atomic 0600; parked blobs are the lossless full map in grok-creds/ (0600).
• Hot-reload first, restart fallback: a plain swap writes no respawn marker (running sessions pick it up on the next API call — unsupervised sessions included, the documented blast radius). Markers exist only for (a) the depleted-pool countdown (waitUntil + grok --resume <session-id>) and (b) the StopFailure rate_limit reactive path, which restarts the refused session in case grok's config watcher skipped a same-key reload.
• Hooks: one always-trusted sibling file ~/.grok/hooks/tokenmaxxing-grok.json (Stop + StopFailure rate_limit matcher, timeout 15s). Stop filters reason == "end_turn", exits 0 with no output, never blocks, never asks for /hooks trust. cmux-session.json untouched.
• No token self-refresh: the real grok binary refreshes an installed credential itself. Parked access tokens past their hours-scale TTL report honest sample misses (never probed, never flagged); only a refusal of an in-TTL parked token marks needs-reauth.
• Supervisor (argv0 grok / __supervise-grok): scrubs XAI_API_KEY + GROK_AUTH_PROVIDER_COMMAND (managed and passthrough spawns alike — the pool is OIDC-session-only), wrap-depth/rate loop guards, child-pid presence files under the flock, headless -p still managed.
• grokBin pin: init --grok prefers the newest ~/.grok/downloads/grok-* binary (survives grok update clobbering the ~/.grok/bin launcher), verifies --version, and never overwrites ~/.grok/bin/grok. init + doctor flag PATH shadowers (~/.grok/bin, ~/.local/bin/grok) with the exact ln -sf retarget command.
• Doctor: grok checks run only when the grok pool or shim exists — a claude-only install stays green with zero new findings (pinned by a test).
• Tests: test/grok.test.ts (51 tests) mirrors the codex suite hermetically — mapper fixtures (credits + monthly-zeros), picker/margin/engagement, swap sequence + refusals, decide incl. depleted-wait, the rate_limit force path and its transient-529 guard, presence, stop-hook marker matrix, install lifecycle, argv dispatch permutations, --grok+--codex mutual exclusion. Mock billing on a third pid-strided port (test/setup.ts stride 2→3).

Verification

• bun test: 394 pass / 1 skip (the pre-existing macOS keychain skip) / 0 fail
• bun run typecheck (tsc --noEmit): clean
• bun test/e2e/swap-concurrency.ts (standalone): ALL PASS
• Resume flag verified against the real pinned binary (grok --help, 1.0.8 Mach-O): -r, --resume [<SESSION_ID_OR_TITLE>], bare --resume = most recent. Login flags verified: --oauth (default), --device-auth/--device-code. Hook envelope (camelCase, reason/error/stopHookActive), always-trusted global hooks dir, hot-reload, and GROK_AUTH_EARLY_INVALIDATION_SECS=300 verified against the local 1.0.8 user-guide docs.

Not live-verified (per issue constraints — no billed runs, no real credentials touched)

• Resume-after-swap across accounts (whether cli-chat-proxy binds a session to user_id) — fallback is the restart path, one cold turn.
• The hot-reload same-key skip in anger — the restart fallback is implemented regardless.
• A live billed credits ping / real init --grok on the desk logins (QA step 4 is Chase's, post-merge).
• productUsage[GrokBuild] divergence from config.creditUsagePercent — v1 uses config as primary, GrokBuild row as fallback, per the issue.
• Multi-issuer auth.json — v1 pools the principal_type=User session entry; desk blobs have exactly one.

One interpretation call

Issue acceptance says add --grok "refuses duplicate user_id", while the validation rules name isolated re-login as the needs-reauth recovery. Implemented as the codex precedent: an idle existing account upserts (re-parks the fresh grant, clears needs-reauth — one index entry per user_id, so no duplicates ever exist), while a live-supervised account and the current live login still refuse. If a hard refusal is preferred, it's a 5-line change.

Notes

• No version bump included — this repo's release flow can bump when Chase ships; happy to add one if preferred.
• No sume-com/sumelabs files touched, no upstream (anaclumos) PR, no bun-global overlay, and this PR will not be merged by me.

Closes #1

🤖 Generated with Claude Code