tokenmaxxing 0.19.0 → 0.21.0

package/src/cli/doctor.ts

@@ -1,4 +1,4 @@
-// `tokenmaxxing doctor` - verify the supervisor + three settings entries survived
+// `tokenmaxxing doctor` - verify the supervisor + four settings entries survived
 // and the pool is healthy.
 
 import { existsSync, readFileSync } from "node:fs";
@@ -55,7 +55,7 @@ export async function cmdDoctor(): Promise<number> {
       if (org) check(org.organization_uuid === active.organizationUuid, `live credential identity matches active (${active.email})`, `token belongs to ${org.organization_name} - run \`tokenmaxxing switch\``);
       else console.log(c.dim(`  - live credential identity unverifiable (access token expired)`));
     } catch (e) {
-      check(false, `live credential identity matches active (${active.email})`, String((e as Error).message ?? e).slice(0, 100));
+      check(false, `live credential identity matches active (${active.email})`, (e instanceof Error ? e.message : String(e)).slice(0, 100));
     }
   }
 
@@ -68,7 +68,7 @@ export async function cmdDoctor(): Promise<number> {
         if (org) check(org.organization_uuid === a.organizationUuid, `parked credential identity matches ${a.email}`, `token belongs to ${org.organization_name} - run \`tokenmaxxing auth ${a.label}\``);
         else console.log(c.dim(`  - ${a.email} identity unverifiable (access token expired)`));
       } catch (e) {
-        check(false, `parked credential identity matches ${a.email}`, String((e as Error).message ?? e).slice(0, 100));
+        check(false, `parked credential identity matches ${a.email}`, (e instanceof Error ? e.message : String(e)).slice(0, 100));
       }
     }
     if (a.needsReauth) check(false, `${a.email} needs re-auth`, `run \`tokenmaxxing auth ${a.label}\` to re-login`);

package/src/cli/init.ts

@@ -1,11 +1,13 @@
 // `tokenmaxxing init` - import the account you're already on (no prompts), then
-// install the supervisor + the three settings entries.
+// install the supervisor + the four settings entries.
 
 import { mkdirSync } from "node:fs";
 import { isApiKeyMode, readOAuthAccount } from "../lib/claudejson.ts";
 import { readItem, writeItem, liveTarget, parkedTarget, mergeIntoLive } from "../lib/credstore.ts";
 import { refreshCredential, isAccessTokenExpiring, fetchTokenOrg } from "../lib/oauth.ts";
-import { loadAccounts, saveAccounts, loadConfig, saveConfig } from "../lib/state.ts";
+import { withClaudeRefreshLock } from "../lib/claudelock.ts";
+import { loadAccounts, saveAccounts, loadConfig, pinBinOverride } from "../lib/state.ts";
+import { withLock } from "../lib/lock.ts";
 import { installSupervisor, shellRcPath, ensurePathInRc, timerActivationHint, type InstallOutcome } from "../lib/install.ts";
 import { resolveVerifiedClaude } from "../lib/claudebin.ts";
 import { credItemFor, paths } from "../lib/paths.ts";
