tokenmaxxing 1.131.0 → 1.132.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "1.131.0",
+  "version": "1.132.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/key.ts

@@ -0,0 +1,147 @@
+import { z } from "zod";
+import { keySessions, loadApiKeys, removeApiKeySecret, saveApiKeys, writeApiKeySecret } from "../lib/apikeys.ts";
+import { withLock } from "../lib/lock.ts";
+import { claudePool } from "../lib/paths.ts";
+import { readStdin } from "../lib/proc.ts";
+import type { ApiKey } from "../lib/types.ts";
+import { c, emitError, plain } from "./render.ts";
+
+const USAGE = "usage: tokenmaxxing key add <label> [credit-usd] [workspace-id] (the key on stdin) | key credit <label> <usd> | key rm <label>";
+
+const UsdSchema = z.coerce.number().finite().min(0);
+
+const WorkspaceIdSchema = z
+  .string()
+  .min(1)
+  .refine((id) => id.trim() === id && !id.includes("\n") && !id.includes("\r"), "a workspace id is one line with no surrounding whitespace");
+
+export function usd(amount: number): string {
+  return `$${amount.toFixed(2)}`;
+}
+
+function findKey(keys: ApiKey[], label: string): ApiKey | undefined {
+  return keys.find((k) => k.label.toLowerCase() === label.toLowerCase());
+}
+
+function parseUsd(raw: string): number | null {
+  const parsed = UsdSchema.safeParse(raw);
+  if (parsed.success) return parsed.data;
+  emitError({ message: `"${raw}" is not a dollar amount (a number at or above 0)` });
+  return null;
+}
+
+async function add(args: string[]): Promise<number> {
+  const [label, creditRaw, workspaceRaw] = args;
+  if (!label) {
+    emitError({ message: USAGE, paint: plain });
+    return 2;
+  }
+  const credit = creditRaw == null ? undefined : parseUsd(creditRaw);
+  if (credit === null) return 2;
+  const workspace = workspaceRaw == null ? undefined : WorkspaceIdSchema.safeParse(workspaceRaw);
+  if (workspace != null && !workspace.success) {
+    emitError({ message: `"${workspaceRaw}" is not a workspace id: ${workspace.error.issues[0]?.message ?? "invalid"}` });
+    return 2;
+  }
+  const workspaceId = workspace?.data;
+  if (process.stdin.isTTY) {
+    emitError({ message: "refusing to read the API key from a terminal, which would echo it - pipe it in: read -rs KEY && printf '%s' \"$KEY\" | tokenmaxxing key add <label> ...; unset KEY" });
+    return 2;
+  }
+  const secret = (await readStdin()).trim();
+  if (secret === "") {
+    emitError({ message: "no API key on stdin - pipe the key in, for example from your password manager" });
+    return 2;
+  }
+  if (secret.includes("\n") || secret.includes("\r")) {
+    emitError({ message: "stdin holds more than one line - pass one API key per `key add`" });
+    return 2;
+  }
+  if (secret.startsWith("sk-ant-admin")) {
+    emitError({ message: "that is an Admin API key, which cannot run inference - create a regular API key in the Console" });
+    return 2;
+  }
+  return withLock(claudePool.lockFile, () => {
+    const idx = loadApiKeys();
+    const taken = findKey(idx.keys, label);
+    if (taken) {
+      emitError({ message: `label "${label}" is already used by another API key - labels must be unique` });
+      return 1;
+    }
+    let id = crypto.randomUUID().slice(0, 8);
+    while (idx.keys.some((k) => k.id === id)) id = crypto.randomUUID().slice(0, 8);
+    const now = Date.now();
+    writeApiKeySecret(id, secret);
+    idx.keys.push({
+      id,
+      label,
+      ...(workspaceId != null ? { workspaceId } : {}),
+      ...(credit != null ? { creditUsd: credit } : {}),
+      spentUsd: 0,
+      creditSetAt: now,
+      addedAt: now,
+    });
+    saveApiKeys(idx);
+    console.log(`added API key ${c.bold(label)} (${credit != null ? `credit ${usd(credit)}` : "credit unknown, ranks after keys with a balance"}${workspaceId != null ? `, workspace ${workspaceId}` : ""})`);
+    return 0;
+  });
+}
+
+async function credit(args: string[]): Promise<number> {
+  const [label, amountRaw] = args;
+  if (!label || amountRaw == null || args.length > 2) {
+    emitError({ message: USAGE, paint: plain });
+    return 2;
+  }
+  const amount = parseUsd(amountRaw);
+  if (amount === null) return 2;
+  return withLock(claudePool.lockFile, () => {
+    const idx = loadApiKeys();
+    const key = findKey(idx.keys, label);
+    if (!key) {
+      emitError({ message: `no API key is labeled "${label}"` });
+      return 1;
+    }
+    key.creditUsd = amount;
+    key.spentUsd = 0;
+    key.creditSetAt = Date.now();
+    key.refusedAt = undefined;
+    saveApiKeys(idx);
+    console.log(`set ${c.bold(key.label)} credit to ${usd(amount)}`);
+    return 0;
+  });
+}
+
+async function rm(args: string[]): Promise<number> {
+  const [label] = args;
+  if (!label || args.length > 1) {
+    emitError({ message: USAGE, paint: plain });
+    return 2;
+  }
+  return withLock(claudePool.lockFile, () => {
+    const idx = loadApiKeys();
+    const key = findKey(idx.keys, label);
+    if (!key) {
+      emitError({ message: `no API key is labeled "${label}"` });
+      return 1;
+    }
+    if (keySessions().has(key.id)) {
+      emitError({ message: `${key.label} is running in a live session - close that session before removing the key.` });
+      return 1;
+    }
+    removeApiKeySecret(key.id);
+    idx.keys = idx.keys.filter((k) => k.id !== key.id);
+    saveApiKeys(idx);
+    console.log(`removed API key ${c.bold(key.label)} (${idx.keys.length} left)`);
+    return 0;
+  });
+}
+
+export async function cmdKey(args: string[]): Promise<number> {
+  const [action, ...rest] = args;
+  if (action === "add") return add(rest);
+  if (action === "credit") return credit(rest);
+  if (action === "rm") return rm(rest);
+  emitError({ message: USAGE, paint: plain });
+  return 2;
+}

package/src/cli/status.ts

@@ -1,4 +1,5 @@
 import { chunk, sortBy } from "es-toolkit";
+import { creditLeft, keySessions, loadApiKeys } from "../lib/apikeys.ts";
 import { claude } from "../lib/claude.ts";
 import { codex } from "../lib/codex.ts";
 import { grok } from "../lib/grok.ts";
@@ -7,6 +8,7 @@ import { withLock } from "../lib/lock.ts";
 import { codexPool, grokPool } from "../lib/paths.ts";
 import { barFor, bufferedUsed, earliestReset, gatedWindows, landGrant, landWindows, isExhausted, isSessionWindow, limitWindows, liveUsed, nextWeeklyReset, sessionWindow, thresholdBars, weeklyWindow } from "../lib/picker.ts";
 import type { Provider, SampleReport } from "../lib/provider.ts";
+import { usd } from "./key.ts";
 import { bar, c, count, emitJson, fmtAgo } from "./render.ts";
 import type { Account, AccountThresholds, Bars, Config, Thresholds, Window } from "../lib/types.ts";
 
@@ -38,7 +40,48 @@ type PoolReport = {
   accounts: StatusAccount[];
 };
 
