tokenmaxxing 0.19.0 → 0.21.0

package/src/lib/lock.ts

@@ -2,57 +2,79 @@
 // 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).
+//
+// The acquire is NON-BLOCKING (LOCK_EX|LOCK_NB) with an async retry loop: a
+// blocking LOCK_EX from this runtime freezes the whole event loop, and in
+// `xx serve` (many actors, one process) a second actor's blocking acquire
+// would stop the holder from ever resuming to release - a true single-process
+// deadlock; a cross-process holder would freeze the daemon for its whole
+// critical section (adversarial review catch, 2026-07-19). EWOULDBLOCK is
+// told apart from real failures via errno, so a bad fd still fails fast
+// instead of spinning.
 
 import { closeSync, mkdirSync, openSync } from "node:fs";
 import { dirname } from "node:path";
-import { dlopen, FFIType, suffix } from "bun:ffi";
+import { dlopen, FFIType, read } from "bun:ffi";
+import { delay } from "es-toolkit";
 
 // 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_NB = 4;
 const LOCK_UN = 8;
+// errno.h: EWOULDBLOCK/EAGAIN is 35 on darwin, 11 on linux; EINTR is 4 on both.
+const EAGAIN = process.platform === "darwin" ? 35 : 11;
+const EINTR = 4;
+const RETRY_MS = 75;
 
-let _flock: ((fd: number, op: number) => number) | null = null;
+const FLOCK_DEF = { flock: { args: [FFIType.i32, FFIType.i32], returns: FFIType.i32 } } as const;
 
-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;
-    }
+// darwin: flock(2) + __error live 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 + __errno_location (verified
+// in-container 2026-07-09, arm64). Exactly one verified path per platform -
+// a broken environment fails fast instead of falling through a guess list.
+function loadLibc() {
+  if (process.platform === "darwin") {
+    const lib = dlopen("libSystem.B.dylib", { ...FLOCK_DEF, __error: { args: [], returns: FFIType.ptr } });
+    return { flock: lib.symbols.flock, errnoPtr: lib.symbols.__error };
   }
-  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;
+  const lib = dlopen("libc.so.6", { ...FLOCK_DEF, __errno_location: { args: [], returns: FFIType.ptr } });
+  return { flock: lib.symbols.flock, errnoPtr: lib.symbols.__errno_location };
+}
+
+let _libc: ReturnType<typeof loadLibc> | null = null;
+
+function libc(): ReturnType<typeof loadLibc> {
+  _libc ??= loadLibc();
+  return _libc;
+}
+
+function currentErrno(): number {
+  const p = libc().errnoPtr();
+  return p == null ? -1 : read.i32(p, 0);
 }
 
 /**
- * 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.
+ * Acquire an exclusive advisory lock on `lockPath`, waiting (without blocking
+ * the event loop) until available. Returns a handle whose release() drops the
+ * lock. The lock is fd-scoped, so racing hooks in separate processes serialize
+ * and same-process actors queue on the retry loop.
  */
