tokenmaxxing 1.43.0 → 1.45.0

package/src/lib/codex.ts

@@ -1,23 +1,38 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { writeFileAtomic } from "./atomic.ts";
 import { MAX_WRAP_DEPTH, WRAP_DEPTH_ENV } from "./claudebin.ts";
-import { codexIdentityOf, deleteParkedCodexAuth, isCodexAccessExpiring, liveCodexAccountId, readCodexAuthAt, readLiveCodexAuth, readParkedCodexAuth, writeLiveCodexAuth, writeParkedCodexAuth } from "./codexauth.ts";
+import { codexIdentityOf, deleteCodexStoreAuth, isCodexAccessExpiring, readCodexAuthAt, readCodexStoreAuth, writeCodexStoreAuth } from "./codexauth.ts";
 import { resolveRealCodex, verifyRealCodex } from "./codexbin.ts";
 import { CodexInvalidGrantError, CodexRefreshFailedError, refreshCodexAuth } from "./codexoauth.ts";
-import { livingPresences, seatCounts } from "./presence.ts";
+import { seatCounts } from "./presence.ts";
 import { CodexUsageReadError, codexLimitLabel, fetchCodexUsage } from "./codexusage.ts";
 import { codexSupervisorLink, ensurePathInRc, installCodexSupervisor, managedShellRcSkipLines, shellRcPath } from "./install.ts";
 import { withLock } from "./lock.ts";
 import { log } from "./log.ts";
-import { codexCredItemFor, codexPaths, codexPool } from "./paths.ts";
-import { isExhausted, thresholdBars, type PickCtx } from "./picker.ts";
+import { codexPaths, codexPool, codexSeatFromEnv } from "./paths.ts";
+import { isExhausted, pickBest, pickEarliestReset, thresholdBars, type PickCtx } from "./picker.ts";
 import type { Observation, Provider, SampleReport } from "./provider.ts";
-import { loadAccounts, loadConfig, pinBinOverride, saveAccounts, saveLastSwapAt, type Harvest } from "./state.ts";
+import { loadAccounts, loadConfig, pinBinOverride, saveAccounts, type Harvest } from "./state.ts";
 import { restoreTermios, saveTermios } from "./tty.ts";
-import { CodexReconcileMarkerSchema, type Account, type CodexAuthJson, type CodexUsage, type Config } from "./types.ts";
+import type { Account, CodexAuthJson, CodexUsage, Config } from "./types.ts";
 import { c } from "../cli/render.ts";
 
