@modelprofile.com/authswitch 3.3.0 → 4.0.0

package/ts/classes.listrenderer.ts

@@ -0,0 +1,328 @@
+import * as plugins from './plugins.js';
+import { accountUsageWindows, compactUsageLine, credentialDriftProblem, localDate, localDateTime, localiseTimestamps } from './accounts.js';
+import { accountBilling, accountCell, accountLimits, accountType, CondensedRenderer, nextRenewal, renewalCell, UNAVAILABLE, usageColor, type THarnessTraits } from './classes.limits.js';
+import { consoleHeading, consoleNote, consoleTable, consoleWidth } from './consoletable.js';
+import type { IHarnessStatusFact, IHarnessStatusSummary } from './interfaces.harness.js';
+import type { IAccountList, IAccountLimitRow, IHarnessAccountList } from './interfaces.list.js';
+import { orange, plainText } from './formatting.js';
+
+type TListedAccount = IHarnessAccountList['accounts'][number];
+type TNamedAccount = TListedAccount & { name: string };
+type TText = plugins.smartconsole.TText;
+
+const { color } = plugins.smartconsole;
+const dimText = (textArg: string): TText => color.text(textArg, { dim: true });
+/** Cell lines, one per part; parts that are null are left out. */
+const stack = (...partsArg: (TText | null)[]): TText =>
+  color.concat(...partsArg.filter((part): part is TText => part !== null).flatMap((part, index) => index ? ['\n', part] : [part]));
+
+/** How many dated rows a date series keeps: the newest week, as the providers report daily totals. */
+const DATED_ROWS = 7;
+const DATED_LABEL = /\d{4}-\d{2}-\d{2}$/;
+/** A problem that names what failed before its message: `Usage: Claude account service returned HTTP 429.` */
+const TOPIC_PROBLEM = /^([^:.]{1,40}): (.+)$/s;
+/** A saved-login note of the form `name: value` or `name:value`. */
+const NOTE_PAIR = /^([^:]{1,40}):\s*(.+)$/s;
+
+/**
+ * Names every account of one harness by its label, numbering each later account that repeats a label
+ * (`alice@example.com (2)`), so all tables name an account alike and the metric columns stay distinct.
+ */
+const nameAccounts = (accountsArg: TListedAccount[]): TNamedAccount[] => {
+  const labels = accountsArg.map(account => plainText(account.label));
+  const taken = new Set(labels);
+  return accountsArg.map((account, index) => {
+    const label = labels[index];
+    let name = label;
+    if (labels.indexOf(label) < index) {
+      for (let ordinal = 2; taken.has(name); ordinal++) name = `${label} (${ordinal})`;
+      taken.add(name);
+    }
+    return { ...account, name };
+  });
+};
+
+/** Whether a fact restates a structured field that the Accounts or Limits table shows. */
+const shownSummaryField = (factArg: IHarnessStatusFact, summaryArg: IHarnessStatusSummary): boolean => {
+  switch (factArg.summaryKey) {
+    case 'subscription': return summaryArg.subscription !== undefined;
+    case 'billing': return summaryArg.billing !== undefined;
+    case 'usageWindows': return summaryArg.usageWindows !== undefined;
+    case 'resets': return summaryArg.resets !== undefined;
+    case 'resetDetails': return summaryArg.resets?.details !== undefined;
+    default: return false;
+  }
+};
+/** Facts the other tables already show: a displayed structured field, or the account's own label (a profile's email). */
+const covered = (factArg: IHarnessStatusFact, accountArg: TNamedAccount): boolean =>
+  (accountArg.status.summary !== undefined && shownSummaryField(factArg, accountArg.status.summary))
+  || plainText(factArg.value).toLowerCase() === plainText(accountArg.label).toLowerCase();
+
+const isSentence = (valueArg: string): boolean => /\s/.test(valueArg) && /[.!?]$/.test(valueArg);
+/** A topic continuing a list starts in lower case, unless its first word is a name (`OpenAI`). */
+const lowerFirst = (textArg: string): string => /^[A-Z][a-z]*(\s|$)/.test(textArg) ? `${textArg.charAt(0).toLowerCase()}${textArg.slice(1)}` : textArg;
+
+interface IDetailRow {
+  section: string;
+  label: string;
+  /** Value per account index. */
+  values: Map<number, string>;
+}
+type TDetailLine = IDetailRow | { section: string };
+
+interface IDetails {
+  /** Rows grouped by section, sections in first-seen order. */
+  sections: Map<string, IDetailRow[]>;
+  /** Sentences stated once instead of per account. */
+  notes: string[];
+}
+
+/**
+ * One comparison of everything the Accounts and Limits tables do not show, by section.
+ *
+ * A metric keeps one row across accounts, and a label an account repeats keeps a row per occurrence. A section of
+ * dated rows (daily totals) is merged across accounts and keeps the newest week. A sentence that every account in its
+ * section states identically is said once, as a note. Saved-login notes form their own section; a note that only
+ * restates the account's credential slot is left out, since the Accounts table names the slot.
+ */
+const collectDetails = (accountsArg: TNamedAccount[]): IDetails => {
+  const sections = new Map<string, Map<string, IDetailRow>>();
+  accountsArg.forEach((account, index) => {
+    const occurrences = new Map<string, number>();
+    const put = (sectionArg: string, labelArg: string, valueArg: string): void => {
+      const occurrenceKey = JSON.stringify([sectionArg, labelArg]);
+      const occurrence = occurrences.get(occurrenceKey) ?? 0;
+      occurrences.set(occurrenceKey, occurrence + 1);
+      const rows = sections.get(sectionArg) ?? new Map<string, IDetailRow>();
+      sections.set(sectionArg, rows);
+      const key = JSON.stringify([labelArg, occurrence]);
+      const row = rows.get(key) ?? { section: sectionArg, label: labelArg, values: new Map<number, string>() };
+      row.values.set(index, valueArg);
+      rows.set(key, row);
+    };
+    for (const fact of account.status.facts) {
+      if (!covered(fact, account)) put(plainText(fact.section ?? 'Additional information'), plainText(fact.label), localiseTimestamps(plainText(fact.value)));
+    }
+    for (const detail of account.details.map(plainText)) {
+      if (account.slotId !== undefined && detail === `Provider: ${plainText(account.slotId)}`) continue;
+      const pair = NOTE_PAIR.exec(detail);
+      put('Saved login', pair ? pair[1].trim() : 'Note', pair ? pair[2] : detail);
+    }
+  });
+  const notes: string[] = [];
+  const result = new Map<string, IDetailRow[]>();
+  for (const [section, keyed] of sections) {
+    const rows = [...keyed.values()];
+    const inSection = new Set(rows.flatMap(row => [...row.values.keys()]));
+    const dated = rows.filter(row => DATED_LABEL.test(row.label)).sort((left, right) => right.label.localeCompare(left.label)).slice(0, DATED_ROWS);
+    const kept: IDetailRow[] = [];
+    for (const row of [...dated, ...rows.filter(row => !DATED_LABEL.test(row.label))]) {
+      const values = [...new Set(row.values.values())];
+      if (values.length === 1 && isSentence(values[0]) && row.values.size === inSection.size) {
+        const names = row.values.size === accountsArg.length ? '' : `${[...row.values.keys()].map(index => accountsArg[index].name).join(', ')} — `;
+        notes.push(`${names}${row.label}: ${values[0]}`);
+      } else kept.push(row);
+    }
+    if (kept.length) result.set(section, kept);
+  }
+  return { sections: result, notes };
+};
+
+/**
+ * Problems with one message are merged, their topics joined: `Profile, usage: Login expired …`. Several topics take a
+ * line of their own and the message follows one sentence per line, so its words stay together in a narrow cell.
+ */
+const mergeProblems = (problemsArg: string[]): string[] => {
+  const topics = new Map<string, string[]>();
+  for (const problem of problemsArg.map(plainText)) {
+    const match = TOPIC_PROBLEM.exec(problem);
+    const message = match ? match[2] : problem;
+    const known = topics.get(message) ?? [];
+    if (match && !known.includes(match[1])) known.push(match[1]);
+    topics.set(message, known);
+  }
+  return [...topics].map(([message, names]) => !names.length ? message
+    : names.length === 1 ? `${names[0]}: ${message}`
+      : `${names.map((name, index) => index ? lowerFirst(name) : name).join(', ')}:\n${message.replace(/(?<=[.!?]) +(?=\S)/g, '\n')}`);
+};
+
+interface IProblemRow {
+  group: string;
+  accounts: string;
+  problem: string;
+}
+
+/** Shared, provider-independent list presentation: per harness an Accounts, a Limits, a Details and a Problems table. */
+export class AccountListRenderer {
+  constructor(private readonly out: plugins.smartconsole.SmartConsole) {}
+  private get width(): number { return consoleWidth(); }
+
+  public async render(listArg: IAccountList, harnessesArg: readonly THarnessTraits[]): Promise<void> {
+    const now = Date.parse(listArg.generatedAt);
+    if (!listArg.harnesses.length) process.stdout.write('No harnesses registered.\n');
+    const limits = accountLimits(listArg, harnessesArg).limits;
+    // The same harness order as `limits`: by provider name.
+    const order = [...new Set(limits.map(row => row.harnessId))];
+    const harnesses = [...listArg.harnesses].sort((left, right) => order.indexOf(left.id) - order.indexOf(right.id));
+    for (const harness of harnesses) {
+      consoleHeading(plainText(harness.label));
+      if (harness.problems.length) {
+        for (const problem of harness.problems) process.stdout.write(`${orange('Unavailable')}: ${plainText(problem)}\n`);
+        continue;
+      }
+      if (!harness.accounts.length) {
+        consoleNote(plainText(harness.saveUnavailableReason ?? 'No known accounts. ' + harness.loginHint));
+        continue;
+      }
+      const accounts = nameAccounts(harness.accounts);
+      const slots = new Set(harness.accounts.map(account => account.slotId)).size > 1;
+      await this.accounts(accounts, slots, now);
+      // The Renewal cell can only read `n/a` for such a provider, so the declaration explains it here as it does in `limits`.
+      const renewalUnavailable = harnessesArg.find(traits => traits.id === harness.id)?.renewalUnavailableReason;
+      if (renewalUnavailable !== undefined) consoleNote(`${plainText(harness.label)}: ${plainText(renewalUnavailable)}`, `Renewal ${UNAVAILABLE} — `);
+      const names = new Map(accounts.map(account => [account.id, account.name]));
+      const limitRows: IAccountLimitRow[] = limits
+        .filter(row => row.harnessId === harness.id && row.limitType !== null)
+        .map(row => ({ ...row, account: row.accountId === null ? row.account : names.get(row.accountId) ?? row.account }));
+      if (limitRows.length) {
+        process.stdout.write('\n');
+        await new CondensedRenderer(this.out).limitsTable(limitRows, { provider: false, renewal: false, slots });
+      }
+      await this.details(accounts);
+      await this.problems(harness, accounts);
+    }
+  }
+
+  private async accounts(accountsArg: TNamedAccount[], slotsArg: boolean, nowArg: number): Promise<void> {
+    /** Whether the account is active and saved, then when it was saved; an active login without a save says so instead. */
+    const status = (account: TNamedAccount): TText => stack(
+      account.isActive ? color.text(account.isStashed ? 'active, saved' : 'active', { foreground: 'green', bold: false })
+        : color.text(account.isStashed ? 'saved' : 'not saved', { foreground: account.isStashed ? undefined : 'orange', bold: false }),
+      account.savedAt !== null ? dimText(localDateTime(account.savedAt))
+        : account.isActive && !account.isStashed ? color.text('not saved', { foreground: 'orange', bold: false }) : null,
+    );
+    const usage = (account: TNamedAccount): TText => {
+      const windows = accountUsageWindows(account);
+      if (windows === undefined) return dimText(`usage ${UNAVAILABLE}`);
+      if (!windows.length) return dimText('no usage reported');
+      return stack(...windows.map(window => color.text(compactUsageLine(window, windows, nowArg), { foreground: usageColor(window.severity ?? null, window.usedPercent) })));
+    };
+    const reportsResets = accountsArg.some(account => account.status.summary?.resets !== undefined);
+    const resetsCell = (account: TNamedAccount): TText => {
+      const summary = account.status.summary?.resets;
+      if (summary === undefined) return dimText(UNAVAILABLE);
+      return stack(String(summary.available), ...(summary.details ?? []).map(detail =>
+        dimText(`${plainText(detail.kind)} ${plainText(detail.status)}${detail.expiresAt === null ? '' : ` · until ${localDate(detail.expiresAt)}`}`)));
+    };
+    /** Earned resets as extra cell lines, for the layouts without their own column; only where the harness reports any. */
+    const resets = (account: TNamedAccount): TText | null => reportsResets ? color.concat(dimText('earned resets: '), resetsCell(account)) : null;
+    const renewalLine = (account: TNamedAccount): TText => {
+      const renewal = nextRenewal(accountBilling(account));
+      return renewal === null ? dimText(`renewal ${UNAVAILABLE}`) : `renewal ${localDate(renewal.at)} · ${renewal.kind}`;
+    };
+    const account = (row: TNamedAccount): TText => accountCell({ account: row.name, accountType: accountType(row), slotId: row.slotId }, slotsArg);
+    type TColumn = plugins.smartconsole.IBackendTableColumn<TNamedAccount>;
+    const accountColumn = (render: (row: TNamedAccount) => TText): TColumn =>
+      ({ key: 'account', title: 'Account', value: row => row.name, render, style: row => ({ bold: row.isActive }) });
+    const statusColumn: TColumn = { key: 'status', title: 'Status', value: row => color.plain(status(row)), render: status };
+    const renewalColumn: TColumn = { key: 'renewal', title: 'Renewal', value: row => nextRenewal(accountBilling(row))?.at ?? UNAVAILABLE, render: row => renewalCell(accountBilling(row)) };
+    const usageValue = (row: TNamedAccount): string => color.plain(usage(row));
+    let columns: TColumn[];
+    if (this.width >= 120) {
+      columns = [accountColumn(account), statusColumn, { key: 'usage', title: 'Usage', value: usageValue, render: usage }, renewalColumn,
+        ...(reportsResets ? [{ key: 'resets', title: 'Earned resets', value: (row: TNamedAccount) => row.status.summary?.resets?.available, render: resetsCell }] : [])];
+    } else if (this.width >= 100) {
+      columns = [accountColumn(account), statusColumn, { key: 'usage', title: 'Usage', value: usageValue, render: row => stack(usage(row), resets(row)) }, renewalColumn];
+    } else if (this.width >= 60) {
+      columns = [accountColumn(row => stack(account(row), status(row))), { key: 'usage', title: 'Usage', value: usageValue, render: row => stack(usage(row), resets(row)) }, renewalColumn];
+    } else {
+      columns = [accountColumn(account), { ...statusColumn, render: row => stack(status(row), usage(row), renewalLine(row), resets(row)) }];
+    }
+    await consoleTable(this.out, accountsArg, columns, { divider: row => row.id });
+  }
+
+  /** The Details table, paged across as many account columns as the width holds, with its notes beneath. */
+  private async details(accountsArg: TNamedAccount[]): Promise<void> {
+    const { sections, notes } = collectDetails(accountsArg);
+    const rows = [...sections.values()].flat();
+    const withValues = accountsArg.map((_, index) => index).filter(index => rows.some(row => row.values.has(index)));
+    if (withValues.length) {
+      process.stdout.write('\n');
+      if (this.width < 40) this.narrowDetails(accountsArg, withValues, sections);
+      else {
+        // Section rows span the whole table, so only metric labels size the first column. A table is one edge plus, per
+        // column, its content, two spaces of padding and a rule; pages take accounts in order while they fit.
+        const labelWidth = Math.max('Metric'.length, ...rows.map(row => row.label.length));
+        const columnWidth = (indexArg: number): number => 3 + Math.min(40, Math.max(accountsArg[indexArg].name.length, ...rows.map(row => row.values.get(indexArg)?.length ?? 0)));
+        const pages: number[][] = [];
+        let used = 0;
+        for (const index of withValues) {
+          if (!pages.length || used + columnWidth(index) > this.width - 1) { pages.push([]); used = 1 + labelWidth + 3; }
+          pages[pages.length - 1].push(index);
+          used += columnWidth(index);
+        }
+        for (const page of pages) await this.detailsPage(accountsArg, page, sections);
+      }
+    }
+    if (notes.length) {
+      if (!withValues.length) process.stdout.write('\n');
+      for (const note of notes) consoleNote(note);
+    }
+  }
+
+  private async detailsPage(accountsArg: TNamedAccount[], indicesArg: number[], sectionsArg: Map<string, IDetailRow[]>): Promise<void> {
+    const lines: TDetailLine[] = [];
+    for (const [section, rows] of sectionsArg) {
+      const shown = rows.filter(row => indicesArg.some(index => row.values.has(index)));
+      if (shown.length) lines.push({ section }, ...shown);
+    }
+    const isRow = (lineArg: TDetailLine): lineArg is IDetailRow => 'values' in lineArg;
+    await consoleTable(this.out, lines, [
+      { key: 'metric', title: 'Metric', value: line => isRow(line) ? line.label : line.section,
+        colSpan: line => isRow(line) ? 1 : 1 + indicesArg.length, style: line => isRow(line) ? {} : { bold: true, foreground: 'cyan' } },
+      ...indicesArg.map((index): plugins.smartconsole.IBackendTableColumn<TDetailLine> => ({
+        key: `account-${index}`, title: accountsArg[index].name,
+        value: line => isRow(line) ? line.values.get(index) ?? UNAVAILABLE : line.section,
+        render: line => (isRow(line) ? line.values.get(index) : undefined) ?? dimText(UNAVAILABLE),
+      })),
+    ]);
+  }
+
+  private narrowDetails(accountsArg: TNamedAccount[], indicesArg: number[], sectionsArg: Map<string, IDetailRow[]>): void {
+    for (const index of indicesArg) {
+      process.stdout.write(`  Account: ${accountsArg[index].name}\n`);
+      for (const [section, rows] of sectionsArg) {
+        for (const row of rows) if (row.values.has(index)) process.stdout.write(`  - ${section} · ${row.label}: ${row.values.get(index)}\n`);
+      }
+    }
+  }
+
+  /** One Problems table: a changed active login first, then each account's merged problems, then the harness's own. */
+  private async problems(harnessArg: IHarnessAccountList, accountsArg: TNamedAccount[]): Promise<void> {
+    const rows: IProblemRow[] = harnessArg.credentialDrift.map((drift, index) => ({
+      group: `drift:${index}`,
+      accounts: accountsArg.find(account => account.id === drift.currentAccountId)?.name ?? (drift.currentLabel === null ? plainText(harnessArg.label) : plainText(drift.currentLabel)),
+      problem: credentialDriftProblem(harnessArg.id, drift),
+    }));
+    // Accounts with the same problems share one block.
+    const blocks = new Map<string, { names: string[]; problems: string[] }>();
+    for (const account of accountsArg) {
+      const problems = mergeProblems(account.status.problems);
+      if (!problems.length) continue;
+      const key = JSON.stringify(problems);
+      const block = blocks.get(key) ?? { names: [], problems };
+      block.names.push(account.name);
+      blocks.set(key, block);
+    }
+    // One line, not one name per line: a row-spanned cell lays its lines onto the rows it covers, which would read
+    // as "this account has this problem" for a block whose accounts all have all of them.
+    for (const [key, block] of blocks) rows.push(...block.problems.map(problem => ({ group: key, accounts: block.names.join(', '), problem })));
+    if (harnessArg.saveUnavailableReason !== null) rows.push({ group: 'harness', accounts: plainText(harnessArg.label), problem: plainText(harnessArg.saveUnavailableReason) });
+    if (!rows.length) return;
+    process.stdout.write('\n');
+    await consoleTable(this.out, rows, [
+      { key: 'account', title: 'Account', value: row => row.accounts, rowSpan: plugins.smartconsole.rowSpansBy(rows, row => row.group) },
+      { key: 'problem', title: 'Problem', value: row => row.problem, style: row => ({ foreground: row.group.startsWith('drift:') ? 'orange' : undefined }) },
+    ], { divider: row => row.group });
+  }
+}