-export function acquireLock(lockPath: string): { release: () => void } {
+export async function acquireLock(lockPath: string): Promise<{ 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) {
+  const { flock } = libc();
+  try {
+    while (flock(fd, LOCK_EX | LOCK_NB) !== 0) {
+      const errno = currentErrno();
+      if (errno !== EAGAIN && errno !== EINTR) {
+        throw new Error(`flock LOCK_EX|LOCK_NB failed on ${lockPath} (errno ${errno})`);
+      }
+      await delay(RETRY_MS);
+    }
+  } catch (e) {
     closeSync(fd);
-    throw new Error(`flock LOCK_EX failed on ${lockPath} (rc=${rc})`);
+    throw e;
   }
   let released = false;
   const release = () => {
@@ -69,7 +91,7 @@ export function acquireLock(lockPath: string): { release: () => void } {
 
 /** 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);
+  const held = await acquireLock(lockPath);
   try {
     return await fn();
   } finally {

package/src/lib/log.ts

@@ -1,28 +1,57 @@
 // 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 { appendFileSync, existsSync, mkdirSync, renameSync, statSync } from "node:fs";
 import { dirname } from "node:path";
 import { z } from "zod";
 import { paths } from "./paths.ts";
 
+const LOG_MAX_BYTES = 5_000_000;
+
 /** Redact anything that looks like a token so an accidental pass-through can't leak. */
-export function redact(s: string): string {
+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})`);
 }
 
+let echo: ((input: { event: string; parts: string }) => void) | null = null;
+
+/** Tee every subsequent log() line to a terminal printer. Only the serve
+ *  daemon opts in: hooks and the statusline own their stdout protocol, so the
+ *  echo stays off by default. The printer receives the same redacted parts the
+ *  file line gets. */
+export function setLogEcho(input: { printer: (input: { event: string; parts: string }) => void }): void {
+  echo = input.printer;
+}
+
 export function log(event: string, fields: Record<string, unknown> = {}): void {
+  let line = "";
   try {
+    line = Object.entries(fields)
+      .map(([k, v]) => {
+        const str = z.string().safeParse(v);
+        return `${k}=${redact(str.success ? str.data : JSON.stringify(v))}`;
+      })
+      .join(" ");
     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`);
+    // Rotation cap: the check timer logs every 180s and the serve daemon
+    // echoes every event, so an uncapped append-only file grows forever on a
+    // live install (closing-review critic gap). One .old generation bounds
+    // total disk at ~2x the cap; older history is disposable diagnostics.
+    if (existsSync(paths.logFile) && statSync(paths.logFile).size > LOG_MAX_BYTES) {
+      renameSync(paths.logFile, `${paths.logFile}.old`);
+    }
+    appendFileSync(paths.logFile, `${new Date().toISOString()} ${event} ${line}\n`);
   } catch {
     // logging must never throw into a hook / supervisor path
   }
+  // separate from the file sink: an unwritable log file must not also silence
+  // the terminal echo (that is exactly when the daemon needs to stay visible).
+  try {
+    echo?.({ event, parts: line });
+  } catch {
+    // the echo printer must never throw into the daemon either
+  }
 }

package/src/lib/oauth.ts

@@ -8,12 +8,16 @@
 //      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 { z } from "zod";
+import { http, safeErrorDetail } 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";
+// zod-parsed like every other env override (repo rule): a set-but-EMPTY value
+// parses to undefined and the default applies, instead of posting to "".
+const EnvOverrideSchema = z.string().min(1).optional().catch(undefined);
+const TOKEN_URL = EnvOverrideSchema.parse(process.env.TOKENMAXXING_OAUTH_TOKEN_URL) ?? "https://platform.claude.com/v1/oauth/token";
+const CLIENT_ID = EnvOverrideSchema.parse(process.env.TOKENMAXXING_OAUTH_CLIENT_ID) ?? "9d1c250a-e61b-44d9-88ed-5944d1962f5e";
+const ROLES_URL = EnvOverrideSchema.parse(process.env.TOKENMAXXING_OAUTH_ROLES_URL) ?? "https://api.anthropic.com/api/oauth/claude_cli/roles";
 
 const DEFAULT_SCOPES = [
   "user:profile",
@@ -53,23 +57,26 @@ export async function refreshCredential(creds: OAuthCreds, now = Date.now()): Pr
       body: JSON.stringify(body),
     });
   } catch (e) {
-    throw new Error(`token endpoint unreachable: ${String((e as Error).message ?? e)}`);
+    throw new Error(`token endpoint unreachable: ${e instanceof Error ? e.message : String(e)}`);
   }
 
   const text = await res.text();
   if (!res.ok) {
     // invalid_grant → dead refresh token; anything else is transient/unknown.
+    // Bodies go through the safeErrorDetail allowlist, never raw: a token
+    // endpoint's failure body can echo request material.
     if (res.status === 400 && /invalid_grant/.test(text)) {
-      throw new InvalidGrantError(text.slice(0, 200));
+      throw new InvalidGrantError(safeErrorDetail({ text }));
     }
-    throw new Error(`token refresh failed (HTTP ${res.status}): ${text.slice(0, 200)}`);
+    throw new Error(`token refresh failed (HTTP ${res.status}): ${safeErrorDetail({ text })}`);
   }
 
   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)}`);
+    // A success-status body holds live tokens: never echo any of it.
+    throw new Error(`token endpoint returned an unrecognized body (${text.length} bytes, withheld)`);
   }
   const json = parsed.data;
 
@@ -105,13 +112,13 @@ export async function fetchTokenOrg(accessToken: string): Promise<RolesResponse>
       headers: { Authorization: `Bearer ${accessToken}`, "anthropic-beta": "oauth-2025-04-20" },
     });
   } catch (e) {
-    throw new Error(`roles endpoint unreachable: ${String((e as Error).message ?? e)}`);
+    throw new Error(`roles endpoint unreachable: ${e instanceof Error ? e.message : String(e)}`);
   }
   const text = await res.text();
-  if (!res.ok) throw new Error(`roles check failed (HTTP ${res.status}): ${text.slice(0, 140)}`);
+  if (!res.ok) throw new Error(`roles check failed (HTTP ${res.status}): ${safeErrorDetail({ text })}`);
   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)}`);
