tokenmaxxing 0.1.0 → 0.2.1

package/src/lib/state.ts

@@ -0,0 +1,125 @@
+// Config + accounts index + usage snapshot persistence. All writes atomic.
+
+import { existsSync, readFileSync } from "node:fs";
+import { isEqual } from "es-toolkit";
+import { z } from "zod";
+import { paths, realClaudeBinFromEnv } from "./paths.ts";
+import { writeFileAtomic } from "./atomic.ts";
+import {
+  AccountsIndexSchema,
+  ConfigSchema,
+  ModelUsageStateSchema,
+  UsageStateSchema,
+  type AccountsIndex,
+  type Config,
+  type ModelUsageState,
+  type UsageState,
+} from "./types.ts";
+
+// ---- config.json (minimal, fixed schema) ---------------------------------
+
+const DEFAULT_CONFIG: Config = {
+  threshold: 95,
+  claudeBin: "",
+  policy: { projectionMargin: 0, switchModels: ["fable", "opus"], usagePollTtlMs: 90_000, maxWaitMs: 3_600_000 },
+};
+
+/** On-disk shape (all optional); validated via Zod, merged over defaults. */
+const ConfigFileSchema = z
+  .object({
+    threshold: z.number(),
+    claudeBin: z.string(),
+    policy: z
+      .object({
+        projectionMargin: z.number(),
+        switchModels: z.array(z.string()),
+        usagePollTtlMs: z.number(),
+        maxWaitMs: z.number(),
+      })
+      .partial(),
+  })
+  .partial();
+
+export function loadConfig(): Config {
+  const cfg: Config = { ...DEFAULT_CONFIG, policy: { ...DEFAULT_CONFIG.policy } };
+  if (existsSync(paths.configJson)) {
+    let raw: unknown = {};
+    try {
+      raw = JSON.parse(readFileSync(paths.configJson, "utf8"));
+    } catch {
+      raw = {};
+    }
+    const parsed = ConfigFileSchema.safeParse(raw);
+    const p = parsed.success ? parsed.data : {};
+    cfg.threshold = p.threshold ?? cfg.threshold;
+    cfg.claudeBin = p.claudeBin ?? cfg.claudeBin;
+    cfg.policy.projectionMargin = p.policy?.projectionMargin ?? cfg.policy.projectionMargin;
+    cfg.policy.usagePollTtlMs = p.policy?.usagePollTtlMs ?? cfg.policy.usagePollTtlMs;
+    cfg.policy.maxWaitMs = p.policy?.maxWaitMs ?? cfg.policy.maxWaitMs;
+    if (p.policy?.switchModels) {
+      cfg.policy.switchModels = p.policy.switchModels.map((s) => s.toLowerCase());
+    }
+  }
+  // env override wins for the claude binary (tests / relocation)
+  const envBin = realClaudeBinFromEnv();
+  if (envBin) cfg.claudeBin = envBin;
+  return ConfigSchema.parse(cfg);
+}
+
+export function saveConfig(c: Config): void {
+  writeFileAtomic(paths.configJson, JSON.stringify(ConfigSchema.parse(c), null, 2) + "\n");
+}
+
+// ---- accounts.json -------------------------------------------------------
+
+const emptyIndex = (): AccountsIndex => ({ version: 1, activeAccountUuid: null, accounts: [] });
+
+export function loadAccounts(): AccountsIndex {
+  if (!existsSync(paths.accountsJson)) return emptyIndex();
+  try {
+    const parsed = AccountsIndexSchema.safeParse(JSON.parse(readFileSync(paths.accountsJson, "utf8")));
+    return parsed.success ? parsed.data : emptyIndex();
+  } catch {
+    return emptyIndex();
+  }
+}
+
+export function saveAccounts(idx: AccountsIndex): void {
+  writeFileAtomic(paths.accountsJson, JSON.stringify(AccountsIndexSchema.parse(idx), null, 2) + "\n");
+}
+
+// ---- usage.json ----------------------------------------------------------
+
+export function loadUsage(): UsageState | null {
+  if (!existsSync(paths.usageJson)) return null;
+  try {
+    const parsed = UsageStateSchema.safeParse(JSON.parse(readFileSync(paths.usageJson, "utf8")));
+    return parsed.success ? parsed.data : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Write-on-change: skip the write (and its fsync) when only `ts` would differ. */
+export function writeUsage(next: UsageState): boolean {
+  const prev = loadUsage();
+  if (prev && isEqual({ ...prev, ts: 0 }, { ...next, ts: 0 })) return false;
+  writeFileAtomic(paths.usageJson, JSON.stringify(next));
+  return true;
+}
+
+// ---- model-usage.json (per-model caps from `/usage`, TTL-cached) ----------
+
+export function loadModelUsage(): ModelUsageState | null {
+  if (!existsSync(paths.modelUsageJson)) return null;
+  try {
+    const parsed = ModelUsageStateSchema.safeParse(JSON.parse(readFileSync(paths.modelUsageJson, "utf8")));
+    return parsed.success ? parsed.data : null;
+  } catch {
+    return null;
+  }
+}
+
+export function saveModelUsage(next: ModelUsageState): void {
+  writeFileAtomic(paths.modelUsageJson, JSON.stringify(next));
+}

package/src/lib/swap.ts

@@ -0,0 +1,143 @@
+// The account-switch sequence. Runs under the tokenmaxxing flock (held by the
+// caller - the Stop hook or a CLI command). The keychain/json writes additionally
+// run under claude's own refresh lock so they can't interleave with a token refresh.
+//
+//   refresh B (network, no lock)
+//   resolve the live credential's TRUE owner (network, no lock)
+//   ── under claude refresh lock ──
+//     harvest live → its OWNER's backup (mandatory: refresh token rotates in place)
+//     install B into the live item
+//     persist B's rotated token into B's backup
+//     rewrite oauthAccount in ~/.claude.json
+//     mark B active (inside the lock: a crash before this write leaves a stale
+//     active label, which is exactly what once made a harvest destroy a backup)
+
+import { loadAccounts, saveAccounts } from "./state.ts";
+import { readItem, writeItem, liveTarget, parkedTarget, claudeAiOauthOnly, mergeIntoLive } from "./credstore.ts";
+import { refreshCredential, isAccessTokenExpiring, fetchTokenOrg, InvalidGrantError } from "./oauth.ts";
+import { swapOAuthAccount } from "./claudejson.ts";
+import { withLock } from "./lock.ts";
+import { withClaudeRefreshLock } from "./claudelock.ts";
+import { paths } from "./paths.ts";
+import { log } from "./log.ts";
+import { pickBest, type PickCtx } from "./picker.ts";
+import { CredentialBlobSchema, type Account, type OAuthCreds } from "./types.ts";
+
+function parseBlob(raw: string) {
+  return CredentialBlobSchema.parse(JSON.parse(raw));
+}
+
+/**
+ * Mechanically switch the LIVE credential to `target`. Assumes the caller holds
+ * the tokenmaxxing flock. Throws InvalidGrantError (after marking needs_reauth)
+ * when target's refresh token is dead.
+ */
+export async function performSwap(target: Account): Promise<void> {
+  const idx = loadAccounts();
+
+  // 1. refresh target's parked credential (network) BEFORE taking claude's lock.
+  const parkedRaw = await readItem(parkedTarget(target.keychainItem));
+  if (!parkedRaw) throw new Error(`no parked credential for ${target.email}`);
+  let fresh: OAuthCreds;
+  try {
+    fresh = await refreshCredential(parseBlob(parkedRaw).claudeAiOauth);
+  } catch (e) {
+    if (e instanceof InvalidGrantError) {
+      const t = idx.accounts.find((a) => a.accountUuid === target.accountUuid);
+      if (t) { t.needsReauth = true; saveAccounts(idx); }
+      log("swap.invalid_grant", { account: target.accountUuid.slice(0, 8) });
+    }
+    throw e;
+  }
+  // 2. resolve the live credential's TRUE owner - the harvest destination.
+  //    activeAccountUuid is a label, and labels drift from the blob they describe
+  //    (crash mid-swap, manual /login, historical re-init); harvesting by label is
+  //    how a backup once got destroyed. The token itself cannot lie. A rotation
+  //    between here and the harvest write keeps the same owner, so this can stay
+  //    outside the (fast, local) critical section.
+  const preLive = await readItem(liveTarget());
+  let liveOwner: Account | null = null;
+  if (preLive) {
+    let liveCreds = parseBlob(preLive).claudeAiOauth;
+    let identifiable = true;
+    if (isAccessTokenExpiring(liveCreds, 60_000)) {
+      try {
+        liveCreds = await refreshCredential(liveCreds);
+        await writeItem(liveTarget(), mergeIntoLive(preLive, liveCreds));
+      } catch (e) {
+        if (!(e instanceof InvalidGrantError)) throw e;
+        // dead credential family: nothing worth preserving, skip the harvest.
+        identifiable = false;
+        log("swap.harvest_skipped_dead_live", {});
+      }
+    }
+    if (identifiable) {
+      const org = await fetchTokenOrg(liveCreds.accessToken);
+      liveOwner = idx.accounts.find((a) => a.organizationUuid === org.organization_uuid) ?? null;
+      if (!liveOwner) {
+        throw new Error(
+          `live credential belongs to ${org.organization_name} (org ${org.organization_uuid.slice(0, 8)}), which is not in the pool - refusing to swap over it; import it first with \`tokenmaxxing add\``,
+        );
+      }
+      if (liveOwner.accountUuid !== idx.activeAccountUuid) {
+        log("swap.harvest_drift", {
+          labeled: idx.activeAccountUuid?.slice(0, 8) ?? null,
+          actual: liveOwner.accountUuid.slice(0, 8),
+        });
+      }
+    }
+  }
+
+  // 3. the fast, local, atomic-vs-claude-refresh critical section.
+  await withClaudeRefreshLock(async () => {
+    const currentLive = await readItem(liveTarget());
+
+    // harvest the live claudeAiOauth into its OWNER's (small) backup item.
+    if (liveOwner && currentLive) {
+      await writeItem(parkedTarget(liveOwner.keychainItem), claudeAiOauthOnly(currentLive));
+      log("swap.harvest", { account: liveOwner.accountUuid.slice(0, 8) });
+    }
+
+    // install B: merge B's fresh claudeAiOauth into the CURRENT live blob so all
+    // sibling state (MCP OAuth tokens, etc.) is preserved across the swap.
+    await writeItem(liveTarget(), mergeIntoLive(currentLive, fresh));
+    // persist B's rotated token into its small backup item.
+    await writeItem(parkedTarget(target.keychainItem), JSON.stringify({ claudeAiOauth: fresh }));
+    swapOAuthAccount(target.oauthAccount);
+    // record B as active INSIDE the critical section so a crash cannot leave the
+    // installed credential and the active label pointing at different accounts.
+    idx.activeAccountUuid = target.accountUuid;
+    const t2 = idx.accounts.find((a) => a.accountUuid === target.accountUuid);
+    if (t2) { t2.needsReauth = false; }
+    saveAccounts(idx);
+  });
+  log("swap.done", { account: target.accountUuid.slice(0, 8), email: target.email });
+}
+
+/**
+ * Pick the best candidate and swap to it, retrying past dead refresh tokens.
+ * Assumes the caller holds the flock (does NOT lock - avoids same-process
+ * flock self-deadlock). Returns the account landed on, or null if none usable.
+ */
+export async function chooseAndSwap(ctx: Omit<PickCtx, "currentAccountUuid">): Promise<Account | null> {
+  const tried = new Set<string>();
+  while (true) {
+    const idx = loadAccounts();
+    const candidates = idx.accounts.filter((a) => !tried.has(a.accountUuid));
+    const best = pickBest(candidates, { ...ctx, currentAccountUuid: idx.activeAccountUuid });
+    if (!best) return null;
+    tried.add(best.accountUuid);
+    try {
+      await performSwap(best);
+      return best;
+    } catch (e) {
+      if (e instanceof InvalidGrantError) continue; // dead token - next candidate
+      throw e;
+    }
+  }
+}
+
+/** Standalone lock-taking variant for CLI/manual use (NEVER call under a held flock). */
+export async function swapToBest(ctx: Omit<PickCtx, "currentAccountUuid">): Promise<Account | null> {
+  return withLock(paths.lockFile, () => chooseAndSwap(ctx));
+}

package/src/lib/tty.ts

@@ -0,0 +1,14 @@
+// Save/restore the controlling terminal's line settings around a child that owns
+// the tty via inherited stdio. If we SIGTERM such a child (supervisor respawn, or
+// `add` auto-exit), the terminal can be left in raw mode; restoring stty fixes it.
+
+export function saveTermios(): string | null {
+  const p = Bun.spawnSync(["/bin/sh", "-c", "stty -g </dev/tty"]);
+  const s = p.stdout?.toString().trim();
+  return s && p.exitCode === 0 ? s : null;
+}
+
+export function restoreTermios(saved: string | null): void {
+  const cmd = saved ? `stty ${saved} </dev/tty` : "stty sane </dev/tty";
+  Bun.spawnSync(["/bin/sh", "-c", cmd], { stdout: "ignore", stderr: "ignore" });
+}

package/src/lib/types.ts

@@ -0,0 +1,152 @@
+// Shared data model - Zod schemas are the single source of truth; TS types are
+// inferred from them. Everything that crosses an external boundary (keychain
+// blob, ~/.claude.json, hook/statusLine stdin, OAuth response, our own state
+// files) is validated through these instead of hand-checked.
+
+import { z } from "zod";
+
+/** OAuth object inside the keychain blob (`claudeAiOauth`). Loose: preserve any
+ *  extra fields claude may add so a harvest→install round-trip is lossless. */
+export const OAuthCredsSchema = z.looseObject({
+  accessToken: z.string(),
+  refreshToken: z.string(),
+  expiresAt: z.number(),
+  refreshTokenExpiresAt: z.number().optional(),
+  scopes: z.array(z.string()).default([]),
+  subscriptionType: z.string().optional(),
+  rateLimitTier: z.string().optional(),
+});
+export type OAuthCreds = z.infer<typeof OAuthCredsSchema>;
+
+/** The `Claude Code-credentials` keychain item. Loose: the live item also holds
+ *  sibling state (e.g. per-MCP-server OAuth tokens), which we must preserve when
+ *  swapping - we only ever replace `claudeAiOauth`. */
+export const CredentialBlobSchema = z.looseObject({ claudeAiOauth: OAuthCredsSchema });
+export type CredentialBlob = z.infer<typeof CredentialBlobSchema>;
+
+/** The `oauthAccount` identity object in ~/.claude.json. Loose: preserve every
+ *  key so we can reinstall it verbatim on activation. Only the three ids are
+ *  required; real blobs carry many more fields (some null), so descriptive ones
+ *  are `.nullish()` (string | null | undefined) to tolerate them. */
+export const OAuthAccountSchema = z.looseObject({
+  accountUuid: z.string(),
+  emailAddress: z.string(),
+  organizationUuid: z.string(),
+  organizationName: z.string().nullish(),
+  seatTier: z.string().nullish(),
+  billingType: z.string().nullish(),
+  displayName: z.string().nullish(),
+});
+export type OAuthAccount = z.infer<typeof OAuthAccountSchema>;
+
+export const UsageWindowSchema = z.object({
+  usedPercentage: z.number(),
+  resetsAt: z.number().nullable(),
+});
+export type UsageWindow = z.infer<typeof UsageWindowSchema>;
+
+export const UsageWindowsSchema = z.object({
+  fiveHour: UsageWindowSchema,
+  sevenDay: UsageWindowSchema,
+});
+export type UsageWindows = z.infer<typeof UsageWindowsSchema>;
+
+export const ModelInfoSchema = z.object({ id: z.string(), display: z.string() });
+export type ModelInfo = z.infer<typeof ModelInfoSchema>;
+
+/** usage.json - written by the statusLine shim, read by the Stop hook. Carries
+ *  the two AGGREGATE windows (session=fiveHour, week-all-models=sevenDay) plus
+ *  the active model. Per-model caps live in ModelUsageState (from `/usage`). */
+export const UsageStateSchema = UsageWindowsSchema.extend({
+  org: z.string().nullable(),
+  ts: z.number(),
+  model: ModelInfoSchema.nullable().default(null),
+});
+export type UsageState = z.infer<typeof UsageStateSchema>;
+
+/** model-usage.json - per-model weekly caps parsed from `claude -p '/usage'`,
+ *  TTL-cached so we don't poll every turn. Keyed by model display name ("Fable"). */
+export const ModelUsageStateSchema = z.object({
+  perModel: z.record(z.string(), UsageWindowSchema).default({}),
+  org: z.string().nullable(),
+  ts: z.number(),
+});
+export type ModelUsageState = z.infer<typeof ModelUsageStateSchema>;
+
+/** A parked account in the pool (accounts.json - NON-secret). */
+export const AccountSchema = z.object({
+  accountUuid: z.string(),
+  email: z.string(),
+  organizationUuid: z.string(),
+  label: z.string(),
+  keychainItem: z.string(),
+  oauthAccount: OAuthAccountSchema,
+  addedAt: z.string(),
+  lastUsage: UsageWindowsSchema.optional(),
+  lastPerModel: z.record(z.string(), UsageWindowSchema).optional(),
+  needsReauth: z.boolean().optional(),
+  subscriptionType: z.string().optional(),
+});
+export type Account = z.infer<typeof AccountSchema>;
+
+export const AccountsIndexSchema = z.object({
+  version: z.literal(1),
+  activeAccountUuid: z.string().nullable(),
+  accounts: z.array(AccountSchema).default([]),
+});
+export type AccountsIndex = z.infer<typeof AccountsIndexSchema>;
+
+export const ConfigSchema = z.object({
+  threshold: z.number(),
+  claudeBin: z.string(),
+  policy: z.object({
+    projectionMargin: z.number(),
+    /** models whose PER-MODEL weekly cap should trigger a switch (display names, lowercased). */
+    switchModels: z.array(z.string()),
+    /** how long a `/usage` per-model poll stays fresh before we re-poll (ms). */
+    usagePollTtlMs: z.number(),
+    /** when every account is depleted, auto-wait for a reset only if it is within this window (ms). */
+    maxWaitMs: z.number(),
+  }),
+});
+export type Config = z.infer<typeof ConfigSchema>;
+
+/** The hook -> supervisor respawn marker at respawn/<session-id>. */
+export const RespawnMarkerSchema = z.object({
+  account: z.string(),
+  ts: z.number(),
+  /** when set, the supervisor waits until this epoch ms before relaunching. */
+  waitUntil: z.number().optional(),
+});
+export type RespawnMarker = z.infer<typeof RespawnMarkerSchema>;
+
+/** rate_limits + model as they appear in statusLine stdin (epoch-seconds resets). */
+export const RateLimitsStdinSchema = z.looseObject({
+  rate_limits: z
+    .looseObject({
+      five_hour: z.looseObject({ used_percentage: z.number(), resets_at: z.number().nullable().optional() }).optional(),
+      seven_day: z.looseObject({ used_percentage: z.number(), resets_at: z.number().nullable().optional() }).optional(),
+    })
+    .optional(),
+  model: z.looseObject({ id: z.string().optional(), display_name: z.string().optional() }).optional(),
+  organizationUuid: z.string().optional(),
+});
+
+/** Success body of the OAuth refresh grant. */
+export const RefreshResponseSchema = z.looseObject({
+  access_token: z.string(),
+  refresh_token: z.string().optional(),
+  expires_in: z.number().optional(),
+  refresh_token_expires_in: z.number().optional(),
+  scope: z.string().optional(),
+  token_type: z.string().optional(),
+});
+export type RefreshResponse = z.infer<typeof RefreshResponseSchema>;
+
+/** Success body of GET /api/oauth/claude_cli/roles - the org a token ACTUALLY
+ *  belongs to, independent of any stored label. */
+export const RolesResponseSchema = z.looseObject({
+  organization_uuid: z.string(),
+  organization_name: z.string(),
+});
+export type RolesResponse = z.infer<typeof RolesResponseSchema>;

package/src/lib/usage.ts

@@ -0,0 +1,216 @@
+// Usage data from two sources: statusLine stdin (pushed every turn, aggregate
+// windows only, epoch resets) and `claude -p '/usage'` (free, 0 tokens, all
+// three limit kinds). `/usage` is a client-side command that renders the same
+// figures claude's own usage screen shows; we run it in a throwaway
+// CLAUDE_CONFIG_DIR to sample a parked account without disturbing the live login.
+
+import { delay } from "es-toolkit";
+import { z } from "zod";
+import { resolveRealClaude } from "./claudebin.ts";
+import { log } from "./log.ts";
+import { RateLimitsStdinSchema, UsageWindowSchema, type ModelInfo, type UsageWindow, type UsageWindows } from "./types.ts";
+
+/** Normalize a resets_at value (epoch s, epoch ms, or ISO string) to epoch ms. */
+export function normalizeResetsAt(v: unknown): number | null {
+  const num = z.number().finite().safeParse(v);
+  if (num.success) {
+    return num.data < 1e12 ? Math.round(num.data * 1000) : Math.round(num.data);
+  }
+  const str = z.string().safeParse(v);
+  if (str.success && str.data.trim() !== "") {
+    const n = Number(str.data);
+    if (Number.isFinite(n)) return normalizeResetsAt(n);
+    const t = Date.parse(str.data);
+    return Number.isFinite(t) ? t : null;
+  }
+  return null;
+}
+
+const win = (w?: { used_percentage: number; resets_at?: number | null }): UsageWindow => ({
+  usedPercentage: w?.used_percentage ?? 0,
+  resetsAt: normalizeResetsAt(w?.resets_at),
+});
+
+/** Extract the two AGGREGATE windows from statusLine stdin. null if absent. */
+export function parseStatusLineStdin(obj: unknown): UsageWindows | null {
+  const parsed = RateLimitsStdinSchema.safeParse(obj);
+  if (!parsed.success) return null;
+  const rl = parsed.data.rate_limits;
+  if (!rl || (!rl.five_hour && !rl.seven_day)) return null;
+  return { fiveHour: win(rl.five_hour), sevenDay: win(rl.seven_day) };
+}
+
+/** Extract the active model from statusLine stdin. null if absent. */
+export function parseStatusLineModel(obj: unknown): ModelInfo | null {
+  const parsed = RateLimitsStdinSchema.safeParse(obj);
+  if (!parsed.success) return null;
+  const m = parsed.data.model;
+  if (!m?.id && !m?.display_name) return null;
+  return { id: m?.id ?? m?.display_name ?? "", display: m?.display_name ?? m?.id ?? "" };
+}
+
+export const FullUsageSchema = z.object({
+  session: UsageWindowSchema,
+  weekAll: UsageWindowSchema,
+  perModel: z.record(z.string(), UsageWindowSchema),
+});
+export type FullUsage = z.infer<typeof FullUsageSchema>;
+
+// ---- `/usage` text parsing -----------------------------------------------
+
+const MONTHS: Record<string, number> = {
+  jan: 0, feb: 1, mar: 2, apr: 3, may: 4, jun: 5, jul: 6, aug: 7, sep: 8, oct: 9, nov: 10, dec: 11,
+};
+
+/** The tz offset (wall-clock minus UTC, in ms) in `tz` at instant `utcMs`. */
+function tzOffsetMs(utcMs: number, tz: string): number {
+  const parts = new Intl.DateTimeFormat("en-US", {
+    timeZone: tz,
+    hourCycle: "h23",
+    year: "numeric", month: "2-digit", day: "2-digit",
+    hour: "2-digit", minute: "2-digit", second: "2-digit",
+  }).formatToParts(new Date(utcMs));
+  const p: Record<string, number> = {};
+  for (const part of parts) if (part.type !== "literal") p[part.type] = Number(part.value);
+  const asUTC = Date.UTC(p.year!, p.month! - 1, p.day!, p.hour!, p.minute!, p.second!);
+  return asUTC - utcMs;
+}
+
+/** Interpret a wall-clock time in `tz` as an epoch (DST-correct via one refine). */
+function zonedWallToEpoch(y: number, mon: number, day: number, hour: number, min: number, tz: string): number {
+  const guess = Date.UTC(y, mon, day, hour, min);
+  const off1 = tzOffsetMs(guess, tz);
+  const off2 = tzOffsetMs(guess - off1, tz);
+  return guess - off2;
+}
+
+/**
+ * Parse a `/usage` reset clock like `Jul 11 at 12pm (Asia/Seoul)` or
+ * `Jul 9 at 11:20pm (Asia/Seoul)` to epoch ms. The text carries no year, so we
+ * pick the year whose resulting instant is nearest `now` (resets are always days
+ * away, so the correct year wins by ~360 days). Returns null if unparseable.
+ */
+export function parseResetClock(clock: string, now = Date.now()): number | null {
+  const m = clock.match(/\b([A-Za-z]{3,9})\s+(\d{1,2})\s+at\s+(\d{1,2})(?::(\d{2}))?\s*([ap])m\s*\(([^)]+)\)/i);
+  if (!m) return null;
+  const mon = MONTHS[m[1]!.slice(0, 3).toLowerCase()];
+  if (mon === undefined) return null;
+  const day = Number(m[2]);
+  let hour = Number(m[3]) % 12;
+  if (m[5]!.toLowerCase() === "p") hour += 12;
+  const min = m[4] ? Number(m[4]) : 0;
+  const tz = m[6]!.trim();
+
+  const baseYear = new Date(now).getUTCFullYear();
+  let best: number | null = null;
+  for (const y of [baseYear - 1, baseYear, baseYear + 1]) {
+    let epoch: number;
+    try {
+      epoch = zonedWallToEpoch(y, mon, day, hour, min, tz);
+    } catch {
+      return null; // invalid tz
+    }
+    if (best === null || Math.abs(epoch - now) < Math.abs(best - now)) best = epoch;
+  }
+  return best;
+}
+
+/**
+ * Parse `claude -p '/usage'` .result text into all three limit kinds:
+ *   Current session: N% used · resets <clock>      → session (5h)
+ *   Current week (all models): N% used · resets …   → weekAll (7d aggregate)
+ *   Current week (<Model>): N% used · resets …      → perModel[<Model>]
+ */
+export function parseUsageTextFull(text: string, now = Date.now()): FullUsage | null {
+  if (!text) return null;
+  // The reset clock is required in full (month day at h[:mm]am/pm (tz)) inside its
+  // optional group, so the lazy bridge is forced to find it when present yet the
+  // group cleanly skips a line that has no clock - and it never swallows a
+  // following "Current …" entry on a single line.
+  const re = /current (session|week \(([^)]+)\)):\s*(\d+)\s*%(?:[^\n]*?\bresets\s+([A-Z][a-z]{2,8}\s+\d{1,2}\s+at\s+\d{1,2}(?::\d{2})?\s*[ap]m\s*\([^)]+\)))?/gi;
+  let session: UsageWindow | null = null;
+  let weekAll: UsageWindow | null = null;
+  const perModel: Record<string, UsageWindow> = {};
+  for (let m = re.exec(text); m !== null; m = re.exec(text)) {
+    const window: UsageWindow = { usedPercentage: Number(m[3]), resetsAt: m[4] ? parseResetClock(m[4], now) : null };
+    if (m[1]!.toLowerCase() === "session") session = window;
+    else if (/^all models$/i.test(m[2]!.trim())) weekAll = window;
+    else perModel[m[2]!.trim()] = window;
+  }
+  if (!session && !weekAll && Object.keys(perModel).length === 0) return null;
+  return {
+    session: session ?? { usedPercentage: 0, resetsAt: null },
+    weekAll: weekAll ?? { usedPercentage: 0, resetsAt: null },
+    perModel,
+  };
+}
+
+/** Aggregate windows only (session→5h, week-all→7d), for the cold-start fallback. */
+export function parseUsageText(text: string, now = Date.now()): UsageWindows | null {
+  const f = parseUsageTextFull(text, now);
+  if (!f) return null;
+  return { fiveHour: f.session, sevenDay: f.weekAll };
+}
+
+/** Env-var identity/credential overrides the claude binary honors BEFORE its
+ *  keychain lookup (verified 2.1.205). A probe MUST scrub every one of these or
+ *  an ambient value silently meters the wrong account. */
+const CRED_ENV_OVERRIDES = [
+  "ANTHROPIC_API_KEY",
+  "ANTHROPIC_AUTH_TOKEN",
+  "CLAUDE_CODE_OAUTH_TOKEN",
+  "CLAUDE_CODE_SUBSCRIPTION_TYPE",
+  "CLAUDE_CODE_RATE_LIMIT_TIER",
+  "CLAUDE_SECURESTORAGE_CONFIG_DIR",
+  "CLAUDE_CODE_USE_BEDROCK",
+  "CLAUDE_CODE_USE_VERTEX",
+] as const;
+
+/** One `claude -p '/usage'` invocation → parsed usage, or null if it produced no
+ *  limit lines (claude prints only a local-stats footer when its own usage fetch
+ *  errors/throttles) or failed to run. */
+async function probeUsageOnce(env: Record<string, string>, now: number): Promise<FullUsage | null> {
+  let out: string;
+  try {
+    const p = Bun.spawn([resolveRealClaude(), "-p", "/usage", "--output-format", "json"], {
+      env,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    out = await new Response(p.stdout).text();
+    const errText = await new Response(p.stderr).text();
+    await p.exited;
+    if (p.exitCode !== 0) {
+      log("usage.probe_failed", { exit: p.exitCode ?? "signal", stderr: errText.trim().slice(0, 200) });
+      return null;
+    }
+  } catch (e) {
+    log("usage.probe_failed", { err: String((e as Error).message ?? e) });
+    return null;
+  }
+
+  const j = z.object({ result: z.string() }).safeParse((() => { try { return JSON.parse(out); } catch { return null; } })());
+  const full = parseUsageTextFull(j.success ? j.data.result : out, now);
+  if (!full) log("usage.probe_unparsed", { sample: out.trim().slice(0, 120) });
+  return full;
+}
+
+/**
+ * Run `claude -p '/usage'` (free, 0 tokens) and parse all three limit kinds.
+ * Pass `configDir` to sample a specific account (its CLAUDE_CONFIG_DIR); omit to
+ * sample the live account. All ambient credential overrides are scrubbed so the
+ * probe meters exactly the OAuth credential in the (possibly namespaced)
+ * keychain item. The empty-footer case (claude's own usage call throttled) is
+ * transient, so retry it a couple of times. Returns null if it never yields data.
+ */
+export async function probeUsage(configDir?: string, now = Date.now()): Promise<FullUsage | null> {
+  const env: Record<string, string> = { ...process.env, TOKENMAXXING_PROBE: "1" };
+  for (const k of CRED_ENV_OVERRIDES) delete env[k];
+  if (configDir) env.CLAUDE_CONFIG_DIR = configDir;
+
+  for (let attempt = 0; ; attempt++) {
+    const full = await probeUsageOnce(env, now);
+    if (full || attempt >= 2) return full;
+    await delay(1500);
+  }
+}