tokenmaxxing 1.66.0 → 1.68.0

package/DESIGN.md

@@ -1,6 +1,6 @@
 # tokenmaxxing - design
 
-Automatic Claude Code account switching. You run `claude` exactly as always; every session starts on the pooled account with the most session-window headroom per running session, and when the account a session runs on crosses its bar (**90%** of the 5h session window minus the 3-point projection margin, so 87 by default, or **98%** of a weekly window), tokenmaxxing resumes that session on a fresher account at a safe turn boundary. Works across many concurrent sessions at once, each on its own account; a fully depleted pool pauses a session with a countdown and auto-resumes at the soonest reset when it lands within `policy.maxWaitMs` (default 1h; further out, the session stays put rather than parking for hours).
+Automatic Claude Code account switching. You run `claude` exactly as always; every session starts on the pooled account with the most session-window headroom per running session, and when the account a session runs on crosses its bar (**90%** of the 5h session window minus the 3-point projection margin, so 87 by default, or **98%** of a weekly window), tokenmaxxing resumes that session on a fresher account at a safe turn boundary. Works across many concurrent sessions at once, each on its own account; a fully depleted pool queues sessions first come first served onto reset targets (at most four waiters per account, overflow takes the soonest anyway), pauses each one with a countdown, and auto-resumes at its assigned reset when that lands within `policy.maxWaitMs` (default 1h; further out, the session stays put rather than parking for hours).
 
 > Scope: **Claude Code first (macOS + Linux, the latter since 2026-07-09).** Codex support landed in 0.13.0 (2026-07-16) with its own parallel state and supervisor; since 1.35.0 both run on one engine. Codex's verified internals live in AGENTS.md's Codex sections.
 >
@@ -12,7 +12,7 @@ Automatic Claude Code account switching. You run `claude` exactly as always; eve
 
 Claude Code namespaces its credential by `CLAUDE_SECURESTORAGE_CONFIG_DIR` (verified in the 2.1.269 binary, `xSe`/`y_`): the variable moves only the credential store (a `.credentials.json` inside that directory on Linux, a keychain item named `Claude Code-credentials-<sha256(dir)[0:8]>` on macOS), while `~/.claude` (settings, transcripts, plugins) and `~/.claude.json` stay shared, so `--resume` works across stores. An empty namespaced store never falls back to the default login. Hooks, the statusline, and MCP servers inherit the variable. That is the whole mechanism: give every pooled account its own store, set the variable per session, and each session runs on its own account with no credential ever moving.
 
-What the variable cannot give you is a change of account for a running process: the store is fixed at spawn. So the supervisor's job is placement and moves: on launch it **picks the seat** (see §5) and spawns claude under that account's store; when the session's Stop hook decides the seat is over its bar, the supervisor **replaces the process at a salvageable moment** - after a turn completes, the conversation is fully written to the transcript JSONL and `claude` is idle at the prompt, so killing it there loses nothing - and relaunches `claude --resume <session-id>` under the target's store. When the whole pool is over its bars it shows an interruptible countdown to the soonest reset first. **Thresholds sit below 100: the headroom is the budget to reach a clean turn boundary before the account actually hits its real limit.** The session window moves at 90 minus the margin (a 5h reset is cheap to sit out), while the weekly windows drain to 98 (weekly allowance is use-it-or-lose-it).
+What the variable cannot give you is a change of account for a running process: the store is fixed at spawn. So the supervisor's job is placement and moves: on launch it **picks the seat** (see §5) and spawns claude under that account's store; when the session's Stop hook decides the seat is over its bar, the supervisor **replaces the process at a salvageable moment** - after a turn completes, the conversation is fully written to the transcript JSONL and `claude` is idle at the prompt, so killing it there loses nothing - and relaunches `claude --resume <session-id>` under the target's store. When the whole pool is over its bars it shows an interruptible countdown to the reset the wait queue assigned (at most four waiters per account, first come first served, overflow on the soonest). **Thresholds sit below 100: the headroom is the budget to reach a clean turn boundary before the account actually hits its real limit.** The session window moves at 90 minus the margin (a 5h reset is cheap to sit out), while the weekly windows drain to 98 (weekly allowance is use-it-or-lose-it).
 
 A hook can't do the placement or the relaunch - when `claude` exits, the shell owns the terminal. So tokenmaxxing installs a **supervisor** (aliased to `claude`) that owns the process lifecycle:
 