+  if (!parsed.success) throw new Error(`roles endpoint returned an unrecognized body (${text.length} bytes, withheld)`);
   return parsed.data;
 }

package/src/lib/paths.ts

@@ -16,7 +16,7 @@ function env(name: string, fallback: string): string {
 }
 
 /** Root of all tokenmaxxing config + state. Default ~/.config/tokenmaxxing. */
-export const TM_HOME = env("TOKENMAXXING_HOME", join(HOME, ".config", "tokenmaxxing"));
+const TM_HOME = env("TOKENMAXXING_HOME", join(HOME, ".config", "tokenmaxxing"));
 
 export const paths = {
   home: TM_HOME,
@@ -25,6 +25,8 @@ export const paths = {
   usageJson: join(TM_HOME, "usage.json"),
   modelUsageJson: join(TM_HOME, "model-usage.json"),
   lastSwapJson: join(TM_HOME, "lastswap.json"),
+  /** the last depleted-wait decision, replayed to sibling hooks (self-expiring). */
+  depletedJson: join(TM_HOME, "depleted.json"),
   respawnDir: join(TM_HOME, "respawn"),
   binDir: join(TM_HOME, "bin"),
   supervisorLink: join(TM_HOME, "bin", "claude"),
@@ -36,20 +38,23 @@ export const paths = {
   credsDir: join(TM_HOME, "creds"),
 
   /** `xx serve` slack bridge: tokens + channel->repo links (0600: holds the
-   *  xoxb-/xapp- tokens), per-thread claude session records, and the git
-   *  worktrees threads run in. */
+   *  xoxb-/xapp- tokens), per-thread claude session records, and the
+   *  single-instance flock (a new daemon generation blocks on it until the
+   *  previous one - possibly still draining an in-flight turn - fully exits,
+   *  so two generations never act on the same thread records or cwd). */
   slackJson: join(TM_HOME, "slack.json"),
   slackThreadsDir: join(TM_HOME, "slack-threads"),
-  slackWorktreesDir: join(TM_HOME, "slack-worktrees"),
+  serveLockFile: join(TM_HOME, "serve-lock"),
 
   /** ~/.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. */
+  /** ~/.claude/settings.json - user-owned; we merge four 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. */
+  /** ~/.claude - claude's config dir (settings.json, projects/ transcripts;
+   *  credDir() falls back to it). */
   claudeDir: env("CLAUDE_CONFIG_DIR", join(HOME, ".claude")),
 
   /** where the periodic-check timer units live (launchd / systemd user). */
@@ -57,11 +62,6 @@ export const paths = {
   systemdUserDir: env("TOKENMAXXING_SYSTEMD_USER_DIR", join(HOME, ".config", "systemd", "user")),
 } 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"));
-}
-
 /** Codex home: where the live auth.json lives. Test override first, then
  *  codex's own CODEX_HOME env, then its default ~/.codex. */
 const CODEX_HOME = env("TOKENMAXXING_CODEX_HOME", env("CODEX_HOME", join(HOME, ".codex")));
@@ -86,6 +86,12 @@ export const codexPaths = {
    *  running account's parked token must never be refreshed or targeted (its
    *  live rotations supersede the parked copy, and reuse is punished). */
   presenceDir: join(TM_HOME, "codex-live"),
+  /** cross-session reconcile signals, one file per supervisorId: a deciding
+   *  actor saw that supervisor's session running on a pooled NON-LIVE account
+   *  (healthy or not - owner decisions 2026-07-20) while the live seat is
+   *  usable; the session's OWN Stop hook promotes the signal into a respawn
+   *  marker at its next turn boundary. */
+  reconcileDir: join(TM_HOME, "codex-reconcile"),
 } as const;
 
 /** Per-account parked codex credential file name: tokenmaxxing-codex-<id8>. */

