@modelprofile.com/authswitch 3.3.0 → 5.0.0

package/ts/classes.claudestatus.ts

@@ -1,8 +1,9 @@
-import { credentialRecord, credentialText } from './classes.credentialstore.js';
+import { credentialHash, credentialRecord, credentialText } from './classes.credentialstore.js';
+import { claudeRequest, ClaudeLoginRejectedError, ClaudeRateLimitError, ClaudeRequestError } from './claudehttp.js';
+import { latestRetryAt } from './ratelimit.js';
 import { plainText } from './formatting.js';
-import type { IHarnessAccountStatus, IHarnessStatusOptions, IHarnessUsageWindow, TUsageSeverity } from './interfaces.harness.js';
-
-class ClaudeStatusError extends Error {}
+import { usageWindowPeriod } from './accounts.js';
+import type { IHarnessAccountStatus, IHarnessStatusFact, IHarnessStatusOptions, IHarnessUsageWindow, TUsageSeverity } from './interfaces.harness.js';
 
 interface IClaudeUsageWindows {
   windows: IHarnessUsageWindow[];
@@ -22,31 +23,31 @@ const serverName = (value: unknown): string => {
   return name;
 };
 
-/** Keyed windows, read only from a usage body that carries no limits[] rows. */
+/** Keyed windows, read only from a usage body that carries no limits[] rows: what each meter is about, and how long its window is. */
 const KEYED_WINDOWS = [
-  ['five_hour', 'Claude five-hour', 18000, 'account'], ['seven_day', 'Claude weekly', 604800, 'account'],
-  ['seven_day_oauth_apps', 'OAuth apps weekly', 604800, 'feature'], ['seven_day_opus', 'Opus weekly', 604800, 'feature'], ['seven_day_sonnet', 'Sonnet weekly', 604800, 'feature'],
+  ['five_hour', 'Claude', 18000, 'account'], ['seven_day', 'Claude', 604800, 'account'],
+  ['seven_day_oauth_apps', 'OAuth apps', 604800, 'feature'], ['seven_day_opus', 'Opus', 604800, 'feature'], ['seven_day_sonnet', 'Sonnet', 604800, 'feature'],
 ] as const;
 
 const keyedWindows = (usage: Record<string, unknown>): IHarnessUsageWindow[] => {
   const windows: IHarnessUsageWindow[] = [];
-  for (const [key, label, durationSeconds, scope] of KEYED_WINDOWS) {
+  for (const [key, subject, durationSeconds, scope] of KEYED_WINDOWS) {
     if (usage[key] == null) continue;
     const window = credentialRecord(usage[key]);
     if (window.utilization == null) continue;
     if (typeof window.utilization !== 'number' || !Number.isFinite(window.utilization) || window.utilization < 0) throw new Error('Unsupported Claude usage utilization.');
-    windows.push({ label, durationSeconds, scope, usedPercent: window.utilization, resetAt: resetTimestamp(window.resets_at) });
+    windows.push({ label: `${subject} ${usageWindowPeriod(durationSeconds)}`, durationSeconds, scope, usedPercent: window.utilization, resetAt: resetTimestamp(window.resets_at) });
   }
   return windows;
 };
 
 /**
- * The limits[] row groups the window model represents: each group's duration, the period word its
- * labels use, and the kind of the group's unscoped account meter, which keeps the plain label.
+ * The limits[] row groups the window model represents: each group's duration, which names its windows,
+ * and the kind of the group's unscoped account meter, which keeps the plain label.
  */
-const LIMIT_GROUPS: ReadonlyMap<string, { durationSeconds: number; period: string; accountKind: string }> = new Map([
-  ['session', { durationSeconds: 18000, period: 'five-hour', accountKind: 'session' }],
-  ['weekly', { durationSeconds: 604800, period: 'weekly', accountKind: 'weekly_all' }],
+const LIMIT_GROUPS: ReadonlyMap<string, { durationSeconds: number; accountKind: string }> = new Map([
+  ['session', { durationSeconds: 18000, accountKind: 'session' }],
+  ['weekly', { durationSeconds: 604800, accountKind: 'weekly_all' }],
 ]);
 
 const isUsageSeverity = (value: unknown): value is TUsageSeverity => value === 'normal' || value === 'warning' || value === 'critical';
@@ -82,8 +83,9 @@ const limitWindows = (rows: readonly unknown[]): IClaudeUsageWindows => {
       continue;
     }
     const severity = row.severity;
+    const period = usageWindowPeriod(meter.durationSeconds);
     windows.push({
-      label: subject === undefined ? `Claude ${meter.period}${kind === meter.accountKind ? '' : ` (${kindName})`}` : `${subject} ${meter.period}`,
+      label: subject === undefined ? `Claude ${period}${kind === meter.accountKind ? '' : ` (${kindName})`}` : `${subject} ${period}`,
       durationSeconds: meter.durationSeconds, scope: subject === undefined ? 'account' : 'feature', usedPercent, resetAt,
       ...(isUsageSeverity(severity) ? { severity } : {}),
       ...(row.is_active === true ? { headline: true as const } : {}),
@@ -102,66 +104,96 @@ const claudeUsageWindows = (usage: Record<string, unknown>): IClaudeUsageWindows
   return Array.isArray(limits) && limits.length ? limitWindows(limits) : { windows: keyedWindows(usage), unsupported: [] };
 };
 
-/** Read-only Claude Code OAuth account endpoints. No refresh, inference, or browser session is used. */
+/** A profile lookup's answer. Only a lookup that could not be completed is thrown, and so never reused. */
+type TClaudeProfile =
+  | { kind: 'found'; plan: string | undefined; facts: IHarnessStatusFact[] }
+  | { kind: 'mismatch' }
+  | { kind: 'unavailable'; problem: string };
+
+/**
+ * How long a session reuses an account's profile. The watch polls every few minutes, and the profile (plan,
+ * organization, billing type) changes far more rarely, so it is read at most hourly there.
+ */
+const PROFILE_REUSE_MS = 3_600_000;
+const REQUEST_TIMEOUT_MS = 10_000;
+const MISMATCH = 'Claude returned a different account or organization; no account data was displayed.';
+
+/**
+ * Claude Code's read-only OAuth account endpoints: the profile and usage of one login, with the access token it
+ * carries. It never refreshes that token; `ClaudeCodeHarness` refreshes a saved login first, and leaves the active
+ * login's tokens to Claude Code. No inference or browser session is used.
+ */
 export class ClaudeAccountStatus {
-  constructor(private readonly fetcher: typeof fetch = globalThis.fetch) {}
-  private async get(route: 'usage' | 'profile', accessToken: string, cancelArg?: AbortSignal): Promise<Record<string, unknown>> {
-    const timeout = AbortSignal.timeout(10_000);
-    const signal = cancelArg ? AbortSignal.any([cancelArg, timeout]) : timeout;
+  constructor(private readonly fetcher: typeof fetch = globalThis.fetch, private readonly now: () => number = Date.now) {}
+
+  private async get(route: 'usage' | 'profile', accessToken: string, signal?: AbortSignal): Promise<Record<string, unknown>> {
+    const { status, body } = await claudeRequest(this.fetcher, {
+      url: `https://api.anthropic.com/api/oauth/${route}`, method: 'GET', subject: 'Claude account', timeoutMs: REQUEST_TIMEOUT_MS, signal, now: this.now,
+      headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json',
+        ...(route === 'usage' ? { 'anthropic-beta': 'oauth-2025-04-20' } : { 'Cache-Control': 'no-cache' }) },
+    });
+    if (status === 401) throw new ClaudeLoginRejectedError();
+    if (status < 200 || status > 299) throw new ClaudeRequestError(`Claude account service returned HTTP ${status}.`);
+    if (body === null) throw new ClaudeRequestError('The Claude account service returned invalid data.');
+    return body;
+  }
+
+  /** The profile, from the session while it is younger than an hour; the session key is a hash of the token, never the token. */
+  private profile(token: string, account: Record<string, unknown>, optionsArg: IHarnessStatusOptions): Promise<TClaudeProfile> {
+    const lookup = () => this.lookupProfile(token, account, optionsArg.signal);
+    return optionsArg.session ? optionsArg.session.reuse(`claude:profile:${credentialHash(token)}`, PROFILE_REUSE_MS, lookup) : lookup();
+  }
+
+  /** A rejected login and an unsupported or foreign profile are answers; a rate limit or a failed request is thrown. */
+  private async lookupProfile(token: string, account: Record<string, unknown>, signal?: AbortSignal): Promise<TClaudeProfile> {
+    let body: Record<string, unknown>;
+    try { body = await this.get('profile', token, signal); }
+    catch (error) {
+      if (error instanceof ClaudeLoginRejectedError) return { kind: 'unavailable', problem: `Profile: ${error.message}` };
+      throw error;
+    }
     try {
-      const response = await this.fetcher(`https://api.anthropic.com/api/oauth/${route}`, {
-        method: 'GET', redirect: 'error', signal,
-        headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json',
-          ...(route === 'usage' ? { 'anthropic-beta': 'oauth-2025-04-20' } : { 'Cache-Control': 'no-cache' }) },
-      });
-      if (!response.ok) {
-        await response.body?.cancel();
-        throw new ClaudeStatusError(response.status === 401 ? 'Login expired or was rejected. Log in again with Claude Code and save it.' : `Claude account service returned HTTP ${response.status}.`);
+      const user = credentialRecord(body.account);
+      const organization = credentialRecord(body.organization);
+      if (user.uuid !== account.accountUuid || organization.uuid !== account.organizationUuid) return { kind: 'mismatch' };
+      const facts: IHarnessStatusFact[] = [];
+      for (const [label, value] of [['Email', user.email], ['Organization', organization.name], ['Billing type', organization.billing_type], ['Seat tier', organization.seat_tier]]) {
+        if (credentialText(value)) facts.push({ section: 'Account', label: String(label), value: String(value) });
       }
-      const reader = response.body?.getReader();
-      if (!reader) throw new ClaudeStatusError('The Claude account service returned an empty response.');
-      const chunks: Uint8Array[] = [];
-      let size = 0;
-      try {
-        while (true) {
-          const part = await reader.read();
-          if (part.done) break;
-          size += part.value.byteLength;
-          if (size > 1024 * 1024) { await reader.cancel(); throw new ClaudeStatusError('The Claude account response is too large.'); }
-          chunks.push(part.value);
-        }
-      } finally { reader.releaseLock(); }
-      try { return credentialRecord(JSON.parse(Buffer.concat(chunks).toString('utf8'))); }
-      catch { throw new ClaudeStatusError('The Claude account service returned invalid data.'); }
-    } catch (error) {
-      if (signal.aborted) throw new ClaudeStatusError(timeout.aborted ? 'The Claude account request timed out.' : 'The Claude account request was cancelled.');
-      if (error instanceof ClaudeStatusError) throw error;
-      throw new ClaudeStatusError('The Claude account service could not be reached.');
-    }
+      return { kind: 'found', plan: credentialText(organization.organization_type)?.replace(/^claude_/, ''), facts };
+    } catch { return { kind: 'unavailable', problem: 'Claude profile response is unsupported; no profile values were inferred.' }; }
+  }
+
+  /** The plan the login was saved with, the only one known while the service cannot be asked. */
+  private storedSummary(oauth: Record<string, unknown>): Pick<IHarnessAccountStatus, 'summary'> {
+    const plan = credentialText(oauth.subscriptionType);
+    return plan ? { summary: { subscription: { plan, source: 'stored' } } } : {};
   }
+
+  /** A login that could not be made usable for a lookup: its stored plan and why, with the service's retry time for a rate limit. */
+  public unavailable(oauth: Record<string, unknown>, problem: string, rateLimit?: IHarnessAccountStatus['rateLimit']): IHarnessAccountStatus {
+    return { facts: [], problems: [problem], ...this.storedSummary(oauth), ...(rateLimit ? { rateLimit } : {}) };
+  }
+
   public async read(oauth: Record<string, unknown>, account: Record<string, unknown>, optionsArg: IHarnessStatusOptions = {}): Promise<IHarnessAccountStatus> {
-    const result: IHarnessAccountStatus = { facts: [], problems: [] };
-    const storedPlan = credentialText(oauth.subscriptionType);
-    if (storedPlan) result.summary = { subscription: { plan: storedPlan, source: 'stored' } };
+    const result: IHarnessAccountStatus = { facts: [], problems: [], ...this.storedSummary(oauth) };
     if (!Array.isArray(oauth.scopes) || !oauth.scopes.includes('user:profile')) {
       result.facts.push({ section: 'Availability', label: 'Live account status', value: 'This login lacks the user:profile scope. Log in through Claude Code to obtain subscriber status.' });
       return result;
     }
     const token = credentialText(oauth.accessToken);
     if (!token) return { facts: [], problems: ['No usable Claude Code access token is available.'] };
-    const [profile, usage] = await Promise.allSettled([this.get('profile', token, optionsArg.signal), this.get('usage', token, optionsArg.signal)]);
+    const [profile, usage] = await Promise.allSettled([this.profile(token, account, optionsArg), this.get('usage', token, optionsArg.signal)]);
+    const failure = (reason: unknown): string => reason instanceof ClaudeRequestError ? reason.message : 'Lookup failed.';
     if (profile.status === 'fulfilled') {
-      try {
-        const user = credentialRecord(profile.value.account);
-        const organization = credentialRecord(profile.value.organization);
-        if (user.uuid !== account.accountUuid || organization.uuid !== account.organizationUuid) return { facts: [], problems: ['Claude returned a different account or organization; no account data was displayed.'] };
-        const plan = credentialText(organization.organization_type)?.replace(/^claude_/, '');
-        if (plan) result.summary = { ...result.summary, subscription: { plan, source: 'live' } };
-        for (const [label, value] of [['Email', user.email], ['Organization', organization.name], ['Billing type', organization.billing_type], ['Seat tier', organization.seat_tier]]) {
-          if (credentialText(value)) result.facts.push({ section: 'Account', label: String(label), value: String(value) });
-        }
-      } catch { result.problems.push('Claude profile response is unsupported; no profile values were inferred.'); }
-    } else result.problems.push(`Profile: ${profile.reason instanceof ClaudeStatusError ? profile.reason.message : 'Lookup failed.'}`);
+      const found = profile.value;
+      if (found.kind === 'mismatch') return { facts: [], problems: [MISMATCH] };
+      if (found.kind === 'unavailable') result.problems.push(found.problem);
+      else {
+        if (found.plan) result.summary = { ...result.summary, subscription: { plan: found.plan, source: 'live' } };
+        result.facts.push(...found.facts.map(fact => ({ ...fact })));
+      }
+    } else result.problems.push(`Profile: ${failure(profile.reason)}`);
     if (usage.status === 'fulfilled') {
       try {
         const { windows, unsupported } = claudeUsageWindows(usage.value);
@@ -181,8 +213,11 @@ export class ClaudeAccountStatus {
         }
         if (unsupported.length) result.facts.push({ section: 'Availability', label: 'Unsupported limits', value: `The service returned limits without a supported reset window, which are not shown: ${unsupported.join(', ')}.` });
       } catch { result.problems.push('Claude usage response is unsupported; missing values were not inferred.'); }
-    } else result.problems.push(`Usage: ${usage.reason instanceof ClaudeStatusError ? usage.reason.message : 'Lookup failed.'}`);
-    result.facts.push({ section: 'Availability', label: 'Billing dates and earned resets', value: 'Renewal dates, cancellation dates and earned reset credits are not exposed by these Claude Code endpoints.' });
+    } else result.problems.push(`Usage: ${failure(usage.reason)}`);
+    const limited = [profile, usage].flatMap(item => item.status === 'rejected' && item.reason instanceof ClaudeRateLimitError ? [item.reason] : []);
+    if (limited.length) result.rateLimit = { retryAt: latestRetryAt(limited.map(error => error.retryAt)) };
+    // The missing renewal dates are the harness's `renewalUnavailableReason`, stated once by the views that show them.
+    result.facts.push({ section: 'Availability', label: 'Earned resets', value: 'authswitch does not read earned reset credits for Claude Code logins.' });
     return result;
   }
 }

package/ts/classes.claudetokenrefresh.ts

@@ -0,0 +1,85 @@
+import { credentialText } from './classes.credentialstore.js';
+import { claudeRequest, ClaudeLoginRejectedError, ClaudeRequestError } from './claudehttp.js';
+
+/** Claude Code 2.1.273's token endpoint (`TOKEN_URL`, bundle offset @12733057; see hints.md). */
+const TOKEN_URL = 'https://platform.claude.com/v1/oauth/token';
+/** Claude Code 2.1.273's public OAuth client (`CLIENT_ID`, @12733057), used when a login does not name its own. */
+export const CLAUDE_CODE_CLIENT_ID = '9d1c250a-e61b-44d9-88ed-5944d1962f5e';
+/** Claude Code 2.1.273 refreshes an access token that expires within five minutes (`cF`, @15359182). */
+const REFRESH_MARGIN_MS = 300_000;
+/**
+ * Claude Code 2.1.273 allows a refresh 30 seconds. A refresh is never cut shorter than that, nor cancelled once sent:
+ * the service may already have replaced the refresh token the request carries.
+ */
+const REFRESH_TIMEOUT_MS = 30_000;
+
+/** The token fields a refresh replaces in a stored `claudeAiOauth`; every other field is kept. */
+export interface IClaudeTokens {
+  accessToken: string;
+  refreshToken: string;
+  /** Milliseconds since the epoch, as Claude Code stores them. */
+  expiresAt: number;
+  refreshTokenExpiresAt?: number;
+  scopes?: string[];
+}
+
+const seconds = (valueArg: unknown): number | undefined =>
+  typeof valueArg === 'number' && Number.isFinite(valueArg) && valueArg >= 0 ? valueArg : undefined;
+
+/**
+ * Refreshes a saved Claude Code login with the refresh-token grant Claude Code 2.1.273 uses (`RQ`, @15355055).
+ *
+ * It only talks to the token endpoint; which login is refreshed, and how the result is stored, belongs to the harness.
+ */
+export class ClaudeTokenRefresh {
+  constructor(private readonly fetcher: typeof fetch = globalThis.fetch, private readonly now: () => number = Date.now) {}
+
+  /**
+   * Whether Claude Code would refresh this login before using it: its access token expires within five minutes. A
+   * login without a numeric expiry or without a refresh token is used as it is, exactly as Claude Code does.
+   */
+  public due(oauthArg: Record<string, unknown>): boolean {
+    const expiresAt = oauthArg.expiresAt;
+    return typeof expiresAt === 'number' && Number.isFinite(expiresAt) && credentialText(oauthArg.refreshToken) !== undefined
+      && this.now() + REFRESH_MARGIN_MS >= expiresAt;
+  }
+
+  /**
+   * New tokens for the login. A response without a refresh token keeps the one sent, and one without a scope keeps the
+   * stored scopes, as Claude Code merges them. Throws `ClaudeRequestError` with a fixed diagnostic; a grant the service
+   * rejects is `ClaudeLoginRejectedError`, and a rate limit is `ClaudeRateLimitError`.
+   */
+  public async refresh(oauthArg: Record<string, unknown>): Promise<IClaudeTokens> {
+    const refreshToken = credentialText(oauthArg.refreshToken);
+    const scopes = oauthArg.scopes;
+    if (!refreshToken || !Array.isArray(scopes) || !scopes.every(scope => typeof scope === 'string')) {
+      throw new ClaudeRequestError('This saved login has no refresh token or scopes to refresh with. Log in again with Claude Code and save it.');
+    }
+    const { status, body } = await claudeRequest(this.fetcher, {
+      url: TOKEN_URL, method: 'POST', headers: { 'Content-Type': 'application/json' }, subject: 'Claude sign-in',
+      body: JSON.stringify({
+        grant_type: 'refresh_token', refresh_token: refreshToken,
+        client_id: credentialText(oauthArg.clientId) ?? CLAUDE_CODE_CLIENT_ID, scope: scopes.join(' '),
+      }),
+      timeoutMs: REFRESH_TIMEOUT_MS, readErrorBody: true, now: this.now,
+    });
+    if ((status === 400 || status === 401) && body?.error === 'invalid_grant') throw new ClaudeLoginRejectedError();
+    if (status < 200 || status > 299) throw new ClaudeRequestError(`The Claude sign-in service returned HTTP ${status}.`);
+    const receivedAt = this.now();
+    const accessToken = credentialText(body?.access_token);
+    const tokenType = body?.token_type;
+    const expiresIn = seconds(body?.expires_in);
+    const refreshExpiresIn = body?.refresh_token_expires_in == null ? null : seconds(body.refresh_token_expires_in);
+    const rotated = body?.refresh_token == null ? null : credentialText(body.refresh_token);
+    const scope = body?.scope == null ? null : typeof body.scope === 'string' ? body.scope.split(/\s+/).filter(Boolean) : undefined;
+    if (!accessToken || (tokenType != null && (typeof tokenType !== 'string' || tokenType.toLowerCase() !== 'bearer'))
+      || expiresIn === undefined || refreshExpiresIn === undefined || rotated === undefined || scope === undefined) {
+      throw new ClaudeRequestError('The Claude sign-in service returned an unsupported token response; the saved login was not changed.');
+    }
+    return {
+      accessToken, refreshToken: rotated ?? refreshToken, expiresAt: receivedAt + expiresIn * 1000,
+      ...(refreshExpiresIn === null ? {} : { refreshTokenExpiresAt: receivedAt + refreshExpiresIn * 1000 }),
+      ...(scope === null || !scope.length ? {} : { scopes: scope }),
+    };
+  }
+}

package/ts/classes.cli.ts

@@ -5,29 +5,34 @@ 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, readAccountBadges, until } from './accounts.js';
+import { consoleTable } from './consoletable.js';
+import { accountName, credentialDriftNote, 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'];
-
-/** An account as prompts and reports name it: its label, qualified by its credential slot when it has one. */
-const accountName = (accountArg: IHarnessAccount): string =>
-  `${plainText(accountArg.label)}${accountArg.slotId ? ` (${plainText(accountArg.slotId)})` : ''}`;
+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 {
@@ -73,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]
@@ -92,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}"
@@ -121,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; }
@@ -234,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; }
@@ -250,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({
@@ -298,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();
@@ -366,13 +382,12 @@ ${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: [
-            { key: 'window', title: 'Window', value: row => `${plainText(row.label)} (${duration(row.durationSeconds)})` },
-            { key: 'usage', title: 'Used', value: row => `${row.usedPercent}%` },
+          await consoleTable(this.out, windows, [
+            // The label already names the window by its length, so the column never repeats it.
+            { key: 'window', title: 'Window', value: row => plainText(row.label) },
+            { 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');
@@ -384,6 +399,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()) {
@@ -494,7 +560,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> {
@@ -515,12 +581,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);
@@ -530,17 +597,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;

package/ts/classes.codexharness.ts

@@ -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(),