tokenmaxxing 1.8.0 → 1.9.0

package/src/lib/paths.ts

@@ -1,21 +1,15 @@
-// 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";
 import { z } from "zod";
 
 const HOME = homedir();
 
-/** A set env override; empty or unset parses to undefined and the fallback applies. */
 const EnvOverrideSchema = z.string().min(1).optional().catch(undefined);
 
 function env(name: string, fallback: string): string {
   return EnvOverrideSchema.parse(process.env[name]) ?? fallback;
 }
 
-/** Root of all tokenmaxxing config + state. Default ~/.config/tokenmaxxing. */
 const TM_HOME = env("TOKENMAXXING_HOME", join(HOME, ".config", "tokenmaxxing"));
 
 export const paths = {
@@ -25,8 +19,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"),
+  nextCheckJson: join(TM_HOME, "nextcheck.json"),
   respawnDir: join(TM_HOME, "respawn"),
   binDir: join(TM_HOME, "bin"),
   supervisorLink: join(TM_HOME, "bin", "claude"),
@@ -34,105 +28,64 @@ export const paths = {
   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"),
-  /** Durable tmux relay companion: config + per-session state (not respawn/). */
-  relayJson: join(TM_HOME, "relay.json"),
-  relayDir: join(TM_HOME, "relay"),
 
-  /** ~/.claude.json - holds the active `oauthAccount` identity object. */
   claudeJson: env("TOKENMAXXING_CLAUDE_JSON", join(HOME, ".claude.json")),
-  /** ~/.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 - 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). */
   launchdAgentsDir: env("TOKENMAXXING_LAUNCHD_DIR", join(HOME, "Library", "LaunchAgents")),
   systemdUserDir: env("TOKENMAXXING_SYSTEMD_USER_DIR", join(HOME, ".config", "systemd", "user")),
 } as const;
 
-/** 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")));
 
 export const codexPaths = {
   home: CODEX_HOME,
-  /** the live credential file (codex file-mode store; verified 0.144.4/5). */
   authJson: join(CODEX_HOME, "auth.json"),
-  /** user-level hook declarations codex reads (verified against the binary + docs). */
   hooksJson: join(CODEX_HOME, "hooks.json"),
-  /** tokenmaxxing's codex pool state, parallel to the claude files in TM_HOME. */
   accountsJson: join(TM_HOME, "codex-accounts.json"),
   lastSwapJson: join(TM_HOME, "codex-lastswap.json"),
   lockFile: join(TM_HOME, "codex-lock"),
-  /** parked auth.json blobs: 0600 files on BOTH platforms (codex's own store is
-   *  a plaintext file, and parked blobs at ~6KB would risk the security(1)
-   *  write-size trap that once truncated a 4.3KB claude blob). */
   credsDir: join(TM_HOME, "codex-creds"),
   onboardDir: join(TM_HOME, "codex-onboard"),
   respawnDir: join(TM_HOME, "codex-respawn"),
-  /** one file per RUNNING supervised codex session: {accountId, pid, ts}. A
-   *  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>. */
 export function codexCredItemFor(accountId: string): string {
   return `tokenmaxxing-codex-${accountId.slice(0, 8)}`;
 }
 
-/** 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 {
   return EnvOverrideSchema.parse(process.env.TOKENMAXXING_CLAUDE_BIN);
 }
 
-/** Same override hook for the real codex binary (tests / relocation). */
 export function realCodexBinFromEnv(): string | undefined {
   return EnvOverrideSchema.parse(process.env.TOKENMAXXING_CODEX_BIN);
 }

package/src/lib/picker.ts

@@ -1,25 +1,8 @@
-// Choose the account to switch TO. Greedy policy: among usable accounts (no
-// reauth, no window >= threshold that hasn't reset yet), take the one furthest
-// behind its own weekly pace - highest pacePressure, the burn rate its
-// remaining weekly quota demands to be consumed at before the fixed
-// per-account reset forfeits it (weekly allowance is use-it-or-lose-it).
-// This refines the older soonest-expiry policy in both directions: equal
-// remaining reduces to soonest expiry first, equal expiry to most remaining
-// first. Runs entirely off each account's cached windows (absolute UTC
-// epochs, so a stale snapshot still resolves to the correct upcoming reset),
-// which makes the pick deterministic and idempotent: re-running lands on the
-// same account.
-
 import { minBy, sortBy } from "es-toolkit";
 import { z } from "zod";
 import { familyTokens } from "./usage.ts";
 import { AccountSchema, ThresholdsSchema, type Account, type Config, type Thresholds, type UsageWindow } from "./types.ts";
 
-/** The effective per-window bars: configured thresholds minus the projection
- *  margin. ONE bar per window for BOTH the trigger and candidate screening -
- *  a screen laxer than the trigger would land swaps on accounts the trigger
- *  immediately re-flags (cooldown-throttled ping-pong). Every PickCtx and the
- *  trigger floors must be built from this. */
 export function effectiveBars(cfg: Config): Thresholds {
   return {
     session: cfg.thresholds.session - cfg.policy.projectionMargin,
@@ -27,16 +10,6 @@ export function effectiveBars(cfg: Config): Thresholds {
   };
 }
 
-/** LAYER 2 - the wall bars. The projection margin is subtracted the SAME way
- *  effectiveBars does it, for two reasons: (1) it keeps the documented disable
- *  contract honest - `hardThresholds == thresholds` then yields hardBars ==
- *  effectiveBars, so Layer 2 has no band to act in and is truly off (without
- *  the margin here a nonzero margin left a live band between the two, review
- *  catch PR #47); (2) at the default margin 0 the wall is still the literal 100
- *  (the server's own figure /rate-limit-options reads). Used only in the
- *  all-Layer-1-exhausted fallback, where an account under its wall is still
- *  worth squeezing. Config's refine (hardThresholds >= thresholds) guarantees
- *  hardBars >= effectiveBars, so Layer 2 is never stricter than Layer 1. */
 export function hardBars(cfg: Config): Thresholds {
   return {
     session: cfg.hardThresholds.session - cfg.policy.projectionMargin,
@@ -47,16 +20,11 @@ export function hardBars(cfg: Config): Thresholds {
 const PickCtxSchema = z.object({
   now: z.number(),
   thresholds: ThresholdsSchema,
-  /** account to exclude (hooks switch AWAY from it); null ranks everyone. */
   currentAccountUuid: z.string().nullable(),
-  /** families whose per-model weekly cap counts toward exhaustion (from
-   *  gatedFamilies): a candidate with a burnt gated cap is no switch target -
-   *  landing on it would re-trigger the same gate and ping-pong the pool. */
   switchFamilies: z.array(z.string()),
 });
 export type PickCtx = z.infer<typeof PickCtxSchema>;
 
-/** The account's cached per-model windows that belong to a gated family. */
 function gatedPerModelWindows(a: Account, families: string[]): UsageWindow[] {
   return Object.entries(a.lastPerModel ?? {})
     .filter(([model]) => families.some((f) => familyTokens(model).includes(f)))
@@ -66,23 +34,12 @@ function gatedPerModelWindows(a: Account, families: string[]): UsageWindow[] {
 const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
 const FIVE_HOURS_MS = 5 * 60 * 60 * 1000;
 
-/** Epoch until which `w` blocks the account; anything <= now means it does not
- *  block. A window with no known reset (unparsed clock) is still bounded by
- *  its own duration past the sample time - a 5h window sampled 6h ago has
- *  certainly reset - so a benched account always recovers by itself. With no
- *  sample time either, it blocks indefinitely: guessing "usable now" would
- *  swap onto it with waitUntil=now and churn kill/respawn. */
 function blockedUntil(w: UsageWindow, windowMs: number, sampledAt: number | undefined, threshold: number): number {
   if (w.usedPercentage < threshold) return 0;
   if (w.resetsAt != null) return w.resetsAt;
   return sampledAt != null ? sampledAt + windowMs : Number.POSITIVE_INFINITY;
 }
 
-/** When each of the account's windows stops blocking: the two aggregates plus
- *  the gated per-model caps, each against its own threshold (session swaps
- *  earlier than the weekly windows, and a candidate is screened by the same
- *  bar that would trigger a switch off it - landing below the trigger bar
- *  would ping-pong). */
 function blockingUntil(a: Account, ctx: PickCtx): number[] {
   const u = a.lastUsage;
   return [
@@ -92,50 +49,29 @@ function blockingUntil(a: Account, ctx: PickCtx): number[] {
           blockedUntil(u.sevenDay, 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)),
+    ...(a.enforcedUntil != null ? [a.enforcedUntil] : []),
   ];
 }
 
-/** An account is "exhausted" if a window is >= its threshold and hasn't reset yet. */
 export function isExhausted(a: Account, ctx: PickCtx): boolean {
   return blockingUntil(a, ctx).some((t) => t > ctx.now);
 }
 
-/** Next occurrence of a weekly reset. The weekly reset is a fixed per-account
- *  anchor, so a cached (past) resetsAt extrapolates forward in 7-day steps -
- *  an old snapshot still yields the correct upcoming reset. */
 export function nextWeeklyReset(resetsAt: number | null, now: number): number | null {
   if (resetsAt == null || resetsAt > now) return resetsAt;
   return resetsAt + (Math.floor((now - resetsAt) / WEEK_MS) + 1) * WEEK_MS;
 }
 
-/** Epoch ms when the account's weekly quota is next forfeited; an account with
- *  no sampled reset sorts last. */
 export function weeklyExpiry(a: Account, now: number): number {
   return nextWeeklyReset(a.lastUsage?.sevenDay.resetsAt ?? null, now) ?? Number.POSITIVE_INFINITY;
 }
 
-/** Soonest upcoming reset among the account's cached windows: the 5h session
- *  reset if still ahead, else the extrapolated weekly expiry; Infinity with no
- *  known reset anchor (sorts last). Display order for `status` and the
- *  statusLine pool (user decision 2026-07-18) - deliberately decoupled from
- *  swapPreference, which keeps ranking actual swaps. */
 export function earliestReset(a: Account, now: number): number {
   const fiveHour = a.lastUsage?.fiveHour.resetsAt;
   return Math.min(fiveHour != null && fiveHour > now ? fiveHour : Number.POSITIVE_INFINITY, weeklyExpiry(a, now));
 }
 
-/** How far behind its own weekly pace the account is, measured forward: the
- *  burn rate (percent per ms) its remaining weekly quota must be consumed at
- *  to beat the reset that forfeits it. A backward-looking used/expected ratio
- *  blows up right after a reset (expected ~0) and ignores how much quota is
- *  at risk; the required forward rate has neither problem. A window past its
- *  cached reset counts as empty (the account is fresh again); an account with
- *  no sampled reset anchor has nothing to forfeit on any known clock and
- *  ranks last (0). */
 export function pacePressure(a: Account, now: number): number {
   const cached = a.lastUsage?.sevenDay;
   const reset = nextWeeklyReset(cached?.resetsAt ?? null, now);
@@ -144,17 +80,9 @@ export function pacePressure(a: Account, now: number): number {
   return Math.max(0, 100 - used) / Math.max(1, reset - now);
 }
 
-/** 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. */
 const swapPreference = (now: number) => [
   (a: Account) => -pacePressure(a, now),
   (a: Account) => weeklyExpiry(a, now),
-  // 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,
 ];
 
@@ -165,11 +93,6 @@ export function pickBest(accounts: Account[], ctx: PickCtx): Account | null {
   return sortBy(usable, swapPreference(ctx.now))[0] ?? null;
 }
 
-/** Greedy idempotence, shared by bare `xx switch` and the hooks/timer path:
- *  the active account keeps its seat while it is usable and no other usable
- *  account ranks STRICTLY better on swapPreference - swapping between equals
- *  buys nothing and would ping-pong. Rank with currentAccountUuid null so the
- *  active account competes. */
 export function currentWins(active: Account | null, accounts: Account[], ctx: PickCtx): boolean {
   if (!active || active.needsReauth || isExhausted(active, ctx)) return false;
   const best = pickBest(accounts, { ...ctx, currentAccountUuid: null });
@@ -177,9 +100,6 @@ export function currentWins(active: Account | null, accounts: Account[], ctx: Pi
   return swapPreference(ctx.now).every((k) => k(active) === k(best));
 }
 
-/** When an account becomes usable again: the latest blocking bound among its
- *  windows (all must clear), or `now` if nothing blocks. Consistent with
- *  isExhausted by construction (same blockingUntil). */
 export function usableAt(a: Account, ctx: PickCtx): number {
   const blocking = blockingUntil(a, ctx).filter((t) => t > ctx.now);
   return blocking.length ? Math.max(...blocking) : ctx.now;
@@ -188,9 +108,6 @@ export function usableAt(a: Account, ctx: PickCtx): number {
 const EarliestResetSchema = z.object({ account: AccountSchema, availableAt: z.number() });
 export type EarliestReset = z.infer<typeof EarliestResetSchema>;
 
-/** For the all-depleted case: the account (not current, not reauth) that becomes
- *  usable soonest. Accounts blocked with no known reset are unknowable, never
- *  a wait target. */
 export function pickEarliestReset(accounts: Account[], ctx: PickCtx): EarliestReset | null {
   const mapped = accounts
     .filter((a) => a.accountUuid !== ctx.currentAccountUuid && !a.needsReauth)

package/src/lib/proc.ts

@@ -1,19 +1,5 @@
-// 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;
@@ -21,9 +7,6 @@ export function pidStartTime(pid: number): string | null {
   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);

package/src/lib/sample.ts

@@ -1,23 +1,3 @@
-// Live-sample a PARKED account's `/usage` without disturbing the live login.
-// `/usage` is free (0 tokens), so `status` can show every account's real usage.
-// We install the account's parked credential into a throwaway CLAUDE_CONFIG_DIR
-// (the isolated credential claude reads for that dir), run `claude -p /usage`
-// against it, then tear the item down.
-//
-// Contamination guards (the incident that motivated these):
-//   1. probeUsage scrubs every ambient credential-override env var, so an
-//      inherited CLAUDE_CODE_OAUTH_TOKEN can't hijack the isolated probe.
-//   2. before trusting a backup we verify (roles endpoint) that its token really
-//      belongs to this account - a mislabeled backup (drifted harvest) surfaces
-//      as an explicit error, never as another account's bars.
-//
-// Refresh tokens rotate single-use, so the one hazard is a rotation we fail to
-// capture. Two guards: refresh an expiring token OURSELVES up front, and
-// capture-before-delete the isolated item in case claude rotated it anyway.
-//
-// The caller MUST hold the tokenmaxxing flock so a parked refresh cannot collide
-// with an in-flight performSwap refreshing the same account.
-
 import { mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
@@ -28,9 +8,6 @@ import { refreshCredential, isAccessTokenExpiring, fetchTokenOrg, InvalidGrantEr
 import { FullUsageSchema, pingSession, probeUsage } from "./usage.ts";
 import { CredentialBlobSchema, type Account, type OAuthCreds, type RolesResponse } from "./types.ts";
 
-/** 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. */
 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() }),
@@ -44,10 +21,6 @@ const IdentityCheckSchema = z.discriminatedUnion("status", [
 ]);
 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 {
@@ -59,22 +32,11 @@ async function checkIdentity(creds: OAuthCreds, account: Account): Promise<Ident
   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
- *  after the identity check passed, so a drifted credential can never write
- *  another account's tier. Absent blob fields keep the last-known values. */
 function refreshPlanFields(account: Account, creds: OAuthCreds): void {
   if (creds.subscriptionType != null) account.subscriptionType = creds.subscriptionType;
   if (creds.rateLimitTier != null) account.rateLimitTier = creds.rateLimitTier;
 }
 
-/**
- * Live-sample `account`'s `/usage` in isolation. On a dead refresh token or a
- * mislabeled credential it sets `account.needsReauth` in place (the caller
- * persists accounts.json). Mutates only the passed object and keychain items.
- * With `ping`, one minimal metered request runs first (through the same
- * isolated credential) so the account's 5h session window starts now and the
- * sample that follows reports the freshly opened window.
- */
 export async function probeParkedUsage(account: Account, opts: { ping?: boolean } = {}): Promise<SampleOutcome> {
   const backup = parkedTarget(account.keychainItem);
   const parkedRaw = await readItem(backup);
@@ -87,16 +49,6 @@ export async function probeParkedUsage(account: Account, opts: { ping?: boolean
     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;
@@ -111,9 +63,6 @@ export async function probeParkedUsage(account: Account, opts: { ping?: boolean
     }
   }
 
-  // Hand claude a token with comfortable headroom so it won't run its own refresh
-  // (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);
@@ -154,7 +103,6 @@ export async function probeParkedUsage(account: Account, opts: { ping?: boolean
     if (pingError != null) outcome.pingError = pingError;
     return outcome;
   } finally {
-    // capture-before-delete: never discard a rotation claude may have performed.
     const afterIso = await readItem(isoTarget);
     if (afterIso && afterIso !== installed) await writeItem(backup, claudeAiOauthOnly(afterIso));
     await deleteItem(isoTarget);
@@ -162,14 +110,6 @@ 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;
@@ -191,15 +131,7 @@ export async function ensureLiveTokenFresh(): Promise<void> {
   });
 }
 
-/**
- * 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
- * keychain item. A drifted active label surfaces as an error, not another
- * account's bars. With `ping`, one minimal metered request runs first (after
- * 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) {

package/src/lib/sessions.ts

@@ -1,8 +1,3 @@
-// Persist the flags a managed session was launched with, so any later relaunch
-// of that session id (a fresh supervisor invocation, or the depleted-pool
-// recovery in #20) re-applies them instead of dropping --dangerously-skip-
-// permissions / --model / etc.
-
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
@@ -11,10 +6,6 @@ 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 {
@@ -32,8 +23,6 @@ export function loadSessionFlags(sid: string): string[] | 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;
@@ -42,8 +31,6 @@ export function pruneStaleSessions(now: number): void {
     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.
     }
   }
 }