-export type StatusReport = { now: number; claude: PoolReport; codex: PoolReport; grok: PoolReport };
+type StatusApiKey = {
+  label: string;
+  id: string;
+  workspaceId: string | null;
+  creditUsd: number | null;
+  spentUsd: number;
+  creditLeftUsd: number | null;
+  refused: boolean;
+  refusedAt: number | null;
+  sessions: number;
+};
+
+export type StatusReport = { now: number; claude: PoolReport; codex: PoolReport; grok: PoolReport; apiKeys?: StatusApiKey[] };
+
+function apiKeyReport(): StatusApiKey[] {
+  const sessions = keySessions();
+  return loadApiKeys().keys.map((k) => ({
+    label: k.label,
+    id: k.id,
+    workspaceId: k.workspaceId ?? null,
+    creditUsd: k.creditUsd ?? null,
+    spentUsd: k.spentUsd,
+    creditLeftUsd: creditLeft(k),
+    refused: k.refusedAt != null,
+    refusedAt: k.refusedAt ?? null,
+    sessions: sessions.get(k.id) ?? 0,
+  }));
+}
+
+function renderApiKeys(keys: StatusApiKey[]): void {
+  console.log(c.dim(`api keys  (${count({ n: keys.length, noun: "key" })}, used only while every claude account is at its limit)`));
+  console.log();
+  for (const k of keys) {
+    const badges: string[] = [];
+    if (k.sessions > 0) badges.push(c.green(count({ n: k.sessions, noun: "session" })));
+    if (k.refused) badges.push(c.red("refused"));
+    else if (k.creditLeftUsd != null && k.creditLeftUsd <= 0) badges.push(c.yellow("spent"));
+    const credit = k.creditLeftUsd == null ? c.dim("credit unknown") : `credit left ${usd(k.creditLeftUsd)}`;
+    console.log(`${k.sessions > 0 ? c.green("●") : c.dim("○")} ${c.bold(k.label)} ${credit}${badges.length ? ` ${badges.join(" ")}` : ""}`);
+  }
+  console.log();
+}
 
 function currentWindow(a: Account, w: Window, bars: Bars | null, now: number): WindowReport {
   const passed = w.resetsAt != null && w.resetsAt <= now;
@@ -259,11 +302,12 @@ export async function cmdStatus(opts: { json?: boolean; cached?: boolean } = {})
   const cfg = loadConfig();
   const now = Date.now();
   const claudeReport = await collect(claude, cfg, now, cached);
+  const apiKeys = apiKeyReport();
   if (!json) {
     const codexPooled = loadAccounts(codexPool).accounts.length > 0;
     const grokPooled = loadAccounts(grokPool).accounts.length > 0;
     if (claudeReport.accounts.length === 0) {
-      if (!codexPooled && !grokPooled) {
+      if (!codexPooled && !grokPooled && apiKeys.length === 0) {
         console.log(c.dim("no accounts yet, run `tokenmaxxing init` (or `tokenmaxxing init --codex`, `--grok`)"));
         return 0;
       }
@@ -273,11 +317,12 @@ export async function cmdStatus(opts: { json?: boolean; cached?: boolean } = {})
       const header = `thresholds 5h ${claudeReport.thresholds.session}% weekly ${claudeReport.thresholds.weekly}%  bars 5h ${claudeReport.bars.session}% weekly ${claudeReport.bars.weekly}%  (${count({ n: claudeReport.accounts.length, noun: "claude account" })})`;
       renderPool(claude, claudeReport, header, Date.now(), cfg.policy.usagePollTtlMs);
     }
+    if (apiKeys.length > 0) renderApiKeys(apiKeys);
   }
   const codexReport = await collect(codex, cfg, now, cached);
   const grokReport = await collect(grok, cfg, now, cached);
   if (json) {
-    const report: StatusReport = { now, claude: claudeReport, codex: codexReport, grok: grokReport };
+    const report: StatusReport = { now, claude: claudeReport, codex: codexReport, grok: grokReport, ...(apiKeys.length > 0 ? { apiKeys } : {}) };
     emitJson({ ok: true, ...report });
     return 0;
   }

package/src/entries/statusline.ts

@@ -1,5 +1,8 @@
+import { existsSync } from "node:fs";
 import { sortBy } from "es-toolkit";
+import { writeSessionCost } from "../lib/apikeys.ts";
 import { claudePool, seatFromEnv } from "../lib/paths.ts";
+import { supervisedSession } from "../lib/sessions.ts";
 import { errorMessage } from "../lib/log.ts";
 import { loadAccounts, loadConfig, writeUsage } from "../lib/state.ts";
 import { familyTokens, matchedFamily, parseStatusLineStdin, parseStatusLineModel } from "../lib/usage.ts";
@@ -8,6 +11,7 @@ import { readStdin } from "../lib/proc.ts";
 import { worktreeName } from "../lib/worktree.ts";
 import { fmtResetShort, makeColors, makeUsagePaint, statuslineColor } from "../cli/render.ts";
 import {
+  CostLineSchema,
   JsonTextSchema,
   StatusLineStdinSchema,
   type Account,
@@ -127,6 +131,12 @@ export async function runStatusline(): Promise<number> {
     }
   } catch {
   }
+  try {
+    const session = existsSync(claudePool.apiKeysJson) ? supervisedSession() : null;
+    const cost = session == null ? null : (CostLineSchema.safeParse(obj).data ?? null);
+    if (session != null && cost != null && cost.sessionId === session.live) writeSessionCost(session.sid, cost);
+  } catch {
+  }
 
   let line: string;
   try {

package/src/entries/stopfailurehook.ts

@@ -2,9 +2,10 @@ import { existsSync, readdirSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { z } from "zod";
 import { claude } from "../lib/claude.ts";
-import { evaluateAndMaybeSwap } from "../lib/decide.ts";
+import { liveApiKeyId, refuseApiKey } from "../lib/apikeys.ts";
+import { evaluateAndMaybeSwap, moveTarget } from "../lib/decide.ts";
 import { readStdin } from "../lib/proc.ts";
-import { adoptLiveSession, refusedAccounts, supervisedSession, writeRespawnMarker } from "../lib/sessions.ts";
+import { adoptLiveSession, keyMovesSupported, refusedAccounts, supervisedSession, writeRespawnMarker } from "../lib/sessions.ts";
 import { loadConfig } from "../lib/state.ts";
 import { classifyEnforcedLimit, ENFORCED_ERRORS, findEnforcedRow, parseErrorBody, readTranscriptTail, type TranscriptRow } from "../lib/usage.ts";
 import { paths } from "../lib/paths.ts";
@@ -60,6 +61,22 @@ export async function runStopFailureHook(): Promise<number> {
       return 0;
     }
     const canRespawn = session != null && mainLoop;
+    const keyId = account == null ? liveApiKeyId() : null;
+    if (keyId != null) {
+      if (error !== "billing_error") return 0;
+      const known = await refuseApiKey(keyId, now);
+      log("stopfailure.key_refused", { key: keyId, known, subagent: !mainLoop });
+      const decision = await evaluateAndMaybeSwap(claude, now, canRespawn, null, { waiterId: canRespawn ? session?.sid : undefined, refused: refusedAccounts(), apiKeys: true, apiKeyId: keyId });
+      const target = moveTarget(decision);
+      if (session && canRespawn && target) {
+        writeRespawnMarker({ session, ...target, waitUntil: target.waitUntil ?? now, compact: false, origin: "stopfailure" });
+        log("stopfailure.marker", { session: session.sid.slice(0, 8), live: session.live.slice(0, 8), account: target.accountId.slice(0, 8), key: target.apiKeyId, waitUntil: target.waitUntil ?? now });
+      } else {
+        log("stopfailure.decision", { reason: decision.reason, swapped: decision.swapped, account: decision.account?.id.slice(0, 8), waitUntil: decision.waitUntil });
+      }
+      return 0;
+    }
+    if (error === "billing_error") return 0;
     const cfg = loadConfig();
     const row = stdin.transcript_path
       ? await awaitEnforcedRow({ transcriptPath: stdin.transcript_path, agentId: stdin.agent_id, error, lastAssistantMessage: stdin.last_assistant_message })
@@ -92,10 +109,11 @@ export async function runStopFailureHook(): Promise<number> {
     }
 
     const refused = enforced?.kind === "credits" ? [...new Set([...refusedAccounts(), enforced.account])] : undefined;
-    const decision = await evaluateAndMaybeSwap(claude, now, canRespawn, enforced, { waiterId: canRespawn ? session?.sid : undefined, exclude: refused });
-    if (session && canRespawn && decision.account && (decision.swapped || decision.waitUntil !== undefined)) {
-      writeRespawnMarker({ session, accountId: decision.account.id, waitUntil: decision.waitUntil ?? now, compact: false, origin: "stopfailure", refused });
-      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 });
+    const decision = await evaluateAndMaybeSwap(claude, now, canRespawn, enforced, { waiterId: canRespawn ? session?.sid : undefined, exclude: refused, apiKeys: canRespawn && keyMovesSupported() });
+    const target = moveTarget(decision);
+    if (session && canRespawn && target) {
+      writeRespawnMarker({ session, ...target, waitUntil: target.waitUntil ?? now, compact: false, origin: "stopfailure", refused });
+      log("stopfailure.marker", { session: session.sid.slice(0, 8), live: session.live.slice(0, 8), account: target.accountId.slice(0, 8), key: target.apiKeyId, waitUntil: target.waitUntil ?? now });
     } else {
       log("stopfailure.decision", { reason: decision.reason, swapped: decision.swapped, account: decision.account?.id.slice(0, 8), waitUntil: decision.waitUntil });
     }

package/src/entries/stophook.ts

@@ -1,8 +1,8 @@
 import { z } from "zod";
 import { claude } from "../lib/claude.ts";
-import { evaluateAndMaybeSwap } from "../lib/decide.ts";
+import { evaluateAndMaybeSwap, moveTarget } from "../lib/decide.ts";
 import { readStdin } from "../lib/proc.ts";
-import { adoptLiveSession, refusedAccounts, supervisedSession, writeRespawnMarker } from "../lib/sessions.ts";
+import { adoptLiveSession, keyMovesSupported, refusedAccounts, supervisedSession, writeRespawnMarker } from "../lib/sessions.ts";
 import { JsonTextSchema } from "../lib/types.ts";
 import { errorMessage, log } from "../lib/log.ts";
 
@@ -24,10 +24,11 @@ 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, null, { waiterId: session?.sid, refused: refusedAccounts() });
-    if (session && decision.account && (decision.swapped || decision.waitUntil !== undefined)) {
-      writeRespawnMarker({ session, accountId: decision.account.id, waitUntil: decision.waitUntil ?? Date.now(), compact: true, origin: event });
-      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) });
+    const decision = await evaluateAndMaybeSwap(claude, Date.now(), session != null, null, { waiterId: session?.sid, refused: refusedAccounts(), apiKeys: session != null && keyMovesSupported() });
+    const target = moveTarget(decision);
+    if (session && target) {
+      writeRespawnMarker({ session, ...target, waitUntil: target.waitUntil ?? Date.now(), compact: true, origin: event });
+      log(`${event}.${target.waitUntil !== undefined ? "wait" : "move"}`, { source: stdin.source, account: target.accountId.slice(0, 8), key: target.apiKeyId, waitUntil: target.waitUntil, session: session.sid.slice(0, 8), live: session.live.slice(0, 8) });
     }
   } catch (e) {
     log(`${event}.error`, { err: errorMessage(e) });

package/src/entries/supervisor.ts

@@ -6,9 +6,10 @@ import { maxBy, omit } from "es-toolkit";
 import { z } from "zod";
 import { claudePool, paths, storeDirFor } from "../lib/paths.ts";
 import { CLAUDE_BIN, UNMANAGED_ENV, WRAP_DEPTH_ENV, resolveRealBin, wrapDepth } from "../lib/claudebin.ts";
-import { claude, pickSeat } from "../lib/claude.ts";
+import { apiKeyEnv, clearSessionCost, foldSessionCost, loadApiKeys, readApiKey, sendApiKey, usableApiKey, writeSessionCost } from "../lib/apikeys.ts";
+import { claude, pickLaunch, type LaunchTarget } from "../lib/claude.ts";
 import { compactClaudeSession } from "../lib/compact.ts";
-import { evaluateAndMaybeSwap } from "../lib/decide.ts";
+import { evaluateAndMaybeSwap, moveTarget } from "../lib/decide.ts";
 import { withLock } from "../lib/lock.ts";
 import { thresholdBars, usableAt } from "../lib/picker.ts";
 import { clearPresence } from "../lib/presence.ts";
@@ -19,7 +20,7 @@ import { saveTermios } from "../lib/tty.ts";
 import { liveSessionId, loadSessionFlags, pruneStaleSessions, saveSessionFlags, writeRespawnMarker } from "../lib/sessions.ts";
 import { loadAccounts, loadConfig, readJsonFile, releaseWaitClaim, writeUsage } from "../lib/state.ts";
 import { gatedFamilies, modelFromFlag, parseStreamLine, scrubCredEnv } from "../lib/usage.ts";
-import { JsonTextSchema, RespawnMarkerSchema, type Account, type Config, type ModelInfo, type UsageWindows } from "../lib/types.ts";
+import { CostLineSchema, JsonTextSchema, RespawnMarkerSchema, type Account, type ApiKey, type Config, type ModelInfo, type UsageWindows } from "../lib/types.ts";
 import { errorMessage, log } from "../lib/log.ts";
 
 const SUBCOMMANDS = new Set([
@@ -254,10 +255,11 @@ 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, { seatId: seat.id, sessionFamilies: families, waiterId: sid, refused });
-    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, origin: "seatwatch" });
+    const decision = await evaluateAndMaybeSwap(claude, now, true, null, { seatId: seat.id, sessionFamilies: families, waiterId: sid, refused, apiKeys: true });
+    log("supervisor.seat_exhausted", { seat: seat.id.slice(0, 8), until, reason: decision.reason, account: decision.account?.id.slice(0, 8), key: decision.apiKey?.id, waitUntil: decision.waitUntil });
+    const target = moveTarget(decision);
+    if (target) {
+      writeRespawnMarker({ session: { sid, launchedAt: gate.launchedAt, live: liveSessionId(sid) }, ...target, waitUntil: target.waitUntil ?? now, compact: true, origin: "seatwatch" });
     }
   } catch (e) {
     log("supervisor.seat_watch_error", { err: errorMessage(e) });
@@ -265,14 +267,54 @@ async function moveExhaustedSeat(seat: Account, sid: string, gate: MarkerGate, m
   return true;
 }
 
+async function moveKeySession(key: ApiKey, sid: string, gate: MarkerGate, model: ModelInfo | null, refused: string[], resumed: Set<string>): Promise<boolean> {
+  await foldCost(sid, key.id, resumed);
+  try {
+    if (usableApiKey(key.id) != null) return false;
+    const now = Date.now();
+    const cfg = loadConfig();
+    const families = gatedFamilies(model, cfg.policy.switchModels);
+    const decision = await evaluateAndMaybeSwap(claude, now, true, null, { seatId: null, sessionFamilies: families, waiterId: sid, refused, apiKeys: true, apiKeyId: key.id });
+    log("supervisor.key_watch", { key: key.id, reason: decision.reason, account: decision.account?.id.slice(0, 8), next: decision.apiKey?.id, waitUntil: decision.waitUntil });
+    const target = moveTarget(decision);
+    if (target && (target.waitUntil === undefined || target.waitUntil > gate.overriddenUntil)) {
+      writeRespawnMarker({ session: { sid, launchedAt: gate.launchedAt, live: liveSessionId(sid) }, ...target, waitUntil: target.waitUntil ?? now, compact: true, origin: "seatwatch" });
+    }
+  } catch (e) {
+    log("supervisor.key_watch_error", { err: errorMessage(e) });
+  }
+  return true;
+}
+
+function resolveLaunch(wanted: { accountId: string | null; apiKeyId: string | null } | null, now: number, model: ModelInfo | null): LaunchTarget | null {
+  if (wanted?.apiKeyId != null) {
+    const key = usableApiKey(wanted.apiKeyId);
+    if (key) return { account: null, apiKey: key };
+  } else if (wanted?.accountId != null) {
+    const id = wanted.accountId;
+    const account = loadAccounts(claudePool).accounts.find((a) => a.id === id);
+    if (account) return { account, apiKey: null };
+  }
+  return pickLaunch(now, model);
+}
+
+async function foldCost(sid: string, keyId: string | null, resumed: Set<string>): Promise<void> {
+  try {
+    await foldSessionCost(sid, keyId, resumed);
+  } catch (e) {
+    log("supervisor.cost_fold_failed", { err: errorMessage(e) });
+  }
+}
+
 function systemLine(sid: string, text: string): string {
   return `${JSON.stringify({ type: "system", subtype: "informational", content: text, level: "warning", uuid: crypto.randomUUID(), session_id: sid })}\n`;
 }
 
-function resumePrompt(input: { compacted: boolean; origin: z.infer<typeof RespawnMarkerSchema>["origin"] }): string {
+function resumePrompt(input: { compacted: boolean; origin: z.infer<typeof RespawnMarkerSchema>["origin"]; onKey: boolean }): string {
+  const where = input.onKey ? "on an Anthropic API key, because every pooled account is at its limit or the previous key ran out" : "on an account with quota headroom";
   const moved = input.compacted
-    ? "tokenmaxxing compacted this conversation and resumed the session on an account with quota headroom."
-    : "tokenmaxxing resumed this session on an account with quota headroom.";
+    ? `tokenmaxxing compacted this conversation and resumed the session ${where}.`
+    : `tokenmaxxing resumed this session ${where}.`;
   if (input.origin === "stop") {
     return `${moved} The previous turn finished before the move. If it waited on the user or completed the task, end this turn without restating it. If it waited on a background Bash task, Monitor, or Workflow run, relaunch that work, because the move ended it.`;
   }
@@ -304,11 +346,14 @@ function stoppedTaskLines(open: OpenTasks): string[] {
   return [...open].map(([id, task]) => `${JSON.stringify({ type: "system", subtype: "task_notification", task_id: id, status: "stopped", reason: "worker_restart", output_file: "", summary: `Stopped by a tokenmaxxing restart: ${task.description || id}`, uuid: crypto.randomUUID(), session_id: task.sessionId })}\n`);
 }
 
-function seatTee(seatId: string, model: ModelInfo | null, open: OpenTasks): (line: string) => void {
+function seatTee(seatId: string | null, model: ModelInfo | null, open: OpenTasks, costSid: string | null): (line: string) => void {
   let last: UsageWindows | null = null;
   return (line) => {
     const value = JsonTextSchema.safeParse(line).data;
     trackTask(open, value);
+    const cost = costSid == null ? null : (CostLineSchema.safeParse(value).data ?? null);
+    if (costSid != null && cost != null) writeSessionCost(costSid, cost);
+    if (seatId == null) return;
     const msg = parseStreamLine(value);
     if (msg?.windows) last = msg.windows;
     else if (msg?.type !== "assistant") return;
@@ -508,7 +553,7 @@ export async function runSupervisor(argv: string[]): Promise<number> {
   });
 
   if (!info.manage || process.env[UNMANAGED_ENV]) {
-    const passthroughEnv = omit(childEnv, ["TOKENMAXXING_SUPERVISED", "TOKENMAXXING_SESSION_ID", "TOKENMAXXING_MODEL", "TOKENMAXXING_REFUSED"]);
+    const passthroughEnv = omit(childEnv, ["TOKENMAXXING_SUPERVISED", "TOKENMAXXING_SESSION_ID", "TOKENMAXXING_MODEL", "TOKENMAXXING_REFUSED", "TOKENMAXXING_API_KEY_ID"]);
     return runPassthrough({ real, argv, env: passthroughEnv, onSpawn: (p) => { child = p; } });
   }
 
@@ -536,6 +581,7 @@ export async function runSupervisor(argv: string[]): Promise<number> {
   pruneStaleSessions(Date.now());
 
   let launchArgs = resume ? ["--resume", sid, ...base] : ["--session-id", sid, ...base];
+  const resumed = new Set<string>(resume ? [sid] : []);
   let pendingTranscript = resume ? null : transcriptPath(sid);
 
   mkdirSync(paths.respawnDir, { recursive: true });
@@ -557,7 +603,7 @@ export async function runSupervisor(argv: string[]): Promise<number> {
   let firstLine: string | null = null;
   let respawns = 0;
   let overriddenUntil = 0;
-  let wanted: string | null = null;
+  let wanted: { accountId: string | null; apiKeyId: string | null } | null = null;
   let refused: string[] = [];
   let drainStdout: (() => Promise<void>) | null = null;
   try {
@@ -567,55 +613,62 @@ export async function runSupervisor(argv: string[]): Promise<number> {
     const gate: MarkerGate = { launchedAt: Date.now(), overriddenUntil };
     const launched = await withLock(claudePool.lockFile, async () => {
       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 target = resolveLaunch(wanted, gate.launchedAt, model);
+      const picked = target?.account ?? null;
+      const key = target?.apiKey ?? null;
+      log("supervisor.launch", { sid, respawns, seat: picked?.id.slice(0, 8) ?? null, key: key?.id, args: launchArgs.join(" "), injected: firstLine !== null });
       const open: OpenTasks = new Map();
-      const tee = stream && picked ? seatTee(picked.id, model, open) : null;
+      const costSid = existsSync(claudePool.apiKeysJson) ? sid : null;
+      const tee = stream && (picked || costSid != null) ? seatTee(picked?.id ?? null, model, open, costSid) : null;
+      const secret = key ? readApiKey(key) : null;
+      const extra: "pipe"[] = secret == null ? [] : ["pipe"];
+      const scrubbed = scrubCredEnv(childEnv);
       const spawned = Bun.spawn([real, ...launchArgs], {
-        stdin: relay === null ? "inherit" : "pipe",
-        stdout: tee === null ? "inherit" : "pipe",
-        stderr: "inherit",
+        stdio: [relay === null ? "inherit" : "pipe", tee === null ? "inherit" : "pipe", "inherit", ...extra],
         env: {
-          ...(picked ? { ...scrubCredEnv(childEnv), CLAUDE_SECURESTORAGE_CONFIG_DIR: storeDirFor(picked.id) } : childEnv),
+          ...(picked ? { ...scrubbed, CLAUDE_SECURESTORAGE_CONFIG_DIR: storeDirFor(picked.id) } : key ? apiKeyEnv(scrubbed, key) : childEnv),
           TOKENMAXXING_SUPERVISED: "1",
           TOKENMAXXING_SESSION_ID: sid,
           TOKENMAXXING_LAUNCHED_AT: String(gate.launchedAt),
           TOKENMAXXING_MODEL: effective.model ?? "",
           TOKENMAXXING_REFUSED: refused.join(","),
+          TOKENMAXXING_API_KEY_ID: key?.id ?? "",
         },
       });
       child = spawned;
+      if (secret != null) sendApiKey(spawned, secret);
       const drain = tee !== null && spawned.stdout instanceof ReadableStream ? relayStdout(spawned.stdout, tee) : null;
       if (relay !== null) relay.attach(spawned.stdin!, firstLine, pendingTranscript);
       firstLine = null;
-      if (picked) {
+      if (picked || key) {
         await recordPresenceOrStop({
           child: spawned,
           dir: paths.presenceDir,
           id: sid,
-          accountId: picked.id,
+          accountId: picked?.id ?? "",
+          ...(key ? { apiKeyId: key.id } : {}),
           event: "supervisor.presence_failed",
           message: "could not write the session presence file - refusing to run a session whose seat placement cannot see",
           savedTermios,
         });
       }
       releaseClaimLocked(sid);
-      return { child: spawned, seat: picked, drain, open };
+      return { child: spawned, seat: picked, key, drain, open };
     });
     if (launched == null) {
       await releaseClaim();
       return 143;
     }
 
-    const { child: proc, seat, open } = launched;
+    const { child: proc, seat, key, open } = launched;
     drainStdout = launched.drain;
     let seatCheckAt = 0;
     await raceMarkerOrExit({
       child: proc,
       tick: async () => {
         if (existsSync(marker) && (await consumableMarker(marker, gate)) != null) return true;
-        if (seat && !terminating && Date.now() >= seatCheckAt) {
-          const decided = await moveExhaustedSeat(seat, sid, gate, model, refused);
+        if ((seat || key) && !terminating && Date.now() >= seatCheckAt) {
+          const decided = seat ? await moveExhaustedSeat(seat, sid, gate, model, refused) : key ? await moveKeySession(key, sid, gate, model, refused, resumed) : false;
           seatCheckAt = Date.now() + (decided ? SEAT_RETRY_MS : SEAT_POLL_MS);
         }
         return false;
@@ -630,6 +683,7 @@ export async function runSupervisor(argv: string[]): Promise<number> {
     });
     await drainStdout?.();
     drainStdout = null;
+    await foldCost(sid, key?.id ?? null, resumed);
 
     const m = !terminating && existsSync(marker) ? await consumableMarker(marker, gate) : null;
     if (m) {
@@ -638,7 +692,8 @@ export async function runSupervisor(argv: string[]): Promise<number> {
       noticeSid = m.sessionId;
       for (const line of stoppedTaskLines(open)) process.stdout.write(line);
       const accounts = loadAccounts(claudePool).accounts;
-      const label = accounts.find((a) => a.id === m.accountId)?.label ?? m.accountId.slice(0, 8);
+      const nextKey = m.apiKeyId == null ? null : (loadApiKeys().keys.find((k) => k.id === m.apiKeyId) ?? null);
+      const label = m.apiKeyId != null ? `API key ${nextKey?.label ?? m.apiKeyId}` : (accounts.find((a) => a.id === m.accountId)?.label ?? m.accountId.slice(0, 8));
       const walledUntil = accounts.find((a) => a.id === seat?.id)?.enforcedUntil ?? 0;
       const transcript = findTranscript(m.sessionId);
       const resumable = transcript !== null;
@@ -646,34 +701,50 @@ export async function runSupervisor(argv: string[]): Promise<number> {
         for (const id of relay.replay()) process.stdout.write(controlErrorLine(id));
       }
       let compacted = false;
+      const compactKey = key != null && usableApiKey(key.id) != null ? key : null;
+      const compactOn = seat?.label ?? (compactKey ? `API key ${compactKey.label}` : null);
       if (m.compact && seat && resumable && walledUntil > Date.now()) {
         log("supervisor.compact_skipped", { sid: m.sessionId.slice(0, 8), seat: seat.id.slice(0, 8), until: walledUntil });
-      } else if (m.compact && seat && resumable) {
-        say(`\n\x1b[36m↻ tokenmaxxing: compacting the conversation on ${seat.label} before the move...\x1b[0m\n`, `tokenmaxxing: compacting the conversation on ${seat.label} before the move.`);
-        const compactEnv = { ...omit(scrubCredEnv(childEnv), ["TOKENMAXXING_SUPERVISED", "TOKENMAXXING_SESSION_ID", "TOKENMAXXING_LAUNCHED_AT", "TOKENMAXXING_MODEL", "TOKENMAXXING_REFUSED"]), TOKENMAXXING_PROBE: "1", CLAUDE_SECURESTORAGE_CONFIG_DIR: storeDirFor(seat.id) };
-        const outcome = await compactClaudeSession({ real, sid: m.sessionId, transcript, env: compactEnv, onSpawn: (p) => { child = p; } });
+      } else if (m.compact && compactOn != null && resumable) {
+        say(`\n\x1b[36m↻ tokenmaxxing: compacting the conversation on ${compactOn} before the move...\x1b[0m\n`, `tokenmaxxing: compacting the conversation on ${compactOn} before the move.`);
+        const baseEnv = { ...omit(scrubCredEnv(childEnv), ["TOKENMAXXING_SUPERVISED", "TOKENMAXXING_SESSION_ID", "TOKENMAXXING_LAUNCHED_AT", "TOKENMAXXING_MODEL", "TOKENMAXXING_REFUSED", "TOKENMAXXING_API_KEY_ID"]), TOKENMAXXING_PROBE: "1" };
+        const compactEnv = seat ? { ...baseEnv, CLAUDE_SECURESTORAGE_CONFIG_DIR: storeDirFor(seat.id) } : compactKey ? apiKeyEnv(baseEnv, compactKey) : baseEnv;
+        const compactSecret = seat == null && compactKey ? readApiKey(compactKey) : null;
+        const outcome = await compactClaudeSession({
+          real,
+          sid: m.sessionId,
+          transcript,
+          env: compactEnv,
+          keyPipe: compactSecret != null,
+          onSpawn: (p) => {
+            child = p;
+            if (compactSecret != null) sendApiKey(p, compactSecret);
+          },
+        });
         child = null;
         if (terminating) {
           await releaseClaim();
           return 143;
         }
-        log("supervisor.compact", { sid: m.sessionId.slice(0, 8), seat: seat.id.slice(0, 8), ok: outcome.ok, reason: outcome.ok ? undefined : outcome.reason });
+        log("supervisor.compact", { sid: m.sessionId.slice(0, 8), seat: seat?.id.slice(0, 8), key: compactKey?.id, ok: outcome.ok, reason: outcome.ok ? undefined : outcome.reason });
         if (!outcome.ok) say(`\x1b[33m   compaction did not land (${outcome.reason}) - resuming with the full context\x1b[0m\n`, `tokenmaxxing: compaction did not land; resuming with the full context. (${outcome.reason})`);
         compacted = outcome.ok;
       }
       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.`);
-      wanted = m.accountId;
+      wanted = m.apiKeyId != null ? { accountId: null, apiKeyId: m.apiKeyId } : { accountId: m.accountId, apiKeyId: null };
       refused = m.refused ?? refused;
       saveSessionFlags(m.sessionId, persistable, process.cwd());
-      const prompt = resumable ? resumePrompt({ compacted, origin: m.origin }) : null;
+      const prompt = resumable ? resumePrompt({ compacted, origin: m.origin, onKey: m.apiKeyId != null }) : null;
       firstLine = relay !== null && prompt !== null ? userLine(prompt) : null;
       pendingTranscript = resumable ? null : transcriptPath(m.sessionId);
+      if (resumable) resumed.add(m.sessionId);
       launchArgs = [resumable ? "--resume" : "--session-id", m.sessionId, ...(relay === null && prompt !== null ? [prompt] : []), ...persistable];
       continue;
     }
     clearPresence({ dir: paths.presenceDir, id: sid });
+    clearSessionCost(sid);
     await releaseClaim();
     log("supervisor.exit", { sid, respawns, code: proc.exitCode, signal: proc.signalCode, terminated: terminating || undefined });
     return exitStatus(proc);

package/src/lib/apikeys.ts

@@ -0,0 +1,142 @@
+import { chmodSync, closeSync, existsSync, mkdirSync, readFileSync, rmSync, writeSync } from "node:fs";
+import { join } from "node:path";
+import { countBy, isEqual, sortBy } from "es-toolkit";
+import { writeFileAtomic } from "./atomic.ts";
+import { withLock } from "./lock.ts";
+import { claudePool, optionalEnv, paths } from "./paths.ts";
+import { livingPresences } from "./presence.ts";
+import type { ApiKeyPool } from "./provider.ts";
+import { readJsonFile } from "./state.ts";
+import { ApiKeysIndexSchema, SessionCostSchema, type ApiKey, type ApiKeysIndex, type SessionCost } from "./types.ts";
+
+export const API_KEY_ENV = "TOKENMAXXING_API_KEY_ID";
+export const API_KEY_FD = 3;
+
+export function apiKeyEnv(env: Record<string, string | undefined>, key: ApiKey): Record<string, string | undefined> {
+  const header = key.workspaceId == null ? null : `anthropic-workspace-id: ${key.workspaceId}`;
+  const headers = header == null ? env.ANTHROPIC_CUSTOM_HEADERS : env.ANTHROPIC_CUSTOM_HEADERS ? `${env.ANTHROPIC_CUSTOM_HEADERS}\n${header}` : header;
+  return { ...env, CLAUDE_CODE_API_KEY_FILE_DESCRIPTOR: String(API_KEY_FD), ...(headers != null ? { ANTHROPIC_CUSTOM_HEADERS: headers } : {}) };
+}
+
+export function readApiKey(key: ApiKey): string {
+  return `${readFileSync(apiKeySecretFor(key.id), "utf8").trim()}\n`;
+}
+
+export function sendApiKey(child: { stdio: readonly (number | null)[] }, secret: string): void {
+  const fd = child.stdio[API_KEY_FD];
+  if (fd == null) throw new Error(`the child has no descriptor ${API_KEY_FD} to receive the API key`);
+  try {
+    const written = writeSync(fd, secret);
+    if (written !== Buffer.byteLength(secret)) throw new Error(`wrote ${written} of ${Buffer.byteLength(secret)} bytes of the API key to descriptor ${API_KEY_FD}`);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+export function apiKeySecretFor(id: string): string {
+  return join(paths.apiKeysDir, id);
+}
+
+export function loadApiKeys(): ApiKeysIndex {
+  if (!existsSync(claudePool.apiKeysJson)) return { version: 1, keys: [], baselines: {} };
+  return readJsonFile(claudePool.apiKeysJson, ApiKeysIndexSchema);
+}
+
+export function saveApiKeys(idx: ApiKeysIndex): void {
+  writeFileAtomic(claudePool.apiKeysJson, JSON.stringify(ApiKeysIndexSchema.parse(idx), null, 2) + "\n");
+}
+
+export function writeApiKeySecret(id: string, secret: string): void {
+  mkdirSync(paths.apiKeysDir, { recursive: true, mode: 0o700 });
+  chmodSync(paths.apiKeysDir, 0o700);
+  writeFileAtomic(apiKeySecretFor(id), secret);
+}
+
+export function removeApiKeySecret(id: string): void {
+  rmSync(apiKeySecretFor(id), { force: true });
+}
+
+export function creditLeft(k: ApiKey): number | null {
+  return k.creditUsd == null ? null : k.creditUsd - k.spentUsd;
+}
+
+export function keyUsable(k: ApiKey): boolean {
+  const left = creditLeft(k);
+  return k.refusedAt == null && (left == null || left > 0);
+}
+
+export function keySessions(): Map<string, number> {
+  const ids = livingPresences(paths.presenceDir).flatMap((p) => (p.apiKeyId == null ? [] : [p.apiKeyId]));
+  return new Map(Object.entries(countBy(ids, (id) => id)));
+}
+
+export function pickApiKey(keys: ApiKey[], sessions: Map<string, number>, exclude: string[]): ApiKey | null {
+  const candidates = keys.filter((k) => keyUsable(k) && !exclude.includes(k.id));
+  return sortBy(candidates, [(k) => (creditLeft(k) == null ? 1 : 0), (k) => -(creditLeft(k) ?? 0), (k) => sessions.get(k.id) ?? 0, (k) => k.addedAt])[0] ?? null;
+}
+
+function availableKeys(): ApiKey[] {
+  return loadApiKeys().keys.filter((k) => existsSync(apiKeySecretFor(k.id)));
+}
+
+export function usableApiKey(id: string): ApiKey | null {
+  const key = availableKeys().find((k) => k.id === id);
+  return key != null && keyUsable(key) ? key : null;
+}
+
+export function launchApiKey(): ApiKey | null {
+  return pickApiKey(availableKeys(), keySessions(), []);
+}
+
+export function liveApiKeyId(env: Record<string, string | undefined> = process.env): string | null {
+  return optionalEnv(API_KEY_ENV, env) ?? null;
+}
+
+export const claudeApiKeys: ApiKeyPool = {
+  liveId: () => liveApiKeyId(),
+  holds: (id) => usableApiKey(id) != null,
+  pick: (exclude) => pickApiKey(availableKeys(), keySessions(), exclude),
+};
+
+export async function refuseApiKey(id: string, now: number): Promise<boolean> {
+  return withLock(claudePool.lockFile, () => {
+    const idx = loadApiKeys();
+    const key = idx.keys.find((k) => k.id === id);
+    if (!key) return false;
+    key.refusedAt = now;
+    saveApiKeys(idx);
+    return true;
+  });
+}
+
+const costFileFor = (sid: string): string => join(paths.costDir, `${sid}.json`);
+
+export function writeSessionCost(sid: string, cost: SessionCost): void {
+  const file = costFileFor(sid);
+  if (existsSync(file) && isEqual(readJsonFile(file, SessionCostSchema), cost)) return;
+  writeFileAtomic(file, JSON.stringify(cost));
+}
+
+export function clearSessionCost(sid: string): void {
+  rmSync(costFileFor(sid), { force: true });
+}
+
+const BASELINE_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+
+export async function foldSessionCost(sid: string, keyId: string | null, resumed: Set<string>): Promise<void> {
+  const file = costFileFor(sid);
+  if (!existsSync(file) || !existsSync(claudePool.apiKeysJson)) return;
+  const seen = readJsonFile(file, SessionCostSchema);
+  await withLock(claudePool.lockFile, () => {
+    const idx = loadApiKeys();
+    const prev = idx.baselines[seen.sessionId];
+    if (prev?.usd === seen.usd) return;
+    const delta = prev != null ? Math.max(0, seen.usd - prev.usd) : resumed.has(seen.sessionId) ? 0 : seen.usd;
+    const key = keyId == null ? undefined : idx.keys.find((k) => k.id === keyId);
+    if (key) key.spentUsd += delta;
+    const now = Date.now();
+    idx.baselines = Object.fromEntries(Object.entries(idx.baselines).filter(([, b]) => now - b.at <= BASELINE_RETENTION_MS));
+    idx.baselines[seen.sessionId] = { usd: seen.usd, at: now };
+    saveApiKeys(idx);
+  });
+}

package/src/lib/claude.ts

@@ -2,6 +2,7 @@ import { mkdirSync, readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { countBy } from "es-toolkit";
 import { z } from "zod";
+import { claudeApiKeys, launchApiKey } from "./apikeys.ts";
 import { readItem, writeItem, deleteItem, isolatedTarget, readStore, storeTarget, claudeAiOauthOnly } from "./credstore.ts";
 import { CLAUDE_BIN, resolveRealBin, resolveVerifiedClaude } from "./claudebin.ts";
 import { activationHint, CHECK_JOB, ensurePathInRc, HUB_JOB, installSupervisor, managedShellRcSkipLines, shellRcPath } from "./install.ts";
@@ -17,7 +18,7 @@ import { claimSample, foldTee, landRead, readyToSample, runSample, sampleAccount
 import { clearUsageSnapshot, liveWaitClaims, loadAccounts, loadConfig, loadUsageSnapshot, pinBinOverride, readJsonFile, saveAccounts, type Harvest } from "./state.ts";
 import { saveTermios, restoreTermios } from "./tty.ts";
 import { claimResetGrant, fetchUsageDirect, gatedFamilies, mergeWindows, modelFromFlag, scrubCredEnv, windowsOf } from "./usage.ts";
-import { CredentialBlobSchema, JsonTextSchema, OAuthAccountSchema, type Account, type Config, type ModelInfo } from "./types.ts";
+import { CredentialBlobSchema, JsonTextSchema, OAuthAccountSchema, type Account, type ApiKey, type Config, type ModelInfo } from "./types.ts";
 import { c } from "../cli/render.ts";
 
 function liveId(): string | null {
@@ -25,7 +26,7 @@ function liveId(): string | null {
 }
 
 function presence(living = livingPresences(paths.presenceDir)): Map<string, number> {
-  const seats = new Map(living.map((s) => [s.id, s.accountId]));
+  const seats = new Map(living.filter((s) => s.apiKeyId == null).map((s) => [s.id, s.accountId]));
   for (const claim of liveWaitClaims(Date.now())) seats.set(claim.sessionId, claim.accountId);
   return new Map(Object.entries(countBy([...seats.values()], (id) => id)));
 }
@@ -138,7 +139,7 @@ async function storeUsable(a: Account): Promise<boolean> {
   }
 }
 
-export function pickSeat(now: number, model: ModelInfo | null, eligible: (a: Account) => boolean = () => true): Account | null {
+function seatContext(now: number, model: ModelInfo | null, eligible: (a: Account) => boolean): { candidates: Account[]; ctx: PickCtx; fallback: () => Account | null } {
   const cfg = loadConfig();
   const bars = thresholdBars(cfg);
   const idx = loadAccounts(claudePool);
@@ -148,12 +149,28 @@ export function pickSeat(now: number, model: ModelInfo | null, eligible: (a: Acc
   const seats = presence();
   const ctx: PickCtx = { now, thresholds: bars, currentId: null, families: gatedFamilies(model, cfg.policy.switchModels), seats };
   const candidates = idx.accounts.filter(eligible);
-  return (
-    pickBest(candidates, ctx) ??
+  const fallback = () =>
     pickWaitTarget(candidates, ctx, seats, MAX_WAITERS_PER_ACCOUNT, now + cfg.policy.maxWaitMs, now + 2 * cfg.policy.maxWaitMs)?.account ??
     pickEarliestReset(candidates, ctx)?.account ??
-    null
-  );
+    null;
+  return { candidates, ctx, fallback };
+}
+
+export function pickSeat(now: number, model: ModelInfo | null, eligible: (a: Account) => boolean = () => true): Account | null {
+  const { candidates, ctx, fallback } = seatContext(now, model, eligible);
+  return pickBest(candidates, ctx) ?? fallback();
+}
+
+export type LaunchTarget = { account: Account; apiKey: null } | { account: null; apiKey: ApiKey };
+
+export function pickLaunch(now: number, model: ModelInfo | null): LaunchTarget | null {
+  const { candidates, ctx, fallback } = seatContext(now, model, () => true);
+  const best = pickBest(candidates, ctx);
+  if (best) return { account: best, apiKey: null };
+  const key = launchApiKey();
+  if (key) return { account: null, apiKey: key };
+  const account = fallback();
+  return account ? { account, apiKey: null } : null;
 }
 
 export async function borrowClaudeSeat(pid: number): Promise<SeatBorrow> {
@@ -335,6 +352,7 @@ export const claude: Provider = {
   seats: "shared",
   waitsWhenDepleted: true,
   statusOnly: false,
+  apiKeys: claudeApiKeys,
   liveId,
   presence,
   gatedFamilies: (cfg) => {

package/src/lib/compact.ts

@@ -13,13 +13,12 @@ const PIPE_GRACE_MS = 2_000;
 
 const CompactBoundarySchema = z.looseObject({ type: z.literal("system"), subtype: z.literal("compact_boundary") });
 
-export async function compactClaudeSession(input: { real: string; sid: string; transcript: string; env: Record<string, string | undefined>; onSpawn: (child: Subprocess) => void }): Promise<CompactOutcome> {
+export async function compactClaudeSession(input: { real: string; sid: string; transcript: string; env: Record<string, string | undefined>; keyPipe: boolean; onSpawn: (child: Subprocess) => void }): Promise<CompactOutcome> {
   const offset = statSync(input.transcript).size;
+  const extra: "pipe"[] = input.keyPipe ? ["pipe"] : [];
   const p = Bun.spawn([input.real, "-p", "--resume", input.sid, "/compact"], {
     env: input.env,
-    stdin: "ignore",
-    stdout: "pipe",
-    stderr: "pipe",
+    stdio: ["ignore", "pipe", "pipe", ...extra],
     timeout: CLAUDE_COMPACT_KILL_MS,
     killSignal: "SIGKILL",
   });

package/src/lib/decide.ts

@@ -6,9 +6,9 @@ import { MAX_WAITERS_PER_ACCOUNT, isExhausted, landWindows, limitWindows, liveUs
 import { familyTokens } from "./usage.ts";
 import { errorMessage, log } from "./log.ts";
 import type { Observation, Provider, ResetClaim } from "./provider.ts";
-import type { Account, Bars, Config, EnforcedLimit } from "./types.ts";
+import type { Account, ApiKey, Bars, Config, EnforcedLimit } from "./types.ts";
 
-export type SwapDecision = { swapped: boolean; account: Account | null; reason: string; waitUntil?: number };
+export type SwapDecision = { swapped: boolean; account: Account | null; apiKey?: ApiKey; reason: string; waitUntil?: number };
 
 export type EvalOpts = {
   seatId?: string | null;
@@ -16,8 +16,18 @@ export type EvalOpts = {
   waiterId?: string;
   exclude?: string[];
   refused?: string[];
+  apiKeys?: boolean;
+  apiKeyId?: string;
 };
 
+export type MoveTarget = { accountId: string; apiKeyId?: string; waitUntil: number | undefined };
+
+export function moveTarget(d: SwapDecision): MoveTarget | null {
+  if (d.apiKey) return { accountId: "", apiKeyId: d.apiKey.id, waitUntil: undefined };
+  if (d.account && (d.swapped || d.waitUntil !== undefined)) return { accountId: d.account.id, waitUntil: d.waitUntil };
+  return null;
+}
+
 const MOVE_CLAIM_MS = 2 * CLAUDE_COMPACT_KILL_MS;
 
 const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
@@ -106,6 +116,8 @@ export async function useBankedResets(p: Provider, cfg: Config, now: number): Pr
 
 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 keys = opts.apiKeys === true ? p.apiKeys : undefined;
+  const keyId = activeId == null && keys ? (opts.apiKeyId ?? keys.liveId()) : null;
   const waiterId = canRespawn ? opts.waiterId : undefined;
   const cfg = loadConfig();
   const bars = thresholdBars(cfg);
@@ -116,7 +128,7 @@ export async function evaluateAndMaybeSwap(p: Provider, now = Date.now(), canRes
   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 (!enforced && keyId == null && !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);
@@ -168,7 +180,7 @@ export async function evaluateAndMaybeSwap(p: Provider, now = Date.now(), canRes
     const seats = p.seats === "shared" ? present : null;
 
     const seatExhausted = active != null && isExhausted(active, { now, thresholds: bars, currentId: id2, families: switchFamilies, seats });
-    if (!enforced2 && !isOver(active, obs2, { now, thresholds: bars, currentId: id2, families, seats }) && !(enforced && seatExhausted)) {
+    if (keyId == null && !enforced2 && !isOver(active, obs2, { now, thresholds: bars, currentId: id2, families, seats }) && !(enforced && seatExhausted)) {
       return { swapped: false, account: null, reason: "raced-already-swapped" };
     }
     if (p.seats === "shared" && !canRespawn) {
@@ -189,9 +201,9 @@ export async function evaluateAndMaybeSwap(p: Provider, now = Date.now(), canRes
       const seat = seatOf(cur);
       const ctx: PickCtx = { now, thresholds: bars, currentId: seat?.id ?? null, families: switchFamilies, seats };
       const credited = !enforced2 && seat != null && !seat.needsReauth && !isExhausted(seat, ctx) && onCredits(seat, ctx);
-      const best = pickBest(usable(cur.accounts).filter((a) => !(credited && opts.refused?.includes(a.id))), ctx);
+      const best = pickBest(usable(cur.accounts).filter((a) => !((credited || keyId != null) && opts.refused?.includes(a.id))), ctx);
       if (credited && (best == null || onCredits(best, ctx))) return { swapped: false, account: null, reason: "no-plan-headroom" };
-      if (!best) break;
+      if (!best || (keyId != null && onCredits(best, ctx))) break;
       try {
         await p.swap(best);
       } catch (e) {
@@ -203,6 +215,15 @@ export async function evaluateAndMaybeSwap(p: Provider, now = Date.now(), canRes
       return { swapped: true, account: best, reason: "swapped" };
     }
 
+    if (keys) {
+      if (keyId != null && keys.holds(keyId)) return { swapped: false, account: null, reason: "api-key-holds" };
+      const key = keys.pick(keyId == null ? [] : [keyId]);
+      if (key) {
+        log("decide.api_key", { key: key.id, from: keyId ?? id2?.slice(0, 8) });
+        return { swapped: true, account: null, apiKey: key, reason: "api-key" };
+      }
+    }
+
     if (!p.waitsWhenDepleted) {
       log("decide.depleted", { waitUntil: 0 });
       return { swapped: false, account: null, reason: "all-depleted" };

package/src/lib/paths.ts

@@ -28,6 +28,8 @@ export const paths = {
   onboardDir: join(TM_HOME, "onboard"),
   storesDir: join(TM_HOME, "stores"),
   hubKeyFile: join(TM_HOME, "hub-key"),
+  apiKeysDir: join(TM_HOME, "api-keys"),
+  costDir: join(TM_HOME, "cost"),
 
   claudeSettings: env(
     "TOKENMAXXING_CLAUDE_SETTINGS",
@@ -43,6 +45,7 @@ export const claudePool = {
   accountsJson: join(TM_HOME, "accounts.json"),
   lockFile: join(TM_HOME, "lock"),
   waitQueueJson: join(TM_HOME, "wait-queue.json"),
+  apiKeysJson: join(TM_HOME, "api-keys.json"),
 } as const;
 
 export const codexPool = {

package/src/lib/pi.ts

@@ -98,6 +98,7 @@ export async function piLogin(pool: PiPool): Promise<PiLogin | null> {
 function piMover(base: Provider, pool: PiPool): Provider {
   return {
     ...base,
+    apiKeys: undefined,
     swap: async (target) => {
       if (!piStoreUsable(pool, target.id)) {
         throw new StoreUnusableError(`${target.label} has no pi login - run \`tokenmaxxing auth --pi${base.flag} ${target.label}\``);

package/src/lib/presence.ts

@@ -13,12 +13,13 @@ const PresenceSchema = z.object({
   accountId: z.string(),
   pid: z.number(),
   startedAt: z.string(),
+  apiKeyId: z.string().optional(),
 });
 
-export function writePresence(input: { dir: string; id: string; accountId: string; pid: number }): void {
+export function writePresence(input: { dir: string; id: string; accountId: string; pid: number; apiKeyId?: string }): void {
   const startedAt = pidStartTimes([input.pid]).get(input.pid);
   if (startedAt == null) throw new Error(`could not read pid ${input.pid}'s start time (ps lstart) - refusing to write an unverifiable presence file`);
-  writeFileAtomic(join(input.dir, input.id), JSON.stringify(PresenceSchema.parse({ accountId: input.accountId, pid: input.pid, startedAt })));
+  writeFileAtomic(join(input.dir, input.id), JSON.stringify(PresenceSchema.parse({ accountId: input.accountId, pid: input.pid, startedAt, ...(input.apiKeyId != null ? { apiKeyId: input.apiKeyId } : {}) })));
 }
 
 export function presencePid(input: { dir: string; id: string }): number | null {
@@ -34,7 +35,7 @@ export function clearPresence(input: { dir: string; id: string }): void {
   rmSync(join(input.dir, input.id), { force: true });
 }
 
-export type LivingPresence = { id: string; accountId: string };
+export type LivingPresence = { id: string; accountId: string; apiKeyId?: string };
 
 export function livingPresences(dir: string): LivingPresence[] {
   if (!existsSync(dir)) return [];
@@ -65,11 +66,11 @@ export function livingPresences(dir: string): LivingPresence[] {
       rmSync(file, { force: true });
       continue;
     }
-    living.push({ id: name, accountId: record.accountId });
+    living.push({ id: name, accountId: record.accountId, ...(record.apiKeyId != null ? { apiKeyId: record.apiKeyId } : {}) });
   }
   return living;
 }
 
 export function seatCounts(dir: string): Map<string, number> {
-  return new Map(Object.entries(countBy(livingPresences(dir), (p) => p.accountId)));
+  return new Map(Object.entries(countBy(livingPresences(dir).filter((p) => p.apiKeyId == null), (p) => p.accountId)));
 }

package/src/lib/provider.ts

@@ -1,6 +1,12 @@
 import type { PoolPaths } from "./paths.ts";
 import type { Harvest } from "./state.ts";
-import type { Account, Config, Window } from "./types.ts";
+import type { Account, ApiKey, Config, Window } from "./types.ts";
+
+export type ApiKeyPool = {
+  liveId(): string | null;
+  holds(id: string): boolean;
+  pick(exclude: string[]): ApiKey | null;
+};
 
 export type Observation = { windows: Window[]; at: number };
 
@@ -26,6 +32,7 @@ export type Provider = {
   seats: "shared" | "live";
   waitsWhenDepleted: boolean;
   statusOnly: boolean;
+  apiKeys?: ApiKeyPool;
   liveId(): string | null;
   presence(): Map<string, number>;
   gatedFamilies(cfg: Config): string[] | null;

package/src/lib/sessions.ts

@@ -60,7 +60,7 @@ function listDir(dir: string, root: string): Dirent[] {
 }
 
 function tmpSweepDirs(root: string): string[] {
-  const dirs = [paths.home, paths.usageDir, paths.presenceDir, paths.respawnDir, sessionsDir(), paths.binDir, codexPaths.presenceDir, codexPaths.respawnDir, codexPaths.onboardDir];
+  const dirs = [paths.home, paths.usageDir, paths.presenceDir, paths.respawnDir, sessionsDir(), paths.binDir, paths.apiKeysDir, paths.costDir, codexPaths.presenceDir, codexPaths.respawnDir, codexPaths.onboardDir];
   for (const parent of STORE_PARENTS) {
     for (const child of listDir(parent, root)) {
       if (child.isDirectory()) dirs.push(join(parent, child.name));
@@ -113,6 +113,10 @@ export function supervisedSession(env: Record<string, string | undefined> = proc
   return { sid, launchedAt: LaunchedAtSchema.parse(env.TOKENMAXXING_LAUNCHED_AT) ?? null, live: liveSessionId(sid) };
 }
 
+export function keyMovesSupported(env: Record<string, string | undefined> = process.env): boolean {
+  return env.TOKENMAXXING_API_KEY_ID !== undefined;
+}
+
 export function refusedAccounts(env: Record<string, string | undefined> = process.env): string[] {
   return RefusedSchema.parse(env.TOKENMAXXING_REFUSED);
 }
@@ -129,9 +133,10 @@ export function adoptLiveSession(session: SupervisedSession, stdinSid: string |
   return { ...session, live: stdinSid };
 }
 
-export function writeRespawnMarker(input: { session: SupervisedSession; accountId: string; waitUntil: number; compact: boolean; origin: z.infer<typeof RespawnMarkerSchema>["origin"]; refused?: string[] }): void {
+export function writeRespawnMarker(input: { session: SupervisedSession; accountId: string; apiKeyId?: string; waitUntil: number; compact: boolean; origin: z.infer<typeof RespawnMarkerSchema>["origin"]; refused?: string[] }): void {
   const payload: z.infer<typeof RespawnMarkerSchema> = {
     accountId: input.accountId,
+    ...(input.apiKeyId != null ? { apiKeyId: input.apiKeyId } : {}),
     ts: Date.now(),
     waitUntil: input.waitUntil,
     sessionId: input.session.live,

package/src/lib/supervise.ts

@@ -82,10 +82,10 @@ export async function runPassthrough(input: { real: string; argv: string[]; env:
   return exitStatus(p);
 }
 
-export async function recordPresenceOrStop(input: { child: ChildHandle; dir: string; id: string; accountId: string; event: string; message: string; savedTermios: string | null }): Promise<void> {
+export async function recordPresenceOrStop(input: { child: ChildHandle; dir: string; id: string; accountId: string; apiKeyId?: string; event: string; message: string; savedTermios: string | null }): Promise<void> {
   for (let attempt = 0; ; attempt++) {
     try {
-      writePresence({ dir: input.dir, id: input.id, accountId: input.accountId, pid: input.child.pid });
+      writePresence({ dir: input.dir, id: input.id, accountId: input.accountId, pid: input.child.pid, ...(input.apiKeyId != null ? { apiKeyId: input.apiKeyId } : {}) });
       return;
     } catch (e) {
       if (input.child.exitCode !== null || input.child.signalCode !== null) return;

package/src/lib/types.ts

@@ -169,8 +169,38 @@ export const RespawnMarkerSchema = z.object({
   origin: z.enum(["stop", "sessionstart", "stopfailure", "seatwatch"]),
   launchedAt: z.number().optional(),
   refused: z.array(z.string()).optional(),
+  apiKeyId: z.string().optional(),
 });
 
+export const ApiKeySchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  workspaceId: z.string().optional(),
+  creditUsd: z.number().optional(),
+  spentUsd: z.number(),
+  creditSetAt: z.number(),
+  refusedAt: z.number().optional(),
+  addedAt: z.number(),
+});
+export type ApiKey = z.infer<typeof ApiKeySchema>;
+
+export const ApiKeysIndexSchema = z.object({
+  version: z.literal(1),
+  keys: z.array(ApiKeySchema).default([]),
+  baselines: z.record(z.string(), z.object({ usd: z.number(), at: z.number() })).default({}),
+});
+export type ApiKeysIndex = z.infer<typeof ApiKeysIndexSchema>;
+
+export const SessionCostSchema = z.object({ sessionId: z.string(), usd: z.number() });
+export type SessionCost = z.infer<typeof SessionCostSchema>;
+
+export const CostLineSchema = z
+  .looseObject({ session_id: z.string(), total_cost_usd: z.number().optional(), cost: z.looseObject({ total_cost_usd: z.number() }).nullable().optional() })
+  .transform((line): SessionCost | null => {
+    const usd = line.total_cost_usd ?? line.cost?.total_cost_usd;
+    return usd == null ? null : { sessionId: line.session_id, usd };
+  });
+
 export const EpochSecondsSchema = z.number().transform((seconds) => seconds * 1000);
 
 export const InstantSchema = z.iso.datetime({ offset: true }).transform((iso) => Date.parse(iso));

package/src/lib/usage.ts

@@ -105,7 +105,7 @@ export function transcriptRowText(row: TranscriptRow): string {
   return blocks.data.filter((b) => b.type === "text").map((b) => b.text ?? "").join("\n").trim();
 }
 
-export const ENFORCED_ERRORS = ["rate_limit", "oauth_org_not_allowed"];
+export const ENFORCED_ERRORS = ["rate_limit", "oauth_org_not_allowed", "billing_error"];
 
 export function findEnforcedRow(input: { rows: TranscriptRow[]; error: string; lastAssistantMessage: string | undefined }): TranscriptRow | null {
   const { rows, error, lastAssistantMessage } = input;

package/src/main.ts

@@ -20,6 +20,7 @@ import { cmdStatus } from "./cli/status.ts";
 import { cmdDoctor } from "./cli/doctor.ts";
 import { cmdRm } from "./cli/rm.ts";
 import { cmdRename } from "./cli/rename.ts";
+import { cmdKey } from "./cli/key.ts";
 import { cmdCheck } from "./cli/check.ts";
 import { cmdConfig } from "./cli/config.ts";
 import { cmdSeat } from "./cli/seat.ts";
@@ -38,7 +39,7 @@ const PI_FLAG = "--pi";
 const JSON_COMMANDS = new Set(["status", "config", "check"]);
 const CODEX_COMMANDS = new Set(["init", "add", "auth", "rm", "rename", "seat"]);
 const STATUS_ONLY_COMMANDS = new Set(["init", "add", "auth", "rm", "rename"]);
-const MAX_OPERANDS = new Map([["init", 0], ["add", 0], ["rm", 1], ["rename", 2]]);
+const MAX_OPERANDS = new Map([["init", 0], ["add", 0], ["rm", 1], ["rename", 2], ["key", 4]]);
 
 function printHelp(): void {
   console.log(`${c.bold("tokenmaxxing")} - automatic Claude Code account switching
@@ -58,6 +59,9 @@ function printHelp(): void {
   ${c.cyan("tokenmaxxing doctor")}     verify the install is intact
   ${c.cyan("tokenmaxxing rename")} [--codex | --grok] <sel> <label>
   ${c.cyan("tokenmaxxing rm")} [--codex | --grok] <sel>
+  ${c.cyan("tokenmaxxing key add")} <label> [credit-usd] [workspace-id]  store an Anthropic API key read from stdin; Claude sessions run on it only while every pooled Claude account is at its limit (workspace-id: for a key that spans several workspaces)
+  ${c.cyan("tokenmaxxing key credit")} <label> <usd>  set the key's balance as the Console shows it and restart its spend count
+  ${c.cyan("tokenmaxxing key rm")} <label>  delete the key and its stored secret (refused while a session runs on it)
   ${c.cyan("tokenmaxxing seat")} <pid>  lend one pooled Claude account to an unattended consumer until <pid> exits: prints the store directory to set as CLAUDE_SECURESTORAGE_CONFIG_DIR (the directory itself, as its owner, never a copy of its credential); host sessions and other borrowers share the account; exit 1 = none usable
   ${c.cyan("tokenmaxxing seat --codex")} <pid>  borrow one pooled codex account for an unattended consumer (plugin, script): prints the CODEX_HOME to set, lent to <pid> until it exits; codex sessions and other borrowers share the account, and a refresh race between them can sign it out until auth --codex runs again; exit 1 = none usable, fall back to the ambient login
   ${c.cyan("tokenmaxxing serve")}      serve the CLIProxyAPI-compatible usage API on http://localhost:<hub.port> (default 8317) so a dashboard such as T3 Code's "Add a CLIProxyAPI hub" shows every pooled Claude and Codex account's quota; the management key is the contents of hub-key in the state directory
@@ -173,6 +177,7 @@ async function main(): Promise<number> {
     case "doctor": return cmdDoctor();
     case "rm": return cmdRm(provider, args[1]);
     case "rename": return cmdRename(provider, args.slice(1));
+    case "key": return cmdKey(args.slice(1));
     case "seat": return cmdSeat(provider === codex ? "codex" : "claude", args[1], args.slice(2));
     case "serve": return cmdServe(args.slice(1));
     case "uninstall": {
@@ -198,7 +203,7 @@ async function main(): Promise<number> {
       if (out.timer === "still-loaded") console.log(c.yellow(`⚠ the check job may still be loaded - run: ${deactivationHint(CHECK_JOB)}`));
       if (out.hub === "still-loaded") console.log(c.yellow(`⚠ the usage hub job may still be loaded - run: ${deactivationHint(HUB_JOB)}`));
       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/; pi: pi-stores/; grok: grok-stores/) - remove accounts with \`xx rm\` to delete their credentials`);
+      console.log(`kept: accounts.json, config.json, and every account credential store (claude: stores/ and its keychain items on macOS; codex: codex-stores/; pi: pi-stores/; grok: grok-stores/), plus api-keys.json and the API keys in api-keys/ - remove accounts with \`xx rm\` and keys with \`xx key rm\` to delete their credentials`);
       return 0;
     }
     case "help":