@modelprofile.com/authswitch 3.2.0 → 4.0.0

package/ts/classes.cli.ts

@@ -5,25 +5,42 @@ import { OpenCodeHarness } from './classes.opencodeharness.js';
 import { ClaudeCodeHarness } from './classes.claudecodeharness.js';
 import { AuthSwitchTui } from './classes.tui.js';
 import { AglAuthSwitchCoordinator, AuthSwitchOperations, type TAuthSwitchCoordinator, type TAuthSwitchMutation } from './classes.operations.js';
-import { AccountListRenderer, readAccountList } from './classes.accountlist.js';
+import { readAccountList } from './classes.accountlist.js';
+import { AccountListRenderer } from './classes.listrenderer.js';
 import { accountLimits, activeAccounts, CondensedRenderer } from './classes.limits.js';
-import { credentialDriftNote, duration, orderedUsageWindows, until } from './accounts.js';
+import { consoleTable } from './consoletable.js';
+import { accountName, credentialDriftNote, duration, orderedUsageWindows, readAccountBadges, until, usagePercentText } from './accounts.js';
 import { describeHarnessProcesses, describeStopOutcome } from './classes.harnessprocesses.js';
 import { defaultPreusePrompt, PreuseError, validatePreuseOptions } from './preuse.js';
+import { parseCommandArgs, parseDurationOption, parseIntegerOption, UsageError } from './cliargs.js';
+import { AuthSwitchWatch, watchEventText } from './classes.watch.js';
+import { WatchBusyError, WatchLock } from './classes.watchlock.js';
+import { authSwitchHome } from './classes.credentialstore.js';
 import type { CodexSwitcher } from './classes.codexswitcher.js';
 import type { IAuthHarness, IHarnessAccount, IHarnessOutcome, IHarnessProcess, IHarnessState, IHarnessStopOutcome, IHarnessPreuseResult } from './interfaces.harness.js';
 import { bold, dim, green, orange, plainText, red } from './formatting.js';
 
 const canPrompt = (): boolean =>
   process.stdin.isTTY === true && process.stdout.isTTY === true && !process.env.CI;
-const COMMANDS = ['login', 'stash', 'list', 'ls', 'limits', 'active', 'use', 'preuse', 'current', 'drop', 'rm', 'doctor'];
+const COMMANDS = ['login', 'stash', 'list', 'ls', 'limits', 'active', 'use', 'preuse', 'watch', 'current', 'drop', 'rm', 'doctor'];
 /** What to do about the harness's own running instances before a credential file is rewritten. */
 export type TStopMode = 'stop' | 'force-stop' | 'keep-running';
 const STOP_FLAGS = ['--stop', '--force-stop', '--keep-running'];
 /** Commands that replace or clear a native login, and therefore offer to stop its instances. */
 const STOP_COMMANDS = ['use', 'stash'];
-/** Read-only overviews that work across every registered harness and support --json. */
+/** Overviews across every registered harness; none of them changes which account is in use, and all support --json. */
 const OVERVIEW_COMMANDS = ['list', 'ls', 'limits', 'active'];
+const WATCH_USAGE = 'Usage: authswitch [harness] watch [harness] [--interval <duration>] [--threshold <percent>] [--dry-run] [--once] [--json]';
+const WATCH_INTERVAL = { defaultMs: 120_000, minMs: 60_000, maxMs: 86_400_000 };
+const WATCH_THRESHOLD = { default: 95, min: 50, max: 100 };
+
+/** The account a command acts on, named as it was offered, with the badge it was offered with. */
+interface IChosenAccount {
+  id: string;
+  name: string;
+  /** ` (type:Max) (5h:63%) (w:88%)`, empty when no part is known, or null when it was not read. */
+  badge: string | null;
+}
 
 /** Harness-independent command routing and interactive account management. */
 export class AuthSwitchCli {
@@ -61,6 +78,9 @@ ${bold('Usage')}
   authswitch active                  one row per provider: which account is in use, and since when
   authswitch <harness> preuse <account> [--prompt <text>] [--model <id>]
                                     send one prompt through that account without switching
+  authswitch watch [harness] [--interval <duration>] [--threshold <percent>] [--dry-run] [--once] [--json]
+                                    check usage every 2m and switch to a better saved account
+                                    when the active one reaches the threshold (95%)
   authswitch <harness> stash [account/provider] [--keep]
                                     save one active login; --keep leaves it active
   authswitch <harness> use [account] [--stop|--force-stop|--keep-running]
@@ -80,14 +100,24 @@ ${bold('Options')}
   -v, --version                      show the version
   -i, --interactive                  open the guided account manager
   --tui                             open the terminal management dashboard
-  --json                            JSON output for list / ls / limits / active only
+  --json                            JSON output for list / ls / limits / active; one JSON event per line for
+                                    watch, written after the command (authswitch watch --json)
   --stop                            stop this harness's running instances before the switch
   --force-stop                      the same, then kill instances that ignore SIGTERM
   --keep-running                    switch without stopping anything
 
-A switch works while OpenCode or Claude Code is running. Instances that keep running hold
-the previous login in memory and can write it back at their next token refresh, so the
-switch offers to stop them first; without a terminal it leaves them running and says so.
+A switch works while OpenCode or Claude Code is running. Claude Code picks the new login
+up on its next request, so its sessions are stopped only on --stop or --force-stop.
+OpenCode keeps the previous login in memory and can write it back at its next token
+refresh, so an OpenCode switch offers to stop it first; without a terminal it leaves
+it running and says so.
+
+Watch covers the harnesses that support automatic switching (${[...this.harnesses.values()].filter(harness => harness.autoSwitch === true).map(harness => harness.id).join(', ') || 'none registered'}).
+--interval takes seconds or a unit (120, 90s, 2m; from 1m to 1d); --threshold takes 50 to 100.
+A switch goes to a saved account at least 10 points below the threshold, or, when every
+account is used up, to the one usable again first. No session of yours is stopped, though
+a Codex switch restarts Codex' own app-server; --dry-run only reports, --once checks once.
+One watch runs per AUTHSWITCH_HOME.
 
 Preuse consumes the selected account's quota. Its default prompt is:
   "${defaultPreusePrompt}"
@@ -109,6 +139,11 @@ ${bold('Environment')}
         const qualified = args[0] !== 'preuse';
         return await this.commandPreuse(qualified ? this.harnesses.get(args[0]) : undefined, args.slice(qualified ? 2 : 1));
       }
