tokenmaxxing 1.113.0 → 1.114.0

package/DESIGN.md

@@ -53,7 +53,7 @@ The switching path runs no long-lived daemon. The statusline pushes usage. Hooks
 ## 3. How a move happens
 
 ### 3.1 Usage feed (free, push-based)
-The Stop hook's stdin has no usage data, but the **statusLine does** (`rate_limits.{five_hour,seven_day}.{used_percentage,resets_at}`, after every turn, 300ms debounce, zero cost). tokenmaxxing's statusLine tees that to `usage/<uuid8>.json` for the session's seat, read from the inherited `CLAUDE_SECURESTORAGE_CONFIG_DIR` (write-on-change, O(ms)), and renders its own native line (it replaced the earlier pass-through delegation on 2026-07-11: install takes the statusLine slot outright, so a pre-existing custom statusline command is overwritten). A session with no pooled seat writes no tee. The seat is sampled when its tee is older than `policy.usagePollTtlMs`, and for the per-model rows when the active model is a gated family, at most once per the account's sample interval (§5): the direct no-spend usage read with the seat's stored token. The compact child still sets `TOKENMAXXING_PROBE=1` so the hook entries return at once. The sample takes one attempt per interval; a failed sample doubles the interval up to 30 minutes, and a success resets it. A sample that finds the stored access token expired has Claude Code refresh it first (§5).
+The Stop hook's stdin has no usage data, but the **statusLine does** (`rate_limits.{five_hour,seven_day}.{used_percentage,resets_at}`, after every turn, 300ms debounce, zero cost). tokenmaxxing's statusLine tees that to `usage/<uuid8>.json` for the session's seat, read from the inherited `CLAUDE_SECURESTORAGE_CONFIG_DIR` (write-on-change, O(ms)), and renders its own native line (it replaced the earlier pass-through delegation on 2026-07-11: install takes the statusLine slot outright, so a pre-existing custom statusline command is overwritten). A session with no pooled seat writes no tee. A stream-json session runs no statusLine, so its supervisor writes the same tee from the child's stdout: it relays every chunk unchanged, tees each `rate_limit_event` line's `unifiedWindows` (the same response-header figures, pushed on every one-point move), and restamps the tee on each `assistant` line. The seat is sampled when its tee is older than `policy.usagePollTtlMs`, and for the per-model rows when the active model is a gated family, at most once per the account's sample interval (§5): the direct no-spend usage read with the seat's stored token. The compact child still sets `TOKENMAXXING_PROBE=1` so the hook entries return at once. The sample takes one attempt per interval; a failed sample doubles the interval up to 30 minutes, and a success resets it. A sample that finds the stored access token expired has Claude Code refresh it first (§5).
 
 ### 3.2 Detect + decide + signal (Stop hook, per turn)
 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.
