@modelprofile.com/authswitch 3.3.0 → 5.0.0

package/ts/classes.operations.ts

@@ -1,4 +1,5 @@
 import * as plugins from './plugins.js';
+import { authSwitchHome } from './classes.credentialstore.js';
 import type { IAuthHarness, IHarnessOutcome } from './interfaces.harness.js';
 
 export type TAuthSwitchMutation = { harnessId: string } & (
@@ -30,7 +31,7 @@ export type TAuthSwitchLocalPreparation = () => Promise<void>;
 
 export const authSwitchEnvironmentId = (env: NodeJS.ProcessEnv = process.env): string => plugins.crypto.createHash('sha256').update(JSON.stringify({
   home: plugins.os.homedir(),
-  stash: plugins.path.resolve(env.AUTHSWITCH_HOME || plugins.path.join(plugins.os.homedir(), '.authswitch')),
+  stash: plugins.path.resolve(authSwitchHome(env)),
   codex: plugins.path.resolve(env.CODEX_HOME || plugins.path.join(plugins.os.homedir(), '.codex')),
   data: plugins.path.resolve(env.XDG_DATA_HOME || plugins.path.join(plugins.os.homedir(), '.local/share')),
   claude: plugins.path.resolve(env.CLAUDE_CONFIG_DIR || plugins.path.join(plugins.os.homedir(), '.claude')),

package/ts/classes.tui.ts

@@ -65,11 +65,12 @@ export class AuthSwitchTui {
      *
      * The dashboard makes the same offer the command line does, with the same rule: only pids
      * enumerated for this user are signalled, the session running this dashboard is never one of
-     * them, and declining still performs the switch.
+     * them, and declining still performs the switch. A harness that picks up swaps live is never
+     * offered a stop here; the dashboard has no explicit stop request.
      */
     const settleInstances = (screen: plugins.smartconsole.ITuiContext) => async (): Promise<void> => {
       const control = harness.processes;
-      if (!control) return;
+      if (!control || harness.liveSwap === true) return;
       let running: IHarnessProcess[];
       try { running = control.list(); }
       catch { ui.logs.append(`Could not check for running ${plainText(harness.label)} processes.`); return; }

package/ts/classes.watch.ts

@@ -0,0 +1,263 @@
+import { accountBadge, accountName, durationText, localTime, readAccountRows, type IAccountRow } from './accounts.js';
+import { pause } from './helpers.js';
+import { bold, dim, green, orange, plainText, red } from './formatting.js';
+import { decideWatchAction, type IWatchReading } from './watchpolicy.js';
+import type { AuthSwitchOperations } from './classes.operations.js';
+import type { WatchLock } from './classes.watchlock.js';
+import type { IAccountType, IAuthHarness, IHarnessStatusSession, IHarnessUsageWindow } from './interfaces.harness.js';
+
+/** The watch's time source; tests replace it so that no test waits for an interval. */
+export interface IWatchClock {
+  now(): number;
+  /** Resolves after the delay; rejects when the signal aborts first, leaving no timer behind. */
+  sleep(millisecondsArg: number, signalArg: AbortSignal): Promise<void>;
+}
+
+const systemClock: IWatchClock = { now: () => Date.now(), sleep: pause };
+
+/** An account as a watch event names it. Carries no credential. */
+export interface IWatchAccount {
+  accountId: string;
+  label: string;
+  slotId?: string;
+  accountType: IAccountType | null;
+  /** The usage windows the decision used; null while the usage is unknown. */
+  usageWindows: IHarnessUsageWindow[] | null;
+}
+
+/** One line of `authswitch watch --json`. Times are ISO 8601 UTC. */
+export type TWatchEvent =
+  | { type: 'start'; at: string; harnesses: { harnessId: string; label: string; note: string | null }[]; intervalSeconds: number; threshold: number; dryRun: boolean }
+  | { type: 'tick'; at: string; harnessId: string; label: string; active: IWatchAccount | null; ok: boolean; reason: string }
+  | { type: 'switch'; at: string; harnessId: string; label: string; dryRun: boolean; from: IWatchAccount; to: IWatchAccount; reason: string }
+  | { type: 'error'; at: string; harnessId: string; label: string; message: string };
+
+export interface IAuthSwitchWatchOptions {
+  harnesses: readonly IAuthHarness[];
+  /** The one mutation path every switch goes through. */
+  operations: AuthSwitchOperations;
+  lock: WatchLock;
+  intervalMs: number;
+  threshold: number;
+  dryRun: boolean;
+  onEvent: (eventArg: TWatchEvent) => void;
+  clock?: IWatchClock;
+}
+
+/** How long a reading stands in for an account that is backing off. */
+const READING_REUSE_MS = 10 * 60_000;
+/** The longest backoff after repeated failures that named no retry time. */
+const MAX_BACKOFF_MS = 30 * 60_000;
+/** How a rate limited account's deferral reads; a lookup that failed otherwise is named by its own problem. */
+const RATE_LIMITED = 'rate limited';
+
+/** A caller-owned memo of slow-changing lookups, aged by the watch's clock. */
+class WatchStatusSession implements IHarnessStatusSession {
+  private readonly entries = new Map<string, { at: number; maxAgeMs: number; value: unknown }>();
+  constructor(private readonly now: () => number) {}
+  public async reuse<T>(keyArg: string, maxAgeMsArg: number, lookupArg: () => Promise<T>): Promise<T> {
+    const now = this.now();
+    for (const [key, entry] of this.entries) if (now - entry.at >= entry.maxAgeMs) this.entries.delete(key);
+    const entry = this.entries.get(keyArg);
+    // Keys are adapter-owned and always name values of one type (IHarnessStatusSession).
+    if (entry) return entry.value as T;
+    const value = await lookupArg();
+    this.entries.set(keyArg, { at: this.now(), maxAgeMs: maxAgeMsArg, value });
+    return value;
+  }
+}
+
+/** What the watch remembers about one account between ticks. */
+interface IAccountMemory {
+  usage: { accountType: IAccountType | null; windows: IHarnessUsageWindow[]; at: number } | null;
+  /** No lookup before this time, after the provider rate limited one or a lookup failed. */
+  retryAt: number;
+  /** Consecutive failures without a named retry time, for the exponential backoff. */
+  strikes: number;
+  /** Why the account is backing off, so a tick that skips its lookup reads like the one that failed; null while none did. */
+  deferralReason: string | null;
+}
+
+interface IHarnessTick {
+  harness: IAuthHarness;
+  rows: IAccountRow[];
+  readings: IWatchReading[];
+  accounts: Map<string, IWatchAccount>;
+}
+
+/**
+ * `authswitch watch`: reads every account's usage on an interval and switches a harness to a better saved account when
+ * its active one runs out, through the same mutation path as `use`.
+ *
+ * Ticks never overlap: the next one starts an interval after the previous one started, or at once when that one took
+ * longer. Lookups never change which account is in use and are bounded; an account whose lookup a provider refused or
+ * whose lookup failed is not asked about again until the time the provider named, or after an exponentially growing
+ * delay, and its last reading stands in meanwhile while it is recent. A failed or refused switch is reported and
+ * decided again on the next tick.
+ */
+export class AuthSwitchWatch {
+  private readonly clock: IWatchClock;
+  private readonly session: WatchStatusSession;
+  /** Per harness id, per account id. */
+  private readonly memory = new Map<string, Map<string, IAccountMemory>>();
+
+  constructor(private readonly options: IAuthSwitchWatchOptions) {
+    this.clock = options.clock ?? systemClock;
+    this.session = new WatchStatusSession(() => this.clock.now());
+  }
+
+  private at(): string { return new Date(this.clock.now()).toISOString(); }
+
+  /**
+   * Holds the lock and ticks until the signal aborts, or once. Resolves whether every switch it attempted completed;
+   * throws `WatchBusyError` when another watch is running.
+   */
+  public async run(signalArg: AbortSignal, optionsArg: { once?: boolean } = {}): Promise<boolean> {
+    this.options.lock.acquire();
+    try {
+      this.options.onEvent({
+        type: 'start', at: this.at(), intervalSeconds: this.options.intervalMs / 1000, threshold: this.options.threshold, dryRun: this.options.dryRun,
+        harnesses: this.options.harnesses.map(harness => ({ harnessId: harness.id, label: plainText(harness.label),
+          note: harness.liveSwap === true ? null : `Running ${plainText(harness.label)} sessions keep the login they loaded; new sessions use the switched one.` })),
+      });
+      let completed = true;
+      while (!signalArg.aborted) {
+        const startedAt = this.clock.now();
+        completed = await this.tick(signalArg) && completed;
+        if (optionsArg.once) break;
+        try { await this.clock.sleep(Math.max(0, startedAt + this.options.intervalMs - this.clock.now()), signalArg); }
+        catch (error) { if (!signalArg.aborted) throw error; }
+      }
+      return completed;
+    } finally { this.options.lock.release(); }
+  }
+
+  /** One round over every harness. Resolves false when a switch was attempted and did not complete. */
+  private async tick(signalArg: AbortSignal): Promise<boolean> {
+    const now = this.clock.now();
+    const reads = await Promise.allSettled(this.options.harnesses.map(harness => this.read(harness, now, signalArg)));
+    let completed = true;
+    for (const [index, read] of reads.entries()) {
+      if (signalArg.aborted) break;
+      const harness = this.options.harnesses[index];
+      if (read.status === 'rejected') {
+        this.options.onEvent({ type: 'error', at: this.at(), harnessId: harness.id, label: plainText(harness.label),
+          message: `Could not read the accounts. Run authswitch ${harness.id} doctor.` });
+        continue;
+      }
+      completed = await this.decide(read.value, now) && completed;
+    }
+    return completed;
+  }
+
+  private async read(harnessArg: IAuthHarness, nowArg: number, signalArg: AbortSignal): Promise<IHarnessTick> {
+    const previous = this.memory.get(harnessArg.id) ?? new Map<string, IAccountMemory>();
+    const { rows } = await readAccountRows(harnessArg, {
+      signal: signalArg, session: this.session, lookup: account => nowArg >= (previous.get(account.id)?.retryAt ?? 0),
+    });
+    // Only listed accounts are remembered, so a removed account leaves nothing behind.
+    const current = new Map<string, IAccountMemory>();
+    const readings: IWatchReading[] = [];
+    const accounts = new Map<string, IWatchAccount>();
+    for (const row of rows) {
+      const memory = previous.get(row.account.id) ?? { usage: null, retryAt: 0, strikes: 0, deferralReason: null };
+      current.set(row.account.id, memory);
+      const { reading, account } = this.remember(memory, row, nowArg);
+      readings.push(reading);
+      accounts.set(row.account.id, account);
+    }
+    this.memory.set(harnessArg.id, current);
+    return { harness: harnessArg, rows, readings, accounts };
+  }
+
+  /**
+   * Folds one lookup into the account's memory and returns what the decision may use. A row without a status was not
+   * looked up because the account is backing off.
+   *
+   * A lookup that a provider refused (a rate limit) or that failed (a rejected login, a timeout, an unreachable
+   * service) puts the account on hold for the time the provider named, else for a delay that doubles from one
+   * interval, and its last reading stands in meanwhile while it is recent: the accounts failing hardest must not be
+   * the ones asked most often, and one flaky request must not discard a reading taken moments ago. A lookup that
+   * answered without usage and without a problem is the provider reporting none, which is an answer: it clears both.
+   */
+  private remember(memoryArg: IAccountMemory, rowArg: IAccountRow, nowArg: number): { reading: IWatchReading; account: IWatchAccount } {
+    const status = rowArg.status;
+    const windows = status?.summary?.usageWindows;
+    const limited = status?.rateLimit !== undefined;
+    const failed = status !== undefined && !limited && windows === undefined && status.problems.length > 0;
+    if (status !== undefined && (limited || failed)) {
+      const named = status.rateLimit?.retryAt == null ? Number.NaN : Date.parse(status.rateLimit.retryAt);
+      memoryArg.strikes = Number.isFinite(named) ? 0 : memoryArg.strikes + 1;
+      memoryArg.retryAt = Number.isFinite(named) ? named : nowArg + Math.min(this.options.intervalMs * 2 ** (memoryArg.strikes - 1), MAX_BACKOFF_MS);
+      memoryArg.deferralReason = limited ? RATE_LIMITED : plainText(status.problems[0]);
+    } else if (status) {
+      memoryArg.strikes = 0;
+      memoryArg.retryAt = 0;
+      memoryArg.deferralReason = null;
+    }
+    if (windows !== undefined) memoryArg.usage = { accountType: status!.summary!.subscription ?? null, windows, at: nowArg };
+    else if (status && !limited && !failed) memoryArg.usage = null;
+    const deferred = status === undefined || limited || failed;
+    const usage = deferred && memoryArg.usage !== null && nowArg - memoryArg.usage.at >= READING_REUSE_MS ? null : memoryArg.usage;
+    const unknownReason = usage !== null ? undefined
+      : `${memoryArg.deferralReason ?? 'usage not reported'}${nowArg < memoryArg.retryAt ? `, next lookup at ${localTime(memoryArg.retryAt)}` : ''}`;
+    const accountType = usage?.accountType ?? status?.summary?.subscription ?? null;
+    return {
+      reading: { id: rowArg.account.id, label: plainText(rowArg.account.label), isSaved: rowArg.account.isStashed, windows: usage?.windows ?? null,
+        ...(unknownReason === undefined ? {} : { unknownReason }) },
+      account: { accountId: rowArg.account.id, label: plainText(rowArg.account.label), ...(rowArg.account.slotId === undefined ? {} : { slotId: plainText(rowArg.account.slotId) }),
+        accountType: accountType === null ? null : { plan: plainText(accountType.plan), source: accountType.source }, usageWindows: usage === null ? null : [...usage.windows] },
+    };
+  }
+
+  private async decide(tickArg: IHarnessTick, nowArg: number): Promise<boolean> {
+    const { harness } = tickArg;
+    const label = plainText(harness.label);
+    const activeId = tickArg.rows.find(row => row.account.isActive)?.account.id ?? null;
+    const decision = decideWatchAction({ activeId, readings: tickArg.readings, threshold: this.options.threshold, intervalMs: this.options.intervalMs, now: nowArg });
+    const active = activeId === null ? null : tickArg.accounts.get(activeId)!;
+    if (decision.action === 'stay') {
+      this.options.onEvent({ type: 'tick', at: this.at(), harnessId: harness.id, label, active, ok: decision.ok, reason: decision.reason });
+      return true;
+    }
+    const target = tickArg.accounts.get(decision.target)!;
+    const switched = { type: 'switch', harnessId: harness.id, label, from: active!, to: target, reason: decision.reason } as const;
+    if (this.options.dryRun) {
+      this.options.onEvent({ ...switched, at: this.at(), dryRun: true });
+      return true;
+    }
+    let problems: string[];
+    try { problems = (await this.options.operations.run(harness, { harnessId: harness.id, action: 'switch', accountId: target.accountId })).problems; }
+    catch (error) { problems = [error instanceof Error ? error.message : 'The switch failed.']; }
+    if (problems.length) {
+      this.options.onEvent({ type: 'error', at: this.at(), harnessId: harness.id, label,
+        message: `Switching to ${accountName(target)} did not complete: ${problems.map(plainText).join(' ')} Deciding again next tick.` });
+      return false;
+    }
+    this.options.onEvent({ ...switched, at: this.at(), dryRun: false });
+    return true;
+  }
+}
+
+/** An account and its switch badge: `alice@example.com (type:Max) (5h:17%) (w:4%)`. */
+const badged = (accountArg: IWatchAccount): string => `${bold(accountName(accountArg))}${accountBadge({ facts: [], problems: [], summary: {
+  ...(accountArg.accountType === null ? {} : { subscription: accountArg.accountType }),
+  ...(accountArg.usageWindows === null ? {} : { usageWindows: accountArg.usageWindows }),
+} })}`;
+
+/** How `authswitch watch` prints an event: one line each, with the notes of a start on their own lines. */
+export const watchEventText = (eventArg: TWatchEvent): string => {
+  const time = dim(localTime(Date.parse(eventArg.at)));
+  switch (eventArg.type) {
+    case 'start':
+      return [`${time} Watching ${eventArg.harnesses.map(harness => harness.label).join(', ')} every ${durationText(eventArg.intervalSeconds)}; switching at ${eventArg.threshold}%${eventArg.dryRun ? ' (dry run: nothing is switched)' : ''}.`,
+        ...eventArg.harnesses.flatMap(harness => harness.note === null ? [] : [`${time} ${dim(harness.note)}`])].join('\n');
+    case 'tick':
+      return eventArg.active === null ? `${time} ${eventArg.label} ${orange(eventArg.reason)}`
+        : `${time} ${eventArg.label} ${badged(eventArg.active)} ${eventArg.ok ? green('ok') : orange(eventArg.reason)}`;
+    case 'switch':
+      return `${time} ${eventArg.label} ${eventArg.dryRun ? 'would switch' : 'switched'} ${accountName(eventArg.from)} → ${badged(eventArg.to)} — ${eventArg.reason}`;
+    case 'error':
+      return `${time} ${eventArg.label} ${red(eventArg.message)}`;
+  }
+};

package/ts/classes.watchlock.ts

@@ -0,0 +1,100 @@
+import * as plugins from './plugins.js';
+import { errorCode } from './helpers.js';
+
+/** Another watch holds the lock. */
+export class WatchBusyError extends Error {
+  constructor(public readonly pid: number, fileArg: string) {
+    super(`Another authswitch watch is running (pid ${pid}). If it is not, remove ${fileArg}.`);
+  }
+}
+
+export interface IWatchLockOptions {
+  /** The pid the lock names; this process by default. */
+  pid?: number;
+  /** Whether a process with this pid exists; a pid owned by another user counts as existing. */
+  isAlive?: (pidArg: number) => boolean;
+}
+
+const processExists = (pidArg: number): boolean => {
+  try { process.kill(pidArg, 0); return true; }
+  catch (error) { return errorCode(error) === 'EPERM'; }
+};
+
+/**
+ * The lock files this process holds.
+ *
+ * A lock naming this process's own pid is otherwise taken over, because a process that died can have its pid reused
+ * by the one that replaces it. While a watch in this process still holds the lock, that reasoning does not apply,
+ * and a second watch must be refused like any other.
+ */
+const heldFiles = new Set<string>();
+
+/**
+ * The single watch of one authswitch home: `<home>/watch.lock`, naming the pid that holds it.
+ *
+ * The lock file is created by hard-linking a complete file into place, so it never exists half-written and a second
+ * watch always reads a pid. A lock whose process no longer exists is left over from a watch that died and is taken
+ * over; the stale file is removed only while it still holds exactly what was judged stale. A lock another watch in
+ * this same process holds is never taken over.
+ */
+export class WatchLock {
+  public readonly file: string;
+  private readonly pid: number;
+  private readonly isAlive: (pidArg: number) => boolean;
+  private content: string | null = null;
+
+  constructor(private readonly home: string, optionsArg: IWatchLockOptions = {}) {
+    this.file = plugins.path.join(home, 'watch.lock');
+    this.pid = optionsArg.pid ?? process.pid;
+    this.isAlive = optionsArg.isAlive ?? processExists;
+  }
+
+  private read(): string | null {
+    try { return plugins.fs.readFileSync(this.file, 'utf8'); }
+    catch (error) { if (errorCode(error) === 'ENOENT') return null; throw error; }
+  }
+
+  private static holder(contentArg: string): number | null {
+    try {
+      const pid: unknown = JSON.parse(contentArg).pid;
+      return typeof pid === 'number' && Number.isSafeInteger(pid) && pid > 0 ? pid : null;
+    } catch { return null; }
+  }
+
+  /** Takes the lock, or throws `WatchBusyError` naming the running watch. */
+  public acquire(): void {
+    if (this.content !== null) throw new Error('This watch already holds its lock.');
+    if (heldFiles.has(this.file)) throw new WatchBusyError(this.pid, this.file);
+    plugins.fs.mkdirSync(this.home, { recursive: true, mode: 0o700 });
+    const content = `${JSON.stringify({ pid: this.pid, startedAt: new Date().toISOString() })}\n`;
+    const candidate = `${this.file}.${this.pid}`;
+    plugins.fs.writeFileSync(candidate, content, { mode: 0o600 });
+    try {
+      // One attempt, and one more after removing a stale lock; a watch that took it over in between wins.
+      for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+          plugins.fs.linkSync(candidate, this.file);
+          this.content = content;
+          heldFiles.add(this.file);
+          return;
+        } catch (error) { if (errorCode(error) !== 'EEXIST') throw error; }
+        const existing = this.read();
+        if (existing === null) continue;
+        const holder = WatchLock.holder(existing);
+        if (holder !== null && holder !== this.pid && this.isAlive(holder)) throw new WatchBusyError(holder, this.file);
+        if (this.read() === existing) plugins.fs.rmSync(this.file, { force: true });
+      }
+      const holder = WatchLock.holder(this.read() ?? '');
+      if (holder !== null) throw new WatchBusyError(holder, this.file);
+      throw new Error(`The watch lock ${this.file} could not be taken. Try again.`);
+    } finally { plugins.fs.rmSync(candidate, { force: true }); }
+  }
+
+  /** Releases the lock if this watch still holds it; a lock another watch took over is left alone. */
+  public release(): void {
+    if (this.content === null) return;
+    heldFiles.delete(this.file);
+    if (this.read() === this.content) plugins.fs.rmSync(this.file, { force: true });
+    this.content = null;
+  }
+}

package/ts/claudehttp.ts

@@ -0,0 +1,92 @@
+import { commitinfo } from './00_commitinfo_data.js';
+import { credentialRecord } from './classes.credentialstore.js';
+import { retryAtFrom } from './ratelimit.js';
+
+/** A fixed, local diagnostic. Nothing a service sent (a body, a header) and no request header ever becomes one. */
+export class ClaudeRequestError extends Error {}
+
+/** How every Claude lookup reports a login the service does not accept (HTTP 401, or a refresh grant it rejected). */
+export const CLAUDE_LOGIN_REJECTED = 'Login expired or was rejected. Log in again with Claude Code and save it.';
+
+/** The service did not accept the login. */
+export class ClaudeLoginRejectedError extends ClaudeRequestError {
+  constructor() { super(CLAUDE_LOGIN_REJECTED); }
+}
+
+/** The service refused a request for too many requests. That says nothing about the account's usage or login. */
+export class ClaudeRateLimitError extends ClaudeRequestError {
+  constructor(subjectArg: string, public readonly retryAt: string | null) {
+    super(`The ${subjectArg} service is rate limiting requests (HTTP 429); try again later.`);
+  }
+}
+
+export interface IClaudeRequest {
+  url: string;
+  method: 'GET' | 'POST';
+  headers: Record<string, string>;
+  body?: string;
+  /** What diagnostics call the service: `Claude account` reads `The Claude account service could not be reached.` */
+  subject: string;
+  timeoutMs: number;
+  signal?: AbortSignal;
+  /** Whether an error status's JSON body is read for the caller, such as an OAuth error code; otherwise it is discarded. */
+  readErrorBody?: boolean;
+  /** The clock a `Retry-After` delay is counted from. */
+  now: () => number;
+}
+
+export interface IClaudeResponse {
+  status: number;
+  /** The JSON object the service answered with; null for an empty body, a body that is not a JSON object, or an unread one. */
+  body: Record<string, unknown> | null;
+}
+
+const MAX_RESPONSE_BYTES = 1024 * 1024;
+
+/** The body as a JSON object, read to at most 1 MiB; null when it is empty or not a JSON object. */
+const jsonBody = async (responseArg: Response, subjectArg: string): Promise<Record<string, unknown> | null> => {
+  const reader = responseArg.body?.getReader();
+  if (!reader) return null;
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  try {
+    while (true) {
+      const part = await reader.read();
+      if (part.done) break;
+      size += part.value.byteLength;
+      if (size > MAX_RESPONSE_BYTES) { await reader.cancel(); throw new ClaudeRequestError(`The ${subjectArg} response is too large.`); }
+      chunks.push(part.value);
+    }
+  } finally { reader.releaseLock(); }
+  try { return credentialRecord(JSON.parse(Buffer.concat(chunks).toString('utf8'))); }
+  catch { return null; }
+};
+
+/**
+ * One request to a Claude account service, shaped like Claude Code's own but naming authswitch in its User-Agent:
+ * redirects refused, bounded in time and in size, and cancelled with the caller's signal. A rate limit is reported as
+ * `ClaudeRateLimitError`; every other status is the caller's to interpret.
+ */
+export const claudeRequest = async (fetcherArg: typeof fetch, requestArg: IClaudeRequest): Promise<IClaudeResponse> => {
+  const timeout = AbortSignal.timeout(requestArg.timeoutMs);
+  const signal = requestArg.signal ? AbortSignal.any([requestArg.signal, timeout]) : timeout;
+  try {
+    const response = await fetcherArg(requestArg.url, {
+      method: requestArg.method, redirect: 'error', signal, body: requestArg.body,
+      headers: { ...requestArg.headers, 'User-Agent': `authswitch/${commitinfo.version}` },
+    });
+    if (response.status === 429) {
+      await response.body?.cancel();
+      throw new ClaudeRateLimitError(requestArg.subject, retryAtFrom(response.headers.get('retry-after'), requestArg.now()));
+    }
+    if (!response.ok && !requestArg.readErrorBody) {
+      await response.body?.cancel();
+      return { status: response.status, body: null };
+    }
+    return { status: response.status, body: await jsonBody(response, requestArg.subject) };
+  } catch (error) {
+    if (signal.aborted) throw new ClaudeRequestError(`The ${requestArg.subject} request ${timeout.aborted ? 'timed out' : 'was cancelled'}.`);
+    if (error instanceof ClaudeRequestError) throw error;
+    throw new ClaudeRequestError(`The ${requestArg.subject} service could not be reached.`);
+  }
+};

package/ts/cliargs.ts

@@ -0,0 +1,71 @@
+import { duration } from './accounts.js';
+
+/** A command line a command cannot run with. The command prints the message and exits with status 2. */
+export class UsageError extends Error {}
+
+export interface ICommandArgsSpec {
+  /** Options that take a value: `--name value` or `--name=value`. */
+  values: readonly string[];
+  /** Options that take none. */
+  flags: readonly string[];
+  maxPositionals: number;
+  /** The message for an unknown option or one positional too many. */
+  usage: string;
+}
+
+export interface ICommandArgs {
+  /** Each given value option's value, by option name. */
+  values: ReadonlyMap<string, string>;
+  flags: ReadonlySet<string>;
+  positionals: readonly string[];
+}
+
+/**
+ * A command's own arguments: value options, flags and positionals. Every option is accepted at most once, and a value
+ * is taken as it is, even when it starts with `-`, so a prompt can itself contain an option.
+ */
+export const parseCommandArgs = (argsArg: readonly string[], specArg: ICommandArgsSpec): ICommandArgs => {
+  const values = new Map<string, string>();
+  const flags = new Set<string>();
+  const positionals: string[] = [];
+  for (let index = 0; index < argsArg.length; index++) {
+    const argument = argsArg[index];
+    const separator = argument.startsWith('--') ? argument.indexOf('=') : -1;
+    const name = separator < 0 ? argument : argument.slice(0, separator);
+    if (specArg.values.includes(name)) {
+      if (values.has(name)) throw new UsageError(`Use ${name} only once.`);
+      const value = separator < 0 ? argsArg[++index] : argument.slice(separator + 1);
+      if (value === undefined) throw new UsageError(`${name} requires a value.`);
+      values.set(name, value);
+    } else if (separator < 0 && specArg.flags.includes(argument)) {
+      if (flags.has(argument)) throw new UsageError(`Use ${argument} only once.`);
+      flags.add(argument);
+    } else if (argument.startsWith('-') || positionals.length >= specArg.maxPositionals) {
+      throw new UsageError(specArg.usage);
+    } else positionals.push(argument);
+  }
+  return { values, flags, positionals };
+};
+
+const DURATION_UNITS: Readonly<Record<string, number>> = { '': 1000, s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 };
+
+/**
+ * A duration option in milliseconds: whole seconds (`120`), or a number with a unit (`90s`, `2m`, `1h`, `1d`),
+ * within the bounds. Every unit the bounds message can name is accepted, so a value the message suggests parses.
+ */
+export const parseDurationOption = (nameArg: string, valueArg: string, boundsArg: { minMs: number; maxMs: number }): number => {
+  const match = /^(\d{1,7})([smhd]?)$/.exec(valueArg);
+  if (!match) throw new UsageError(`${nameArg} takes a duration such as 120, 90s or 2m.`);
+  const milliseconds = Number(match[1]) * DURATION_UNITS[match[2]];
+  if (milliseconds < boundsArg.minMs || milliseconds > boundsArg.maxMs) {
+    throw new UsageError(`${nameArg} must be from ${duration(boundsArg.minMs / 1000)} to ${duration(boundsArg.maxMs / 1000)}.`);
+  }
+  return milliseconds;
+};
+
+/** A whole-number option within the bounds. */
+export const parseIntegerOption = (nameArg: string, valueArg: string, boundsArg: { min: number; max: number }): number => {
+  const value = /^\d{1,6}$/.test(valueArg) ? Number(valueArg) : Number.NaN;
+  if (!(value >= boundsArg.min && value <= boundsArg.max)) throw new UsageError(`${nameArg} takes a whole number from ${boundsArg.min} to ${boundsArg.max}.`);
+  return value;
+};

package/ts/consoletable.ts

@@ -0,0 +1,62 @@
+import * as plugins from './plugins.js';
+import { bold, dim } from './formatting.js';
+
+export const consoleWidth = (): number => process.stdout.columns ?? 100;
+export const consoleHeading = (textArg: string): void => { process.stdout.write(`\n${bold(textArg)}\n`); };
+
+/**
+ * One note line beneath a table: dim, wrapped to the terminal, continuation lines under the prefix.
+ *
+ * Table cells wrap themselves (`overflow: 'wrap'` below), so a note is the only text a view writes that could run
+ * past the terminal. Words stay whole: one longer than the remaining width keeps its own line rather than being cut,
+ * so an account id or a URL stays selectable.
+ */
+export const consoleNote = (textArg: string, prefixArg = ''): void => {
+  const words = textArg.split(/\s+/).filter(Boolean);
+  if (!words.length) return;
+  const width = consoleWidth();
+  const indent = ' '.repeat(prefixArg.length);
+  const lines: string[] = [];
+  let line = `${prefixArg}${words[0]}`;
+  for (const word of words.slice(1)) {
+    if (line.length + 1 + word.length > width) { lines.push(line); line = `${indent}${word}`; }
+    else line += ` ${word}`;
+  }
+  lines.push(line);
+  for (const written of lines) process.stdout.write(`${dim(written)}\n`);
+};
+
+/**
+ * One table implementation for every command, including the label-per-line fallback on narrow terminals.
+ *
+ * `groupsArg` is smartconsole's optional visual grouping: a divider between runs of consecutive rows with
+ * different keys, and a colour line along the left edge per run. Keys are identities, never display labels,
+ * and the caller orders the rows so that every group is one run. Below 40 columns the fallback separates
+ * divider runs with one dim rule line; it has no left edge, so it draws no colour line, and it repeats a
+ * spanning cell on every row it covers. A column's `render` content is what both layouts show.
+ */
+export const consoleTable = async <TRow>(
+  outArg: plugins.smartconsole.SmartConsole,
+  rowsArg: TRow[],
+  columnsArg: plugins.smartconsole.IBackendTableColumn<TRow>[],
+  groupsArg?: NoInfer<plugins.smartconsole.IBackendTableGroups<TRow>>,
+): Promise<void> => {
+  if (!rowsArg.length) return;
+  const width = consoleWidth();
+  if (width < 40) {
+    // smartconsole's run semantics: null and undefined are the same key.
+    const dividerKeys = rowsArg.map(row => groupsArg?.divider?.(row) ?? null);
+    const rule = `  ${dim('─'.repeat(Math.max(1, width - 4)))}\n\n`;
+    const content = (column: plugins.smartconsole.IBackendTableColumn<TRow>, row: TRow): string => column.render
+      ? plugins.smartconsole.color.plain(column.render(row)) : String(column.value(row) ?? 'Unavailable');
+    rowsArg.forEach((row, index) => {
+      if (index > 0 && dividerKeys[index] !== dividerKeys[index - 1]) process.stdout.write(rule);
+      process.stdout.write(columnsArg.map(column => `  ${column.title}: ${content(column, row).replace(/\n/g, '\n    ')}`).join('\n') + '\n\n');
+    });
+    return;
+  }
+  await outArg.table(rowsArg, {
+    columns: columnsArg, overflow: 'wrap', groups: groupsArg,
+    theme: { header: { bold: true, foreground: 'cyan' }, border: { dim: true } },
+  });
+};

package/ts/helpers.ts

@@ -53,6 +53,9 @@ export const writeSecretFileAtomically = (
   plugins.fs.chmodSync(destinationPathArg, 0o600);
 };
 
+/** A Node system error's code, for the distinctions the callers make (`EEXIST`, `ENOENT`, `ELOCKED`, `ERELEASED`). */
+export const errorCode = (errorArg: unknown): string | undefined => (errorArg as NodeJS.ErrnoException | null)?.code;
+
 /**
  * Blocks the calling thread for `millisecondsArg`.
  *
@@ -65,6 +68,17 @@ export const pauseSynchronously = (millisecondsArg: number): void => {
   Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, millisecondsArg);
 };
 
+/**
+ * Waits `millisecondsArg` without blocking the thread. An aborted signal rejects the wait with its reason and clears
+ * the timer at once, so an abandoned wait never keeps the process alive.
+ */
+export const pause = (millisecondsArg: number, signalArg?: AbortSignal): Promise<void> => new Promise<void>((resolve, reject) => {
+  if (signalArg?.aborted) { reject(signalArg.reason); return; }
+  const abort = (): void => { clearTimeout(timer); reject(signalArg!.reason); };
+  const timer = setTimeout(() => { signalArg?.removeEventListener('abort', abort); resolve(); }, Math.max(0, millisecondsArg));
+  signalArg?.addEventListener('abort', abort, { once: true });
+});
+
 /**
  * Trims third-party process output down to something safe to put in an error
  * message: one line, length-capped, and never empty.

package/ts/index.ts

@@ -20,6 +20,9 @@ export * from './classes.cli.js';
 export * from './classes.login.js';
 export * from './classes.operations.js';
 export * from './classes.service.js';
+export * from './classes.watch.js';
+export * from './classes.watchlock.js';
+export * from './watchpolicy.js';
 
 import { AuthSwitchCli } from './classes.cli.js';