@@ -37,13 +37,15 @@ It is a process manager only - spawn with inherited stdio (stdin through a relay
   - `usage/<uuid8>.json` - the statusline tee per account, written by the sessions running on it.
   - `live/<session-id>` - PID-validated presence per supervised session, naming its account; placement counts them.
   - `respawn/<session-id>` - per-session respawn markers (the hook→supervisor signal): the target account, the session to resume, a `waitUntil`, a `compact` flag, and the launch time the marker was written for.
+  - `wait-queue.json` - the depleted-pool wait claims (`{sessionId, accountId, at, waitUntil}`), so at most four sessions wait on one account; a session that arrives when every account already has four waiters takes the soonest reset anyway.
   - `bin/claude` and `bin/codex` - the supervisors, beside the `tokenmaxxing` and `xx` entry points.
   - `sessions/<sid>.json`, `onboard/`, `setup-tokens.json`, `setup-token/`, `cloud/`, `hub-key`, `update.json`, `spawnrate.json`, `tokenmaxxing.log`, the codex `codex-onboard/`, `codex-respawn/`, and `codex-live/`, and the `grok-*` and `opencode-go-*` state of the status-only pools: the full table is in [State directory layout](docs/content/docs/state-directory.mdx).
 - Per-account **credential stores** follow the platform's Claude Code store: macOS = a login-keychain item keyed by the store path (never plaintext on disk); Linux = a 0600 `.credentials.json` inside the 0700 store directory (the same plaintext model claude itself uses - its Linux build has no keyring path at all, binary-verified 2.1.205). One `credstore` facade dispatches on a `{kind: keychain|file}` target; call sites never branch on platform. tokenmaxxing writes a store once, at onboarding; Claude Code's own refresh is the only writer afterwards.
 
 - A periodic check job (`com.tokenmaxxing.check` launchd agent on macOS, `tokenmaxxing-check.timer` systemd user timer on Linux) running `tokenmaxxing check` once per tick (`policy.checkIntervalMs`, 60s by default): it runs the decision with no seat (nothing moves), folds fresh tees into the index, samples up to three accounts whose last sample attempt is oldest (the direct no-spend usage GET), deletes leftover dead state files at the state root, and on a Bun global install checks npm for a newer version once a day, so the cached figures every placement reads stay fresh.
+- A usage hub service (`com.tokenmaxxing.hub` launchd agent on macOS, `tokenmaxxing-hub.service` systemd user service on Linux) running `tokenmaxxing serve`, so the [usage hub](docs/content/docs/hub.mdx) is up in the background beside the check timer.
 
-The switching path runs no long-lived daemon. The statusline pushes usage. Hooks and the supervisor react. The periodic check job above is the only recurring process. `tokenmaxxing serve`, the optional [usage hub](docs/content/docs/hub.mdx) that answers the CLIProxyAPI management subset for a dashboard from the cached figures, is a foreground server outside the switching path. The `claude` binary, `~/.claude.json`, and Claude Code's default credential store are untouched; inside `~/.claude` only `settings.json` gets the five entries.
+The switching path runs no long-lived daemon. The statusline pushes usage. Hooks and the supervisor react. The periodic check job above is the only recurring process in the switching path. The [usage hub](docs/content/docs/hub.mdx) that answers the CLIProxyAPI management subset for a dashboard from the cached figures runs outside the switching path, as a background service beside the check timer (`tokenmaxxing serve` runs the same server in the foreground). The `claude` binary, `~/.claude.json`, and Claude Code's default credential store are untouched; inside `~/.claude` only `settings.json` gets the five entries.
 
 ---
 
@@ -56,7 +58,7 @@ The Stop hook's stdin has no usage data, but the **statusLine does** (`rate_limi
 1. Resolve the seat: the pooled account whose store the inherited `CLAUDE_SECURESTORAGE_CONFIG_DIR` names. No seat (a session started outside the supervisor) means nothing to move.
 2. Read the seat's tee and exit while it is under both bars, as defined in the [switching policy](docs/content/docs/switching.mdx).
 3. Take the pool lock, re-check, fold every account's tee into the index, select a candidate under the switching policy from the cached figures, and verify that the target's store holds a usable credential (a store Claude Code dead-cleared flags the account for re-auth and the next candidate is tried).
-4. Write `respawn/<session-id>` (atomic temp+rename) naming the target, with `waitUntil` now for a plain move or the soonest reset when the pool is depleted. No credential is written.
+4. Write `respawn/<session-id>` (atomic temp+rename) naming the target, with `waitUntil` now for a plain move or the assigned reset when the pool is depleted. No credential is written.
 
 ### 3.3 Move and depleted-pool pause (supervisor)
 The supervisor sees `respawn/<sid>`, SIGTERMs its child at the already-committed turn boundary, deletes the marker, resets the terminal, compacts the conversation when the marker asks for it (`compact: true` from the Stop and SessionStart hooks and from the supervisor's own seat watch, `false` from StopFailure: it runs `claude -p --resume <live-id> /compact` under the old seat's store, bounded at five minutes, and a failure only prints why), and (when `waitUntil` is in the future) shows an interruptible countdown to the reset; then it relaunches `claude --resume <live-id>` (`--session-id <live-id>` when that id has no transcript yet, because `--resume` exits with `No conversation found` for it) with `CLAUDE_SECURESTORAGE_CONFIG_DIR` set to the target's store and rewrites the session's presence. The marker file is keyed by the launch id `<sid>`; the live id inside it is the session id the supervised process runs now, which `/clear` and an in-session `/resume` change. A hook adopts a differing stdin id as the live id (`current` in `sessions/<sid>.json`) only when its own process descends, through shell processes alone, from the presence record's pid; any other differing id is a nested session and writes nothing. The resumed process reads that store cold → runs on the target account, same conversation. The `--session-id` path is the exception: the cleared conversation has no prior turn, so it starts empty with no compaction and no first prompt. On the `--resume` path the relaunch submits a first prompt that names the move (and the compaction, when it landed) and asks Claude to continue the task, so the conversation goes on without a keystroke: in a terminal session it is the positional prompt after the session id; in a stream-json session (`--input-format stream-json`, where the binary ignores a positional prompt) the supervisor owns stdin, relays the harness's lines to the child through a pipe, and writes the prompt as the first `user` line of the new process. In a terminal session the supervisor's own notices go to stderr. In a stream-json session (`--output-format stream-json`, read from the effective flags like the relay) there is no terminal and no statusline, so the supervisor writes each notice (the compaction and its failure, the move, the depleted-pool wait with its resume time, the resume) to stdout as a `system` line of subtype `informational` and level `warning`, the shape Claude Code emits for its own print-mode notices, which the harness renders in the conversation while the stream stays parseable; the per-second countdown ticks stay terminal-only, and the supervisor writes only while no child is running. The `SessionStart` hook (every source) re-runs the decision before the first turn and writes the same marker if the seat is already over its bar or the pool is depleted. The supervisor also watches its own seat every ten seconds while the child runs (account record plus tee, the same bars) and writes the marker itself when the seat is at or over a bar, so a move never depends on a hook firing: a harness session between turns whose background workflow burns the window, or a subagent refusal that stamped the wall, is moved within seconds. SIGTERM to the supervisor is forwarded to the child and the supervisor exits after it, so a harness that stops the wrapper (the Agent SDK does) never leaves an orphaned claude on the old seat. A marker whose `launchedAt` does not match the running child is discarded, and after a Ctrl-C on the countdown a later marker whose `waitUntil` falls inside the skipped wait is ignored. A marker that fails to parse is never deleted and never treated as absent: the supervisor stops the child, restores the terminal, and exits naming the marker path. In a stream-json session that fatal, the wrap-depth abort, the wrap-rate abort, and a failed presence write also go to stdout as the same `informational`/`warning` line.
@@ -81,7 +83,7 @@ Each terminal ran the supervisor, so each has its own child `claude`, its own `-
 ---
 
 ## 5. Placement and rotation policy
-The [switching policy](docs/content/docs/switching.mdx) is one rule: under both bars, hold; at or over a bar, move to the usable account that ranks first; nothing usable, wait for the soonest reset. The same ranking places a session at launch.
+The [switching policy](docs/content/docs/switching.mdx) is one rule: under both bars, hold; at or over a bar, move to the usable account that ranks first; nothing usable, queue first come first served onto a reset target (at most four waiters per account, overflow takes the soonest anyway) and wait for that reset. The same ranking places a session at launch.
 
 - Ranking (decided by consult for #79): greatest remaining headroom to the session bar divided by the number of sessions after placement, `(bar - used) / (sessions + 1)`, then highest pace pressure (remaining percent of the binding gated per-model cap, or of the weekly aggregate for an account with no gated row, over time to its reset), then soonest weekly reset, then lowest weekly usage; unknown usage ranks last. Organization membership is not an input. Codex drops the headroom key, keeps the pace ordering and the weekly tie-breaks, and excludes accounts running in another codex session, because codex has no cross-process refresh lock and two sessions must never share a login.
 - Selection reads the cached figures only, after folding every account's tee. Each periodic check tick samples up to three accounts whose last sample attempt is oldest, skipping any attempted within `policy.usagePollTtlMs`, over the direct no-spend usage read with the account's stored token, so every account is attempted about once per three ticks per pooled account, or once per `policy.usagePollTtlMs` plus a tick when that is longer, and its cached figure is as fresh as its last successful attempt or its sessions' latest push. The pool lock covers only the reservation and the result write, never the usage GET. The usage endpoint rate limits each account on its own and names the time to come back in the `retry-after` of its HTTP 429; that time is stored as `usageRetryAt`, and no sampler (the tick, `status`, the seat's in-decision sample) reads the account before it. An expired stored access token stays unmeasured until a session on that store refreshes it.

package/README.md

@@ -1,6 +1,6 @@
 # tokenmaxxing
 
-**Automatic Claude Code account switching.** Run `claude` exactly as you always do; each session starts on the pooled account with the most headroom per running session, and when that account nears its usage limit, tokenmaxxing resumes the session on a fresher account at a safe turn boundary - same conversation, compacted on the account it leaves and restarted under another account's credential store with a first prompt that asks Claude to continue. Works across many concurrent sessions, which spread over the pool instead of draining one account together. When the whole pool is at its limit, a session pauses with a countdown and auto-resumes at the soonest reset, when that reset falls within `policy.maxWaitMs` (default 1h - a longer wait stays put rather than parking your terminal for hours).
+**Automatic Claude Code account switching.** Run `claude` exactly as you always do; each session starts on the pooled account with the most headroom per running session, and when that account nears its usage limit, tokenmaxxing resumes the session on a fresher account at a safe turn boundary - same conversation, compacted on the account it leaves and restarted under another account's credential store with a first prompt that asks Claude to continue. Works across many concurrent sessions, which spread over the pool instead of draining one account together. When the whole pool is at its limit, a session queues first come first served for a reset (at most four sessions wait on one account) and pauses with a countdown until its assigned reset, when that reset falls within `policy.maxWaitMs` (default 1h - a longer wait stays put rather than parking your terminal for hours).
 
 > **Scope:** Claude Code on macOS and Linux, plus OpenAI's Codex CLI as a second switching pool; grok and opencode-go as status-only pools. It pools **subscription** accounts (Pro/Max), not API keys; the opencode-go pool, which holds Zen API keys, is the one exception.
 
@@ -52,7 +52,7 @@ programs.tokenmaxxing.package = inputs.tokenmaxxing.packages.${pkgs.system}.defa
 
 With either module, run `tokenmaxxing init` afterwards.
 
-`init` verifies and pins the real `claude` binary, opens an isolated `claude` session for your first pooled account (run `/login` there, even if you are already signed in; the login you already have stays for sessions started outside the supervisor), installs the `claude` supervisor and the `xx` entry point, five `settings.json` entries (the tokenmaxxing statusLine, a subagentStatusLine, a Stop hook, a StopFailure hook, a SessionStart hook), and the periodic check timer, and adds the supervisor's bin dir to PATH in your shell rc (idempotent; it must sit ahead of the real `claude` to intercept it). Restart your shell, then add more accounts and go:
+`init` verifies and pins the real `claude` binary, opens an isolated `claude` session for your first pooled account (run `/login` there, even if you are already signed in; the login you already have stays for sessions started outside the supervisor), installs the `claude` supervisor and the `xx` entry point, five `settings.json` entries (the tokenmaxxing statusLine, a subagentStatusLine, a Stop hook, a StopFailure hook, a SessionStart hook), the periodic check timer, and the usage hub service, and adds the supervisor's bin dir to PATH in your shell rc (idempotent; it must sit ahead of the real `claude` to intercept it). Restart your shell, then add more accounts and go:
 
 ```sh
 tokenmaxxing add        # logs one in, in isolation, into its own store
@@ -63,7 +63,7 @@ claude                  # use claude as always; each session gets its own accoun
 
 | command | what it does |
 |---|---|
-| `tokenmaxxing init` | verify and pin the real `claude`, log the first account in (isolated) + install supervisor, hooks, PATH line, and check timer |
+| `tokenmaxxing init` | verify and pin the real `claude`, log the first account in (isolated) + install supervisor, hooks, PATH line, check timer, and hub service |
 | `tokenmaxxing init --codex` | same for codex: log in the first account (isolated), install codex supervisor + Stop hook |
 | `tokenmaxxing init --grok` / `init --opencode-go` | pool the first grok login or opencode-go key, status-only: no supervisor, no switching |
 | `tokenmaxxing add [--codex \| --grok \| --opencode-go]` | register an additional account in that pool (isolated login, harvested once into its own store) |
@@ -71,10 +71,10 @@ claude                  # use claude as always; each session gets its own accoun
 | `tokenmaxxing status [--cached]` | every pool: accounts with 5h / weekly / per-model usage bars, live session counts, exhausted-until-reset; `--cached` renders the stored figures without sampling |
 | `tokenmaxxing config` | the config path and the effective values; edit the file in an editor, a bad value fails the next load with the field name |
 | `tokenmaxxing check` | fold fresh tees, sample up to three stale accounts, and self-update a Bun global install once a day; the periodic timer runs this every tick |
-| `tokenmaxxing doctor` | verify the install: PATH order, `claudeBin`, the five settings entries, the timer, the credential identity of every Codex store and of every Claude store whose access token is still fresh (an expiring Claude token is reported as unverifiable, not as a failure), codex hook trust, setup-token age, and shell aliases that shadow `claude` |
+| `tokenmaxxing doctor` | verify the install: PATH order, `claudeBin`, the five settings entries, the timer, the hub service, the credential identity of every Codex store and of every Claude store whose access token is still fresh (an expiring Claude token is reported as unverifiable, not as a failure), codex hook trust, setup-token age, and shell aliases that shadow `claude` |
 | `tokenmaxxing rename [--codex \| --grok \| --opencode-go] <sel> <label>` / `rm [...] <sel>` | manage a pool (one email can hold both a claude and a codex account); `rm` is refused for an account with a running supervised session |
-| `tokenmaxxing serve` | serve the CLIProxyAPI-compatible usage API on `http://localhost:8317` (`hub.port`) so a dashboard such as T3 Code's "Add a CLIProxyAPI hub" shows the quota of every pooled Claude and Codex account; the management key is the contents of `hub-key` in the state directory, minted on the first run. Details in [Usage hub](docs/content/docs/hub.mdx) |
-| `tokenmaxxing uninstall [--yes]` | print the targets, then remove the shims, settings entries, codex Stop hook, check timer, and rc PATH line (accounts/stores kept); refused without `--yes` when `HOME` is the login home |
+| `tokenmaxxing serve` | serve the CLIProxyAPI-compatible usage API on `http://localhost:8317` (`hub.port`) so a dashboard such as T3 Code's "Add a CLIProxyAPI hub" shows the quota of every pooled Claude and Codex account; the management key is the contents of `hub-key` in the state directory, minted on the first run, and `init` runs it as a background service beside the check timer. Details in [Usage hub](docs/content/docs/hub.mdx) |
+| `tokenmaxxing uninstall [--yes]` | print the targets, then remove the shims, settings entries, codex Stop hook, check timer, hub service, and rc PATH line (accounts/stores kept); refused without `--yes` when `HOME` is the login home |
 | `tokenmaxxing setup-token [--print \| rm <label\|uuid>]` | Cursor Cloud only: mint one `claude setup-token` per pooled account (a browser sign-in each) and print the `TOKENMAXXING_TOKENS` secret value; `--print` prints the stored set, `rm` drops one |
 | `tokenmaxxing cursor init [dir]` | write the Claude relay subagent and `.cursor/environment.json` into a repo |
 | `tokenmaxxing cloud run [--session <id>] [--max-turns <n>] "<prompt>"` | on a Cursor Cloud VM: run `claude -p` on a setup token, rotate to the next token on a usage limit |
@@ -92,7 +92,7 @@ The bars' headroom is deliberate: it's the budget to reach a clean turn boundary
 Launches and moves rank usable accounts by session-window headroom per running session, `(bar - used) / (sessions + 1)`, so two fresh accounts alternate and a third session goes to whichever has more headroom left per session; ties break by pace pressure (remaining percent of the binding gated per-model cap, or of the weekly aggregate for an account with no gated row, divided by time to its reset, highest first), then soonest weekly reset, then lowest weekly use. Organization membership is not an input.
 
 - Every periodic check tick folds fresh statusline tees into the index and samples up to three accounts whose last sample attempt is oldest, skipping any attempted within `policy.usagePollTtlMs`, with the direct no-spend usage read; a move reads the cached figures, which are as fresh as each account's last successful attempt or its sessions' latest push. An expired stored access token stays unmeasured until a session on that store refreshes it.
-- When no account is usable, the session pauses until the soonest reset if that lands within `policy.maxWaitMs`, and otherwise stays put.
+- When no account is usable, the session queues first come first served onto a reset target (at most four waiters per account) and pauses until that reset if it lands within `policy.maxWaitMs`, and otherwise stays put.
 
 See [How switching decides](docs/content/docs/switching.mdx) for the policy and the [cache-cost profile](docs/content/docs/switching-profile.mdx) for measurements and their limits.
 
@@ -113,9 +113,9 @@ See [How switching decides](docs/content/docs/switching.mdx) for the policy and
 }
 ```
 
-`thresholds.session` and `thresholds.weekly` are the two bars, one number each (an array `thresholds.session`, the former ladder, fails config loading with a message naming the field); `projectionMargin` is a fixed safety margin subtracted from the session bar only (default 3), so a large turn is less likely to blow past the 5-hour bar between checks; the weekly bar takes no margin because one turn cannot overshoot a week; `switchModels` names the models whose per-model cap triggers a move; `usagePollTtlMs` is how long a usage sample stays fresh, for a seat's own sample and for the accounts each check tick samples; `maxWaitMs` bounds the depleted-pool countdown - a soonest reset further out than this does not pause the session (no respawn marker is written and the session simply keeps hitting its limit until an account recovers); `checkIntervalMs` is the periodic check tick (default 60s), which `init` writes into the timer - re-run `tokenmaxxing init` after changing it so the timer unit picks up the new tick. `claudeBin`, `codexBin`, `grokBin`, and `opencodeBin` pin the real binaries; `init` writes them, and `TOKENMAXXING_CLAUDE_BIN`, `TOKENMAXXING_CODEX_BIN`, `TOKENMAXXING_GROK_BIN`, and `TOKENMAXXING_OPENCODE_BIN` override them for one process, except that `init` pins the binary it resolved into `config.json`.
+`thresholds.session` and `thresholds.weekly` are the two bars, one number each (an array `thresholds.session`, the former ladder, fails config loading with a message naming the field); `projectionMargin` is a fixed safety margin subtracted from the session bar only (default 3), so a large turn is less likely to blow past the 5-hour bar between checks; the weekly bar takes no margin because one turn cannot overshoot a week; `switchModels` names the models whose per-model cap triggers a move; `usagePollTtlMs` is how long a usage sample stays fresh, for a seat's own sample and for the accounts each check tick samples; `maxWaitMs` bounds the depleted-pool countdown - a reset further out than this does not pause the session (no respawn marker is written and the session simply keeps hitting its limit until an account recovers); `checkIntervalMs` is the periodic check tick (default 60s), which `init` writes into the timer - re-run `tokenmaxxing init` after changing it so the timer unit picks up the new tick. `claudeBin`, `codexBin`, `grokBin`, and `opencodeBin` pin the real binaries; `init` writes them, and `TOKENMAXXING_CLAUDE_BIN`, `TOKENMAXXING_CODEX_BIN`, `TOKENMAXXING_GROK_BIN`, and `TOKENMAXXING_OPENCODE_BIN` override them for one process, except that `init` pins the binary it resolved into `config.json`.
 
-State lives in `~/.config/tokenmaxxing/`; outside it the install touches Claude Code's `settings.json`, codex's `hooks.json`, the timer unit, and your shell rc. Each account's credential store is `stores/<uuid8>/`, which Claude Code reads and refreshes as its own: on macOS the credential is a login-keychain item keyed by the store path (never plaintext on disk), on Linux a 0600 `.credentials.json` inside the store (the same plaintext model claude itself uses for `~/.claude/.credentials.json`).
+State lives in `~/.config/tokenmaxxing/`; outside it the install touches Claude Code's `settings.json`, codex's `hooks.json`, the timer and usage hub units, and your shell rc. Each account's credential store is `stores/<uuid8>/`, which Claude Code reads and refreshes as its own: on macOS the credential is a login-keychain item keyed by the store path (never plaintext on disk), on Linux a 0600 `.credentials.json` inside the store (the same plaintext model claude itself uses for `~/.claude/.credentials.json`).
 
 ## Codex support
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "1.66.0",
+  "version": "1.68.0",
   "description": "Automatic Claude Code account switching: pool multiple accounts, start each session on its own account, and resume a session on a fresher account when quota fills.",
   "type": "module",
   "license": "MIT",

package/src/cli/doctor.ts

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { verifyRealClaude } from "../lib/claudebin.ts";
 import { checkSettings, installedBin } from "../lib/settings.ts";
-import { checkTimerHealthy, codexStoreHookTrust, findClaudeShadowers, isBinDirAhead, shellRcPath, timerActivationHint } from "../lib/install.ts";
+import { checkTimerHealthy, codexStoreHookTrust, findClaudeShadowers, hubServiceHealthy, isBinDirAhead, shellRcPath, skipImperativeHub, timerActivationHint } from "../lib/install.ts";
 import { errorMessage } from "../lib/log.ts";
 import { claudePool, codexPool, paths } from "../lib/paths.ts";
 import { loadAccounts, loadConfig } from "../lib/state.ts";
@@ -31,6 +31,10 @@ export async function cmdDoctor(): Promise<number> {
   check(s.stopFailureOk, "StopFailure hook installed in settings.json", "run `tokenmaxxing init`");
   check(s.sessionStartOk, "SessionStart hook installed in settings.json", "run `tokenmaxxing init`");
   check(checkTimerHealthy(), "periodic check timer active", timerActivationHint());
+  if (existsSync(paths.supervisorLink)) {
+    if (skipImperativeHub()) note("usage hub service is owned outside init (TOKENMAXXING_SKIP_HUB set) - not verified here");
+    else check(hubServiceHealthy(), "usage hub service active", "run `tokenmaxxing init` (it writes the unit and activates it)");
+  }
 
   const idx = loadAccounts(claudePool);
   check(idx.accounts.length > 0, "at least one account in the pool", "run `tokenmaxxing init`");

package/src/cli/serve.ts

@@ -7,6 +7,7 @@ import { claude } from "../lib/claude.ts";
 import { codex, observeCodex } from "../lib/codex.ts";
 import { CODEX_USAGE_URL } from "../lib/codexusage.ts";
 import { errorMessage, log } from "../lib/log.ts";
+import { hubDeactivationHint } from "../lib/install.ts";
 import { paths } from "../lib/paths.ts";
 import { isExhausted, thresholdBars } from "../lib/picker.ts";
 import type { Provider } from "../lib/provider.ts";
@@ -198,15 +199,21 @@ export async function cmdServe(args: string[]): Promise<number> {
   }
   const cfg = loadConfig();
   const key = managementKey();
-  const server = Bun.serve({
-    hostname: "localhost",
-    port: cfg.hub.port,
-    fetch: (req) => handle(req, key),
-    error: (e) => {
-      log("hub.error", { err: errorMessage(e) });
-      return json({ error: "internal error" }, 500);
-    },
-  });
+  let server: ReturnType<typeof Bun.serve>;
+  try {
+    server = Bun.serve({
+      hostname: "localhost",
+      port: cfg.hub.port,
+      fetch: (req) => handle(req, key),
+      error: (e) => {
+        log("hub.error", { err: errorMessage(e) });
+        return json({ error: "internal error" }, 500);
+      },
+    });
+  } catch (e) {
+    emitError({ message: `cannot bind localhost:${cfg.hub.port}: ${errorMessage(e)} (another \`tokenmaxxing serve\` or the usage hub service may already hold the port - stop it first: ${hubDeactivationHint()})` });
+    return 1;
+  }
   console.log(`${c.green("✓")} serving the CLIProxyAPI-compatible usage API at http://localhost:${server.port}/v0/management`);
   console.log(c.dim(`management key: the contents of ${paths.hubKeyFile}`));
   log("hub.started", { port: server.port });

