tokenmaxxing 0.2.0 → 0.2.1

package/src/lib/decide.ts

@@ -0,0 +1,149 @@
+// Shared switch decision used by both the Stop hook and the SessionStart hook.
+// Cheap pre-check off the lock; the authoritative re-check + swap under the flock.
+//
+// Two limit families are checked, both metered against the CURRENTLY-active org:
+//   1. AGGREGATE windows (session=five_hour, week-all=seven_day) from statusLine.
+//   2. PER-MODEL weekly cap (e.g. "week (Fable)") - only when the active model is
+//      capacity-constrained (config policy.switchModels). This isn't in statusLine,
+//      so we read it from `claude -p '/usage'`, TTL-cached (not every turn).
+//
+// The org guard is load-bearing: right after a respawn, usage.json still reflects
+// the OLD account, so org != activeOrg → we correctly do nothing until fresh usage
+// for the new account arrives.
+
+import { z } from "zod";
+import { withLock } from "./lock.ts";
+import { paths } from "./paths.ts";
+import { loadAccounts, loadConfig, loadUsage, loadModelUsage, saveAccounts, saveModelUsage } from "./state.ts";
+import { readOAuthAccount } from "./claudejson.ts";
+import { chooseAndSwap, performSwap } from "./swap.ts";
+import { pickEarliestReset, usableAt } from "./picker.ts";
+import { InvalidGrantError } from "./oauth.ts";
+import { probeUsage } from "./usage.ts";
+import { log } from "./log.ts";
+import { AccountSchema, type Account, type Config, type ModelUsageState, type UsageState, type UsageWindow } from "./types.ts";
+
+const SwapDecisionSchema = z.object({
+  swapped: z.boolean(),
+  account: AccountSchema.nullable(),
+  reason: z.string(),
+  /** set when every account is depleted: epoch ms the chosen account recovers. */
+  waitUntil: z.number().optional(),
+});
+export type SwapDecision = z.infer<typeof SwapDecisionSchema>;
+
+/** Cold-start aggregate fallback when statusLine hasn't written usage.json yet. */
+async function probeAggregate(org: string | null): Promise<UsageState | null> {
+  const full = await probeUsage();
+  if (!full) return null;
+  return { fiveHour: full.session, sevenDay: full.weekAll, org, ts: Date.now(), model: null };
+}
+
+/** Ensure a fresh-enough per-model cache for the active org; poll `/usage` if stale. */
+async function ensurePerModel(cfg: Config, org: string | null): Promise<ModelUsageState | null> {
+  const cached = loadModelUsage();
+  const fresh = cached && cached.org === org && Date.now() - cached.ts < cfg.policy.usagePollTtlMs;
+  if (fresh) return cached;
+  const full = await probeUsage();
+  if (!full) return cached; // keep stale on poll failure
+  const state: ModelUsageState = { perModel: full.perModel, org, ts: Date.now() };
+  saveModelUsage(state);
+  return state;
+}
+
+function capForModel(mu: ModelUsageState | null, display: string): UsageWindow | undefined {
+  if (!mu) return undefined;
+  const key = Object.keys(mu.perModel).find((k) => k.toLowerCase() === display.toLowerCase());
+  return key ? mu.perModel[key] : undefined;
+}
+
+/** True if the active account is over the floor on ANY applicable limit. */
+function isOver(u: UsageState | null, mu: ModelUsageState | null, org: string | null, cfg: Config, floor: number): boolean {
+  if (!u || !org || u.org !== org) return false;
+  if (u.fiveHour.usedPercentage >= floor || u.sevenDay.usedPercentage >= floor) return true;
+  const display = u.model?.display;
+  if (display && cfg.policy.switchModels.includes(display.toLowerCase()) && mu && mu.org === org) {
+    const cap = capForModel(mu, display);
+    if (cap && cap.usedPercentage >= floor) return true;
+  }
+  return false;
+}
+
+/** Does the active model warrant a per-model `/usage` poll? */
+function needsPerModel(u: UsageState | null, cfg: Config): boolean {
+  const display = u?.model?.display;
+  return !!display && cfg.policy.switchModels.includes(display.toLowerCase());
+}
+
+export async function evaluateAndMaybeSwap(now = Date.now()): Promise<SwapDecision> {
+  const cfg = loadConfig();
+  const floor = cfg.threshold - cfg.policy.projectionMargin;
+  const activeOrg = readOAuthAccount()?.organizationUuid ?? null;
+
+  let usage = loadUsage();
+  if (!usage && activeOrg) usage = await probeAggregate(activeOrg);
+
+  // per-model poll (TTL-cached) only when on a capacity-constrained model
+  const mu = needsPerModel(usage, cfg) ? await ensurePerModel(cfg, activeOrg) : null;
+
+  // cheap pre-check off the lock - the common case exits here.
+  if (!isOver(usage, mu, activeOrg, cfg, floor)) {
+    return { swapped: false, account: null, reason: "under-threshold-or-stale" };
+  }
+
+  return withLock(paths.lockFile, async () => {
+    const idx = loadAccounts();
+    const org2 = readOAuthAccount()?.organizationUuid ?? null;
+    const u2 = loadUsage() ?? usage;
+    const mu2 = needsPerModel(u2, cfg) ? loadModelUsage() ?? mu : null;
+
+    // record the active account's aggregate usage so the picker + `status` see it.
+    if (u2 && org2 && u2.org === org2) {
+      const active = idx.accounts.find((a) => a.accountUuid === idx.activeAccountUuid);
+      if (active) {
+        active.lastUsage = { fiveHour: u2.fiveHour, sevenDay: u2.sevenDay };
+        // Snapshot per-model caps too, so they still show after we switch away.
+        if (mu2 && mu2.org === org2) active.lastPerModel = mu2.perModel;
+        saveAccounts(idx);
+      }
+    }
+
+    if (!isOver(u2, mu2, org2, cfg, floor)) {
+      return { swapped: false, account: null, reason: "raced-already-swapped" };
+    }
+
+    const landed = await chooseAndSwap({ now, threshold: cfg.threshold });
+    if (landed) return { swapped: true, account: landed, reason: "swapped" };
+
+    // Every account is depleted. Wait for whichever recovers soonest (including the
+    // current one), if that reset is within the auto-wait window.
+    const fresh = loadAccounts();
+    const ctx = { now, threshold: cfg.threshold, currentAccountUuid: fresh.activeAccountUuid };
+    const current = fresh.accounts.find((a) => a.accountUuid === fresh.activeAccountUuid);
+    const currentAt = current ? usableAt(current, cfg.threshold, now) : Number.POSITIVE_INFINITY;
+    const other = pickEarliestReset(fresh.accounts, ctx);
+
+    let target: Account | null = null;
+    let waitUntil = Number.POSITIVE_INFINITY;
+    if (other && other.availableAt < currentAt) { target = other.account; waitUntil = other.availableAt; }
+    else if (current) { target = current; waitUntil = currentAt; }
+    else if (other) { target = other.account; waitUntil = other.availableAt; }
+
+    if (!target || waitUntil - now > cfg.policy.maxWaitMs) {
+      log("decide.depleted", { waitUntil: Number.isFinite(waitUntil) ? waitUntil : 0 });
+      return { swapped: false, account: null, reason: "all-depleted" };
+    }
+
+    const isCurrent = target.accountUuid === fresh.activeAccountUuid;
+    if (!isCurrent) {
+      try {
+        await performSwap(target);
+      } catch (e) {
+        if (e instanceof InvalidGrantError) return { swapped: false, account: null, reason: "all-depleted" };
+        throw e;
+      }
+    }
+    log("decide.depleted_wait", { account: target.accountUuid.slice(0, 8), waitUntil });
+    return { swapped: !isCurrent, account: target, reason: "depleted-wait", waitUntil };
+  });
+}