@@ -87,7 +87,7 @@ Each terminal ran the supervisor, so each has its own child `claude`, its own `-
 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 the account's sample interval, over the direct no-spend usage read with the account's stored token. The interval is 15 minutes times the unused fraction of the bar closest to being reached, never under `policy.usagePollTtlMs`, and 15 minutes for an account at or over an aggregate bar. The windows are the session and weekly aggregates plus the `policy.switchModels` caps that are still under their bar, and an account with no stored aggregate gets `policy.usagePollTtlMs`. Every account is attempted about once per three ticks per pooled account, or once per its sample interval 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. No sampler sends a read with an expired stored access token, because the endpoint answers it with 401 and, after a few, with the same 429. A sample that finds the token expired first runs `claude -p /usage --no-session-persistence --safe-mode` with the account's store set and a throwaway `CLAUDE_CONFIG_DIR`, so Claude Code refreshes the token under its own lock, and then reads with the new token; the child's output is not read. A refresh that leaves the token expired fails the sample with no read, and one that clears the store flags the account `needsReauth`.
+- 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 the account's sample interval, over the direct no-spend usage read with the account's stored token. The interval is 15 minutes times the unused fraction of the bar closest to being reached, never under `policy.usagePollTtlMs`, and 15 minutes for an account at or over an aggregate bar or with no session or borrower on this host. Every sampler claims a read under the pool lock before it sends it, so concurrent hooks and `status` runs send an account one read. The windows are the session and weekly aggregates plus the `policy.switchModels` caps that are still under their bar, and an account with no stored aggregate gets `policy.usagePollTtlMs`. Every account is attempted about once per three ticks per pooled account, or once per its sample interval 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. No sampler sends a read with an expired stored access token, because the endpoint answers it with 401 and, after a few, with the same 429. A sample that finds the token expired first runs `claude -p /usage --no-session-persistence --safe-mode` with the account's store set and a throwaway `CLAUDE_CONFIG_DIR`, so Claude Code refreshes the token under its own lock, and then reads with the new token; the child's output is not read. A refresh that leaves the token expired fails the sample with no read, and one that clears the store flags the account `needsReauth`.
 - The depleted pause happens at the bar, not at 100; Codex has no pause and rides its account until the server refuses it, because a running sibling cannot adopt another account without restarting.
 - Neither pool has a post-swap cooldown or a manual `switch`: a move is a respawn of one session under a fixed store, so nothing another session reads is invalidated by it, and placement at launch replaces the manual pick.
 

package/README.md

@@ -90,7 +90,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 the account's sample interval (15 minutes for an empty account, shrinking to `policy.usagePollTtlMs` as it nears a bar, and 15 minutes again at or over an aggregate bar), 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. A sample that finds the stored access token expired has Claude Code refresh it first (`claude -p /usage` under that store) and reads with the new token.
+- Every periodic check tick folds fresh session tees (the statusline of a terminal session, the `rate_limit_event` stream of a T3 Code or Agent SDK session) into the index and samples up to three accounts whose last sample attempt is oldest, skipping any attempted within the account's sample interval (15 minutes for an empty account or one with no session on this host, shrinking to `policy.usagePollTtlMs` as a live account nears a bar, and 15 minutes again at or over an aggregate bar), 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. A sample that finds the stored access token expired has Claude Code refresh it first (`claude -p /usage` under that store) and reads with the new token.
 - 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "1.113.0",
+  "version": "1.114.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/entries/supervisor.ts

@@ -1,3 +1,4 @@
+import { once } from "node:events";
 import { existsSync, mkdirSync, rmSync, readdirSync, statSync } from "node:fs";
 import { basename, join } from "node:path";
 import type { FileSink, Subprocess } from "bun";
@@ -16,9 +17,9 @@ import { teeObservation } from "../lib/sample.ts";
 import { countdownWait, exitStatus, loopGuardTripped, raceMarkerOrExit, recordPresenceOrStop, runPassthrough, SEAT_POLL_MS, SEAT_RETRY_MS, type Say } from "../lib/supervise.ts";
 import { saveTermios } from "../lib/tty.ts";
 import { liveSessionId, loadSessionFlags, pruneStaleSessions, saveSessionFlags, writeRespawnMarker } from "../lib/sessions.ts";
-import { loadAccounts, loadConfig, readJsonFile, releaseWaitClaim } from "../lib/state.ts";
-import { gatedFamilies, modelFromFlag, scrubCredEnv } from "../lib/usage.ts";
-import { RespawnMarkerSchema, type Account, type Config, type ModelInfo } from "../lib/types.ts";
+import { loadAccounts, loadConfig, readJsonFile, releaseWaitClaim, writeUsage } from "../lib/state.ts";
+import { gatedFamilies, modelFromFlag, parseStreamLine, scrubCredEnv } from "../lib/usage.ts";
+import { RespawnMarkerSchema, type Account, type Config, type ModelInfo, type UsageWindows } from "../lib/types.ts";
 import { errorMessage, log } from "../lib/log.ts";
 
 const SUBCOMMANDS = new Set([
@@ -266,6 +267,54 @@ function userLine(text: string): string {
   return `${JSON.stringify({ type: "user", message: { role: "user", content: [{ type: "text", text }] } })}\n`;
 }
 
+const STDOUT_QUIET_MS = 1000;
+
+function seatTee(seatId: string, model: ModelInfo | null): (line: string) => void {
+  let last: UsageWindows | null = null;
+  return (line) => {
+    const msg = parseStreamLine(line);
+    if (msg?.windows) last = msg.windows;
+    else if (msg?.type !== "assistant") return;
+    if (last) writeUsage({ fiveHour: last.fiveHour, sevenDay: last.sevenDay, account: seatId, ts: Date.now(), model });
+  };
+}
+
+function relayStdout(source: ReadableStream<Uint8Array>, onLine: (line: string) => void): () => Promise<void> {
+  let ended = false;
+  let blocked = false;
+  let readAt = Date.now();
+  const forwarded = source.pipeThrough(
+    new TransformStream<Uint8Array, Uint8Array>({
+      async transform(chunk, controller) {
+        readAt = Date.now();
+        if (!process.stdout.write(chunk)) {
+          blocked = true;
+          await once(process.stdout, "drain");
+          blocked = false;
+        }
+        controller.enqueue(chunk);
+      },
+    }),
+  );
+  void (async () => {
+    for await (const line of readLines(forwarded)) {
+      try {
+        onLine(line);
+      } catch (e) {
+        log("supervisor.tee_failed", { err: errorMessage(e) });
+      }
+    }
+  })()
+    .catch((e: unknown) => log("supervisor.stdout_relay_failed", { err: errorMessage(e) }))
+    .finally(() => {
+      ended = true;
+    });
+  return async () => {
+    const exitedAt = Date.now();
+    while (!ended && (blocked || Date.now() - Math.max(readAt, exitedAt) < STDOUT_QUIET_MS)) await Bun.sleep(50);
+  };
+}
+
 class StdinRelay {
   private sink: FileSink | null = null;
   private queue: string[] = [];
@@ -430,6 +479,7 @@ export async function runSupervisor(argv: string[]): Promise<number> {
   let overriddenUntil = 0;
   let wanted: string | null = null;
   let refused: string[] = [];
+  let drainStdout: (() => Promise<void>) | null = null;
   try {
   while (true) {
     if (existsSync(marker)) rmSync(marker, { force: true });
@@ -439,9 +489,10 @@ export async function runSupervisor(argv: string[]): Promise<number> {
       if (terminating) return null;
       const picked = (wanted == null ? null : (loadAccounts(claudePool).accounts.find((a) => a.id === wanted) ?? null)) ?? pickSeat(gate.launchedAt, model);
       log("supervisor.launch", { sid, respawns, seat: picked?.id.slice(0, 8) ?? null, args: launchArgs.join(" "), injected: firstLine !== null });
+      const tee = stream && picked ? seatTee(picked.id, model) : null;
       const spawned = Bun.spawn([real, ...launchArgs], {
         stdin: relay === null ? "inherit" : "pipe",
-        stdout: "inherit",
+        stdout: tee === null ? "inherit" : "pipe",
         stderr: "inherit",
         env: {
           ...(picked ? { ...scrubCredEnv(childEnv), CLAUDE_SECURESTORAGE_CONFIG_DIR: storeDirFor(picked.id) } : childEnv),
@@ -453,6 +504,7 @@ export async function runSupervisor(argv: string[]): Promise<number> {
         },
       });
       child = spawned;
+      const drain = tee !== null && spawned.stdout instanceof ReadableStream ? relayStdout(spawned.stdout, tee) : null;
       if (relay !== null) relay.attach(spawned.stdin!, firstLine);
       firstLine = null;
       if (picked) {
@@ -467,7 +519,7 @@ export async function runSupervisor(argv: string[]): Promise<number> {
         });
       }
       releaseClaimLocked(sid);
-      return { child: spawned, seat: picked };
+      return { child: spawned, seat: picked, drain };
     });
     if (launched == null) {
       await releaseClaim();
@@ -475,6 +527,7 @@ export async function runSupervisor(argv: string[]): Promise<number> {
     }
 
     const { child: proc, seat } = launched;
+    drainStdout = launched.drain;
     let seatCheckAt = 0;
     await raceMarkerOrExit({
       child: proc,
@@ -494,6 +547,8 @@ export async function runSupervisor(argv: string[]): Promise<number> {
         relay?.detach();
       },
     });
+    await drainStdout?.();
+    drainStdout = null;
 
     const m = !terminating && existsSync(marker) ? await consumableMarker(marker, gate) : null;
     if (m) {
@@ -538,6 +593,7 @@ export async function runSupervisor(argv: string[]): Promise<number> {
     return exitStatus(proc);
   }
   } catch (e) {
+    await drainStdout?.();
     const msg = errorMessage(e);
     const text = msg.startsWith("tokenmaxxing:") ? msg : `tokenmaxxing: ${msg}`;
     say(`\n\x1b[31m${text}\x1b[0m\n`, text);

package/src/lib/claude.ts

@@ -13,7 +13,7 @@ import { landWindows, pickBest, pickEarliestReset, thresholdBars, type PickCtx }
 import { deletePiStore } from "./piauth.ts";
 import { livingPresences, writePresence } from "./presence.ts";
 import { StoreUnusableError, type Observation, type Provider, type SampleReport, type SeatBorrow } from "./provider.ts";
-import { foldTee, readyToSample, runSample, sampleAccountUsage, sampleDue, sampleIntervalMs, teeObservation, usageBlockedUntil } from "./sample.ts";
+import { claimSample, foldTee, readyToSample, runSample, sampleAccountUsage, sampleDue, sampleIntervalMs, teeObservation, usageBlockedUntil } from "./sample.ts";
 import { clearUsageSnapshot, liveWaitClaims, loadAccounts, loadConfig, loadUsageSnapshot, pinBinOverride, readJsonFile, saveAccounts, type Harvest } from "./state.ts";
 import { saveTermios, restoreTermios } from "./tty.ts";
 import { fetchUsageDirect, gatedFamilies, mergeWindows, modelFromFlag, scrubCredEnv, windowsOf } from "./usage.ts";
@@ -33,11 +33,10 @@ function presence(living = livingPresences(paths.presenceDir)): Map<string, numb
 const PROBE_BACKOFF_CAP_MS = 30 * 60 * 1000;
 
 async function observeLive(account: Account, cfg: Config, now: number, opts: { probe: boolean; perModel: boolean }): Promise<Observation | null> {
-  const interval = Math.min(sampleIntervalMs(account, cfg, now) * 2 ** (account.probeFails ?? 0), PROBE_BACKOFF_CAP_MS);
-  const probeAttempted = account.lastProbeAt != null && now - account.lastProbeAt <= interval;
+  const probeDue = (a: Account) => a.lastProbeAt == null || now - a.lastProbeAt > Math.min(sampleIntervalMs(a, cfg, now, true) * 2 ** (a.probeFails ?? 0), PROBE_BACKOFF_CAP_MS);
   const snap = loadUsageSnapshot(account.id);
   const fresh = snap != null && now - snap.at <= cfg.policy.usagePollTtlMs;
-  if (opts.probe && !probeAttempted && usageBlockedUntil(account, now) == null && (!fresh || opts.perModel)) {
+  if (opts.probe && (!fresh || opts.perModel) && probeDue(account) && usageBlockedUntil(account, now) == null && (await claimSample(account.id, now, probeDue))) {
     const startedAt = Date.now();
     const outcome = await sampleAccountUsage(account);
     await withLock(claudePool.lockFile, () => {
@@ -67,6 +66,7 @@ async function samplePool(accounts: Account[], _liveId: string | null, now: numb
   const reports = new Map<string, SampleReport>();
   const cfg = loadConfig();
   const bars = thresholdBars(cfg);
+  const live = presence();
   await Promise.all(
     accounts.map(async (a) => {
       const tee = loadUsageSnapshot(a.id);
@@ -81,7 +81,8 @@ async function samplePool(accounts: Account[], _liveId: string | null, now: numb
         reports.set(a.id, { ok: false, reason: ready.reason });
         return;
       }
-      if (!sampleDue(a, cfg, now)) {
+      const due = (stored: Account) => sampleDue(stored, cfg, now, live.has(a.id));
+      if (!due(a) || !(await claimSample(a.id, now, due))) {
         reports.set(a.id, { ok: true, source: "cached" });
         return;
       }

package/src/lib/sample.ts

@@ -20,13 +20,13 @@ type PreparedSample = { ok: true; token: string; expiresAt: number } | { ok: fal
 
 const SAMPLE_INTERVAL_MAX_MS = 15 * 60 * 1000;
 
-export function sampleIntervalMs(account: Account, cfg: Config, now: number): number {
+export function sampleIntervalMs(account: Account, cfg: Config, now: number, live: boolean): number {
   const floor = cfg.policy.usagePollTtlMs;
   const bars = thresholdBars(cfg);
   const aggregates = account.windows.filter((w) => w.name == null);
   if (aggregates.length === 0) return floor;
   const blocked = (w: Window) => liveUsed(w, now) >= barFor(account, w, bars, now);
-  if (aggregates.some(blocked)) return Math.max(floor, SAMPLE_INTERVAL_MAX_MS);
+  if (!live || aggregates.some(blocked)) return Math.max(floor, SAMPLE_INTERVAL_MAX_MS);
   const open = [...aggregates, ...gatedWindows(account, cfg.policy.switchModels).filter((w) => !blocked(w))];
   const spare = Math.min(...open.map((w) => 1 - liveUsed(w, now) / barFor(account, w, bars, now)));
   return Math.max(floor, SAMPLE_INTERVAL_MAX_MS * spare);
@@ -34,8 +34,20 @@ export function sampleIntervalMs(account: Account, cfg: Config, now: number): nu
 
 const sampledAt = (a: Account) => Math.max(a.lastUsageAt ?? 0, a.lastProbeAt ?? 0);
 
-export function sampleDue(account: Account, cfg: Config, now: number): boolean {
-  return now - sampledAt(account) > sampleIntervalMs(account, cfg, now);
+export function sampleDue(account: Account, cfg: Config, now: number, live: boolean): boolean {
+  const since = live && gatedWindows(account, cfg.policy.switchModels).length > 0 ? (account.lastProbeAt ?? 0) : sampledAt(account);
+  return now - since > sampleIntervalMs(account, cfg, now, live);
+}
+
+export async function claimSample(id: string, now: number, due: (stored: Account) => boolean): Promise<boolean> {
+  return withLock(claudePool.lockFile, () => {
+    const idx = loadAccounts(claudePool);
+    const stored = idx.accounts.find((a) => a.id === id);
+    if (!stored || usageBlockedUntil(stored, now) != null || !due(stored)) return false;
+    stored.lastProbeAt = now;
+    saveAccounts(claudePool, idx);
+    return true;
+  });
 }
 
 export function teeObservation(account: Account): Observation | null {
@@ -118,6 +130,7 @@ export async function runSample(account: Account, prepared: { token: string; exp
     token = refreshed.token;
   }
   const read = await fetchUsageDirect(token);
+  log("usage.read", { account: account.id.slice(0, 8), ok: read.ok });
   if (read.ok) return { ok: true, usage: read.usage, via: "get" };
   if (read.retryAt == null) return { ok: false, reason: "usage read failed (see log)" };
   return { ok: false, reason: rateLimitedReason(read.retryAt, Date.now()), retryAt: read.retryAt };
@@ -145,7 +158,7 @@ export async function sampleOldest(cfg: Config): Promise<void> {
     for (const a of idx.accounts) dirty = foldTee(a, thresholdBars(cfg)) || dirty;
     const seats = seatCounts(paths.presenceDir);
     const stale = idx.accounts
-      .filter((a) => a.needsReauth !== true && sampleDue(a, cfg, now))
+      .filter((a) => a.needsReauth !== true && sampleDue(a, cfg, now, seats.has(a.id)))
       .sort((a, b) => Number(seats.has(b.id)) - Number(seats.has(a.id)) || sampledAt(a) - sampledAt(b))
       .slice(0, SAMPLE_BATCH);
     if (stale.length === 0) {

package/src/lib/usage.ts

@@ -18,6 +18,25 @@ export function parseStatusLineStdin(obj: unknown): UsageWindows | null {
   return { fiveHour: win(rl.five_hour), sevenDay: win(rl.seven_day), perModel: {} };
 }
 
+const StreamWindowSchema = z.looseObject({ utilization: z.number(), resetsAt: EpochSecondsSchema });
+const StreamLineSchema = z.looseObject({
+  type: z.string(),
+  rate_limit_info: z
+    .looseObject({
+      unifiedWindows: z.looseObject({ five_hour: StreamWindowSchema.optional(), seven_day: StreamWindowSchema.optional() }).optional(),
+    })
+    .optional(),
+});
+
+export function parseStreamLine(line: string): { type: string; windows: UsageWindows | null } | null {
+  const parsed = StreamLineSchema.safeParse(JsonTextSchema.safeParse(line).data);
+  if (!parsed.success) return null;
+  const unified = parsed.data.type === "rate_limit_event" ? parsed.data.rate_limit_info?.unifiedWindows : undefined;
+  const win = (w: z.infer<typeof StreamWindowSchema>): UsageWindow => ({ usedPercentage: Math.round(w.utilization * 100), resetsAt: w.resetsAt });
+  const windows = unified?.five_hour && unified.seven_day ? { fiveHour: win(unified.five_hour), sevenDay: win(unified.seven_day), perModel: {} } : null;
+  return { type: parsed.data.type, windows };
+}
+
 export function parseStatusLineModel(obj: unknown): ModelInfo | null {
   const parsed = RateLimitsStdinSchema.safeParse(obj);
   if (!parsed.success) return null;