package/src/entries/stopfailurehook.ts

@@ -80,7 +80,7 @@ export async function runStopFailureHook(): Promise<number> {
       );
     }
 
-    const decision = await evaluateAndMaybeSwap(claude, now, canRespawn && enforced != null, enforced);
+    const decision = await evaluateAndMaybeSwap(claude, now, canRespawn && enforced != null, enforced, { waiterId: canRespawn ? session?.sid : undefined });
     if (enforced && session && canRespawn && decision.account && (decision.swapped || decision.waitUntil !== undefined)) {
       writeRespawnMarker({ session, accountId: decision.account.id, waitUntil: decision.waitUntil ?? now, compact: false });
       log("stopfailure.marker", { session: session.sid.slice(0, 8), live: session.live.slice(0, 8), account: decision.account.id.slice(0, 8), waitUntil: decision.waitUntil ?? now });

package/src/entries/stophook.ts

@@ -24,7 +24,7 @@ export async function runBoundaryHook(event: "stop" | "sessionstart"): Promise<n
       log(`${event}.nested_session`, { stdin: stdin.session_id?.slice(0, 8), supervised: supervised.live.slice(0, 8), source: stdin.source });
       return 0;
     }
-    const decision = await evaluateAndMaybeSwap(claude, Date.now(), session != null);
+    const decision = await evaluateAndMaybeSwap(claude, Date.now(), session != null, null, { waiterId: session?.sid });
     if (session && decision.account && (decision.swapped || decision.waitUntil !== undefined)) {
       writeRespawnMarker({ session, accountId: decision.account.id, waitUntil: decision.waitUntil ?? Date.now(), compact: true });
       log(`${event}.${decision.waitUntil !== undefined ? "wait" : "move"}`, { source: stdin.source, account: decision.account.id.slice(0, 8), waitUntil: decision.waitUntil, session: session.sid.slice(0, 8), live: session.live.slice(0, 8) });

package/src/entries/supervisor.ts

@@ -16,7 +16,7 @@ import { teeObservation } from "../lib/sample.ts";
 import { exitStatus, loopGuardTripped, raceMarkerOrExit, recordPresenceOrStop, runPassthrough } from "../lib/supervise.ts";
 import { saveTermios } from "../lib/tty.ts";
 import { liveSessionId, loadSessionFlags, pruneStaleSessions, saveSessionFlags, writeRespawnMarker } from "../lib/sessions.ts";
-import { loadAccounts, loadConfig } from "../lib/state.ts";
+import { loadAccounts, loadConfig, releaseWaitClaim } from "../lib/state.ts";
 import { gatedFamilies, modelFromFlag } from "../lib/usage.ts";
 import { RespawnMarkerSchema, type Account, type Config, type ModelInfo } from "../lib/types.ts";
 import { errorMessage, log } from "../lib/log.ts";
@@ -222,7 +222,7 @@ async function moveExhaustedSeat(seat: Account, sid: string, gate: MarkerGate, m
     const families = gatedFamilies(model, cfg.policy.switchModels);
     const until = seatBlockedUntil(seat.id, now, families, cfg);
     if (until == null || until <= gate.overriddenUntil) return false;
-    const decision = await evaluateAndMaybeSwap(claude, now, true, null, seat.id, families);
+    const decision = await evaluateAndMaybeSwap(claude, now, true, null, { seatId: seat.id, sessionFamilies: families, waiterId: sid });
     log("supervisor.seat_exhausted", { seat: seat.id.slice(0, 8), until, reason: decision.reason, account: decision.account?.id.slice(0, 8), waitUntil: decision.waitUntil });
     if (decision.account && (decision.swapped || decision.waitUntil !== undefined)) {
       writeRespawnMarker({ session: { sid, launchedAt: gate.launchedAt, live: liveSessionId(sid) }, accountId: decision.account.id, waitUntil: decision.waitUntil ?? now, compact: true });
@@ -364,10 +364,27 @@ export async function runSupervisor(argv: string[]): Promise<number> {
 
   let child: Subprocess | null = null;
   let terminating = false;
+  let claimSid: string | null = null;
+  const releaseClaim = async (): Promise<void> => {
+    const claimed = claimSid;
+    if (claimed == null) return;
+    try {
+      await withLock(claudePool.lockFile, () => {
+        releaseWaitClaim(claimed);
+      });
+    } catch (e) {
+      log("supervisor.claim_release_failed", { err: errorMessage(e) });
+    }
+  };
   process.on("SIGTERM", () => {
     terminating = true;
-    if (child) child.kill("SIGTERM");
-    else process.exit(143);
+    const released = releaseClaim();
+    if (child) {
+      child.kill("SIGTERM");
+      void released;
+    } else {
+      released.finally(() => process.exit(143));
+    }
   });
 
   if (!info.manage || process.env[UNMANAGED_ENV]) {
@@ -392,6 +409,7 @@ export async function runSupervisor(argv: string[]): Promise<number> {
   } else {
     sid = crypto.randomUUID();
   }
+  claimSid = sid;
 
   if (resuming && base.length === 0) {
     const persisted = loadSessionFlags(sid);
@@ -504,6 +522,7 @@ export async function runSupervisor(argv: string[]): Promise<number> {
       if (m.waitUntil > Date.now()) {
         if (await countdownWait(label, m.waitUntil, { stream, say })) overriddenUntil = m.waitUntil;
       } else say(`\n\x1b[36m↻ tokenmaxxing: moving to ${label} - resuming...\x1b[0m\n`, `tokenmaxxing: moving to ${label} and resuming.`);
+      await releaseClaim();
       wanted = m.accountId;
       saveSessionFlags(m.sessionId, persistable, process.cwd());
       const prompt = resumable ? resumePrompt(compacted) : null;
@@ -512,6 +531,7 @@ export async function runSupervisor(argv: string[]): Promise<number> {
       continue;
     }
     clearPresence({ dir: paths.presenceDir, id: sid });
+    await releaseClaim();
     log("supervisor.exit", { sid, respawns, code: proc.exitCode, signal: proc.signalCode, terminated: terminating || undefined });
     return exitStatus(proc);
   }
@@ -520,6 +540,7 @@ export async function runSupervisor(argv: string[]): Promise<number> {
     const text = msg.startsWith("tokenmaxxing:") ? msg : `tokenmaxxing: ${msg}`;
     say(`\n\x1b[31m${text}\x1b[0m\n`, text);
     log("supervisor.fatal", { err: msg });
+    await releaseClaim();
     return 1;
   }
 }

package/src/lib/claude.ts

@@ -4,7 +4,7 @@ import { z } from "zod";
 import { readItem, writeItem, deleteItem, isolatedTarget, readStore, storeTarget, claudeAiOauthOnly } from "./credstore.ts";
 import { resolveRealClaude, resolveVerifiedClaude } from "./claudebin.ts";
 import { withClaudeRefreshLock } from "./claudelock.ts";
-import { ensurePathInRc, installSupervisor, managedShellRcSkipLines, shellRcPath, timerActivationHint } from "./install.ts";
+import { ensurePathInRc, hubActivationHint, installSupervisor, managedShellRcSkipLines, shellRcPath, timerActivationHint } from "./install.ts";
 import { withLock } from "./lock.ts";
 import { errorMessage, log } from "./log.ts";
 import { claudeTierLabel, describeIdentity, fetchTokenIdentity, isDeadCredential, InvalidGrantError } from "./oauth.ts";
@@ -270,6 +270,8 @@ function install(): void {
   console.log(`${c.green("✓")} installed ${c.bold("claude")} supervisor + statusLine/Stop/StopFailure/SessionStart hooks`);
   if (out.timerLoaded) console.log(`${c.green("✓")} periodic check timer active (every ${out.checkIntervalS}s)`);
   else console.log(c.yellow(`⚠ check timer written but not activated - run: ${timerActivationHint()}`));
+  if (out.hubLoaded) console.log(`${c.green("✓")} usage hub service active`);
+  else console.log(c.yellow(`⚠ usage hub service written but not activated - run: ${hubActivationHint()}`));
   if (!out.pathAhead) {
     console.log();
     ensurePathAhead();

package/src/lib/decide.ts

@@ -1,6 +1,6 @@
 import { withLock } from "./lock.ts";
-import { loadAccounts, loadConfig, saveAccounts } from "./state.ts";
-import { isExhausted, limitWindows, liveUsed, nextWeeklyReset, pickBest, pickEarliestReset, sessionWindow, thresholdBars, usableAt, weeklyWindow, type PickCtx } from "./picker.ts";
+import { loadAccounts, loadConfig, liveWaitClaims, releaseWaitClaim, replaceWaitClaim, saveAccounts } from "./state.ts";
+import { isExhausted, limitWindows, liveUsed, nextWeeklyReset, pickBest, pickWaitTarget, sessionWindow, thresholdBars, weeklyWindow, type PickCtx } from "./picker.ts";
 import { familyTokens } from "./usage.ts";
 import { errorMessage, log } from "./log.ts";
 import type { Observation, Provider } from "./provider.ts";
@@ -8,6 +8,14 @@ import type { Account, EnforcedLimit } from "./types.ts";
 
 export type SwapDecision = { swapped: boolean; account: Account | null; reason: string; waitUntil?: number };
 
+export type EvalOpts = {
+  seatId?: string | null;
+  sessionFamilies?: string[];
+  waiterId?: string;
+};
+
+const MAX_WAITERS_PER_ACCOUNT = 4;
+
 const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
 const FIVE_HOURS_MS = 5 * 60 * 60 * 1000;
 
@@ -42,23 +50,30 @@ function enforcedWall(limit: EnforcedLimit, account: Account, now: number): numb
   return limit.resetsAt ?? cachedReset ?? now + (limit.kind === "session" ? FIVE_HOURS_MS : WEEK_MS);
 }
 
-export async function evaluateAndMaybeSwap(p: Provider, now = Date.now(), canRespawn = false, enforced: EnforcedLimit | null = null, seatId: string | null = p.liveId(), sessionFamilies?: string[]): Promise<SwapDecision> {
-  const activeId = seatId;
+export async function evaluateAndMaybeSwap(p: Provider, now = Date.now(), canRespawn = false, enforced: EnforcedLimit | null = null, opts: EvalOpts = {}): Promise<SwapDecision> {
+  const activeId = opts.seatId === undefined ? p.liveId() : opts.seatId;
+  const waiterId = canRespawn ? opts.waiterId : undefined;
   const cfg = loadConfig();
   const bars = thresholdBars(cfg);
   const stored0 = loadAccounts(p.pool).accounts.find((a) => a.id === activeId);
   const walled0 = stored0?.enforcedUntil != null && stored0.enforcedUntil > now;
-  const gated = sessionFamilies ?? p.gatedFamilies(cfg);
+  const gated = opts.sessionFamilies ?? p.gatedFamilies(cfg);
   const observed = stored0 ? await p.observeLive(stored0, cfg, now, { probe: enforced == null && !walled0, perModel: gated == null || gated.length > 0 }) : null;
   const stored = loadAccounts(p.pool).accounts.find((a) => a.id === activeId);
 
   if (!enforced && !isOver(stored, observed, { now, thresholds: bars, currentId: activeId, families: gated, seats: null })) {
+    if (waiterId != null && liveWaitClaims(now).some((c) => c.sessionId === waiterId)) {
+      await withLock(p.pool.lockFile, () => {
+        releaseWaitClaim(waiterId);
+      });
+    }
     return { swapped: false, account: null, reason: "under-threshold-or-stale" };
   }
 
   return withLock(p.pool.lockFile, async () => {
+    if (waiterId != null) releaseWaitClaim(waiterId);
     const idx = loadAccounts(p.pool);
-    const id2 = seatId;
+    const id2 = activeId;
     const active = id2 ? idx.accounts.find((a) => a.id === id2) : undefined;
 
     const origin = enforced ? idx.accounts.find((a) => a.id === enforced.account) : undefined;
@@ -91,7 +106,7 @@ export async function evaluateAndMaybeSwap(p: Provider, now = Date.now(), canRes
     }
     saveAccounts(p.pool, idx);
 
-    const families = sessionFamilies ?? p.gatedFamilies(cfg);
+    const families = opts.sessionFamilies ?? p.gatedFamilies(cfg);
     const walled = active?.enforcedUntil != null && active.enforcedUntil > now;
     const blindScreen = (enforced != null && (prior || enforced.blind)) || (walled && !enforced2);
     const screened = blindScreen && families != null ? cfg.policy.switchModels : families;
@@ -142,31 +157,35 @@ export async function evaluateAndMaybeSwap(p: Provider, now = Date.now(), canRes
       const fresh = loadAccounts(p.pool);
       const current = seatOf(fresh);
       const ctx: PickCtx = { now, thresholds: bars, currentId: current?.id ?? null, families: switchFamilies, seats };
-      const currentAt = current ? usableAt(current, ctx) : Number.POSITIVE_INFINITY;
-      const other = pickEarliestReset(usable(fresh.accounts), ctx);
-
-      let target: Account | null = null;
-      let waitUntil = Number.POSITIVE_INFINITY;
-      if (other && other.availableAt < currentAt) { target = other.account; waitUntil = other.availableAt; }
-      else if (current) { target = current; waitUntil = currentAt; }
-      else if (other) { target = other.account; waitUntil = other.availableAt; }
+      const waiters = new Map<string, number>();
+      for (const claim of liveWaitClaims(now)) {
+        if (claim.sessionId === waiterId) continue;
+        waiters.set(claim.accountId, (waiters.get(claim.accountId) ?? 0) + 1);
+      }
+      const target = pickWaitTarget(usable(fresh.accounts), ctx, waiters, MAX_WAITERS_PER_ACCOUNT, now + cfg.policy.maxWaitMs);
 
-      if (!target || waitUntil - now > cfg.policy.maxWaitMs) {
+      if (!target) {
+        const soonest = pickWaitTarget(usable(fresh.accounts), ctx, new Map(), MAX_WAITERS_PER_ACCOUNT, Number.POSITIVE_INFINITY);
+        const waitUntil = soonest?.availableAt ?? Number.POSITIVE_INFINITY;
         log("decide.depleted", { waitUntil: Number.isFinite(waitUntil) ? waitUntil : 0 });
         return { swapped: false, account: null, reason: "all-depleted", ...(Number.isFinite(waitUntil) ? { waitUntil } : {}) };
       }
 
-      const isCurrent = target.id === (current?.id ?? null);
+      const waitUntil = target.availableAt;
+      const isCurrent = target.account.id === (current?.id ?? null);
       if (!isCurrent) {
         try {
-          await p.swap(target);
+          await p.swap(target.account);
         } catch (e) {
-          skipOrThrow(e, target);
+          skipOrThrow(e, target.account);
           continue;
         }
       }
-      log("decide.depleted_wait", { account: target.id.slice(0, 8), waitUntil });
-      return { swapped: !isCurrent, account: target, reason: "depleted-wait", waitUntil };
+      if (waiterId != null) {
+        replaceWaitClaim({ sessionId: waiterId, accountId: target.account.id, at: now, waitUntil });
+      }
+      log("decide.depleted_wait", { account: target.account.id.slice(0, 8), waitUntil });
+      return { swapped: !isCurrent, account: target.account, reason: "depleted-wait", waitUntil };
     }
   });
 }

package/src/lib/install.ts

@@ -9,7 +9,7 @@ import { resolveRealClaude } from "./claudebin.ts";
 import { loadConfig } from "./state.ts";
 import { ErrnoSchema } from "./types.ts";
 
-export type InstallOutcome = { claudeWrapper: string; installedBin: string; pathAhead: boolean; timerLoaded: boolean; checkIntervalS: number };
+export type InstallOutcome = { claudeWrapper: string; installedBin: string; pathAhead: boolean; timerLoaded: boolean; hubLoaded: boolean; checkIntervalS: number };
 
 export function isBinDirAhead(): boolean {
   const dirs = (process.env.PATH ?? "").split(":");
@@ -39,6 +39,10 @@ export function skipImperativeTimer(): boolean {
   return envFlag("TOKENMAXXING_SKIP_TIMER");
 }
 
+export function skipImperativeHub(): boolean {
+  return envFlag("TOKENMAXXING_SKIP_HUB");
+}
+
 function isNixStorePath(path: string): boolean {
   return path === "/nix/store" || path.startsWith("/nix/store/");
 }
@@ -103,6 +107,7 @@ export function installSupervisor(): InstallOutcome {
     installedBin: target,
     pathAhead: isBinDirAhead(),
     timerLoaded: installCheckTimer(checkIntervalS),
+    hubLoaded: installHubService(),
     checkIntervalS,
   };
 }
@@ -203,9 +208,11 @@ export function uninstallCodexSupervisor(): void {
 }
 
 const LAUNCHD_LABEL = "com.tokenmaxxing.check";
+const LAUNCHD_HUB_LABEL = "com.tokenmaxxing.hub";
+const HUB_UNIT = "tokenmaxxing-hub.service";
 
-function launchdPlist(): string {
-  return join(paths.launchdAgentsDir, `${LAUNCHD_LABEL}.plist`);
+function launchdPlist(label: string): string {
+  return join(paths.launchdAgentsDir, `${label}.plist`);
 }
 
 function launchdDomain(): string | null {
@@ -221,11 +228,19 @@ function run(cmd: string[]): boolean {
   }
 }
 
+function systemdEnv(): string {
+  return `Environment="TOKENMAXXING_HOME=${paths.home.replaceAll("%", "%%")}"\n`;
+}
+
+function launchdEnv(): string {
+  return `  <key>EnvironmentVariables</key><dict><key>TOKENMAXXING_HOME</key><string>${escape(paths.home)}</string></dict>\n`;
+}
+
 function installCheckTimer(intervalS: number): boolean {
   if (skipImperativeTimer()) return true;
 
   if (process.platform === "darwin") {
-    const plist = launchdPlist();
+    const plist = launchdPlist(LAUNCHD_LABEL);
     writeFileAtomic(
       plist,
       `<?xml version="1.0" encoding="UTF-8"?>
@@ -235,7 +250,7 @@ function installCheckTimer(intervalS: number): boolean {
   <key>Label</key><string>${LAUNCHD_LABEL}</string>
   <key>ProgramArguments</key><array><string>${escape(installedBin())}</string><string>check</string></array>
   <key>StartInterval</key><integer>${intervalS}</integer>
-  <key>StandardOutPath</key><string>/dev/null</string>
+${launchdEnv()}  <key>StandardOutPath</key><string>/dev/null</string>
   <key>StandardErrorPath</key><string>${escape(join(paths.home, "check.stderr.log"))}</string>
 </dict>
 </plist>
@@ -257,7 +272,7 @@ Description=tokenmaxxing account-switch check
 [Service]
 Type=oneshot
 ExecStart=${exec}
-`,
+${systemdEnv()}`,
     0o644,
   );
   writeFileAtomic(
@@ -283,16 +298,23 @@ WantedBy=timers.target
 
 export function timerActivationHint(): string {
   if (process.platform === "darwin") {
-    return `launchctl bootstrap gui/$(id -u) ${launchdPlist()}`;
+    return `launchctl bootstrap gui/$(id -u) ${launchdPlist(LAUNCHD_LABEL)}`;
   }
   return "systemctl --user daemon-reload && systemctl --user enable --now tokenmaxxing-check.timer";
 }
 
+export function hubActivationHint(): string {
+  if (process.platform === "darwin") {
+    return `launchctl bootstrap gui/$(id -u) ${launchdPlist(LAUNCHD_HUB_LABEL)}`;
+  }
+  return `systemctl --user daemon-reload && systemctl --user enable --now ${HUB_UNIT}`;
+}
+
 export function checkTimerHealthy(): boolean {
   if (skipImperativeTimer()) return true;
   if (process.platform === "darwin") {
     const domain = launchdDomain();
-    return existsSync(launchdPlist()) && domain != null && run(["launchctl", "print", `${domain}/${LAUNCHD_LABEL}`]);
+    return existsSync(launchdPlist(LAUNCHD_LABEL)) && domain != null && run(["launchctl", "print", `${domain}/${LAUNCHD_LABEL}`]);
   }
   return (
     existsSync(join(paths.systemdUserDir, "tokenmaxxing-check.timer")) &&
@@ -300,6 +322,15 @@ export function checkTimerHealthy(): boolean {
   );
 }
 
+export function hubServiceHealthy(): boolean {
+  if (skipImperativeHub()) return true;
+  if (process.platform === "darwin") {
+    const domain = launchdDomain();
+    return existsSync(launchdPlist(LAUNCHD_HUB_LABEL)) && domain != null && run(["launchctl", "print", `${domain}/${LAUNCHD_HUB_LABEL}`]);
+  }
+  return existsSync(join(paths.systemdUserDir, HUB_UNIT)) && run(["systemctl", "--user", "is-active", "--quiet", HUB_UNIT]);
+}
+
 export function timerDeactivationHint(): string {
   if (process.platform === "darwin") {
     return `launchctl bootout gui/$(id -u)/${LAUNCHD_LABEL}`;
@@ -307,11 +338,18 @@ export function timerDeactivationHint(): string {
   return "systemctl --user disable --now tokenmaxxing-check.timer";
 }
 
-function launchdJobLoaded(): "loaded" | "not-loaded" | "unavailable" {
+export function hubDeactivationHint(): string {
+  if (process.platform === "darwin") {
+    return `launchctl bootout gui/$(id -u)/${LAUNCHD_HUB_LABEL}`;
+  }
+  return `systemctl --user disable --now ${HUB_UNIT}`;
+}
+
+function launchdJobLoaded(label: string): "loaded" | "not-loaded" | "unavailable" {
   const domain = launchdDomain();
   if (domain == null) return "unavailable";
   try {
-    const { exitCode } = Bun.spawnSync(["launchctl", "print", `${domain}/${LAUNCHD_LABEL}`], { stdout: "ignore", stderr: "ignore", timeout: 10_000 });
+    const { exitCode } = Bun.spawnSync(["launchctl", "print", `${domain}/${label}`], { stdout: "ignore", stderr: "ignore", timeout: 10_000 });
     if (exitCode === 0) return "loaded";
     return exitCode === 113 ? "not-loaded" : "unavailable";
   } catch {
@@ -319,9 +357,9 @@ function launchdJobLoaded(): "loaded" | "not-loaded" | "unavailable" {
   }
 }
 
-function systemdTimerActive(): "active" | "not-active" | "unavailable" {
+function systemdUnitActive(unit: string): "active" | "not-active" | "unavailable" {
   try {
-    const proc = Bun.spawnSync(["systemctl", "--user", "is-active", "tokenmaxxing-check.timer"], { stdout: "pipe", stderr: "ignore", timeout: 10_000 });
+    const proc = Bun.spawnSync(["systemctl", "--user", "is-active", unit], { stdout: "pipe", stderr: "ignore", timeout: 10_000 });
     const state = proc.stdout.toString().trim();
     if (state === "active" || state === "activating" || state === "reloading") return "active";
     if (state === "inactive" || state === "failed" || state === "deactivating" || state === "unknown" || state === "maintenance") return "not-active";
@@ -333,16 +371,16 @@ function systemdTimerActive(): "active" | "not-active" | "unavailable" {
 
 function removeTimerUnits(): void {
   if (process.platform === "darwin") {
-    rmSync(launchdPlist(), { force: true });
+    rmSync(launchdPlist(LAUNCHD_LABEL), { force: true });
     return;
   }
   rmSync(join(paths.systemdUserDir, "tokenmaxxing-check.timer"), { force: true });
   rmSync(join(paths.systemdUserDir, "tokenmaxxing-check.service"), { force: true });
 }
 
-type TimerOutcome = "removed" | "skipped" | "still-loaded";
+type UnitOutcome = "removed" | "skipped" | "still-loaded";
 
-function uninstallCheckTimer(live: boolean): TimerOutcome {
+function uninstallCheckTimer(live: boolean): UnitOutcome {
   if (skipImperativeTimer()) return "skipped";
   if (!live) {
     removeTimerUnits();
@@ -350,18 +388,94 @@ function uninstallCheckTimer(live: boolean): TimerOutcome {
   }
   if (process.platform === "darwin") {
     const domain = launchdDomain();
-    const loaded = launchdJobLoaded();
+    const loaded = launchdJobLoaded(LAUNCHD_LABEL);
     const deactivated = loaded === "loaded" && domain != null ? run(["launchctl", "bootout", `${domain}/${LAUNCHD_LABEL}`]) : loaded === "not-loaded";
     removeTimerUnits();
     return deactivated ? "removed" : "still-loaded";
   }
-  const active = systemdTimerActive();
-  const deactivated = active === "active" ? run(["systemctl", "--user", "disable", "--now", "tokenmaxxing-check.timer"]) : active === "not-active";
+  const active = systemdUnitActive("tokenmaxxing-check.timer");
+  const deactivated = active !== "unavailable" && (run(["systemctl", "--user", "disable", "--now", "tokenmaxxing-check.timer"]) || active === "not-active");
   removeTimerUnits();
   run(["systemctl", "--user", "daemon-reload"]);
   return deactivated ? "removed" : "still-loaded";
 }
 
+function installHubService(): boolean {
+  if (skipImperativeHub()) return true;
+
+  if (process.platform === "darwin") {
+    const plist = launchdPlist(LAUNCHD_HUB_LABEL);
+    writeFileAtomic(
+      plist,
+      `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${LAUNCHD_HUB_LABEL}</string>
+  <key>ProgramArguments</key><array><string>${escape(installedBin())}</string><string>serve</string></array>
+  <key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>
+  <key>RunAtLoad</key><true/>
+${launchdEnv()}  <key>StandardOutPath</key><string>/dev/null</string>
+  <key>StandardErrorPath</key><string>${escape(join(paths.home, "hub.stderr.log"))}</string>
+</dict>
+</plist>
+`,
+      0o644,
+    );
+    const domain = launchdDomain();
+    if (domain == null) return false;
+    run(["launchctl", "bootout", `${domain}/${LAUNCHD_HUB_LABEL}`]);
+    return run(["launchctl", "bootstrap", domain, plist]) || hubServiceHealthy();
+  }
+
+  const exec = `"${installedBin().replaceAll("%", "%%")}" serve`;
+  writeFileAtomic(
+    join(paths.systemdUserDir, HUB_UNIT),
+    `[Unit]
+Description=tokenmaxxing usage hub
+StartLimitIntervalSec=0
+
+[Service]
+ExecStart=${exec}
+${systemdEnv()}Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+`,
+    0o644,
+  );
+  return run(["systemctl", "--user", "daemon-reload"]) && run(["systemctl", "--user", "enable", "--now", HUB_UNIT]);
+}
+
+function removeHubUnits(): void {
+  if (process.platform === "darwin") {
+    rmSync(launchdPlist(LAUNCHD_HUB_LABEL), { force: true });
+    return;
+  }
+  rmSync(join(paths.systemdUserDir, HUB_UNIT), { force: true });
+}
+
+function uninstallHubService(live: boolean): UnitOutcome {
+  if (skipImperativeHub()) return "skipped";
+  if (!live) {
+    removeHubUnits();
+    return "removed";
+  }
+  if (process.platform === "darwin") {
+    const domain = launchdDomain();
+    const loaded = launchdJobLoaded(LAUNCHD_HUB_LABEL);
+    const deactivated = loaded === "loaded" && domain != null ? run(["launchctl", "bootout", `${domain}/${LAUNCHD_HUB_LABEL}`]) : loaded === "not-loaded";
+    removeHubUnits();
+    return deactivated ? "removed" : "still-loaded";
+  }
+  const active = systemdUnitActive(HUB_UNIT);
+  const deactivated = active !== "unavailable" && (run(["systemctl", "--user", "disable", "--now", HUB_UNIT]) || active === "not-active");
+  removeHubUnits();
+  run(["systemctl", "--user", "daemon-reload"]);
+  return deactivated ? "removed" : "still-loaded";
+}
+
 export function shellRcPath(): string | null {
   const override = optionalEnv("TOKENMAXXING_SHELL_RC");
   if (override != null) return override;
@@ -445,7 +559,7 @@ export function removePathFromRc(rc: string): boolean {
   return true;
 }
 
-export type UninstallOutcome = { timer: "removed" | "skipped" | "still-loaded"; pathLineRemoved: boolean };
+export type UninstallOutcome = { timer: UnitOutcome; hub: UnitOutcome; pathLineRemoved: boolean };
 
 export function loginHome(): string {
   const cmd = process.platform === "darwin" ? ["id", "-P"] : ["getent", "passwd", String(process.getuid?.() ?? "")];
@@ -462,13 +576,18 @@ export function onLoginHome(): boolean {
 export function uninstallTargets(live: boolean): string[] {
   const timer =
     process.platform === "darwin"
-      ? `${launchdPlist()}${live ? ` (and launchctl bootout gui/${process.getuid?.() ?? "?"}/${LAUNCHD_LABEL})` : ""}`
+      ? `${launchdPlist(LAUNCHD_LABEL)}${live ? ` (and launchctl bootout gui/${process.getuid?.() ?? "?"}/${LAUNCHD_LABEL})` : ""}`
       : `${join(paths.systemdUserDir, "tokenmaxxing-check.timer")} and .service${live ? " (and systemctl --user disable --now tokenmaxxing-check.timer)" : ""}`;
+  const hub =
+    process.platform === "darwin"
+      ? `${launchdPlist(LAUNCHD_HUB_LABEL)}${live ? ` (and launchctl bootout gui/${process.getuid?.() ?? "?"}/${LAUNCHD_HUB_LABEL})` : ""}`
+      : `${join(paths.systemdUserDir, HUB_UNIT)}${live ? ` (and systemctl --user disable --now ${HUB_UNIT})` : ""}`;
   const rc = shellRcPath();
   return [
     `${paths.claudeSettings}: the hook and statusline entries`,
     `${codexPaths.hooksJson}: the codex Stop hook entry`,
     ...(skipImperativeTimer() ? [] : [timer]),
+    ...(skipImperativeHub() ? [] : [hub]),
     paths.supervisorLink,
     codexSupervisorLink(),
     join(paths.binDir, "xx"),
@@ -477,14 +596,15 @@ export function uninstallTargets(live: boolean): string[] {
   ];
 }
 
-export function uninstallSupervisor(input: { liveTimer: boolean }): UninstallOutcome {
+export function uninstallSupervisor(input: { live: boolean }): UninstallOutcome {
   uninstallSettings();
-  const timer = uninstallCheckTimer(input.liveTimer);
+  const timer = uninstallCheckTimer(input.live);
+  const hub = uninstallHubService(input.live);
   uninstallCodexSupervisor();
   for (const f of [paths.supervisorLink, join(paths.binDir, "xx"), installedBin()]) {
     if (existsSync(f)) rmSync(f, { force: true });
   }
   const rc = shellRcPath();
   const pathLineRemoved = rc != null && removePathFromRc(rc);
-  return { timer, pathLineRemoved };
+  return { timer, hub, pathLineRemoved };
 }

package/src/lib/paths.ts

@@ -48,6 +48,7 @@ export const paths = {
 export const claudePool = {
   accountsJson: join(TM_HOME, "accounts.json"),
   lockFile: join(TM_HOME, "lock"),
+  waitQueueJson: join(TM_HOME, "wait-queue.json"),
 } as const;
 
 export const codexPool = {

package/src/lib/picker.ts

@@ -135,3 +135,12 @@ export function pickEarliestReset(accounts: Account[], ctx: PickCtx): EarliestRe
     .filter((x) => Number.isFinite(x.availableAt));
   return minBy(mapped, (x) => x.availableAt) ?? null;
 }
+
+export function pickWaitTarget(accounts: Account[], ctx: PickCtx, waiters: Map<string, number>, cap: number, deadline: number): EarliestReset | null {
+  const mapped = accounts
+    .filter((a) => !a.needsReauth)
+    .map((a) => ({ account: a, availableAt: usableAt(a, ctx) }))
+    .filter((x) => Number.isFinite(x.availableAt) && x.availableAt <= deadline)
+    .sort((x, y) => x.availableAt - y.availableAt || (x.account.id === ctx.currentId ? -1 : y.account.id === ctx.currentId ? 1 : 0));
+  return mapped.find((x) => (waiters.get(x.account.id) ?? 0) < cap) ?? mapped[0] ?? null;
+}

package/src/lib/state.ts

@@ -1,17 +1,19 @@
 import { closeSync, existsSync, fstatSync, openSync, readFileSync, rmSync, utimesSync } from "node:fs";
 import { isEqual } from "es-toolkit";
 import { z } from "zod";
-import { optionalEnv, paths, usageJsonFor, type PoolPaths } from "./paths.ts";
+import { claudePool, optionalEnv, paths, usageJsonFor, type PoolPaths } from "./paths.ts";
 import { writeFileAtomic } from "./atomic.ts";
 import {
   AccountsIndexSchema,
   ConfigSchema,
   ErrnoSchema,
   UsageStateSchema,
+  WaitQueueSchema,
   type Account,
   type AccountsIndex,
   type Config,
   type UsageState,
+  type WaitClaim,
   type Window,
 } from "./types.ts";
 
@@ -67,6 +69,41 @@ export function saveAccounts(pool: PoolPaths, idx: AccountsIndex): void {
   writeFileAtomic(pool.accountsJson, JSON.stringify(AccountsIndexSchema.parse(idx), null, 2) + "\n");
 }
 
+function loadWaitQueue(): WaitClaim[] {
+  if (!existsSync(claudePool.waitQueueJson)) return [];
+  let json: unknown;
+  try {
+    json = JSON.parse(readFileSync(claudePool.waitQueueJson, "utf8"));
+  } catch {
+    throw new Error(`${claudePool.waitQueueJson} is corrupt (unparsable JSON) - refusing to treat a damaged wait queue as empty; repair or remove the file`);
+  }
+  const parsed = WaitQueueSchema.safeParse(json);
+  if (!parsed.success) {
+    throw new Error(`${claudePool.waitQueueJson} does not match the wait-queue schema - refusing to treat a damaged wait queue as empty; repair or remove the file`);
+  }
+  return parsed.data.claims;
+}
+
+function saveWaitQueue(claims: WaitClaim[]): void {
+  writeFileAtomic(claudePool.waitQueueJson, JSON.stringify(WaitQueueSchema.parse({ version: 1, claims }), null, 2) + "\n");
+}
+
+export function liveWaitClaims(now: number): WaitClaim[] {
+  return loadWaitQueue().filter((c) => c.waitUntil > now);
+}
+
+export function replaceWaitClaim(claim: WaitClaim): void {
+  saveWaitQueue([...liveWaitClaims(Date.now()).filter((c) => c.sessionId !== claim.sessionId), claim]);
+}
+
+export function releaseWaitClaim(sessionId: string): void {
+  const now = Date.now();
+  const raw = loadWaitQueue();
+  const next = raw.filter((c) => c.waitUntil > now && c.sessionId !== sessionId);
+  if (next.length === raw.length) return;
+  saveWaitQueue(next);
+}
+
 export type Harvest = {
   id: string;
   email: string | null;

package/src/lib/types.ts

@@ -128,6 +128,19 @@ export const ConfigSchema = z
   });
 export type Config = z.infer<typeof ConfigSchema>;
 
+export const WaitClaimSchema = z.object({
+  sessionId: z.string(),
+  accountId: z.string(),
+  at: z.number(),
+  waitUntil: z.number(),
+});
+export type WaitClaim = z.infer<typeof WaitClaimSchema>;
+
+export const WaitQueueSchema = z.object({
+  version: z.literal(1),
+  claims: z.array(WaitClaimSchema).default([]),
+});
+
 export const RespawnMarkerSchema = z.object({
   accountId: z.string(),
   ts: z.number(),

package/src/main.ts

@@ -26,7 +26,7 @@ import { cmdSetupToken } from "./cli/setuptoken.ts";
 import { cmdCloudRun } from "./cli/cloudrun.ts";
 import { cmdCursorInit } from "./cli/cursorinit.ts";
 import { cmdServe } from "./cli/serve.ts";
-import { onLoginHome, timerDeactivationHint, uninstallSupervisor, uninstallTargets } from "./lib/install.ts";
+import { hubDeactivationHint, onLoginHome, timerDeactivationHint, uninstallSupervisor, uninstallTargets } from "./lib/install.ts";
 import { errorMessage } from "./lib/log.ts";
 import { HOME } from "./lib/paths.ts";
 import { c, emitError } from "./cli/render.ts";
@@ -185,15 +185,17 @@ async function main(): Promise<number> {
         emitError({ message: `refused: HOME is the login home (${HOME}) - rerun with ${YES_FLAG} to remove these from the live install` });
         return 2;
       }
-      const out = uninstallSupervisor({ liveTimer: live });
+      const out = uninstallSupervisor({ live });
       const removed = [
         "supervisor wrapper",
         "settings entries",
         ...(out.timer === "removed" ? ["check timer"] : []),
+        ...(out.hub === "removed" ? ["usage hub service"] : []),
         ...(out.pathLineRemoved ? ["rc PATH line"] : []),
       ];
       console.log(`removed ${removed.join(", ")}`);
       if (out.timer === "still-loaded") console.log(c.yellow(`⚠ the check job may still be loaded - run: ${timerDeactivationHint()}`));
+      if (out.hub === "still-loaded") console.log(c.yellow(`⚠ the usage hub job may still be loaded - run: ${hubDeactivationHint()}`));
       if (!out.pathLineRemoved) console.log(c.dim("(no tokenmaxxing PATH line found in the shell rc)"));
       console.log(`kept: accounts.json, config.json, and every account credential store (claude: stores/ and its keychain items on macOS; codex: codex-stores/; grok: grok-stores/; opencode-go: opencode-go-stores/) - remove accounts with \`xx rm\` to delete their credentials`);
       return 0;