@@ -46,6 +48,13 @@ export function printUsage(): void {
 
 export async function cmdInit(): Promise<number> {
   mkdirSync(paths.home, { recursive: true });
+  // Fail fast on a broken merged config BEFORE installing or claiming a
+  // successful repair: pinBinOverride writes sparsely without validating, so
+  // without this gate a re-init printed success while hooks, switching, and
+  // the statusline kept throwing on every loadConfig until the file was
+  // hand-repaired (bugbot review catch, PR #33). The throw carries the
+  // fix-or-remove recovery message.
+  loadConfig();
 
   // Already initialized → repair install ONLY. Never re-import: ~/.claude.json's
   // oauthAccount can drift from the live keychain cred (after swaps / concurrent
@@ -56,10 +65,9 @@ export async function cmdInit(): Promise<number> {
     // repair the claudeBin pin too - hooks run with claude's PATH and must
     // never have to guess which binary is the real claude. Verified pinning:
     // a pin that fails --version (or loops back into the wrapper) is replaced
-    // by a fresh PATH scan instead of being re-saved.
-    const cfg = loadConfig();
-    cfg.claudeBin = resolveVerifiedClaude();
-    saveConfig(cfg);
+    // by a fresh PATH scan instead of being re-saved. Sparse write: only the
+    // pin lands in the file, never the merged config.
+    pinBinOverride({ key: "claudeBin", bin: resolveVerifiedClaude() });
     const active = existingIdx.accounts.find((a) => a.accountUuid === existingIdx.activeAccountUuid);
     console.log(`${c.green("✓")} re-installed supervisor + hooks (pool already has ${existingIdx.accounts.length} account${existingIdx.accounts.length === 1 ? "" : "s"} - not re-importing)`);
     reportTimer(out);
@@ -96,8 +104,16 @@ export async function cmdInit(): Promise<number> {
   // keychain credential, and importing on drifted state parks a mislabeled blob.
   let creds = blob.claudeAiOauth;
   if (isAccessTokenExpiring(creds)) {
-    creds = await refreshCredential(creds);
-    await writeItem(liveTarget(), mergeIntoLive(liveRaw, creds));
+    await withClaudeRefreshLock(async (lock) => {
+      // re-read inside the lock: a running claude may have rotated it already.
+      const raw2 = await readItem(liveTarget());
+      if (raw2 == null) throw new Error("live credential vanished while waiting for the refresh lock");
+      const current = CredentialBlobSchema.parse(JSON.parse(raw2)).claudeAiOauth;
+      creds = isAccessTokenExpiring(current) ? await refreshCredential(current) : current;
+      if (creds === current) return;
+      if (lock.compromised()) throw new Error("refresh lock compromised mid-refresh - discarding the live rewrite");
+      await writeItem(liveTarget(), mergeIntoLive(raw2, creds));
+    });
   }
   const org = await fetchTokenOrg(creds.accessToken);
   if (org.organization_uuid !== oauthAccount.organizationUuid) {
@@ -108,30 +124,35 @@ export async function cmdInit(): Promise<number> {
 
   const uuid = oauthAccount.accountUuid;
   const keychainItem = credItemFor(uuid);
-  await writeItem(parkedTarget(keychainItem), JSON.stringify({ claudeAiOauth: creds })); // park a small backup
+  // Park + index update under the tokenmaxxing flock, like every sibling
+  // index writer (add/auth/rm/status/rename): unlocked, a concurrent `xx add`
+  // completing between this path's load and save had its just-registered
+  // account silently clobbered out of the index (closing-review catch).
+  const account = await withLock(paths.lockFile, async () => {
+    await writeItem(parkedTarget(keychainItem), JSON.stringify({ claudeAiOauth: creds })); // park a small backup
+    const idx = loadAccounts();
+    const existing = idx.accounts.find((a) => a.accountUuid === uuid);
+    const imported: Account = {
+      accountUuid: uuid,
+      email: oauthAccount.emailAddress,
+      organizationUuid: oauthAccount.organizationUuid,
+      label: existing?.label ?? oauthAccount.emailAddress,
+      keychainItem,
+      oauthAccount,
+      addedAt: existing?.addedAt ?? new Date().toISOString(),
+      subscriptionType: blob.claudeAiOauth.subscriptionType,
+      rateLimitTier: blob.claudeAiOauth.rateLimitTier,
+      needsReauth: false,
+    };
+    if (existing) Object.assign(existing, imported);
+    else idx.accounts.push(imported);
+    idx.activeAccountUuid = uuid;
+    saveAccounts(idx);
+    return imported;
+  });
 
-  const idx = loadAccounts();
-  const existing = idx.accounts.find((a) => a.accountUuid === uuid);
-  const account: Account = {
-    accountUuid: uuid,
-    email: oauthAccount.emailAddress,
-    organizationUuid: oauthAccount.organizationUuid,
-    label: existing?.label ?? oauthAccount.emailAddress,
-    keychainItem,
-    oauthAccount,
-    addedAt: existing?.addedAt ?? new Date().toISOString(),
-    subscriptionType: blob.claudeAiOauth.subscriptionType,
-    rateLimitTier: blob.claudeAiOauth.rateLimitTier,
-    needsReauth: false,
-  };
-  if (existing) Object.assign(existing, account);
-  else idx.accounts.push(account);
-  idx.activeAccountUuid = uuid;
-  saveAccounts(idx);
-
-  const cfg = loadConfig();
-  cfg.claudeBin = resolveVerifiedClaude();
-  saveConfig(cfg);
+  // Sparse write: only the pin lands in the file, never the merged config.
+  pinBinOverride({ key: "claudeBin", bin: resolveVerifiedClaude() });
 
   const out = installSupervisor();
 
@@ -142,8 +163,9 @@ export async function cmdInit(): Promise<number> {
     console.log();
     ensurePathAhead();
   }
+  const poolSize = loadAccounts().accounts.length;
   console.log();
-  console.log(`  pool ready (${idx.accounts.length} account${idx.accounts.length === 1 ? "" : "s"})`);
+  console.log(`  pool ready (${poolSize} account${poolSize === 1 ? "" : "s"})`);
   printUsage();
   return 0;
 }

package/src/cli/onboard.ts

@@ -10,13 +10,13 @@ import { join } from "node:path";
 import { z } from "zod";
 import { readItem, deleteItem, isolatedTarget } from "../lib/credstore.ts";
 import { resolveRealClaude } from "../lib/claudebin.ts";
-import { probeUsage, FullUsageSchema } from "../lib/usage.ts";
+import { CRED_ENV_OVERRIDES, probeUsage, FullUsageSchema } from "../lib/usage.ts";
 import { saveTermios, restoreTermios } from "../lib/tty.ts";
 import { paths } from "../lib/paths.ts";
 import { CredentialBlobSchema, OAuthAccountSchema } from "../lib/types.ts";
 import { c } from "./render.ts";
 
-export const HarvestedLoginSchema = z.object({
+const HarvestedLoginSchema = z.object({
   /** the raw isolated credential blob (park it via claudeAiOauthOnly). */
   blobRaw: z.string(),
   blob: CredentialBlobSchema,
@@ -46,6 +46,15 @@ export async function harvestIsolatedLogin(): Promise<HarvestedLogin | null> {
   rmSync(onboardDir, { recursive: true, force: true });
   mkdirSync(onboardDir, { recursive: true });
   const iso = isolatedTarget(onboardDir);
+  // Reap a PREVIOUS run's stranded isolated credential too: on macOS the
+  // isolated store is a namespaced KEYCHAIN item, not a file in onboardDir,
+  // so the rmSync above never touched it - a signal-killed harvest (Ctrl-C
+  // after /login, before the ~400ms poll) left a live credential in the
+  // keychain that the next run's spawned claude would silently reuse as an
+  // already-authenticated session (closing-review catch). deleteItem on a
+  // missing item is a no-op; on Linux iso is a file inside onboardDir and the
+  // rmSync already covered it.
+  await deleteItem(iso);
   const cjPath = join(onboardDir, ".claude.json");
   const real = resolveRealClaude();
 
@@ -54,10 +63,7 @@ export async function harvestIsolatedLogin(): Promise<HarvestedLogin | null> {
   // keychain lookup (verified 2.1.205) - the onboard session must authenticate
   // only via the /login the user performs inside it.
   const env: Record<string, string> = { ...process.env, CLAUDE_CONFIG_DIR: onboardDir, TOKENMAXXING_PROBE: "1", TOKENMAXXING_SUPERVISED: "" };
-  delete env.ANTHROPIC_API_KEY;
-  delete env.ANTHROPIC_AUTH_TOKEN;
-  delete env.CLAUDE_CODE_OAUTH_TOKEN;
-  delete env.CLAUDE_SECURESTORAGE_CONFIG_DIR;
+  for (const key of CRED_ENV_OVERRIDES) delete env[key];
   const p = Bun.spawn([real], {
     stdin: "inherit",
     stdout: "inherit",
@@ -65,48 +71,59 @@ export async function harvestIsolatedLogin(): Promise<HarvestedLogin | null> {
     env,
   });
 
-  // Auto-exit (#17): watch for a completed login - identity written AND the
-  // isolated credential present - then SIGTERM claude. No manual /exit.
-  let exited = false;
-  const onExit = p.exited.then(() => { exited = true; });
-  while (!exited) {
-    await Bun.sleep(400);
-    if (identityReady(cjPath) && (await readItem(iso))) {
-      p.kill();
-      break;
+  // The finally makes the "always destroyed before returning" header true for
+  // every non-signal exit - INCLUDING a failure while the login session is
+  // still being polled (review catch, PR #31): an exception must not strand a
+  // plaintext credential on disk or leave the spawned claude running. (An
+  // interactive Ctrl-C is reaped by the next run's cleanup-first, which
+  // deletes the isolated keychain item as well as the dir.)
+  try {
+    // Auto-exit (#17): watch for a completed login - identity written AND the
+    // isolated credential present - then SIGTERM claude. No manual /exit.
+    let exited = false;
+    const onExit = p.exited.then(() => { exited = true; });
+    while (!exited) {
+      await Bun.sleep(400);
+      if (identityReady(cjPath) && (await readItem(iso))) {
+        p.kill();
+        break;
+      }
     }
-  }
-  await p.exited;
-  await onExit;
-  restoreTermios(savedTermios);
+    await p.exited;
+    await onExit;
+    // restore promptly so the harvest's own output renders on a sane terminal;
+    // the finally's second restore is an idempotent stty and covers the
+    // thrown-mid-poll path.
+    restoreTermios(savedTermios);
 
-  const cleanup = async () => {
-    await deleteItem(iso);
-    rmSync(onboardDir, { recursive: true, force: true });
-  };
-
-  const blobRaw = await readItem(iso);
-  if (!blobRaw || !identityReady(cjPath)) {
-    console.error(c.red("no login detected in the isolated session - nothing changed."));
-    await cleanup();
-    return null;
-  }
+    const blobRaw = await readItem(iso);
+    if (!blobRaw || !identityReady(cjPath)) {
+      console.error(c.red("no login detected in the isolated session - nothing changed."));
+      return null;
+    }
 
-  let blob, oauthAccount;
-  try {
-    blob = CredentialBlobSchema.parse(JSON.parse(blobRaw));
-    oauthAccount = OAuthAccountSchema.parse(JSON.parse(readFileSync(cjPath, "utf8")).oauthAccount);
-  } catch {
-    console.error(c.red("could not parse the onboarded account's credential/identity."));
-    await cleanup();
-    return null;
-  }
+    let blob, oauthAccount;
+    try {
+      blob = CredentialBlobSchema.parse(JSON.parse(blobRaw));
+      oauthAccount = OAuthAccountSchema.parse(JSON.parse(readFileSync(cjPath, "utf8")).oauthAccount);
+    } catch {
+      console.error(c.red("could not parse the onboarded account's credential/identity."));
+      return null;
+    }
 
-  // Sample usage now (#16) so the account isn't "not sampled yet" in status/ls.
-  console.log(c.dim("sampling usage..."));
-  const sampled = await probeUsage(onboardDir);
-  if (!sampled) console.log(c.yellow("could not sample usage now - it will fill in on first use."));
+    // Sample usage now (#16) so the account isn't "not sampled yet" in status/ls.
+    console.log(c.dim("sampling usage..."));
+    const sampled = await probeUsage(onboardDir);
+    if (!sampled) console.log(c.yellow("could not sample usage now - it will fill in on first use."));
 
-  await cleanup();
-  return { blobRaw, blob, oauthAccount, sampled };
+    return { blobRaw, blob, oauthAccount, sampled };
+  } finally {
+    if (p.exitCode === null) {
+      p.kill();
+      await p.exited;
+    }
+    restoreTermios(savedTermios);
+    await deleteItem(iso);
+    rmSync(onboardDir, { recursive: true, force: true });
+  }
 }

package/src/cli/render.ts

@@ -98,19 +98,3 @@ export function fmtAgo(epochMs: number, now = Date.now()): string {
   return `${m}m ago`;
 }
 
-/** Compact time-until-reset for the statusLine: the largest unit only ("6d",
- *  "2h", "45m"), floored to "1m" so a live window never reads as zero, and ""
- *  once the reset has passed (the window is simply empty again). Non-empty
- *  output always ends in a unit letter, so the digit-leading used-percent glued
- *  after it stays parseable. */
-export function fmtResetShort(epochMs: number | null | undefined, now = Date.now()): string {
-  if (epochMs == null) return "";
-  const dsec = Math.round((epochMs - now) / 1000);
-  if (dsec <= 0) return "";
-  const d = Math.floor(dsec / 86400);
-  const h = Math.floor((dsec % 86400) / 3600);
-  const m = Math.floor((dsec % 3600) / 60);
-  if (d > 0) return `${d}d`;
-  if (h > 0) return `${h}h`;
-  return `${Math.max(m, 1)}m`;
-}

package/src/cli/rm.ts

@@ -1,9 +1,13 @@
 // `tokenmaxxing rm <selector>` - remove a pooled account (not the active one).
 
-import { deleteItem, parkedTarget } from "../lib/credstore.ts";
+import { rmSync } from "node:fs";
+import { join } from "node:path";
+import { deleteItem, isolatedTarget, liveTarget, parkedTarget, readItem } from "../lib/credstore.ts";
+import { fetchTokenOrg } from "../lib/oauth.ts";
 import { withLock } from "../lib/lock.ts";
-import { paths } from "../lib/paths.ts";
+import { credItemFor, paths } from "../lib/paths.ts";
 import { loadAccounts, saveAccounts } from "../lib/state.ts";
+import { CredentialBlobSchema } from "../lib/types.ts";
 import { findAccount } from "./rename.ts";
 import { c } from "./render.ts";
 
@@ -24,7 +28,41 @@ export async function cmdRm(selector?: string): Promise<number> {
       console.error(c.red(`${a.email} is the ACTIVE account - switch away before removing it.`));
       return 1;
     }
+    // The label drifts (manual /login); the token cannot lie. Removing the
+    // account whose credential is actually LIVE would destroy its only backup
+    // and leave the next swap refusing over an unpooled credential. Fail
+    // CLOSED (review catch, PR #31): when the live owner cannot be verified -
+    // unparsable blob, expired token, roles outage - refuse rather than trust
+    // the stale label; rm is destructive and can wait. The check is read-only:
+    // an expired bearer simply fails the roles call, nothing is ever rotated.
+    const live = await readItem(liveTarget());
+    if (live != null) {
+      let liveOrg: string;
+      try {
+        const liveCreds = CredentialBlobSchema.parse(JSON.parse(live)).claudeAiOauth;
+        liveOrg = (await fetchTokenOrg(liveCreds.accessToken)).organization_uuid;
+      } catch (e) {
+        console.error(c.red(`cannot verify which account the LIVE credential belongs to (${e instanceof Error ? e.message : String(e)}) - refusing to remove while the live owner is unknown; repair the live credential or retry once the roles endpoint is reachable.`));
+        return 1;
+      }
+      if (liveOrg === a.organizationUuid) {
+        console.error(c.red(`${a.email}'s credential is currently LIVE (the active label is stale - a manual /login drifted it); run \`tokenmaxxing switch\` to move off it first.`));
+        return 1;
+      }
+    }
     await deleteItem(parkedTarget(a.keychainItem));
+    // Sweep sample-probe residue too: a probe killed mid-run strands the
+    // account's isolated credential (macOS: a namespaced keychain item), and
+    // once the account leaves the pool nothing would ever probe-and-heal it
+    // again (closing-review critic gap). deleteItem on a missing item is a
+    // no-op. Hard delete, not trash, on purpose: the sample dir is a
+    // throwaway CLAUDE_CONFIG_DIR that can hold PLAINTEXT credential material
+    // on Linux - the credential-dir cleanup exception (owner 2026-07-16, same
+    // rule sample.ts and onboard.ts follow); trashing would move credentials
+    // into the Trash folder.
+    const sampleDir = join(paths.sampleDir, credItemFor(a.accountUuid));
+    await deleteItem(isolatedTarget(sampleDir));
+    rmSync(sampleDir, { recursive: true, force: true });
     idx.accounts = idx.accounts.filter((x) => x.accountUuid !== a.accountUuid);
     saveAccounts(idx);
     console.log(`removed ${c.bold(a.label)} from the pool (${idx.accounts.length} left)`);