package/src/lib/http.ts

@@ -0,0 +1,19 @@
+// Shared HTTP client. Sampling every account at once, or swapping right at a
+// limit, can trip an endpoint's burst throttle, so GETs retry a bounded number
+// of times, honoring the server's Retry-After (capped). throwHttpErrors is off
+// so callers read the body and shape their own fail-fast error; retry still runs.
+
+import ky from "ky";
+
+export const http = ky.create({
+  timeout: 15_000,
+  throwHttpErrors: false,
+  retry: {
+    limit: 2,
+    methods: ["get"],
+    statusCodes: [429, 500, 502, 503, 504],
+    afterStatusCodes: [429, 503],
+    maxRetryAfter: 10_000,
+    backoffLimit: 3000,
+  },
+});

package/src/lib/install.ts

@@ -0,0 +1,87 @@
+// Install/uninstall the on-PATH `claude` supervisor wrapper + settings entries.
+// The wrapper is a 2-line `exec … __supervise "$@"` shim so dispatch never
+// depends on argv0 semantics.
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { z } from "zod";
+import { HOME, paths } from "./paths.ts";
+import { writeFileAtomic } from "./atomic.ts";
+import { installedBin, installSettings, uninstallSettings } from "./settings.ts";
+import { resolveRealClaude } from "./claudebin.ts";
+
+const InstallOutcomeSchema = z.object({
+  claudeWrapper: z.string(),
+  installedBin: z.string(),
+  priorStatusLine: z.string().nullable(),
+  pathAhead: z.boolean(),
+});
+export type InstallOutcome = z.infer<typeof InstallOutcomeSchema>;
+
+/** True if our binDir comes before the real claude's dir on PATH. */
+export function isBinDirAhead(): boolean {
+  const dirs = (process.env.PATH ?? "").split(":");
+  const ourIdx = dirs.indexOf(paths.binDir);
+  if (ourIdx < 0) return false;
+  try {
+    const realDir = dirname(resolveRealClaude());
+    const realIdx = dirs.indexOf(realDir);
+    return realIdx < 0 || ourIdx < realIdx;
+  } catch {
+    return ourIdx >= 0;
+  }
+}
+
+export function installSupervisor(): InstallOutcome {
+  mkdirSync(paths.binDir, { recursive: true });
+  const target = installedBin(); // binDir/tokenmaxxing
+  // Resolve the entry through the global-bin symlink (bun add -g links
+  // ~/.bun/bin/tokenmaxxing → the package's src/main.ts) so the shim points
+  // into the installed package tree, where its imports resolve.
+  const entry = realpathSync(Bun.main);
+  writeFileAtomic(target, `#!/bin/sh\nexec ${JSON.stringify(process.execPath)} run ${JSON.stringify(entry)} "$@"\n`, 0o755);
+
+  // the on-PATH `claude` wrapper
+  writeFileAtomic(paths.supervisorLink, `#!/bin/sh\nexec ${JSON.stringify(target)} __supervise "$@"\n`, 0o755);
+  // the `xx` short alias → tokenmaxxing
+  writeFileAtomic(join(paths.binDir, "xx"), `#!/bin/sh\nexec ${JSON.stringify(target)} "$@"\n`, 0o755);
+
+  const { priorStatusLine } = installSettings();
+  return {
+    claudeWrapper: paths.supervisorLink,
+    installedBin: target,
+    priorStatusLine,
+    pathAhead: isBinDirAhead(),
+  };
+}
+
+/** The rc file of the user's login shell, or null when the shell is unknown.
+ *  Overridable for hermetic tests. */
+export function shellRcPath(): string | null {
+  const override = process.env.TOKENMAXXING_SHELL_RC;
+  if (override && override.length > 0) return override;
+  const shell = basename(process.env.SHELL ?? "");
+  if (shell === "zsh") return join(process.env.ZDOTDIR || HOME, ".zshrc");
+  if (shell === "bash") return join(HOME, ".bashrc");
+  return null;
+}
+
+const PATH_LINE_MARK = "# tokenmaxxing PATH";
+
+/** Idempotently append the supervisor-bin PATH line to `rc` (created if absent).
+ *  A pre-existing hand-added line for the bin dir also counts as present. */
+export function ensurePathInRc(rc: string): "added" | "present" {
+  const dir = paths.binDir.startsWith(`${HOME}/`) ? `$HOME${paths.binDir.slice(HOME.length)}` : paths.binDir;
+  const current = existsSync(rc) ? readFileSync(rc, "utf8") : "";
+  if (current.includes(PATH_LINE_MARK) || current.includes(`${paths.binDir}:`) || current.includes(`${dir}:`)) return "present";
+  const sep = current === "" || current.endsWith("\n") ? "" : "\n";
+  appendFileSync(rc, `${sep}export PATH="${dir}:$PATH" ${PATH_LINE_MARK}\n`);
+  return "added";
+}
+
+export function uninstallSupervisor(): void {
+  uninstallSettings();
+  for (const f of [paths.supervisorLink, join(paths.binDir, "xx"), installedBin()]) {
+    if (existsSync(f)) rmSync(f, { force: true });
+  }
+}