+      // Watch owns its options, --json among them.
+      if (args[0] === 'watch' || (this.harnesses.has(args[0]) && args[1] === 'watch')) {
+        const qualified = args[0] !== 'watch';
+        return await this.commandWatch(qualified ? this.harnesses.get(args[0]) : undefined, args.slice(qualified ? 2 : 1));
+      }
       const jsonFlags = args.filter(value => value === '--json');
       const json = jsonFlags.length === 1;
       if (jsonFlags.length > 1) { process.stderr.write('Use --json only once.\n'); return 2; }
@@ -222,14 +257,17 @@ ${bold('Environment')}
    * Decide what happens to the harness's own running instances before its credential file changes.
    *
    * The switch itself no longer depends on this: it writes atomically and re-saves the outgoing
-   * login either way. What a running instance still costs is durability -- it holds the previous
-   * login in memory and can write it back at its next refresh -- so the instances are named and
-   * stopping them is offered, never assumed. Without a terminal and without a flag nothing is
-   * signalled, and only pids enumerated here for this user are ever signalled at all.
+   * login either way. A harness that picks up swaps live needs nothing here, so its instances are
+   * only stopped on an explicit --stop or --force-stop. Any other running instance still costs
+   * durability -- it holds the previous login in memory and can write it back at its next refresh --
+   * so the instances are named and stopping them is offered, never assumed. Without a terminal and
+   * without a flag nothing is signalled, and only pids enumerated here for this user are ever
+   * signalled at all.
    */
   private async settleRunningInstances(harnessArg: IAuthHarness, modeArg?: TStopMode): Promise<void> {
     const control = harnessArg.processes;
-    if (!control) return;
+    const stopRequested = modeArg === 'stop' || modeArg === 'force-stop';
+    if (!control || (harnessArg.liveSwap === true && !stopRequested)) return;
     let running: IHarnessProcess[];
     try { running = control.list(); }
     catch { process.stdout.write(`${orange(`Could not check for running ${plainText(harnessArg.label)} processes; continuing with the switch.`)}\n`); return; }
@@ -238,7 +276,7 @@ ${bold('Environment')}
     if (control.stopUnavailableReason !== null) { process.stdout.write(`${dim(control.stopUnavailableReason)}\n`); return; }
     const stoppable = running.filter(item => !item.isAncestor);
     if (!stoppable.length || modeArg === 'keep-running') return;
-    let stop = modeArg === 'stop' || modeArg === 'force-stop';
+    let stop = stopRequested;
     if (modeArg === undefined) {
       if (!canPrompt()) { process.stdout.write(`${dim('Leaving them running. Use --stop, --force-stop or --keep-running to decide this without a terminal.')}\n`); return; }
       stop = await this.out.prompts.ask({
@@ -286,28 +324,18 @@ ${bold('Environment')}
 
   private async commandPreuse(harnessArg: IAuthHarness | undefined, argsArg: string[]): Promise<number> {
     let reference: string | undefined;
-    let prompt = defaultPreusePrompt;
+    let prompt: string;
     let model: string | undefined;
-    const flags = new Set<string>();
     try {
-      for (let index = 0; index < argsArg.length; index++) {
-        const argument = argsArg[index];
-        if (argument.startsWith('--prompt=') || argument.startsWith('--model=') || argument === '--prompt' || argument === '--model') {
-          const separator = argument.indexOf('=');
-          const flag = separator < 0 ? argument : argument.slice(0, separator);
-          if (flags.has(flag)) throw new PreuseError(`Use ${flag} only once.`);
-          flags.add(flag);
-          const value = separator < 0 ? argsArg[++index] : argument.slice(separator + 1);
-          if (value === undefined) throw new PreuseError(`${flag} requires a value.`);
-          if (flag === '--prompt') prompt = value; else model = value;
-        } else if (argument.startsWith('-') || reference !== undefined) {
-          throw new PreuseError('Usage: authswitch [harness] preuse <account> [--prompt <text>] [--model <id>]');
-        } else reference = argument;
-      }
+      const parsed = parseCommandArgs(argsArg, { values: ['--prompt', '--model'], flags: [], maxPositionals: 1,
+        usage: 'Usage: authswitch [harness] preuse <account> [--prompt <text>] [--model <id>]' });
+      [reference] = parsed.positionals;
+      prompt = parsed.values.get('--prompt') ?? defaultPreusePrompt;
+      model = parsed.values.get('--model');
       validatePreuseOptions({ prompt, model });
-      if (!reference && !canPrompt()) throw new PreuseError('preuse requires an account outside an interactive terminal.');
+      if (!reference && !canPrompt()) throw new UsageError('preuse requires an account outside an interactive terminal.');
     } catch (error) {
-      process.stderr.write(`${error instanceof PreuseError ? error.message : 'Invalid preuse arguments.'}\n`);
+      process.stderr.write(`${error instanceof UsageError || error instanceof PreuseError ? error.message : 'Invalid preuse arguments.'}\n`);
       return 2;
     }
     const harness = harnessArg ?? await this.selectHarness();
@@ -354,13 +382,11 @@ ${bold('Environment')}
         if (windows?.length) {
           const now = Date.now();
           process.stdout.write('Reset schedule reported after the prompt:\n');
-          if ((process.stdout.columns ?? 100) < 40) {
-            for (const window of windows) process.stdout.write(`${plainText(window.label)} (${duration(window.durationSeconds)})\n  Used: ${window.usedPercent}%\n  Reset in: ${until(window.resetAt, now)}\n`);
-          } else await this.out.table(windows, { columns: [
+          await consoleTable(this.out, windows, [
             { key: 'window', title: 'Window', value: row => `${plainText(row.label)} (${duration(row.durationSeconds)})` },
-            { key: 'usage', title: 'Used', value: row => `${row.usedPercent}%` },
+            { key: 'usage', title: 'Used', value: row => usagePercentText(row.usedPercent) },
             { key: 'reset', title: 'Reset in', value: row => until(row.resetAt, now) },
-          ], overflow: 'wrap' });
+          ]);
         } else process.stdout.write('Reset schedule could not be verified; the completed prompt will not be repeated.\n');
       } catch {
         process.stderr.write('Prompt completed, but its reset schedule could not be verified or displayed. The prompt will not be repeated.\n');
@@ -372,6 +398,57 @@ ${bold('Environment')}
     }
   }
 
+  /**
+   * Watch usage and switch automatically; see `AuthSwitchWatch`. SIGINT and SIGTERM end it cleanly with status 0.
+   * `--once` runs one check and exits 1 when a switch it attempted did not complete.
+   */
+  private async commandWatch(harnessArg: IAuthHarness | undefined, argsArg: string[]): Promise<number> {
+    let options: { harnesses: IAuthHarness[]; intervalMs: number; threshold: number; dryRun: boolean; once: boolean; json: boolean };
+    try {
+      const parsed = parseCommandArgs(argsArg, { values: ['--interval', '--threshold'], flags: ['--dry-run', '--once', '--json', '--help', '-h'],
+        maxPositionals: harnessArg ? 0 : 1, usage: WATCH_USAGE });
+      if (parsed.flags.has('--help') || parsed.flags.has('-h')) { process.stdout.write(`${this.usage()}\n`); return 0; }
+      const named = parsed.positionals[0];
+      const harness = harnessArg ?? (named === undefined ? undefined : this.harnesses.get(named));
+      if (named !== undefined && !harness) throw new UsageError(`Unknown harness "${plainText(named)}". ${WATCH_USAGE}`);
+      if (harness && harness.autoSwitch !== true) throw new UsageError(`${plainText(harness.label)} does not support automatic switching.`);
+      const harnesses = (harness ? [harness] : [...this.harnesses.values()].filter(item => item.autoSwitch === true))
+        .sort((left, right) => left.label.localeCompare(right.label) || left.id.localeCompare(right.id));
+      if (!harnesses.length) throw new UsageError('No registered harness supports automatic switching.');
+      const interval = parsed.values.get('--interval');
+      const threshold = parsed.values.get('--threshold');
+      options = {
+        harnesses, dryRun: parsed.flags.has('--dry-run'), once: parsed.flags.has('--once'), json: parsed.flags.has('--json'),
+        intervalMs: interval === undefined ? WATCH_INTERVAL.defaultMs : parseDurationOption('--interval', interval, WATCH_INTERVAL),
+        threshold: threshold === undefined ? WATCH_THRESHOLD.default : parseIntegerOption('--threshold', threshold, WATCH_THRESHOLD),
+      };
+    } catch (error) {
+      if (!(error instanceof UsageError)) throw error;
+      process.stderr.write(`${error.message}\n`);
+      return 2;
+    }
+    const watch = new AuthSwitchWatch({
+      harnesses: options.harnesses, operations: this.operations, lock: new WatchLock(authSwitchHome()),
+      intervalMs: options.intervalMs, threshold: options.threshold, dryRun: options.dryRun,
+      onEvent: event => { process.stdout.write(`${options.json ? JSON.stringify(event) : watchEventText(event)}\n`); },
+    });
+    const controller = new AbortController();
+    const stop = () => controller.abort();
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+    try {
+      const completed = await watch.run(controller.signal, { once: options.once });
+      return options.once && !completed ? 1 : 0;
+    } catch (error) {
+      if (!(error instanceof WatchBusyError)) throw error;
+      process.stderr.write(`${error.message}\n`);
+      return 1;
+    } finally {
+      process.removeListener('SIGINT', stop);
+      process.removeListener('SIGTERM', stop);
+    }
+  }
+
   private async selectHarness(): Promise<IAuthHarness | undefined> {
     if (this.harnesses.size === 1) return this.harnesses.values().next().value;
     if (this.harnesses.size === 0 || !canPrompt()) {
@@ -406,7 +483,7 @@ ${bold('Environment')}
     for (const current of state.accounts.filter(account => account.isActive && !account.isStashed)) {
       const answer = await this.out.prompts.ask({
         name: 'saveCurrent', type: 'confirm',
-        message: `${plainText(current.label)}${current.slotId ? ` (${plainText(current.slotId)})` : ''} is not saved in ${harnessArg.label}. Save this login before switching?`, default: true,
+        message: `${accountName(current)} is not saved in ${harnessArg.label}. Save this login before switching?`, default: true,
       });
       if (answer !== true) return 'declined';
       if (this.reportOutcome(await this.mutate(harnessArg, { harnessId: harnessArg.id, action: 'save', keepActive: true, accountId: current.id })) !== 0) return 'failed';
@@ -457,12 +534,12 @@ ${bold('Environment')}
         case 'list': code = await this.commandList([harnessArg]); break;
         case 'doctor': code = this.reportOutcome(await harnessArg.diagnose()); break;
         case 'drop': {
-          const id = await this.promptForAccount(harnessArg, `Which saved ${harnessArg.label} account should be removed?`, true, true);
-          if (!id) break;
+          const target = await this.promptForAccount(harnessArg, `Which saved ${harnessArg.label} account should be removed?`, { allowBack: true, includeIncomplete: true });
+          if (!target) break;
           const confirmation = await this.out.prompts.ask({
-            name: 'confirmDrop', type: 'confirm', message: `Remove the saved login for ${plainText(id)}? The active login stays as it is.`, default: false,
+            name: 'confirmDrop', type: 'confirm', message: `Remove the saved login for ${plainText(target.id)}? The active login stays as it is.`, default: false,
           });
-          if (confirmation === true) code = this.reportOutcome(await harnessArg.removeAccount(id));
+          if (confirmation === true) code = this.reportOutcome(await harnessArg.removeAccount(target.id));
           break;
         }
         case 'harness': return null;
@@ -482,7 +559,7 @@ ${bold('Environment')}
       process.stdout.write(`${dim('no account is currently active')}\n`);
     }
     if (stateArg.saveUnavailableReason) process.stdout.write(`${dim(stateArg.saveUnavailableReason)}\n`);
-    for (const drift of stateArg.credentialDrift ?? []) process.stdout.write(`${orange(credentialDriftNote(harnessArg.id, drift))}\n`);
+    for (const drift of stateArg.credentialDrift ?? []) process.stdout.write(`${orange(credentialDriftNote(harnessArg, drift))}\n`);
   }
 
   private async selectActive(harness: IAuthHarness, reference?: string): Promise<IHarnessAccount | undefined> {
@@ -492,7 +569,7 @@ ${bold('Environment')}
     if (accounts.length === 1) return accounts[0];
     if (!accounts.length) { process.stderr.write('No matching active login to save.\n'); return undefined; }
     if (!canPrompt()) { process.stderr.write(`Several logins are active. Use authswitch ${harness.id} stash <account/provider> [--keep].\n`); return undefined; }
-    const id = await this.out.prompts.ask({ name: 'activeAccount', type: 'list', message: 'Which active login should be saved?', choices: accounts.map(account => ({ name: `${plainText(account.label)}${account.slotId ? ` (${plainText(account.slotId)})` : ''}`, value: account.id })) });
+    const id = await this.out.prompts.ask({ name: 'activeAccount', type: 'list', message: 'Which active login should be saved?', choices: accounts.map(account => ({ name: accountName(account), value: account.id })) });
     return accounts.find(account => account.id === id);
   }
 
@@ -503,12 +580,13 @@ ${bold('Environment')}
   }
 
   /**
-   * The condensed views are projections of the same read-only account list, so a provider is queried
-   * once, per account, with the same bounded timeouts and per-account failure isolation as `list`.
+   * The condensed views are projections of the same account list, which never changes which account is in
+   * use, so a provider is queried once, per account, with the same bounded timeouts and per-account failure
+   * isolation as `list`.
    */
   private async commandCondensed(commandArg: 'limits' | 'active', harnessesArg: IAuthHarness[], jsonArg: boolean): Promise<number> {
     const list = await readAccountList(harnessesArg);
-    const document = commandArg === 'limits' ? accountLimits(list) : activeAccounts(list);
+    const document = commandArg === 'limits' ? accountLimits(list, harnessesArg) : activeAccounts(list, harnessesArg);
     if (jsonArg) process.stdout.write(`${JSON.stringify(document, null, 2)}\n`);
     else if ('limits' in document) await new CondensedRenderer(this.out).renderLimits(document);
     else await new CondensedRenderer(this.out).renderActive(document);
@@ -518,17 +596,10 @@ ${bold('Environment')}
   private async commandList(harnessesArg: IAuthHarness[], jsonArg = false): Promise<number> {
     const list = await readAccountList(harnessesArg);
     if (jsonArg) process.stdout.write(`${JSON.stringify(list, null, 2)}\n`);
-    else await new AccountListRenderer(this.out).render(list);
+    else await new AccountListRenderer(this.out).render(list, harnessesArg);
     return list.complete ? 0 : 1;
   }
 
-  private printAccount(accountArg: IHarnessAccount): void {
-    const saved = accountArg.isStashed ? 'saved' : 'not saved';
-    process.stdout.write(`${accountArg.isActive ? green('*') : ' '} ${bold(plainText(accountArg.label))} ${dim(`(${saved})`)}\n`);
-    if (accountArg.savedAt) process.stdout.write(`  ${dim('Saved: ' + plainText(accountArg.savedAt))}\n`);
-    for (const detail of accountArg.details) process.stdout.write(`  ${detail}\n`);
-  }
-
   private async resolveAccount(harnessArg: IAuthHarness, referenceArg: string): Promise<string | null> {
     const resolved = await harnessArg.resolveAccount(referenceArg);
     if ('id' in resolved) return resolved.id;
@@ -538,6 +609,14 @@ ${bold('Environment')}
     return null;
   }
 
+  /**
+   * Activate a saved account and report what is now active with its badge.
+   *
+   * The badge is read once per command through the bounded status read: the chooser reads it before it
+   * offers the accounts and the report repeats it, while a target named on the command line is read only
+   * after its switch, so nothing waits on it. A read that fails or does not answer in time leaves the name
+   * alone and never decides the outcome.
+   */
   private async commandUse(harnessArg: IAuthHarness, referenceArg?: string, allowBackArg = false, stopModeArg?: TStopMode): Promise<number> {
     let id: string | null = null;
     if (referenceArg) {
@@ -548,21 +627,42 @@ ${bold('Environment')}
       const offered = await this.offerToSave(harnessArg);
       if (offered !== 'ready') return offered === 'failed' ? 1 : 0;
     }
-    id ??= await this.promptForAccount(harnessArg, `Which ${harnessArg.label} account should be active?`, allowBackArg);
-    if (id === null) return allowBackArg ? 0 : 1;
-    return this.reportOutcome(await this.mutate(harnessArg, { harnessId: harnessArg.id, action: 'switch', accountId: id }, stopModeArg));
+    const target = id === null
+      ? await this.promptForAccount(harnessArg, `Which ${harnessArg.label} account should be active?`, { allowBack: allowBackArg, withBadges: true })
+      : await this.namedAccount(harnessArg, id);
+    if (target === null) return allowBackArg ? 0 : 1;
+    const code = this.reportOutcome(await this.mutate(harnessArg, { harnessId: harnessArg.id, action: 'switch', accountId: target.id }, stopModeArg));
+    if (code !== 0) return code;
+    const badge = target.badge ?? (await readAccountBadges(harnessArg, [target.id])).get(target.id) ?? '';
+    process.stdout.write(`Now active: ${bold(target.name)}${badge}\n`);
+    return code;
+  }
+
+  /**
+   * A switch target named on the command line; its badge is not read here, so the switch never waits on it.
+   *
+   * The reference already resolved to this id, so the name is presentation only: a state read that fails
+   * names the account by its id and leaves the switch, which reports any real credential problem, to run.
+   */
+  private async namedAccount(harnessArg: IAuthHarness, idArg: string): Promise<IChosenAccount> {
+    let account: IHarnessAccount | undefined;
+    try { account = (await harnessArg.readState()).accounts.find(item => item.id === idArg); }
+    catch { account = undefined; }
+    return { id: idArg, name: account ? accountName(account) : plainText(idArg), badge: null };
   }
 
-  private async promptForAccount(harnessArg: IAuthHarness, messageArg: string, allowBackArg: boolean, includeIncompleteArg = false): Promise<string | null> {
-    const accounts = (await harnessArg.readState()).accounts.filter((accountArg) => accountArg.isStashed || (includeIncompleteArg && accountArg.savedAt !== null));
+  private async promptForAccount(harnessArg: IAuthHarness, messageArg: string, optionsArg: { allowBack?: boolean; includeIncomplete?: boolean; withBadges?: boolean } = {}): Promise<IChosenAccount | null> {
+    const accounts = (await harnessArg.readState()).accounts.filter((accountArg) => accountArg.isStashed || (optionsArg.includeIncomplete === true && accountArg.savedAt !== null));
     if (accounts.length === 0) { process.stderr.write(`${red('no stashed accounts')} - run \`authswitch ${harnessArg.id} stash\` first\n`); return null; }
     if (!canPrompt()) { process.stderr.write(`${red('an account is required')} without an interactive terminal: authswitch ${harnessArg.id} use <account>\n`); return null; }
+    const badges = optionsArg.withBadges ? await readAccountBadges(harnessArg, accounts.map((accountArg) => accountArg.id)) : null;
+    const offered = accounts.map((accountArg): IChosenAccount => ({ id: accountArg.id, name: accountName(accountArg), badge: badges === null ? null : badges.get(accountArg.id) ?? '' }));
     const answer = await this.out.prompts.ask({
       name: 'account', type: 'list', message: messageArg,
       default: accounts.find((accountArg) => accountArg.isActive)?.id ?? accounts[0].id,
-      choices: [...accounts.map((accountArg) => ({ name: `${plainText(accountArg.label)}${accountArg.slotId ? ` (${plainText(accountArg.slotId)})` : ''}${accountArg.isActive ? ' (active)' : ''}`, value: accountArg.id })),
-        ...(allowBackArg ? [{ name: 'Back', value: null }] : [])],
+      choices: [...accounts.map((accountArg, index) => ({ name: `${offered[index].name}${accountArg.isActive ? ' (active)' : ''}${offered[index].badge ?? ''}`, value: accountArg.id })),
+        ...(optionsArg.allowBack ? [{ name: 'Back', value: null }] : [])],
     });
-    return typeof answer === 'string' ? answer : null;
+    return offered.find((accountArg) => accountArg.id === answer) ?? null;
   }
 }

package/ts/classes.codexharness.ts

@@ -2,7 +2,7 @@ import { CodexSwitcher } from './classes.codexswitcher.js';
 import { CodexAccountStatus } from './classes.codexstatus.js';
 import { CodexPreuse } from './classes.codexpreuse.js';
 import { PreuseError } from './preuse.js';
-import type { IAuthHarness, IHarnessAccount, IHarnessAccountStatus, IHarnessOutcome, IHarnessState, IHarnessPreuseOptions, IHarnessPreuseResult } from './interfaces.harness.js';
+import type { IAuthHarness, IHarnessAccount, IHarnessAccountStatus, IHarnessOutcome, IHarnessState, IHarnessPreuseOptions, IHarnessPreuseResult, IHarnessStatusOptions } from './interfaces.harness.js';
 import type { IStashListing } from './interfaces.js';
 import { countPaired, enrollmentState } from './helpers.js';
 import { beginSavedOpenAiLogin } from './classes.login.js';
@@ -16,6 +16,10 @@ export class CodexHarness implements IAuthHarness {
   public readonly loginHint = 'Use authswitch codex login to sign in and save another account.';
   public readonly loginProviders: IHarnessLoginProvider[] = [{ providerId: 'openai', label: 'OpenAI', flows: ['device'] }];
   public readonly diagnosticsLabel = 'Check credential storage and remote control';
+  /** Running Codex sessions keep the login they loaded; the switch itself restarts the managed app-server. */
+  public readonly liveSwap = false;
+  /** Every saved ChatGPT login reports its usage, and a switch restarts only the managed app-server. */
+  public readonly autoSwitch = true;
 
   constructor(
     private readonly switcher = new CodexSwitcher(),
@@ -70,10 +74,10 @@ export class CodexHarness implements IAuthHarness {
     };
   }
 
-  public async readAccountStatus(accountIdArg: string): Promise<IHarnessAccountStatus> {
+  public async readAccountStatus(accountIdArg: string, optionsArg?: IHarnessStatusOptions): Promise<IHarnessAccountStatus> {
     const credential = this.readAccountCredential(accountIdArg);
     if (!credential) return { facts: [], problems: ['No matching credential is available for status lookup.'] };
-    return this.accountStatus.read(credential.raw, credential.identity);
+    return this.accountStatus.read(credential.raw, credential.identity, optionsArg);
   }
 
   public async preuseAccount(accountIdArg: string, optionsArg: IHarnessPreuseOptions): Promise<IHarnessPreuseResult> {

package/ts/classes.codexstatus.ts

@@ -1,6 +1,7 @@
 import type { ICodexIdentity } from './interfaces.js';
-import type { IHarnessAccountStatus, IHarnessStatusSummary } from './interfaces.harness.js';
+import type { IHarnessAccountStatus, IHarnessStatusOptions, IHarnessStatusSummary } from './interfaces.harness.js';
 import { commitinfo } from './00_commitinfo_data.js';
+import { latestRetryAt, retryAtFrom } from './ratelimit.js';
 
 // Verified Chromium-compatible billing request profile, independent of any locally installed browser.
 const billingUserAgent = 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36';
@@ -31,15 +32,20 @@ const count = (valueArg: unknown): number => {
 /** Only fixed, local diagnostics may cross the HTTP error boundary. */
 class StatusRequestError extends Error {}
 
+/** The service refused a section for too many requests; that says nothing about the account's usage. */
+class StatusRateLimitError extends StatusRequestError {
+  constructor(public readonly retryAt: string | null) { super('The service is rate limiting requests (HTTP 429); try again later.'); }
+}
+
 /**
  * Read-only ChatGPT status contract verified against Codex 0.154.0.
  * These source-defined backend routes are isolated here. No token refresh,
  * credential writes, app-server lifecycle changes or reset consumption occur.
  */
 export class CodexAccountStatus {
-  constructor(private readonly fetcher: typeof fetch = globalThis.fetch) {}
+  constructor(private readonly fetcher: typeof fetch = globalThis.fetch, private readonly now: () => number = Date.now) {}
 
-  public async read(rawArg: string, identityArg: ICodexIdentity): Promise<IHarnessAccountStatus> {
+  public async read(rawArg: string, identityArg: ICodexIdentity, optionsArg: IHarnessStatusOptions = {}): Promise<IHarnessAccountStatus> {
     if (identityArg.kind !== 'chatgpt') return {
       facts: [{ label: 'Authentication', value: 'API key' }, { label: 'Subscription and usage', value: 'Not exposed by Codex for API-key logins' }], problems: [],
     };
@@ -47,18 +53,18 @@ export class CodexAccountStatus {
     try { accessToken = text(record(record(JSON.parse(rawArg)).tokens).access_token); }
     catch { return { facts: [], problems: ['The login has no usable access token. Log in again with Codex, then save the account.'] }; }
     if (!identityArg.accountId) return { facts: [], problems: ['The login has no account ID for a status lookup.'] };
-    return this.readCredential(accessToken, identityArg.accountId, identityArg.planType);
+    return this.readCredential(accessToken, identityArg.accountId, identityArg.planType, optionsArg);
   }
 
   /** Read the ChatGPT account directly, independent of a harness's on-disk format. */
-  public async readCredential(accessToken: string, accountId: string, planType?: string | null): Promise<IHarnessAccountStatus> {
+  public async readCredential(accessToken: string, accountId: string, planType?: string | null, optionsArg: IHarnessStatusOptions = {}): Promise<IHarnessAccountStatus> {
     const result: IHarnessAccountStatus = { facts: [], problems: [] };
     const identityArg = { accountId, planType };
     const sections = await Promise.allSettled([
-      this.get('wham/usage', accessToken, identityArg.accountId),
-      this.get('wham/rate-limit-reset-credits', accessToken, identityArg.accountId),
-      this.get('wham/profiles/me', accessToken, identityArg.accountId),
-      this.get('accounts/check/v4-2023-04-27', accessToken, identityArg.accountId),
+      this.get('wham/usage', accessToken, identityArg.accountId, optionsArg.signal),
+      this.get('wham/rate-limit-reset-credits', accessToken, identityArg.accountId, optionsArg.signal),
+      this.get('wham/profiles/me', accessToken, identityArg.accountId, optionsArg.signal),
+      this.get('accounts/check/v4-2023-04-27', accessToken, identityArg.accountId, optionsArg.signal),
     ]);
     const usage = sections[0];
     if (usage.status === 'fulfilled' && usage.value.account_id != null && usage.value.account_id !== identityArg.accountId) {
@@ -85,6 +91,8 @@ export class CodexAccountStatus {
       }
       catch { result.problems.push(`${labels[index]}: the service returned an unsupported response; no values were inferred.`); }
     }
+    const limited = sections.flatMap(section => section.status === 'rejected' && section.reason instanceof StatusRateLimitError ? [section.reason] : []);
+    if (limited.length) result.rateLimit = { retryAt: latestRetryAt(limited.map(error => error.retryAt)) };
     if (!result.summary?.subscription && identityArg.planType) {
       result.facts.unshift({ section: 'Subscription', summaryKey: 'subscription', label: 'Last known plan', value: `${identityArg.planType} (from stored login; not verified live)` });
       result.summary = { ...result.summary, subscription: { plan: identityArg.planType, source: 'stored' } };
@@ -92,8 +100,9 @@ export class CodexAccountStatus {
     return result;
   }
 
-  private async get(pathArg: string, tokenArg: string, accountIdArg: string): Promise<Record<string, unknown>> {
-    const signal = AbortSignal.timeout(10_000);
+  private async get(pathArg: string, tokenArg: string, accountIdArg: string, cancelArg?: AbortSignal): Promise<Record<string, unknown>> {
+    const timeout = AbortSignal.timeout(10_000);
+    const signal = cancelArg ? AbortSignal.any([cancelArg, timeout]) : timeout;
     try {
       const response = await this.fetcher(`https://chatgpt.com/backend-api/${pathArg}`, {
         method: 'GET', redirect: 'error', signal,
@@ -104,6 +113,7 @@ export class CodexAccountStatus {
       if (!response.ok) {
         await response.body?.cancel();
         if (response.headers.get('cf-mitigated') === 'challenge') throw new StatusRequestError('Blocked by a service verification challenge (Cloudflare); this lookup is unavailable to the current HTTP client.');
+        if (response.status === 429) throw new StatusRateLimitError(retryAtFrom(response.headers.get('retry-after'), this.now()));
         if (response.status === 401) throw new StatusRequestError('Login expired or was rejected. Log in again with the account’s harness, then save the account.');
         if (response.status === 403) throw new StatusRequestError('Access denied by the service (HTTP 403).');
         throw new StatusRequestError(`Service returned HTTP ${response.status}.`);
@@ -125,7 +135,7 @@ export class CodexAccountStatus {
       catch { throw new StatusRequestError('The service returned invalid status data.'); }
     } catch (errorArg) {
       // Never surface remote bodies, request headers, token strings or arbitrary fetch errors.
-      if (signal.aborted) throw new Error('The status request timed out.');
+      if (signal.aborted) throw new Error(timeout.aborted ? 'The status request timed out.' : 'The status request was cancelled.');
       if (errorArg instanceof StatusRequestError) throw errorArg;
       throw new Error('The status service could not be reached.');
     }
@@ -156,9 +166,9 @@ export class CodexAccountStatus {
     const append = (label: string, value: string) => facts.push({ section: 'Billing', summaryKey: 'billing', label, value });
     if (billing.hasActiveSubscription !== undefined) append('Active subscription', billing.hasActiveSubscription ? 'yes' : 'no');
     if (billing.autoRenew !== undefined) append('Automatic renewal', billing.autoRenew ? 'on' : 'off');
-    if (billing.renewsAt) append('Renewal date (UTC)', billing.renewsAt);
-    if (billing.cancelsAt) append('Cancellation date (UTC)', billing.cancelsAt);
-    if (billing.expiresAt) append('Subscription expiry (UTC)', billing.expiresAt);
+    if (billing.renewsAt) append('Renewal date', billing.renewsAt);
+    if (billing.cancelsAt) append('Cancellation date', billing.cancelsAt);
+    if (billing.expiresAt) append('Subscription expiry', billing.expiresAt);
     return { facts, summary: { billing } };
   }
 
@@ -171,8 +181,9 @@ export class CodexAccountStatus {
     const appendLimit = (nameArg: string, valueArg: unknown, scopeArg: 'account' | 'feature') => {
       if (valueArg == null) return;
       const limit = record(valueArg);
-      facts.push({ section: 'Limits & credits', label: `${nameArg} usage allowed`, value: boolean(limit.allowed) ? 'yes' : 'no' });
-      facts.push({ section: 'Limits & credits', label: `${nameArg} limit reached`, value: boolean(limit.limit_reached) ? 'yes' : 'no' });
+      // The service's own reading of the same windows, so a view that shows the windows need not repeat it.
+      facts.push({ section: 'Limits & credits', summaryKey: 'usageWindows', label: `${nameArg} usage allowed`, value: boolean(limit.allowed) ? 'yes' : 'no' });
+      facts.push({ section: 'Limits & credits', summaryKey: 'usageWindows', label: `${nameArg} limit reached`, value: boolean(limit.limit_reached) ? 'yes' : 'no' });
       for (const [key, name] of [['primary_window', 'primary'], ['secondary_window', 'secondary']]) {
         if (limit[key] == null) continue;
         const window = record(limit[key]);
@@ -250,7 +261,7 @@ export class CodexAccountStatus {
         return { date, tokens: numeric(day.tokens) };
       }).sort((leftArg, rightArg) => rightArg.date.localeCompare(leftArg.date));
       for (const day of days.slice(0, 7)) facts.push({ section: 'Daily tokens', label: `Tokens ${day.date}`, value: day.tokens.toLocaleString('en-US') });
-      if (days.length > 7) facts.push({ section: 'Daily tokens', label: 'Daily activity', value: `Showing the latest 7 of ${days.length} reported days` });
+      facts.push({ section: 'Daily tokens', label: 'Reported days', value: String(days.length) });
     }
     return facts;
   }