package/src/lib/picker.ts

@@ -75,7 +75,10 @@ function blockingUntil(a: Account, ctx: PickCtx): number[] {
           blockedUntil(u.sevenDay, WEEK_MS, a.lastUsageAt, ctx.thresholds.weekly),
         ]
       : []),
-    ...gatedPerModelWindows(a, ctx.switchFamilies).map((w) => blockedUntil(w, WEEK_MS, a.lastUsageAt, ctx.thresholds.weekly)),
+    // per-model rows date by their OWN sample time when known: lastUsageAt
+    // advances on every engaged evaluation while the rows may be days older,
+    // which inflated the null-reset self-bound (closing-review catch).
+    ...gatedPerModelWindows(a, ctx.switchFamilies).map((w) => blockedUntil(w, WEEK_MS, a.lastPerModelAt ?? a.lastUsageAt, ctx.thresholds.weekly)),
   ];
 }
 
@@ -127,10 +130,15 @@ export function pacePressure(a: Account, now: number): number {
 /** The switch preference: furthest behind its own weekly pace first (highest
  *  pacePressure), tiebreak soonest weekly expiry then lowest 7-day usage.
  *  Ranks swaps only; display surfaces order by earliestReset instead. */
-export const swapPreference = (now: number) => [
+const swapPreference = (now: number) => [
   (a: Account) => -pacePressure(a, now),
   (a: Account) => weeklyExpiry(a, now),
-  (a: Account) => a.lastUsage?.sevenDay.usedPercentage ?? 0,
+  // unmeasured ranks LAST in this tiebreak (101 > any real percentage):
+  // `?? 0` made a never-sampled account look maximally safe and beat any
+  // measured one, swapping a healthy measured seat onto a complete unknown -
+  // the exact unmeasured-must-not-look-safe rule (closing-review catch);
+  // pacePressure already ranks unmeasured last by the same principle.
+  (a: Account) => a.lastUsage?.sevenDay.usedPercentage ?? 101,
 ];
 
 export function pickBest(accounts: Account[], ctx: PickCtx): Account | null {

package/src/lib/proc.ts

@@ -0,0 +1,37 @@
+// Process identity beyond a bare PID: pids recycle, so anything that must act
+// on "the process I recorded earlier" (reaping an orphan, trusting a presence
+// file) pins pid + start time and treats a mismatch as a different process.
+
+import { z } from "zod";
+
+/** The ps lstart token for a pid, or null when no such process. pid + start
+ *  time is the standard process identity: equality with the token captured
+ *  at spawn proves this is still the SAME process, never a recycled pid.
+ *  LC_ALL=C pins the lstart rendering (cubic review catch): the capturing and
+ *  the comparing process can run under different locales (terminal vs
+ *  launchd), and a formatting mismatch would silently break the identity.
+ *  Tradeoff (flagged and accepted): lstart has one-second resolution, so a
+ *  pid recycled onto a process started within the SAME wall-clock second
+ *  would pass - landing on the exact pid AND second is vanishingly unlikely,
+ *  and finer start-time sources are per-platform native calls ps cannot give. */
+export function pidStartTime(pid: number): string | null {
+  const res = Bun.spawnSync(["ps", "-p", String(pid), "-o", "lstart="], { env: { ...process.env, LC_ALL: "C" } });
+  if (res.exitCode !== 0) return null;
+  const lstart = res.stdout.toString().trim();
+  return lstart === "" ? null : lstart;
+}
+
+/** Whether the pid names a LIVE process (signal-0 probe); EPERM still proves
+ *  existence. Distinguishes "pid is dead" from "ps could not answer", which a
+ *  null pidStartTime alone cannot. */
+export function pidExists(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    const errno = z.object({ code: z.string() }).safeParse(e);
+    if (errno.success && errno.data.code === "ESRCH") return false;
+    if (errno.success && errno.data.code === "EPERM") return true;
+    throw e;
+  }
+}

package/src/lib/sample.ts

@@ -31,22 +31,32 @@ import { CredentialBlobSchema, type Account, type OAuthCreds, type RolesResponse
 /** Result of a live sample: the fresh usage, or why it could not be taken.
  *  `pingError` is set only when a requested ping (status --force) failed - the
  *  account's 5h timer may not have started even if the sample itself succeeded. */
-export const SampleOutcomeSchema = z.discriminatedUnion("ok", [
+const SampleOutcomeSchema = z.discriminatedUnion("ok", [
   z.object({ ok: z.literal(true), usage: FullUsageSchema, pingError: z.string().optional() }),
   z.object({ ok: z.literal(false), reason: z.string(), pingError: z.string().optional() }),
 ]);
 export type SampleOutcome = z.infer<typeof SampleOutcomeSchema>;
 
-/** Verify `creds` belongs to `account`; null on match, else the mismatch reason. */
-async function identityMismatch(creds: OAuthCreds, account: Account): Promise<string | null> {
+const IdentityCheckSchema = z.discriminatedUnion("status", [
+  z.object({ status: z.literal("match") }),
+  z.object({ status: z.literal("mismatch"), reason: z.string() }),
+  z.object({ status: z.literal("unavailable"), reason: z.string() }),
+]);
+type IdentityCheck = z.infer<typeof IdentityCheckSchema>;
+
+/** Verify `creds` belongs to `account`. Only a definitive org DISAGREEMENT is
+ *  a mismatch; an unreachable roles endpoint is "unavailable" and must never
+ *  bench the account - a transient outage is not a dead credential, and
+ *  flagging on it once removed every parked account from switching. */
+async function checkIdentity(creds: OAuthCreds, account: Account): Promise<IdentityCheck> {
   let org: RolesResponse;
   try {
     org = await fetchTokenOrg(creds.accessToken);
   } catch (e) {
-    return `credential identity check failed: ${String((e as Error).message ?? e)}`;
+    return { status: "unavailable", reason: `credential identity check failed: ${e instanceof Error ? e.message : String(e)}` };
   }
-  if (org.organization_uuid === account.organizationUuid) return null;
-  return `credential actually belongs to ${org.organization_name} (org ${org.organization_uuid.slice(0, 8)})`;
+  if (org.organization_uuid === account.organizationUuid) return { status: "match" };
+  return { status: "mismatch", reason: `credential actually belongs to ${org.organization_name} (org ${org.organization_uuid.slice(0, 8)})` };
 }
 
 /** Stamp the blob's plan fields onto the account (caller persists). Runs only
@@ -74,11 +84,36 @@ export async function probeParkedUsage(account: Account, opts: { ping?: boolean
   try {
     creds = CredentialBlobSchema.parse(JSON.parse(parkedRaw)).claudeAiOauth;
   } catch (e) {
-    return { ok: false, reason: `parked credential unreadable (${String((e as Error).message ?? e).slice(0, 80)}) - run \`tokenmaxxing auth\`` };
+    return { ok: false, reason: `parked credential unreadable (${(e instanceof Error ? e.message : String(e)).slice(0, 80)}) - run \`tokenmaxxing auth\`` };
+  }
+
+  // The parked copy must never be refreshed (or probed - the probe can rotate
+  // it too) while its account secretly owns the LIVE login: after a crash
+  // between performSwap's live install and the oauthAccount rewrite, status
+  // still routes the live account here, and a parked-side rotation would
+  // supersede the live item's single-use refresh token out from under the
+  // running session - or, if claude rotated first, falsely flag the healthy
+  // live account needsReauth (closing-review catch; mirrors the codex
+  // sampler's present-account invariant). Verified against the live blob's
+  // TRUE org, fail-closed like the rm guard: an unverifiable live owner
+  // refuses the sample rather than risking the live grant.
+  const liveRaw = await readItem(liveTarget());
+  if (liveRaw != null) {
+    let liveOrg: string;
+    try {
+      const liveCreds = CredentialBlobSchema.parse(JSON.parse(liveRaw)).claudeAiOauth;
+      liveOrg = (await fetchTokenOrg(liveCreds.accessToken)).organization_uuid;
+    } catch (e) {
+      return { ok: false, reason: `cannot verify the live credential's owner (${(e instanceof Error ? e.message : String(e)).slice(0, 80)}) - refusing to sample a possibly-live account` };
+    }
+    if (liveOrg === account.organizationUuid) {
+      return { ok: false, reason: "this account holds the LIVE login (active label drifted) - run `tokenmaxxing switch` to reconcile" };
+    }
   }
 
   // Hand claude a token with comfortable headroom so it won't run its own refresh
-  // (which claude does within 120s of expiry). Refresh + persist ourselves first.
+  // (which claude does within 300s of expiry - the same margin checked here).
+  // Refresh + persist ourselves first.
   if (isAccessTokenExpiring(creds, 300_000)) {
     try {
       creds = await refreshCredential(creds);
@@ -86,16 +121,19 @@ export async function probeParkedUsage(account: Account, opts: { ping?: boolean
     } catch (e) {
       if (e instanceof InvalidGrantError) {
         account.needsReauth = true;
-        return { ok: false, reason: "refresh token dead - re-auth with `tokenmaxxing add`" };
+        return { ok: false, reason: "refresh token dead - re-auth with `tokenmaxxing auth`" };
       }
-      return { ok: false, reason: `token refresh failed: ${String((e as Error).message ?? e)}` };
+      return { ok: false, reason: `token refresh failed: ${e instanceof Error ? e.message : String(e)}` };
     }
   }
 
-  const mismatch = await identityMismatch(creds, account);
-  if (mismatch) {
+  const identity = await checkIdentity(creds, account);
+  if (identity.status === "mismatch") {
     account.needsReauth = true;
-    return { ok: false, reason: `${mismatch} - this account's own credential is gone; re-auth with \`tokenmaxxing add\`` };
+    return { ok: false, reason: `${identity.reason} - this account's own credential is gone; re-auth with \`tokenmaxxing auth\`` };
+  }
+  if (identity.status === "unavailable") {
+    return { ok: false, reason: identity.reason };
   }
   refreshPlanFields(account, creds);
 
@@ -124,6 +162,35 @@ export async function probeParkedUsage(account: Account, opts: { ping?: boolean
   }
 }
 
+/** Refresh the LIVE access token when near expiry, under claude's own refresh
+ *  lock. Exported for `xx status`: every parked probe's fail-closed live-owner
+ *  check reads this token, so it must be fresh BEFORE those probes run - even
+ *  when the active account's own usage comes from the statusline tee and no
+ *  active probe happens (cubic review catch, PR #35: the tee short-circuit
+ *  skipped the refresh and every parked sample 401'd on the first post-idle
+ *  status). No live item, or an unparsable one, is a no-op here: the callers'
+ *  own guards surface those loudly. InvalidGrantError propagates. */
+export async function ensureLiveTokenFresh(): Promise<void> {
+  const liveRaw = await readItem(liveTarget());
+  if (!liveRaw) return;
+  let creds: OAuthCreds;
+  try {
+    creds = CredentialBlobSchema.parse(JSON.parse(liveRaw)).claudeAiOauth;
+  } catch {
+    return;
+  }
+  if (!isAccessTokenExpiring(creds, 300_000)) return;
+  await withClaudeRefreshLock(async (lock) => {
+    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;
+    const next = isAccessTokenExpiring(current, 300_000) ? await refreshCredential(current) : current;
+    if (next === current) return;
+    if (lock.compromised()) throw new Error("refresh lock compromised mid-refresh - discarding the live rewrite");
+    await writeItem(liveTarget(), mergeIntoLive(raw2, next));
+  });
+}
+
 /**
  * Live-sample the ACTIVE account off the live login, verifying the live
  * credential belongs to it. `/usage` with no CLAUDE_CONFIG_DIR meters the live
@@ -132,32 +199,25 @@ export async function probeParkedUsage(account: Account, opts: { ping?: boolean
  * the identity check - never spend quota on a drifted credential).
  */
 export async function probeActiveUsage(account: Account, opts: { ping?: boolean } = {}): Promise<SampleOutcome> {
+  // A running claude keeps the live token fresh; after long idle it may not have.
+  try {
+    await ensureLiveTokenFresh();
+  } catch (e) {
+    if (e instanceof InvalidGrantError) return { ok: false, reason: "live refresh token dead - run `claude` and `/login`" };
+    return { ok: false, reason: `token refresh failed: ${e instanceof Error ? e.message : String(e)}` };
+  }
   const liveRaw = await readItem(liveTarget());
   if (!liveRaw) return { ok: false, reason: "no live credential - run `claude` and `/login`" };
   let creds: OAuthCreds;
   try {
     creds = CredentialBlobSchema.parse(JSON.parse(liveRaw)).claudeAiOauth;
   } catch (e) {
-    return { ok: false, reason: `live credential blob unreadable (${String((e as Error).message ?? e).slice(0, 80)})` };
-  }
-
-  // A running claude keeps the live token fresh; after long idle it may not have.
-  if (isAccessTokenExpiring(creds, 300_000)) {
-    try {
-      await withClaudeRefreshLock(async () => {
-        const raw2 = (await readItem(liveTarget())) ?? liveRaw;
-        const current = CredentialBlobSchema.parse(JSON.parse(raw2)).claudeAiOauth;
-        creds = isAccessTokenExpiring(current, 300_000) ? await refreshCredential(current) : current;
-        if (creds !== current) await writeItem(liveTarget(), mergeIntoLive(raw2, creds));
-      });
-    } catch (e) {
-      if (e instanceof InvalidGrantError) return { ok: false, reason: "live refresh token dead - run `claude` and `/login`" };
-      return { ok: false, reason: `token refresh failed: ${String((e as Error).message ?? e)}` };
-    }
+    return { ok: false, reason: `live credential blob unreadable (${(e instanceof Error ? e.message : String(e)).slice(0, 80)})` };
   }
 
-  const mismatch = await identityMismatch(creds, account);
-  if (mismatch) return { ok: false, reason: `live ${mismatch} - active label drifted; run \`tokenmaxxing switch\`` };
+  const identity = await checkIdentity(creds, account);
+  if (identity.status === "mismatch") return { ok: false, reason: `live ${identity.reason} - active label drifted; run \`tokenmaxxing switch\`` };
+  if (identity.status === "unavailable") return { ok: false, reason: identity.reason };
   refreshPlanFields(account, creds);
 
   const pingError = opts.ping ? await pingSession() : null;

package/src/lib/sessions.ts

@@ -3,7 +3,7 @@
 // recovery in #20) re-applies them instead of dropping --dangerously-skip-
 // permissions / --model / etc.
 
-import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
 import { paths } from "./paths.ts";
@@ -11,6 +11,12 @@ import { writeFileAtomic } from "./atomic.ts";
 
 const SessionSchema = z.object({ flags: z.array(z.string()), cwd: z.string() });
 
+// Matches claude's default transcript retention (cleanupPeriodDays 30): a
+// transcript claude has already deleted cannot be resumed, so its flags file
+// is dead weight. saveSessionFlags rewrites the file on every (re)launch, so
+// an actively resumed session keeps its mtime fresh and is never pruned.
+const SESSION_RETENTION_MS = 30 * 24 * 3600 * 1000;
+
 function sessionFile(sid: string): string {
   return join(paths.home, "sessions", `${sid}.json`);
 }
@@ -25,3 +31,19 @@ export function loadSessionFlags(sid: string): string[] | null {
   if (!existsSync(f)) return null;
   return SessionSchema.parse(JSON.parse(readFileSync(f, "utf8"))).flags;
 }
+
+/** Delete session files past the retention window (also reaps stale
+ *  writeFileAtomic temp siblings from a crashed writer). */
+export function pruneStaleSessions(now: number): void {
+  const dir = join(paths.home, "sessions");
+  if (!existsSync(dir)) return;
+  for (const f of readdirSync(dir)) {
+    const p = join(dir, f);
+    try {
+      if (now - statSync(p).mtimeMs > SESSION_RETENTION_MS) rmSync(p, { force: true });
+    } catch {
+      // A concurrent writeFileAtomic renames its tmp sibling away between
+      // readdir and stat; a vanished entry needs no pruning.
+    }
+  }
+}