+class StoreUnusableError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "StoreUnusableError";
+  }
+}
+
+function liveId(): string | null {
+  return codexSeatFromEnv(loadAccounts(codexPool).accounts.map((a) => a.id));
+}
+
+function presence(): Map<string, number> {
+  return seatCounts(codexPaths.presenceDir);
+}
+
 function applyUsage(account: Account, usage: CodexUsage, at: number): void {
   account.windows = usage.windows;
   account.lastUsageAt = at;
@@ -25,59 +40,23 @@ function applyUsage(account: Account, usage: CodexUsage, at: number): void {
   if (usage.planType != null) account.tier = usage.planType;
 }
 
-async function sampleLiveOntoOwner(now: number): Promise<void> {
-  let live = readLiveCodexAuth();
-  if (!live) return;
-  const idx = loadAccounts(codexPool);
-  const identity = codexIdentityOf({ auth: live });
-  const owner = idx.accounts.find((a) => a.id === identity.accountId);
-  if (!owner) return;
-
-  if (isCodexAccessExpiring({ auth: live, now }) && !seatCounts(codexPaths.presenceDir).has(identity.accountId)) {
-    try {
-      live = await refreshCodexAuth({ auth: live, now });
-    } catch (e) {
-      if (e instanceof CodexInvalidGrantError) {
-        owner.needsReauth = true;
-        saveAccounts(codexPool, idx);
-        log("codex.live_invalid_grant", { account: owner.id.slice(0, 8) });
-        return;
-      }
-      throw e;
-    }
-    writeLiveCodexAuth({ auth: live });
-    writeParkedCodexAuth({ credFile: codexCredItemFor(owner.id), auth: live });
-  }
-  applyUsage(owner, await fetchCodexUsage({ auth: live, at: now }), now);
-  saveAccounts(codexPool, idx);
-}
+type CodexReadOutcome = { ok: true; usage: CodexUsage; at: number } | { ok: false; reason: string; deadGrant: boolean };
 
-async function observeLive(account: Account, cfg: Config, now: number, opts: { probe: boolean }): Promise<Observation | null> {
-  if (opts.probe && (account.lastUsageAt == null || now - account.lastUsageAt > cfg.policy.usagePollTtlMs)) {
-    await withLock(codexPool.lockFile, () => sampleLiveOntoOwner(now));
+async function readCodexUsage(account: Account, now: number): Promise<CodexReadOutcome> {
+  let auth: CodexAuthJson | null;
+  try {
+    auth = readCodexStoreAuth(account.id);
+  } catch (e) {
+    return { ok: false, reason: `store credential unreadable (${(e instanceof Error ? e.message : String(e)).slice(0, 80)})`, deadGrant: false };
   }
-  const fresh = loadAccounts(codexPool).accounts.find((a) => a.id === account.id);
-  return fresh?.lastUsageAt != null ? { windows: fresh.windows, at: fresh.lastUsageAt } : null;
-}
-
-type CodexSampleOutcome = { ok: true; usage: CodexUsage; at: number } | { ok: false; reason: string; deadGrant: boolean };
-
-async function sampleAccount(account: Account, liveId: string | null, now: number): Promise<CodexSampleOutcome> {
-  const isLive = liveId != null && account.id === liveId;
-  const credFile = codexCredItemFor(account.id);
+  if (!auth) return { ok: false, reason: "no credential in this account's store - run `tokenmaxxing auth --codex`", deadGrant: false };
   try {
-    let auth = isLive ? readLiveCodexAuth() : readParkedCodexAuth({ credFile });
-    if (!auth) return { ok: false, reason: isLive ? "live auth.json vanished" : "no parked credential", deadGrant: false };
     if (isCodexAccessExpiring({ auth, now })) {
-      const running = seatCounts(codexPaths.presenceDir).has(account.id);
-      if (running && !isLive) {
-        return { ok: false, reason: "running in a live codex session (parked token refresh unsafe)", deadGrant: false };
-      }
-      if (!running) {
-        auth = await refreshCodexAuth({ auth, now });
-        if (isLive) writeLiveCodexAuth({ auth });
-        writeParkedCodexAuth({ credFile, auth });
+      if (seatCounts(codexPaths.presenceDir).has(account.id)) {
+        return { ok: false, reason: "running in a live codex session (store refresh unsafe)", deadGrant: false };
       }
+      auth = await refreshCodexAuth({ auth, now });
+      writeCodexStoreAuth(account.id, auth);
     }
     const at = Date.now();
     return { ok: true, usage: await fetchCodexUsage({ auth, at }), at };
@@ -88,11 +67,32 @@ async function sampleAccount(account: Account, liveId: string | null, now: numbe
   }
 }
 
-async function samplePool(accounts: Account[], liveId: string | null, now: number): Promise<Map<string, SampleReport>> {
+async function observeLive(account: Account, cfg: Config, now: number, opts: { probe: boolean }): Promise<Observation | null> {
+  if (opts.probe && (account.lastUsageAt == null || now - account.lastUsageAt > cfg.policy.usagePollTtlMs)) {
+    const outcome = await readCodexUsage(account, now);
+    await withLock(codexPool.lockFile, () => {
+      const idx = loadAccounts(codexPool);
+      const a = idx.accounts.find((x) => x.id === account.id);
+      if (!a) return;
+      if (outcome.ok) {
+        if (a.lastUsageAt == null || outcome.at > a.lastUsageAt) {
+          applyUsage(a, outcome.usage, outcome.at);
+        }
+      } else if (outcome.deadGrant) {
+        a.needsReauth = true;
+      }
+      saveAccounts(codexPool, idx);
+    });
+  }
+  const current = loadAccounts(codexPool).accounts.find((a) => a.id === account.id) ?? account;
+  return current.lastUsageAt != null ? { windows: current.windows, at: current.lastUsageAt } : null;
+}
+
+async function samplePool(accounts: Account[], _liveId: string | null, now: number): Promise<Map<string, SampleReport>> {
   const reports = new Map<string, SampleReport>();
   await Promise.all(
     accounts.map(async (account) => {
-      const outcome = await sampleAccount(account, liveId, now);
+      const outcome = await readCodexUsage(account, now);
       if (outcome.ok) {
         applyUsage(account, outcome.usage, outcome.at);
         reports.set(account.id, { ok: true, source: "probe" });
@@ -105,68 +105,15 @@ async function samplePool(accounts: Account[], liveId: string | null, now: numbe
   return reports;
 }
 
-async function swap(target: Account): Promise<void> {
-  const idx = loadAccounts(codexPool);
-  const live = readLiveCodexAuth();
-  let liveOwner: Account | null = null;
-  if (live) {
-    const liveIdentity = codexIdentityOf({ auth: live });
-    liveOwner = idx.accounts.find((a) => a.id === liveIdentity.accountId) ?? null;
-    if (!liveOwner) {
-      throw new Error(
-        `live codex credential belongs to ${liveIdentity.email ?? liveIdentity.accountId.slice(0, 8)}, which is not in the pool - refusing to swap over it; import it first with \`tokenmaxxing add --codex\``,
-      );
-    }
-    if (liveOwner.id !== idx.activeId) {
-      log("codexswap.harvest_drift", { labeled: idx.activeId?.slice(0, 8) ?? null, actual: liveOwner.id.slice(0, 8) });
-    }
-  }
-  const commit = (): void => {
-    idx.activeId = target.id;
-    const entry = idx.accounts.find((a) => a.id === target.id);
-    if (entry) entry.needsReauth = false;
-    saveAccounts(codexPool, idx);
-  };
-
-  if (live && liveOwner && liveOwner.id === target.id) {
-    writeParkedCodexAuth({ credFile: codexCredItemFor(target.id), auth: live });
-    commit();
-    log("codexswap.reconciled", { account: target.id.slice(0, 8) });
-    return;
-  }
-
-  const parked = readParkedCodexAuth({ credFile: codexCredItemFor(target.id) });
-  if (!parked) throw new Error(`no parked codex credential for ${target.label}`);
-
-  let fresh: CodexAuthJson;
+async function prepareMove(target: Account): Promise<void> {
+  let auth: CodexAuthJson | null;
   try {
-    fresh = await refreshCodexAuth({ auth: parked });
+    auth = readCodexStoreAuth(target.id);
   } catch (e) {
-    if (e instanceof CodexInvalidGrantError) {
-      const entry = idx.accounts.find((a) => a.id === target.id);
-      if (entry) {
-        entry.needsReauth = true;
-        saveAccounts(codexPool, idx);
-      }
-      log("codexswap.invalid_grant", { account: target.id.slice(0, 8) });
-    }
-    throw e;
-  }
-  writeParkedCodexAuth({ credFile: codexCredItemFor(target.id), auth: fresh });
-
-  if (live && liveOwner) {
-    const liveNow = readLiveCodexAuth();
-    if (!liveNow || codexIdentityOf({ auth: liveNow }).accountId !== liveOwner.id) {
-      throw new Error("live codex credential changed mid-swap - refusing to harvest under a stale identity; retry");
-    }
-    writeParkedCodexAuth({ credFile: codexCredItemFor(liveOwner.id), auth: liveNow });
-    log("codexswap.harvest", { account: liveOwner.id.slice(0, 8) });
+    throw new StoreUnusableError(`${target.label}'s store is unreadable (${e instanceof Error ? e.message : String(e)}) - re-auth with \`tokenmaxxing auth --codex ${target.label}\``);
   }
-
-  writeLiveCodexAuth({ auth: fresh });
-  commit();
-  saveLastSwapAt(codexPool, Date.now());
-  log("codexswap.done", { account: target.id.slice(0, 8), label: target.label });
+  if (!auth) throw new StoreUnusableError(`${target.label} has no credential in its store - re-auth with \`tokenmaxxing auth --codex ${target.label}\``);
+  log("move.prepared", { account: target.id.slice(0, 8), label: target.label });
 }
 
 async function login(): Promise<Harvest | null> {
@@ -204,7 +151,7 @@ async function login(): Promise<Harvest | null> {
       email: usage?.usage.email ?? identity.email,
       tier: usage?.usage.planType ?? identity.planType,
       sample: usage ? { windows: usage.usage.windows, at: usage.at } : null,
-      park: async () => writeParkedCodexAuth({ credFile: codexCredItemFor(identity.accountId), auth }),
+      park: async () => writeCodexStoreAuth(identity.accountId, auth),
     };
   } finally {
     rmSync(onboardDir, { recursive: true, force: true });
@@ -224,36 +171,9 @@ async function sampleLogin(auth: CodexAuthJson): Promise<{ usage: CodexUsage; at
 }
 
 async function importLive(): Promise<Harvest | null> {
-  const live = readLiveCodexAuth();
-  if (!live) {
-    console.error(c.red(`no codex login found at ${codexPaths.authJson} - run \`codex login\` first, then re-run this.`));
-    return null;
-  }
-  const identity = codexIdentityOf({ auth: live });
-  const usage = await sampleLogin(live);
-
-  if (seatCounts(codexPaths.presenceDir).has(identity.accountId)) {
-    console.error(c.red("a live supervised codex session is running this account - its token rotates under us, so parking a snapshot now could poison the backup."));
-    console.error(c.dim("close that codex session (or let it exit) and re-run `tokenmaxxing init --codex`."));
-    return null;
-  }
-
-  return {
-    id: identity.accountId,
-    email: usage?.usage.email ?? identity.email,
-    tier: usage?.usage.planType ?? identity.planType,
-    sample: usage ? { windows: usage.usage.windows, at: usage.at } : null,
-    park: async () => {
-      if (seatCounts(codexPaths.presenceDir).has(identity.accountId)) {
-        throw new Error("a live supervised codex session started running this account mid-init - close it and re-run `tokenmaxxing init --codex`");
-      }
-      const fresh2 = readLiveCodexAuth();
-      if (!fresh2 || codexIdentityOf({ auth: fresh2 }).accountId !== identity.accountId) {
-        throw new Error("the live codex login changed while init was running (a concurrent swap?) - re-run `tokenmaxxing init --codex`");
-      }
-      writeParkedCodexAuth({ credFile: codexCredItemFor(identity.accountId), auth: fresh2 });
-    },
-  };
+  console.log(c.cyan("Opening an isolated codex login for your first pooled account - the login you already have stays as it is for sessions started outside the supervisor."));
+  console.log();
+  return login();
 }
 
 function storePinnedAwayFromFile(): boolean {
@@ -287,36 +207,26 @@ function install(): void {
   console.log(`${c.green("✓")} codex supervisor installed at ${codexSupervisorLink()}`);
   console.log(`${c.green("✓")} Stop hook declared in ${codexPaths.hooksJson}`);
   console.log();
-  console.log(c.bold(c.yellow("one manual step: codex skips untrusted hooks.")));
-  console.log(c.yellow("open codex, run /hooks, and trust the tokenmaxxing Stop hook - auto-switching is inert until then."));
+  console.log(c.bold(c.yellow("one manual step per seat: codex trusts hooks per store path.")));
+  console.log(c.yellow("open a supervised codex session on each pooled account, run /hooks, and trust the tokenmaxxing Stop hook - auto-switching stays inert on an untrusted seat."));
+  console.log(c.yellow("`tokenmaxxing doctor` lists seats still needing trust."));
 }
 
 export function codexPickCtx(now: number, currentId: string | null): PickCtx {
   return { now, thresholds: thresholdBars(loadConfig()), currentId, families: null, seats: null };
 }
 
-export function reconcileSiblings(now: number): void {
-  const liveId = liveCodexAccountId();
-  if (liveId == null) return;
+export function pickCodexSeat(now: number, wantedId: string | null = null): Account | null {
+  const cfg = loadConfig();
   const idx = loadAccounts(codexPool);
-  const liveAccount = idx.accounts.find((a) => a.id === liveId);
-  if (!liveAccount || liveAccount.needsReauth === true || isExhausted(liveAccount, codexPickCtx(now, liveId))) return;
-  const living = livingPresences(codexPaths.presenceDir);
-  if (existsSync(codexPaths.reconcileDir)) {
-    const alive = new Set(living.map((presence) => presence.id));
-    for (const name of readdirSync(codexPaths.reconcileDir)) {
-      if (!alive.has(name)) rmSync(join(codexPaths.reconcileDir, name), { force: true });
-    }
-  }
-  for (const presence of living) {
-    if (presence.accountId === liveId) continue;
-    if (!idx.accounts.some((a) => a.id === presence.accountId)) continue;
-    const markerPath = join(codexPaths.reconcileDir, presence.id);
-    if (existsSync(markerPath)) continue;
-    mkdirSync(codexPaths.reconcileDir, { recursive: true });
-    writeFileAtomic(markerPath, JSON.stringify(CodexReconcileMarkerSchema.parse({ accountId: presence.accountId, ts: now })));
-    log("codex.reconcile_signal", { supervisorId: presence.id.slice(0, 8), account: presence.accountId.slice(0, 8) });
+  const ctx: PickCtx = { now, thresholds: thresholdBars(cfg), currentId: null, families: null, seats: null };
+  if (wantedId != null) {
+    const wanted = idx.accounts.find((a) => a.id === wantedId && a.needsReauth !== true && !isExhausted(a, { ...ctx, currentId: wantedId }));
+    if (wanted) return wanted;
   }
+  const present = seatCounts(codexPaths.presenceDir);
+  const usable = idx.accounts.filter((a) => a.needsReauth !== true && !isExhausted(a, ctx) && !present.has(a.id));
+  return pickBest(usable, ctx) ?? pickEarliestReset(idx.accounts.filter((a) => a.needsReauth !== true && !present.has(a.id)), ctx)?.account ?? null;
 }
 
 export const codex: Provider = {
@@ -325,18 +235,19 @@ export const codex: Provider = {
   pool: codexPool,
   seats: "live",
   waitsWhenDepleted: false,
-  liveId: liveCodexAccountId,
-  presence: () => seatCounts(codexPaths.presenceDir),
+  statusOnly: false,
+  liveId,
+  presence,
   gatedFamilies: () => null,
   observeLive,
   samplePool,
   mergeWindows: (next) => next,
-  swap,
-  classifySwapError: (e) => (e instanceof CodexInvalidGrantError ? "dead-grant" : "fatal"),
-  removeCredentials: async (a) => deleteParkedCodexAuth({ credFile: codexCredItemFor(a.id) }),
+  swap: prepareMove,
+  classifySwapError: (e) => (e instanceof CodexInvalidGrantError ? "dead-grant" : e instanceof StoreUnusableError ? "skip" : "fatal"),
+  removeCredentials: async (a) => deleteCodexStoreAuth(a.id),
   storeUsable: async (a) => {
     try {
-      return readParkedCodexAuth({ credFile: codexCredItemFor(a.id) }) != null;
+      return readCodexStoreAuth(a.id) != null;
     } catch {
       return false;
     }

package/src/lib/codexauth.ts

@@ -1,8 +1,8 @@
-import { readFileSync, rmSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, symlinkSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
 import { writeFileAtomic } from "./atomic.ts";
-import { codexPaths } from "./paths.ts";
+import { codexAuthJsonFor, codexPaths, codexStoreDirFor } from "./paths.ts";
 import { CodexAuthJsonSchema, ErrnoSchema, type CodexAuthJson } from "./types.ts";
 
 export function readCodexAuthAt(input: { path: string }): CodexAuthJson | null {
@@ -19,41 +19,50 @@ export function readCodexAuthAt(input: { path: string }): CodexAuthJson | null {
   return CodexAuthJsonSchema.parse(parsed);
 }
 
-export function readLiveCodexAuth(): CodexAuthJson | null {
-  return readCodexAuthAt({ path: codexPaths.authJson });
+export function readCodexStoreAuth(accountId: string): CodexAuthJson | null {
+  return readCodexAuthAt({ path: codexAuthJsonFor(accountId) });
 }
 
-export function liveCodexAccountId(): string | null {
-  const live = readLiveCodexAuth();
-  if (!live) return null;
-  return codexIdentityOf({ auth: live }).accountId;
+export function writeCodexStoreAuth(accountId: string, auth: CodexAuthJson): void {
+  mkdirSync(codexStoreDirFor(accountId), { recursive: true });
+  writeFileAtomic(codexAuthJsonFor(accountId), JSON.stringify(CodexAuthJsonSchema.parse(auth), null, 2), 0o600);
 }
 
-export function writeLiveCodexAuth(input: { auth: CodexAuthJson }): void {
-  writeFileAtomic(codexPaths.authJson, JSON.stringify(CodexAuthJsonSchema.parse(input.auth), null, 2), 0o600);
+export function deleteCodexStoreAuth(accountId: string): void {
+  rmSync(codexStoreDirFor(accountId), { recursive: true, force: true });
 }
 
-function parkedPath(input: { credFile: string }): string {
-  return join(codexPaths.credsDir, `${input.credFile}.json`);
-}
-
-export function readParkedCodexAuth(input: { credFile: string }): CodexAuthJson | null {
-  let raw: string;
+export function ensureCodexStoreHome(accountId: string): string {
+  const store = codexStoreDirFor(accountId);
+  mkdirSync(store, { recursive: true });
+  mkdirSync(codexPaths.home, { recursive: true });
+  mkdirSync(join(codexPaths.home, "sessions"), { recursive: true });
+  let names: string[] = [];
   try {
-    raw = readFileSync(parkedPath(input), "utf8");
+    names = readdirSync(codexPaths.home);
   } catch (e) {
-    if (ErrnoSchema.safeParse(e).data?.code === "ENOENT") return null;
+    if (ErrnoSchema.safeParse(e).data?.code === "ENOENT") return store;
     throw e;
   }
-  return CodexAuthJsonSchema.parse(JSON.parse(raw));
-}
-
-export function writeParkedCodexAuth(input: { credFile: string; auth: CodexAuthJson }): void {
-  writeFileAtomic(parkedPath(input), JSON.stringify(CodexAuthJsonSchema.parse(input.auth), null, 2), 0o600);
-}
-
-export function deleteParkedCodexAuth(input: { credFile: string }): void {
-  rmSync(parkedPath(input), { force: true });
+  for (const name of names) {
+    if (name === "auth.json") continue;
+    const target = join(codexPaths.home, name);
+    const link = join(store, name);
+    if (existsSync(link)) {
+      try {
+        if (lstatSync(link).isSymbolicLink()) continue;
+      } catch {
+        continue;
+      }
+      continue;
+    }
+    try {
+      symlinkSync(target, link);
+    } catch (e) {
+      if (ErrnoSchema.safeParse(e).data?.code !== "EEXIST") throw e;
+    }
+  }
+  return store;
 }
 
 const IdClaimsSchema = z.looseObject({

package/src/lib/grok.ts

@@ -0,0 +1,188 @@
+import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { writeFileAtomic } from "./atomic.ts";
+import { grokAuthJsonFor, grokPaths, grokPool, grokSeatFromEnv, grokStoreDirFor } from "./paths.ts";
+import type { Observation, Provider, SampleReport } from "./provider.ts";
+import { loadAccounts, loadConfig, pinBinOverride, type Harvest } from "./state.ts";
+import type { Account } from "./types.ts";
+import { c } from "../cli/render.ts";
+
+const GrokAuthEntrySchema = z.looseObject({
+  user_id: z.string().optional(),
+  principal_id: z.string().optional(),
+  email: z.string().nullish(),
+  first_name: z.string().nullish(),
+  refresh_token: z.string().optional(),
+  expires_at: z.string().nullish(),
+});
+type GrokAuthEntry = z.infer<typeof GrokAuthEntrySchema>;
+
+function parseGrokAuthFile(path: string): { key: string; entry: GrokAuthEntry }[] {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return [];
+  }
+  const map = z.record(z.string(), z.unknown()).safeParse(raw);
+  if (!map.success) return [];
+  const out: { key: string; entry: GrokAuthEntry }[] = [];
+  for (const [key, value] of Object.entries(map.data)) {
+    const parsed = GrokAuthEntrySchema.safeParse(value);
+    if (parsed.success) out.push({ key, entry: parsed.data });
+  }
+  return out;
+}
+
+function identityOf(key: string, entry: GrokAuthEntry): { id: string; email: string | null } {
+  const id = entry.user_id ?? entry.principal_id ?? key;
+  return { id, email: entry.email ?? null };
+}
+
+function resolveRealGrok(): string {
+  const cfg = loadConfig();
+  if (cfg.grokBin) {
+    if (!existsSync(cfg.grokBin)) throw new Error(`configured grokBin does not exist: ${cfg.grokBin} - fix config.json`);
+    return cfg.grokBin;
+  }
+  for (const d of (process.env.PATH ?? "").split(":")) {
+    if (!d) continue;
+    const cand = join(d, "grok");
+    try {
+      if (existsSync(cand)) return cand;
+    } catch {
+      continue;
+    }
+  }
+  throw new Error("could not locate the real `grok` binary (set grokBin in config.json)");
+}
+
+function liveId(): string | null {
+  return grokSeatFromEnv(loadAccounts(grokPool).accounts.map((a) => a.id));
+}
+
+function presence(): Map<string, number> {
+  return new Map();
+}
+
+async function observeLive(account: Account): Promise<Observation | null> {
+  return account.lastUsageAt != null ? { windows: account.windows, at: account.lastUsageAt } : null;
+}
+
+async function samplePool(accounts: Account[]): Promise<Map<string, SampleReport>> {
+  const reports = new Map<string, SampleReport>();
+  for (const a of accounts) {
+    reports.set(a.id, (await storeUsable(a)) ? { ok: true, source: "probe" } : { ok: false, reason: "no usable credential in this account's store - run `tokenmaxxing auth --grok`" });
+  }
+  return reports;
+}
+
+async function storeUsable(a: Account): Promise<boolean> {
+  try {
+    const entries = parseGrokAuthFile(grokAuthJsonFor(a.id));
+    return entries.some((e) => identityOf(e.key, e.entry).id === a.id && (e.entry.refresh_token ?? "") !== "");
+  } catch {
+    return false;
+  }
+}
+
+async function removeCredentials(a: Account): Promise<void> {
+  rmSync(grokStoreDirFor(a.id), { recursive: true, force: true });
+}
+
+function harvestOf(key: string, entry: GrokAuthEntry): Harvest | null {
+  const { id, email } = identityOf(key, entry);
+  if (!id) return null;
+  return {
+    id,
+    email,
+    tier: null,
+    sample: null,
+    park: async () => {
+      mkdirSync(grokStoreDirFor(id), { recursive: true });
+      writeFileAtomic(grokAuthJsonFor(id), JSON.stringify({ [key]: entry }, null, 2), 0o600);
+    },
+  };
+}
+
+async function login(): Promise<Harvest | null> {
+  const real = resolveRealGrok();
+  const onboardDir = grokPaths.onboardDir;
+  rmSync(onboardDir, { recursive: true, force: true });
+  mkdirSync(onboardDir, { recursive: true });
+  const p = Bun.spawn([real, "login"], {
+    stdin: "inherit",
+    stdout: "inherit",
+    stderr: "inherit",
+    env: { ...process.env, GROK_HOME: onboardDir, TOKENMAXXING_PROBE: "1" },
+  });
+  await p.exited;
+  try {
+    if (p.exitCode !== 0) {
+      console.error(c.red("no grok login landed in the isolated home - nothing added."));
+      return null;
+    }
+    const entries = parseGrokAuthFile(join(onboardDir, "auth.json"));
+    if (entries.length === 0) {
+      console.error(c.red("no grok login landed in the isolated home - nothing added."));
+      return null;
+    }
+    return harvestOf(entries[0]!.key, entries[0]!.entry);
+  } finally {
+    rmSync(onboardDir, { recursive: true, force: true });
+  }
+}
+
+async function importLive(): Promise<Harvest | null> {
+  console.log(c.cyan("Opening an isolated grok login for your first pooled account - the login you already have stays as it is."));
+  console.log();
+  const live = parseGrokAuthFile(join(grokPaths.home, "auth.json"));
+  if (live.length > 0) {
+    console.log(c.dim(`found ${live.length} grok login(s) in ${grokPaths.home} - pooling the first; use \`tokenmaxxing add --grok\` for the rest.`));
+    const h = harvestOf(live[0]!.key, live[0]!.entry);
+    if (h) return h;
+  }
+  return login();
+}
+
+function preflight(): void {
+  const real = resolveRealGrok();
+  const p = Bun.spawnSync([real, "--version"], { stdout: "pipe", stderr: "pipe", timeout: 15_000 });
+  const out = (p.stdout?.toString() ?? "").trim().toLowerCase();
+  if (p.exitCode !== 0 || !out.includes("grok")) {
+    throw new Error(`grok binary failed verification: ${real}`);
+  }
+  pinBinOverride({ key: "grokBin", bin: real });
+}
+
+function install(): void {
+  console.log(c.dim("grok pool is status-only: no supervisor or hooks installed. Use `tokenmaxxing status` to view pooled grok accounts."));
+}
+
+export const grok: Provider = {
+  name: "grok",
+  flag: " --grok",
+  pool: grokPool,
+  seats: "live",
+  waitsWhenDepleted: false,
+  statusOnly: true,
+  liveId,
+  presence,
+  gatedFamilies: () => null,
+  observeLive,
+  samplePool,
+  mergeWindows: (next) => next,
+  swap: async () => {
+    throw new Error("grok moves are not supported yet (status-only pool)");
+  },
+  classifySwapError: () => "fatal",
+  removeCredentials,
+  storeUsable,
+  login,
+  importLive,
+  preflight,
+  install,
+  loginStep: () => `Sign in in the browser session that opens (or run ${c.bold("grok login --device-auth")} on headless hosts first).`,
+  windowLabel: (name) => name.toLowerCase(),
+};