package/src/lib/keychain.ts

@@ -0,0 +1,84 @@
+// macOS login-keychain generic-password I/O, ps-safe. The darwin backend of
+// credstore.ts - construct targets there, not here.
+//   READ  : `security find-generic-password -w`  → secret only ever in stdout.
+//   WRITE : pipe an `add-generic-password -U … -w <secret>` line into `security -i`
+//           over STDIN - the secret never appears in any process's argv (verified).
+// The service/account are non-secret and may sit in argv.
+
+import { z } from "zod";
+
+const KeychainTargetSchema = z.object({ service: z.string(), account: z.string() });
+export type KeychainTarget = z.infer<typeof KeychainTargetSchema>;
+
+const SECURITY = "/usr/bin/security";
+// security(1) interactive mode has a ~4KB line buffer; above this we must use argv.
+const INTERACTIVE_MAX = 3800;
+
+/** Double-quote + backslash-escape for security(1)'s interactive tokenizer. */
+function quoteDouble(s: string): string {
+  return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+/** Wrap a value for the `-i` line. Single-quote when possible (blob has no `'`). */
+function quoteValue(s: string): string {
+  return s.includes("'") ? quoteDouble(s) : `'${s}'`;
+}
+
+/** Read an item's password blob. Returns null if the item does not exist. */
+export async function readItem(t: KeychainTarget): Promise<string | null> {
+  const p = Bun.spawn([SECURITY, "find-generic-password", "-s", t.service, "-a", t.account, "-w"], {
+    stdout: "pipe",
+    stderr: "ignore",
+  });
+  const out = await new Response(p.stdout).text();
+  await p.exited;
+  if (p.exitCode !== 0) return null; // 44 = not found
+  return out.replace(/\n$/, ""); // security appends exactly one trailing newline
+}
+
+/** ps-safe write: the command line + secret arrive on stdin, never in argv.
+ *  Bounded by security(1)'s ~4KB interactive line buffer. */
+async function writeViaInteractive(t: KeychainTarget, secret: string): Promise<void> {
+  const line =
+    `add-generic-password -U -a ${quoteDouble(t.account)} -s ${quoteDouble(t.service)} ` +
+    `-w ${quoteValue(secret)}\n`;
+  const p = Bun.spawn([SECURITY, "-i"], {
+    stdin: new TextEncoder().encode(line),
+    stdout: "ignore",
+    stderr: "pipe",
+  });
+  const err = await new Response(p.stderr).text();
+  await p.exited;
+  if (p.exitCode !== 0) throw new Error(`keychain write (interactive) failed (exit ${p.exitCode}): ${err.trim()}`);
+}
+
+/** Fallback for blobs over the interactive line limit. The secret is briefly
+ *  visible in `ps` for this one short-lived process - used only when the payload
+ *  (e.g. a live blob with lots of MCP OAuth state) exceeds ~4KB. */
+async function writeViaArgv(t: KeychainTarget, secret: string): Promise<void> {
+  const p = Bun.spawn([SECURITY, "add-generic-password", "-U", "-a", t.account, "-s", t.service, "-w", secret], {
+    stdout: "ignore",
+    stderr: "pipe",
+  });
+  const err = await new Response(p.stderr).text();
+  await p.exited;
+  if (p.exitCode !== 0) throw new Error(`keychain write (argv) failed (exit ${p.exitCode}): ${err.trim()}`);
+}
+
+/** Create-or-update an item (`-U`) with `secret` as its password. Prefers the
+ *  ps-safe stdin path; falls back to argv only when the blob exceeds the ~4KB
+ *  interactive line limit. Throws on failure. */
+export async function writeItem(t: KeychainTarget, secret: string): Promise<void> {
+  if (secret.length <= INTERACTIVE_MAX) return writeViaInteractive(t, secret);
+  return writeViaArgv(t, secret);
+}
+
+/** Delete an item. Returns true if it existed and was removed. */
+export async function deleteItem(t: KeychainTarget): Promise<boolean> {
+  const p = Bun.spawn([SECURITY, "delete-generic-password", "-s", t.service, "-a", t.account], {
+    stdout: "ignore",
+    stderr: "ignore",
+  });
+  await p.exited;
+  return p.exitCode === 0;
+}

package/src/lib/lock.ts

@@ -0,0 +1,78 @@
+// Cross-process advisory locking via flock(2) through bun:ffi on a real file
+// descriptor (macOS ships no flock(1) binary, and one codepath serves both
+// platforms). The lock is released when we close the fd (explicitly or on
+// process exit).
+
+import { closeSync, mkdirSync, openSync } from "node:fs";
+import { dirname } from "node:path";
+import { dlopen, FFIType, suffix } from "bun:ffi";
+
+// sys/file.h (identical on darwin + linux): LOCK_SH=1 LOCK_EX=2 LOCK_NB=4 LOCK_UN=8
+const LOCK_EX = 2;
+const LOCK_UN = 8;
+
+let _flock: ((fd: number, op: number) => number) | null = null;
+
+function flockFn(): (fd: number, op: number) => number {
+  if (_flock) return _flock;
+  // darwin: flock(2) is in libSystem; the bare name resolves via the dyld shared
+  // cache even though no physical .dylib exists on disk (verified 2026-07-08).
+  // linux: glibc's libc.so.6 (verified in-container 2026-07-09, arm64).
+  const candidates =
+    process.platform === "darwin"
+      ? ["libSystem.B.dylib", "/usr/lib/libSystem.B.dylib", `libc.${suffix}`]
+      : [`libc.so.6`, `libc.${suffix}`];
+  let lib: ReturnType<typeof dlopen> | null = null;
+  let lastErr: unknown;
+  for (const path of candidates) {
+    try {
+      lib = dlopen(path, {
+        flock: { args: [FFIType.i32, FFIType.i32], returns: FFIType.i32 },
+      });
+      break;
+    } catch (e) {
+      lastErr = e;
+    }
+  }
+  if (!lib) throw new Error(`could not load flock(2): ${String(lastErr)}`);
+  const sym = lib.symbols.flock as unknown as (fd: number, op: number) => number;
+  _flock = sym;
+  return _flock;
+}
+
+/**
+ * Acquire an exclusive advisory lock on `lockPath`, blocking until available.
+ * Returns a handle whose release() drops the lock. The lock is process-scoped
+ * (held via an open fd) so racing hooks in separate processes serialize.
+ */
+export function acquireLock(lockPath: string): { release: () => void } {
+  mkdirSync(dirname(lockPath), { recursive: true });
+  const fd = openSync(lockPath, "a", 0o600);
+  const flock = flockFn();
+  const rc = flock(fd, LOCK_EX);
+  if (rc !== 0) {
+    closeSync(fd);
+    throw new Error(`flock LOCK_EX failed on ${lockPath} (rc=${rc})`);
+  }
+  let released = false;
+  const release = () => {
+    if (released) return;
+    released = true;
+    try {
+      flock(fd, LOCK_UN);
+    } finally {
+      closeSync(fd);
+    }
+  };
+  return { release };
+}
+
+/** Run `fn` while holding `lockPath`; always releases, even on throw. */
+export async function withLock<T>(lockPath: string, fn: () => Promise<T> | T): Promise<T> {
+  const held = acquireLock(lockPath);
+  try {
+    return await fn();
+  } finally {
+    held.release();
+  }
+}

package/src/lib/log.ts

@@ -0,0 +1,28 @@
+// Append-only logging. NEVER logs secret material - callers must pass only
+// non-secret context (account uuids/emails, percentages, status strings).
+
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { z } from "zod";
+import { paths } from "./paths.ts";
+
+/** Redact anything that looks like a token so an accidental pass-through can't leak. */
+export function redact(s: string): string {
+  return s
+    // JWT-ish / long opaque tokens
+    .replace(/\b(sk-ant-[A-Za-z0-9._-]{6,})/g, "sk-ant-***")
+    .replace(/\b([A-Za-z0-9_-]{40,})\b/g, (m) => `${m.slice(0, 4)}…(${m.length})`);
+}
+
+export function log(event: string, fields: Record<string, unknown> = {}): void {
+  try {
+    mkdirSync(dirname(paths.logFile), { recursive: true });
+    const parts = Object.entries(fields).map(([k, v]) => {
+      const str = z.string().safeParse(v);
+      return `${k}=${redact(str.success ? str.data : JSON.stringify(v))}`;
+    });
+    appendFileSync(paths.logFile, `${new Date().toISOString()} ${event} ${parts.join(" ")}\n`);
+  } catch {
+    // logging must never throw into a hook / supervisor path
+  }
+}

package/src/lib/oauth.ts

@@ -0,0 +1,117 @@
+// The two OAuth calls tokenmaxxing makes:
+//   1. the refresh_token grant that turns a parked account's (possibly expired)
+//      access token into a fresh one before we install it. Verified against
+//      Claude Code 2.1.204: POST platform.claude.com, JSON body, public PKCE
+//      client (no secret), no auth/beta headers on this call.
+//   2. the roles lookup that reports which org a token ACTUALLY belongs to.
+//      Endpoint string extracted from the Claude Code 2.1.205 binary; verified
+//      live to answer HTTP 200 with plain Bearer auth (with or without the
+//      oauth beta header - we send it to match the CLI's OAuth convention).
+
+import { http } from "./http.ts";
+import { RefreshResponseSchema, RolesResponseSchema, type OAuthCreds, type RolesResponse } from "./types.ts";
+
+const TOKEN_URL = process.env.TOKENMAXXING_OAUTH_TOKEN_URL ?? "https://platform.claude.com/v1/oauth/token";
+const CLIENT_ID = process.env.TOKENMAXXING_OAUTH_CLIENT_ID ?? "9d1c250a-e61b-44d9-88ed-5944d1962f5e";
+const ROLES_URL = process.env.TOKENMAXXING_OAUTH_ROLES_URL ?? "https://api.anthropic.com/api/oauth/claude_cli/roles";
+
+const DEFAULT_SCOPES = [
+  "user:profile",
+  "user:inference",
+  "user:sessions:claude_code",
+  "user:mcp_servers",
+  "user:file_upload",
+];
+
+/** Refresh token is dead / revoked - caller should mark needs_reauth and skip. */
+export class InvalidGrantError extends Error {
+  constructor(public readonly detail: string) {
+    super(`invalid_grant: ${detail}`);
+    this.name = "InvalidGrantError";
+  }
+}
+
+/**
+ * Exchange `creds.refreshToken` for a fresh access token. Returns a NEW OAuthCreds
+ * with the fresh access token, the rotated refresh token (or the old one if the
+ * server omitted it), and recomputed absolute expiries. Non-token fields are
+ * preserved. Throws InvalidGrantError on a dead refresh token.
+ */
+export async function refreshCredential(creds: OAuthCreds, now = Date.now()): Promise<OAuthCreds> {
+  const scope = (creds.scopes?.length ? creds.scopes : DEFAULT_SCOPES).join(" ");
+  const body = {
+    grant_type: "refresh_token",
+    refresh_token: creds.refreshToken,
+    client_id: CLIENT_ID,
+    scope,
+  };
+
+  let res: Response;
+  try {
+    res = await http.post(TOKEN_URL, {
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    });
+  } catch (e) {
+    throw new Error(`token endpoint unreachable: ${String((e as Error).message ?? e)}`);
+  }
+
+  const text = await res.text();
+  if (!res.ok) {
+    // invalid_grant → dead refresh token; anything else is transient/unknown.
+    if (res.status === 400 && /invalid_grant/.test(text)) {
+      throw new InvalidGrantError(text.slice(0, 200));
+    }
+    throw new Error(`token refresh failed (HTTP ${res.status}): ${text.slice(0, 200)}`);
+  }
+
+  const parsed = RefreshResponseSchema.safeParse((() => {
+    try { return JSON.parse(text); } catch { return null; }
+  })());
+  if (!parsed.success) {
+    throw new Error(`token endpoint returned unexpected body: ${text.slice(0, 120)}`);
+  }
+  const json = parsed.data;
+
+  const expiresIn = json.expires_in ?? 8 * 3600;
+  const refreshExpiresIn = json.refresh_token_expires_in;
+
+  return {
+    ...creds,
+    accessToken: json.access_token,
+    refreshToken: json.refresh_token ?? creds.refreshToken, // server may omit → reuse
+    expiresAt: now + expiresIn * 1000,
+    refreshTokenExpiresAt:
+      refreshExpiresIn != null ? now + refreshExpiresIn * 1000 : creds.refreshTokenExpiresAt,
+    scopes: json.scope ? json.scope.split(" ").filter(Boolean) : creds.scopes,
+  };
+}
+
+/** True if the access token is within `skewMs` of expiry (or already expired). */
+export function isAccessTokenExpiring(creds: OAuthCreds, skewMs = 120_000, now = Date.now()): boolean {
+  return !creds.expiresAt || creds.expiresAt - now <= skewMs;
+}
+
+/**
+ * Ask the API which org `accessToken` ACTUALLY belongs to. Stored labels
+ * (accounts.json, oauthAccount) can drift from the credential they describe;
+ * the token itself cannot lie. Requires a non-expired access token. Read-only:
+ * never rotates anything.
+ */
+export async function fetchTokenOrg(accessToken: string): Promise<RolesResponse> {
+  let res: Response;
+  try {
+    res = await http.get(ROLES_URL, {
+      headers: { Authorization: `Bearer ${accessToken}`, "anthropic-beta": "oauth-2025-04-20" },
+    });
+  } catch (e) {
+    throw new Error(`roles endpoint unreachable: ${String((e as Error).message ?? e)}`);
+  }
+  const text = await res.text();
+  if (!res.ok) throw new Error(`roles check failed (HTTP ${res.status}): ${text.slice(0, 140)}`);
+  const parsed = RolesResponseSchema.safeParse((() => {
+    try { return JSON.parse(text); } catch { return null; }
+  })());
+  if (!parsed.success) throw new Error(`roles endpoint returned unexpected body: ${text.slice(0, 120)}`);
+  return parsed.data;
+}

package/src/lib/paths.ts

@@ -0,0 +1,90 @@
+// Central path resolution. EVERY externally-observable path is overridable via an
+// env var so the whole tool can run hermetically in tests without touching the
+// user's real ~/.config, ~/.claude, or login keychain.
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const HOME = homedir();
+
+function env(name: string, fallback: string): string {
+  const v = process.env[name];
+  return v && v.length > 0 ? v : fallback;
+}
+
+/** Root of all tokenmaxxing config + state. Default ~/.config/tokenmaxxing. */
+export const TM_HOME = env("TOKENMAXXING_HOME", join(HOME, ".config", "tokenmaxxing"));
+
+export const paths = {
+  home: TM_HOME,
+  configJson: join(TM_HOME, "config.json"),
+  accountsJson: join(TM_HOME, "accounts.json"),
+  usageJson: join(TM_HOME, "usage.json"),
+  modelUsageJson: join(TM_HOME, "model-usage.json"),
+  respawnDir: join(TM_HOME, "respawn"),
+  binDir: join(TM_HOME, "bin"),
+  supervisorLink: join(TM_HOME, "bin", "claude"),
+  lockFile: join(TM_HOME, "lock"),
+  logFile: join(TM_HOME, "tokenmaxxing.log"),
+  onboardDir: join(TM_HOME, "onboard"),
+  sampleDir: join(TM_HOME, "sample"),
+  /** linux only: parked credential .json files (0700 dir, 0600 files). */
+  credsDir: join(TM_HOME, "creds"),
+
+  /** ~/.claude.json - holds the active `oauthAccount` identity object. */
+  claudeJson: env("TOKENMAXXING_CLAUDE_JSON", join(HOME, ".claude.json")),
+  /** ~/.claude/settings.json - user-owned; we merge three entries into it. */
+  claudeSettings: env(
+    "TOKENMAXXING_CLAUDE_SETTINGS",
+    join(env("CLAUDE_CONFIG_DIR", join(HOME, ".claude")), "settings.json"),
+  ),
+  /** ~/.claude - for the credential-refresh lock and projects/ transcripts. */
+  claudeDir: env("CLAUDE_CONFIG_DIR", join(HOME, ".claude")),
+} as const;
+
+/** Claude's own credential-refresh lock (verified path filled from facts). */
+export function claudeLockPath(): string {
+  return env("TOKENMAXXING_CLAUDE_LOCK", join(HOME, ".claude.lock"));
+}
+
+/** The macOS login-keychain generic-password the live `claude` reads. */
+export const keychain = {
+  service: env("TOKENMAXXING_KEYCHAIN_SERVICE", "Claude Code-credentials"),
+  account: env("TOKENMAXXING_KEYCHAIN_ACCOUNT", process.env.USER ?? "unknown"),
+} as const;
+
+/** Per-account parked credential item name: tokenmaxxing-cred-<accountUuid[:8]>. */
+export function credItemFor(accountUuid: string): string {
+  return `tokenmaxxing-cred-${accountUuid.slice(0, 8)}`;
+}
+
+/**
+ * The dir whose `.credentials.json` is claude's live credential on linux -
+ * mirrors claude's own resolution (verified 2.1.205 `Wde()`): the
+ * CLAUDE_SECURESTORAGE_CONFIG_DIR override is checked FIRST when defined
+ * (defined-but-empty falls to ~/.claude, NFC-normalized), else the config dir.
+ */
+export function credDir(): string {
+  const secure = process.env.CLAUDE_SECURESTORAGE_CONFIG_DIR;
+  if (secure !== undefined) return (secure || join(HOME, ".claude")).normalize("NFC");
+  return paths.claudeDir;
+}
+
+/**
+ * The keychain service claude uses when CLAUDE_CONFIG_DIR is set:
+ * `Claude Code-credentials-<first 8 hex of sha256(NFC(raw dir string))>`.
+ * Hash is over the RAW string, so the dir must be byte-stable.
+ */
+export function namespacedCredService(configDirRaw: string): string {
+  const h = new Bun.CryptoHasher("sha256");
+  h.update(configDirRaw.normalize("NFC"));
+  return `Claude Code-credentials-${h.digest("hex").slice(0, 8)}`;
+}
+
+/** Resolve the REAL claude binary (never our shim). Order: explicit env, config, PATH scan. */
+export function realClaudeBinFromEnv(): string | undefined {
+  const v = process.env.TOKENMAXXING_CLAUDE_BIN;
+  return v && v.length > 0 ? v : undefined;
+}
+
+export { HOME };