@modelprofile.com/authswitch 3.3.0 → 4.0.0

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';
 

package/ts/interfaces.harness.ts

@@ -53,8 +53,9 @@ export interface IHarnessProcessControl {
  * A live credential that no longer holds the account the last switch activated.
  *
  * Authswitch records the hash of what it wrote, in its own store. A different hash with the same
- * account is that account's own token refresh; a different account is what a running instance
- * writing its in-memory login back looks like.
+ * account is that account's own token refresh; a different account means the login changed outside
+ * authswitch -- a new native login, or, for a harness that does not pick up swaps live, a running
+ * instance writing its in-memory login back.
  */
 export interface IHarnessCredentialDrift {
   slotId?: string;
@@ -97,6 +98,12 @@ export interface IHarnessAccountStatus {
   problems: string[];
   /** Optional structured data for shared presentation; never parse the display facts. */
   summary?: IHarnessStatusSummary;
+  /**
+   * Set when the provider refused a lookup for too many requests (HTTP 429). It says nothing about the account's
+   * usage: callers back off, never read it as an exhausted or expired login. `retryAt` is when the provider asked to
+   * be tried again (ISO 8601 UTC), or null when it did not say.
+   */
+  rateLimit?: { retryAt: string | null };
 }
 
 export interface IHarnessStatusFact {
@@ -138,11 +145,19 @@ export interface IAccountType {
   source: 'live' | 'stored';
 }
 
+/** Live billing information only. Never infer these fields from a plan or entitlement expiry. Dates are ISO 8601 UTC. */
+export interface IHarnessBilling {
+  hasActiveSubscription?: boolean;
+  autoRenew?: boolean;
+  renewsAt?: string;
+  cancelsAt?: string;
+  expiresAt?: string;
+}
+
 export interface IHarnessStatusSummary {
   /** A plan name does not imply an active billing status. */
   subscription?: IAccountType;
-  /** Live billing information only. Never infer these fields from a plan or entitlement expiry. */
-  billing?: { hasActiveSubscription?: boolean; autoRenew?: boolean; renewsAt?: string; cancelsAt?: string; expiresAt?: string };
+  billing?: IHarnessBilling;
   /** Missing windows are unknown, not unused. Times are ISO 8601 UTC. */
   usageWindows?: IHarnessUsageWindow[];
   resets?: {
@@ -157,10 +172,25 @@ export interface IHarnessOutcome {
   problems: string[];
 }
 
-/** A read-only status lookup. */
+/**
+ * A caller's status-reading session, such as one `authswitch watch`. Within it an adapter may reuse a lookup whose
+ * answer rarely changes (a Claude profile) instead of repeating it on every read; outside a session every lookup is live.
+ */
+export interface IHarnessStatusSession {
+  /**
+   * The value `lookupArg` resolved to under `keyArg` less than `maxAgeMsArg` ago, otherwise the lookup's fresh result,
+   * which is then remembered. A rejected lookup is never remembered. Keys belong to the adapter that uses them, which
+   * prefixes them with its own id, so a key always names values of one type.
+   */
+  reuse<T>(keyArg: string, maxAgeMsArg: number, lookupArg: () => Promise<T>): Promise<T>;
+}
+
+/** One status lookup; see `IAuthHarness.readAccountStatus` for what it may and may not change. */
 export interface IHarnessStatusOptions {
   /** Cancels the lookup's requests; an adapter still bounds each request with its own timeout. */
   signal?: AbortSignal;
+  /** The session the read belongs to, when the caller reads the same accounts repeatedly. */
+  session?: IHarnessStatusSession;
 }
 
 /** A single text-only inference request. Credentials remain inside the adapter. */
@@ -188,6 +218,31 @@ export interface IAuthHarness {
   readState(): THarnessResult<IHarnessState>;
   /** Running instances of this harness, when the adapter owns their lifecycle. */
   readonly processes?: IHarnessProcessControl;
+  /**
+   * Whether running instances pick up a credential swap by themselves, on their next request.
+   *
+   * Such a harness is never offered a stop before a switch, and its outcomes carry no restart advice;
+   * an explicit stop request is still honoured through `processes`. Absent means running instances keep
+   * the login they loaded until they are restarted.
+   */
+  readonly liveSwap?: boolean;
+  /**
+   * Set when this harness's provider never reports renewal or cancellation dates, as a lower-case clause
+   * that completes "<label>: ...". Views then explain the missing dates once instead of per account.
+   */
+  readonly renewalUnavailableReason?: string;
+  /**
+   * Whether `authswitch watch` may switch this harness's login by itself when the active account runs out: every
+   * saved account's usage can be read, and a switch needs no session of the user's stopped. A helper process the
+   * adapter manages itself may still be restarted by its own switch -- Codex' app-server is, because its
+   * credential file cannot be rewritten underneath it. Absent means the watch never switches this harness.
+   */
+  readonly autoSwitch?: boolean;
+  /**
+   * The account's live status. It must never activate, switch or clear a login. It may renew the tokens of the
+   * saved copy it reads when the provider leaves it no other way to answer -- the Claude Code adapter does, for
+   * saved and inactive logins only, under its store's lock -- and must leave the active login's credential alone.
+   */
   readAccountStatus(accountIdArg: string, optionsArg?: IHarnessStatusOptions): Promise<IHarnessAccountStatus>;
   readonly loginProviders?: IHarnessLoginProvider[];
   beginLogin?(options: IHarnessLoginOptions): Promise<IHarnessLoginHandle>;

package/ts/interfaces.list.ts

@@ -1,4 +1,4 @@
-import type { IAccountType, IHarnessAccount, IHarnessAccountStatus, IHarnessCredentialDrift, TUsageSeverity } from './interfaces.harness.js';
+import type { IAccountType, IHarnessAccount, IHarnessAccountStatus, IHarnessBilling, IHarnessCredentialDrift, TUsageSeverity } from './interfaces.harness.js';
 
 /** Credential-free, versioned output of list --json. Missing status fields stay omitted. */
 export interface IAccountList {
@@ -41,6 +41,8 @@ export interface IAccountLimitRow {
   isActive: boolean;
   /** The adapter's plan name (`max`, `pro`), sanitised but not display-formatted; null when none is known or the row names no account. */
   accountType: IAccountType | null;
+  /** The account's live billing fields as its provider reported them (ISO UTC dates); null when none were reported or the row names no account. */
+  billing: IHarnessBilling | null;
   /** The provider's own window name, or null when no limit data is available. */
   limitType: string | null;
   scope: 'account' | 'feature' | null;

package/ts/plugins.ts

@@ -13,6 +13,15 @@ const nativeRequire = createRequire(import.meta.url);
 /** SQLite is needed only when accessing a Codex state database, not when hosting account APIs. */
 export const loadSqlite = (): typeof import('node:sqlite') => nativeRequire('node:sqlite');
 
+// third party modules
+import type * as properLockfile from 'proper-lockfile';
+export type TProperLockfile = typeof properLockfile;
+/**
+ * Claude Code's own lock library, loaded on first use: it installs process exit hooks when it loads, which a
+ * process that never changes a Claude Code login (such as a host embedding the account service) does not need.
+ */
+export const loadProperLockfile = (): Promise<TProperLockfile> => import('proper-lockfile');
+
 // @push.rocks modules
 import * as smartconsole from '@push.rocks/smartconsole';
 export { smartconsole };

package/ts/ratelimit.ts

@@ -0,0 +1,14 @@
+/**
+ * When a provider that answered HTTP 429 asked to be tried again, read from its `Retry-After` header (RFC 9110: a
+ * number of seconds, or an HTTP date) and returned as ISO 8601 UTC. An absent or unreadable header is null: the
+ * provider did not say, and the caller picks its own backoff.
+ */
+export const retryAtFrom = (headerArg: string | null, nowArg: number): string | null => {
+  const value = headerArg?.trim() ?? '';
+  const time = /^\d{1,9}$/.test(value) ? nowArg + Number(value) * 1000 : /^[A-Za-z]{3}, .+ GMT$/.test(value) ? Date.parse(value) : Number.NaN;
+  return Number.isFinite(time) ? new Date(time).toISOString() : null;
+};
+
+/** The latest retry time several refused requests asked for; null when none of them said. */
+export const latestRetryAt = (retryAtsArg: readonly (string | null)[]): string | null =>
+  retryAtsArg.filter((value): value is string => value !== null).sort().at(-1) ?? null;

package/ts/watchpolicy.ts

@@ -0,0 +1,121 @@
+import { compactUntil, usagePercentText } from './accounts.js';
+import { plainText } from './formatting.js';
+import type { IHarnessUsageWindow } from './interfaces.harness.js';
+
+/** What a watch knows about one account of a harness when it decides. */
+export interface IWatchReading {
+  id: string;
+  label: string;
+  /** Only a saved account can be switched to. */
+  isSaved: boolean;
+  /** The provider's usage windows from a reading recent enough to act on; null while the usage is unknown. */
+  windows: readonly IHarnessUsageWindow[] | null;
+  /** Why the usage is unknown, for a decision that depends on it. */
+  unknownReason?: string;
+}
+
+export interface IWatchPolicyInput {
+  activeId: string | null;
+  readings: readonly IWatchReading[];
+  /** The used percentage at which a window counts as used up. */
+  threshold: number;
+  /** A used-up account is traded for another used-up one only when that one is usable again more than this much sooner. */
+  intervalMs: number;
+  now: number;
+}
+
+/** `ok` says whether the active account is fine; a stay that is not ok still has nothing better to switch to. */
+export type TWatchDecision =
+  | { action: 'stay'; ok: boolean; reason: string }
+  | { action: 'switch'; target: string; reason: string };
+
+/**
+ * How far below the threshold a switch target must be on every limit, so that a switch never lands on an account that
+ * is about to reach it and the watch never flips back and forth.
+ */
+const WATCH_HYSTERESIS = 10;
+
+const accountWindows = (readingArg: IWatchReading): IHarnessUsageWindow[] => (readingArg.windows ?? []).filter(window => window.scope !== 'feature');
+const featureWindows = (readingArg: IWatchReading): IHarnessUsageWindow[] => (readingArg.windows ?? []).filter(window => window.scope === 'feature');
+
+/** The fullest of the windows at or above the threshold (the longer one on a tie), which names why an account is limited. */
+const fullest = (windowsArg: readonly IHarnessUsageWindow[], thresholdArg: number): IHarnessUsageWindow | undefined =>
+  windowsArg.filter(window => window.usedPercent >= thresholdArg)
+    .sort((left, right) => right.usedPercent - left.usedPercent || right.durationSeconds - left.durationSeconds)[0];
+
+const limitText = (windowArg: IHarnessUsageWindow, thresholdArg: number): string =>
+  `${plainText(windowArg.label)} ${usagePercentText(windowArg.usedPercent)} ≥ ${thresholdArg}%`;
+
+/** When a window resets; one without a known reset never does. */
+const resetTime = (windowArg: IHarnessUsageWindow): number => {
+  const time = windowArg.resetAt === null ? Number.NaN : Date.parse(windowArg.resetAt);
+  return Number.isFinite(time) ? time : Number.POSITIVE_INFINITY;
+};
+
+/** When every one of the account's used-up windows has reset. */
+const usableAt = (readingArg: IWatchReading, thresholdArg: number): number =>
+  Math.max(...accountWindows(readingArg).filter(window => window.usedPercent >= thresholdArg).map(resetTime));
+
+/** The reset of the account's longest window: capacity that expires first is used first. */
+const longestWindowReset = (readingArg: IWatchReading): number => {
+  const windows = accountWindows(readingArg);
+  const longest = Math.max(...windows.map(window => window.durationSeconds));
+  return Math.min(...windows.filter(window => window.durationSeconds === longest).map(resetTime));
+};
+
+const peakUsage = (readingArg: IWatchReading): number => Math.max(...accountWindows(readingArg).map(window => window.usedPercent));
+
+/** Numbers that are both unbounded compare as equal, so the next key decides. */
+const ascending = (leftArg: number, rightArg: number): number => leftArg === rightArg ? 0 : leftArg < rightArg ? -1 : 1;
+const byLabel = (leftArg: IWatchReading, rightArg: IWatchReading): number =>
+  leftArg.label.localeCompare(rightArg.label) || leftArg.id.localeCompare(rightArg.id);
+const byPreference = (leftArg: IWatchReading, rightArg: IWatchReading): number =>
+  ascending(longestWindowReset(leftArg), longestWindowReset(rightArg)) || ascending(peakUsage(leftArg), peakUsage(rightArg)) || byLabel(leftArg, rightArg);
+
+/**
+ * Which account a harness should use, from one set of readings. Pure: the same input always decides the same.
+ *
+ * - The active account is used up when any of its account windows is at or above the threshold. The watch then
+ *   switches to the saved account whose account windows are all at least `WATCH_HYSTERESIS` points below it,
+ *   preferring the one whose longest window resets soonest, then the least used, then by label.
+ * - When no account qualifies and every other saved account with a known reading is used up too, it switches to the
+ *   one that is usable again first, and only when that is more than one interval sooner than the active account.
+ * - An active account limited only on a feature window (one model) switches to an account that is below the margin on
+ *   every window; without one it stays, because the active account still serves everything else.
+ * - A reading that is unknown, whatever the cause, never counts as used up and never makes an account a target.
+ */
+export const decideWatchAction = (inputArg: IWatchPolicyInput): TWatchDecision => {
+  const { threshold } = inputArg;
+  const stay = (okArg: boolean, reasonArg: string): TWatchDecision => ({ action: 'stay', ok: okArg, reason: reasonArg });
+  const active = inputArg.readings.find(reading => reading.id === inputArg.activeId);
+  if (!active) return stay(false, 'no active login');
+  if (active.windows === null) return stay(false, `usage unknown${active.unknownReason ? ` (${active.unknownReason})` : ''}`);
+  const margin = threshold - WATCH_HYSTERESIS;
+  const known = inputArg.readings.filter(reading => reading.id !== active.id && reading.isSaved && reading.windows !== null);
+  const below = (windowsArg: readonly IHarnessUsageWindow[]): boolean => windowsArg.every(window => window.usedPercent < margin);
+  const best = (candidatesArg: IWatchReading[]): IWatchReading | undefined => candidatesArg.sort(byPreference)[0];
+
+  const usedUp = fullest(accountWindows(active), threshold);
+  if (usedUp) {
+    const limit = limitText(usedUp, threshold);
+    const target = best(known.filter(reading => accountWindows(reading).length > 0 && below(accountWindows(reading))));
+    if (target) return { action: 'switch', target: target.id, reason: limit };
+    const exhausted = known.filter(reading => fullest(accountWindows(reading), threshold) !== undefined);
+    if (!exhausted.length || exhausted.length < known.length) return stay(false, `${limit}; no other saved account is known to be below ${margin}%`);
+    const soonest = exhausted.map(reading => ({ reading, at: usableAt(reading, threshold) }))
+      .sort((left, right) => ascending(left.at, right.at) || byLabel(left.reading, right.reading))[0];
+    if (soonest.at < usableAt(active, threshold) - inputArg.intervalMs) {
+      return { action: 'switch', target: soonest.reading.id, reason: `${limit}; every saved account is used up, and ${plainText(soonest.reading.label)} is usable again first (in ${compactUntil(new Date(soonest.at).toISOString(), inputArg.now)})` };
+    }
+    return stay(false, `${limit}; every saved account is used up, and none is usable again sooner`);
+  }
+
+  const featureLimit = fullest(featureWindows(active), threshold);
+  if (featureLimit) {
+    const limit = limitText(featureLimit, threshold);
+    const target = best(known.filter(reading => accountWindows(reading).length > 0 && below(reading.windows!)));
+    if (target) return { action: 'switch', target: target.id, reason: limit };
+    return stay(false, `${limit}; no other saved account is known to be below ${margin}% on every limit`);
+  }
+  return stay(true, `every limit below ${threshold}%`);
+};