package/ts/classes.login.ts

@@ -65,7 +65,7 @@ export class AuthSwitchLogin {
 
 /** A hosted or terminal UI sees only the prompt and saved-account outcome. */
 export const beginSavedOpenAiLogin = async (
-  save: (result: IAuthLoginResult) => IHarnessLoginResult,
+  save: (result: IAuthLoginResult) => IHarnessLoginResult | Promise<IHarnessLoginResult>,
   options: IHarnessLoginOptions,
   fetcher?: typeof fetch,
 ): Promise<IHarnessLoginHandle> => {

package/ts/classes.opencodeharness.ts

@@ -22,6 +22,10 @@ export class OpenCodeHarness extends FileHarness {
   public readonly id = 'opencode';
   public readonly label = 'OpenCode';
   public readonly loginHint = 'Use authswitch opencode login for OpenAI; use opencode auth login for other providers.';
+  /** OpenCode loads provider credentials at startup (1.18.28), so a running instance keeps its login until restarted. */
+  public readonly liveSwap = false;
+  /** Only its OpenAI login reports usage, and a supervisor (AGL) restarts it around a switch, so a watch leaves it alone. */
+  public readonly autoSwitch = false;
   public readonly loginProviders: IHarnessLoginProvider[] = [{ providerId: 'openai', label: 'OpenAI', flows: ['device'] }];
   protected readonly store: CredentialStore;
   private readonly file: string;
@@ -47,8 +51,8 @@ export class OpenCodeHarness extends FileHarness {
     return account ? this.openAiInfo(account.credential).accountId : undefined;
   }
   public beginLogin(options: IHarnessLoginOptions = { providerId: 'openai', flow: 'device' }) {
-    return beginSavedOpenAiLogin(result => {
-      const saved = this.importCredential('openai', openCodeCredentialFromLogin(result.credential));
+    return beginSavedOpenAiLogin(async result => {
+      const saved = await this.importCredential('openai', openCodeCredentialFromLogin(result.credential));
       const account = this.readState().accounts.find(account => account.id === saved.accountId)!;
       return { outcome: { lines: [`Saved OpenAI login for ${plainText(account.label)}. Select it to switch OpenCode.`], problems: [] }, account: { id: account.id, label: account.label, slotId: account.slotId } };
     }, options, this.fetcher);

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)}`;
+  }
+};