@modelprofile.com/authswitch 2.3.0 → 3.1.0

package/ts/classes.limits.ts

@@ -1,7 +1,8 @@
 import * as plugins from './plugins.js';
-import { compactSince, compactUntil, orderedUsageWindows } from './accounts.js';
+import { compactSince, compactUntil, credentialDriftNote, orderedUsageWindows } from './accounts.js';
 import { consoleHeading, consoleTable } from './classes.accountlist.js';
-import type { IAccountList, IAccountLimitRow, IAccountLimits, IActiveAccountRow, IActiveAccounts, IHarnessAccountList } from './interfaces.list.js';
+import type { IAccountList, IAccountLimitRow, IAccountLimits, IActiveAccountDrift, IActiveAccountRow, IActiveAccounts, IHarnessAccountList } from './interfaces.list.js';
+import type { IHarnessCredentialDrift, TUsageSeverity } from './interfaces.harness.js';
 import { dim, plainText } from './formatting.js';
 
 type TListedAccount = IHarnessAccountList['accounts'][number];
@@ -34,7 +35,7 @@ const missingLimitReason = (accountArg: TListedAccount): string => {
   if (accountArg.status.summary?.usageWindows === undefined) {
     return availability[0] ?? 'This login does not expose a usage or quota API.';
   }
-  return 'The provider reported no usage window for this account.';
+  return 'The provider reported no usage window that authswitch can show for this account.';
 };
 
 const accountKeys = (harnessArg: IHarnessAccountList, accountArg: TListedAccount) => ({
@@ -60,6 +61,13 @@ const noteFor = (rowArg: { provider: string; account: string | null; unavailable
 const collectNotes = (rowsArg: { provider: string; account: string | null; unavailableReason: string | null }[]): string[] =>
   [...new Set(rowsArg.map(noteFor).filter((note): note is string => note !== null))];
 
+/** The drift a switch record proves, carried into the row document with both accounts named. */
+const activeDrift = (harnessArg: IHarnessAccountList, driftArg: IHarnessCredentialDrift): IActiveAccountDrift => ({
+  expectedAccountId: driftArg.expectedAccountId, expectedAccount: driftArg.expectedLabel === null ? null : plainText(driftArg.expectedLabel),
+  currentAccountId: driftArg.currentAccountId, currentAccount: driftArg.currentLabel === null ? null : plainText(driftArg.currentLabel),
+  currentIsSaved: driftArg.currentIsSaved, switchedAt: driftArg.switchedAt, reason: credentialDriftNote(harnessArg.id, driftArg),
+});
+
 /**
  * One row per account and limit type, projected from the account list.
  *
@@ -72,7 +80,7 @@ export const accountLimits = (listArg: IAccountList): IAccountLimits => {
   for (const harness of listArg.harnesses) {
     const problem = harnessProblem(harness);
     const empty = {
-      limitType: null, scope: null, windowSeconds: null, usedPercent: null, resetAt: null, resetsIn: UNAVAILABLE,
+      limitType: null, scope: null, windowSeconds: null, usedPercent: null, resetAt: null, resetsIn: UNAVAILABLE, severity: null, headline: false,
     } as const;
     if (problem !== null) {
       rows.push({ harnessId: harness.id, provider: providerName(harness), account: null, accountId: null, isActive: false, ...empty, unavailableReason: problem });
@@ -94,7 +102,7 @@ export const accountLimits = (listArg: IAccountList): IAccountLimits => {
           ...accountKeys(harness, account), isActive: account.isActive,
           limitType: plainText(window.label), scope: window.scope ?? 'account', windowSeconds: window.durationSeconds,
           usedPercent: window.usedPercent, resetAt: window.resetAt, resetsIn: compactUntil(window.resetAt, now, UNAVAILABLE),
-          unavailableReason: null,
+          severity: window.severity ?? null, headline: window.headline === true, unavailableReason: null,
         });
       }
     }
@@ -112,10 +120,16 @@ export const accountLimits = (listArg: IAccountList): IAccountLimits => {
 export const activeAccounts = (listArg: IAccountList): IActiveAccounts => {
   const now = Date.parse(listArg.generatedAt);
   const rows: IActiveAccountRow[] = [];
+  const unattached: string[] = [];
   for (const harness of listArg.harnesses) {
     const problem = harnessProblem(harness);
+    const drifts = [...harness.credentialDrift];
+    const driftFor = (slotIdArg?: string): IActiveAccountDrift | null => {
+      const index = drifts.findIndex(item => item.slotId === slotIdArg);
+      return index < 0 ? null : activeDrift(harness, drifts.splice(index, 1)[0]);
+    };
     if (problem !== null) {
-      rows.push({ harnessId: harness.id, provider: providerName(harness), account: null, accountId: null, savedAt: null, savedAgo: UNAVAILABLE, source: 'none', unavailableReason: problem });
+      rows.push({ harnessId: harness.id, provider: providerName(harness), account: null, accountId: null, savedAt: null, savedAgo: UNAVAILABLE, source: 'none', unavailableReason: problem, drift: null });
       continue;
     }
     const active = harness.accounts.filter(account => account.isActive);
@@ -127,24 +141,37 @@ export const activeAccounts = (listArg: IAccountList): IActiveAccounts => {
         unavailableReason: harness.saveUnavailableReason !== null ? plainText(harness.saveUnavailableReason)
           : stashed.length ? `No login is active; ${stashed.length} saved account(s) can be activated with authswitch ${plainText(harness.id)} use.`
             : `No login is active and none is saved. ${plainText(harness.loginHint)}`,
+        drift: drifts.length ? activeDrift(harness, drifts.shift()!) : null,
       });
-      continue;
-    }
-    for (const account of active) {
-      rows.push({
-        ...accountKeys(harness, account),
-        savedAt: account.savedAt, savedAgo: compactSince(account.savedAt, now, UNAVAILABLE),
-        source: 'credential file',
-        unavailableReason: account.isStashed ? null : 'This active login is not saved yet; authswitch cannot restore it after a switch.',
-      });
+    } else {
+      for (const account of active) {
+        rows.push({
+          ...accountKeys(harness, account),
+          savedAt: account.savedAt, savedAgo: compactSince(account.savedAt, now, UNAVAILABLE),
+          source: 'credential file',
+          unavailableReason: account.isStashed ? null : 'This active login is not saved yet; authswitch cannot restore it after a switch.',
+          drift: driftFor(account.slotId),
+        });
+      }
     }
+    // A drifted slot with no row of its own still has to be reported, not dropped.
+    for (const drift of drifts) unattached.push(`${providerName(harness)}${drift.slotId === undefined ? '' : ` / ${plainText(drift.slotId)}`}: ${credentialDriftNote(harness.id, drift)}`);
   }
   const active = byProviderThenAccount(rows);
-  return { schemaVersion: 1, generatedAt: listArg.generatedAt, complete: listArg.complete, active, notes: collectNotes(active) };
+  const driftNotes = active.filter(row => row.drift !== null)
+    .map(row => `${row.provider}${row.account === null ? '' : ` · ${row.account}`}: ${row.drift!.reason}`);
+  return { schemaVersion: 1, generatedAt: listArg.generatedAt, complete: listArg.complete, active, notes: [...collectNotes(active), ...driftNotes, ...unattached] };
 };
 
 const percent = (rowArg: IAccountLimitRow): string => rowArg.usedPercent === null ? UNAVAILABLE : `${rowArg.usedPercent}%`;
 
+const SEVERITY_COLORS: Record<TUsageSeverity, plugins.smartconsole.TColorName | undefined> = { normal: undefined, warning: 'orange', critical: 'red' };
+
+/** The provider's own reading colours a window; without one, n/a and exhausted windows stand out. */
+const percentColor = (rowArg: IAccountLimitRow): plugins.smartconsole.TColorName | undefined =>
+  rowArg.severity !== null ? SEVERITY_COLORS[rowArg.severity]
+    : rowArg.usedPercent === null ? 'orange' : rowArg.usedPercent >= 100 ? 'red' : undefined;
+
 /** Condensed presentation for `authswitch limits` and `authswitch active`. */
 export class CondensedRenderer {
   constructor(private readonly out: plugins.smartconsole.SmartConsole) {}
@@ -163,7 +190,7 @@ export class CondensedRenderer {
       { key: 'account', title: 'Account', value: row => row.account ?? UNAVAILABLE, style: row => ({ bold: row.isActive }) },
       { key: 'limit', title: 'Limit type', value: row => row.limitType ?? UNAVAILABLE },
       { key: 'used', title: 'Used %', value: percent, align: 'right',
-        style: row => ({ foreground: row.usedPercent === null ? 'orange' : row.usedPercent >= 100 ? 'red' : undefined }) },
+        style: row => ({ foreground: percentColor(row) }) },
       { key: 'reset', title: 'Resets in', value: row => row.resetsIn, align: 'right' },
     ]);
     this.notes(limitsArg.notes, 'n/a — ');
@@ -177,10 +204,12 @@ export class CondensedRenderer {
       { key: 'account', title: 'Account', value: row => row.account ?? NONE,
         style: row => ({ bold: row.account !== null, foreground: row.account === null ? 'orange' : undefined }) },
       // The absolute timestamp stays in --json; one screen is worth more here than one more column.
-      { key: 'saved', title: 'Saved', value: row => row.savedAt === null ? (row.account === null ? UNAVAILABLE : 'not saved') : `${row.savedAgo} ago`, align: 'right',
+      // "ago" belongs to a duration only; the unavailable marker is not one.
+      { key: 'saved', title: 'Saved', value: row => row.savedAt === null ? (row.account === null ? UNAVAILABLE : 'not saved')
+        : row.savedAgo === UNAVAILABLE ? UNAVAILABLE : `${row.savedAgo} ago`, align: 'right',
         style: row => ({ foreground: row.savedAt === null && row.account !== null ? 'orange' : undefined }) },
-      { key: 'source', title: 'Source', value: row => row.source,
-        style: row => ({ foreground: row.source === 'credential file' ? 'green' : 'orange' }) },
+      { key: 'source', title: 'Source', value: row => row.drift === null ? row.source : `${row.source} (changed)`,
+        style: row => ({ foreground: row.drift !== null ? 'red' : row.source === 'credential file' ? 'green' : 'orange' }) },
     ]);
     this.notes(activeArg.notes, 'note — ');
   }

package/ts/classes.opencodeharness.ts

@@ -1,9 +1,10 @@
 import * as plugins from './plugins.js';
 import { FileHarness, type IFileAccount, type IFileHarnessSnapshot } from './classes.fileharness.js';
-import { CredentialStore, credentialHash, credentialRecord, credentialText, readCredentialDocument, readCredentialRaw, requireHarnessStopped } from './classes.credentialstore.js';
+import { CredentialStore, credentialHash, credentialRecord, credentialText, readCredentialDocument, readCredentialRaw } from './classes.credentialstore.js';
+import { HarnessProcesses } from './classes.harnessprocesses.js';
 import { CodexAccountStatus } from './classes.codexstatus.js';
 import { writeSecretFileAtomically } from './helpers.js';
-import type { IHarnessAccountStatus, IHarnessLoginOptions, IHarnessLoginProvider } from './interfaces.harness.js';
+import type { IHarnessAccountStatus, IHarnessLoginOptions, IHarnessLoginProvider, IHarnessProcessControl } from './interfaces.harness.js';
 import { beginSavedOpenAiLogin, openCodeCredentialFromLogin } from './classes.login.js';
 import { plainText } from './formatting.js';
 
@@ -12,8 +13,8 @@ export interface IOpenCodeHarnessOptions {
   stashRoot?: string;
   env?: NodeJS.ProcessEnv;
   fetch?: typeof fetch;
-  /** Process inspection dependency, injectable for isolated installations and tests. */
-  checkStopped?: () => void;
+  /** Running-instance inspection, injectable for isolated installations and tests. */
+  processes?: IHarnessProcessControl;
 }
 
 /** OpenCode owns one login per provider. Replacing a slot never replaces the whole provider set. */
@@ -26,7 +27,7 @@ export class OpenCodeHarness extends FileHarness {
   private readonly file: string;
   private readonly env: NodeJS.ProcessEnv;
   private readonly status: CodexAccountStatus;
-  private readonly checkStopped: () => void;
+  public readonly processes: IHarnessProcessControl;
   private readonly fetcher?: typeof fetch;
 
   constructor(options: IOpenCodeHarnessOptions = {}) {
@@ -36,9 +37,8 @@ export class OpenCodeHarness extends FileHarness {
     this.store = new CredentialStore(this.id, options.stashRoot);
     this.status = new CodexAccountStatus(options.fetch);
     this.fetcher = options.fetch;
-    this.checkStopped = options.checkStopped ?? (() => requireHarnessStopped('opencode'));
+    this.processes = options.processes ?? new HarnessProcesses('opencode');
   }
-  protected beforeMutation(): void { this.checkStopped(); }
   /** Every provider entry lives in one file, so its bytes are the whole stability proof. */
   protected nativeSources(): (string | null)[] { return [readCredentialRaw(this.file)]; }
   /** Public identity only, for reconciling a host's OpenAI association after native refresh/restart. */

package/ts/classes.operations.ts

@@ -19,6 +19,14 @@ export type TAuthSwitchCoordinationResult =
   | { status: 'complete'; outcome: IHarnessOutcome };
 export type TAuthSwitchCoordinator = (request: IAuthSwitchCoordinationRequest) => Promise<TAuthSwitchCoordinationResult>;
 export type TAuthSwitchConfirmation = (message: string) => Promise<boolean>;
+/**
+ * Runs immediately before a mutation this process performs itself.
+ *
+ * It never runs when a supervisor completed the mutation: a client must not stop a process whose
+ * lifecycle another manager owns, and stopping it after that manager already restarted it would
+ * split one transaction across two owners.
+ */
+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(),
@@ -56,7 +64,7 @@ export const runAuthSwitchMutation = async (harness: IAuthHarness, mutation: TAu
 /** One mutation path for command, guide and TUI. Supervisors own their complete restart transaction. */
 export class AuthSwitchOperations {
   constructor(private readonly coordinator?: TAuthSwitchCoordinator) {}
-  public async run(harness: IAuthHarness, mutation: TAuthSwitchMutation, confirm?: TAuthSwitchConfirmation): Promise<IHarnessOutcome> {
+  public async run(harness: IAuthHarness, mutation: TAuthSwitchMutation, confirm?: TAuthSwitchConfirmation, prepareLocal?: TAuthSwitchLocalPreparation): Promise<IHarnessOutcome> {
     assertAuthSwitchMutation(mutation);
     if (harness.id !== mutation.harnessId) throw new Error('Account operation targets a different harness.');
     if (this.coordinator && mutation.action !== 'remove') {
@@ -69,6 +77,7 @@ export class AuthSwitchOperations {
       if (result.status === 'complete') return result.outcome;
       if (result.status === 'busy') return { lines: [], problems: [result.message] };
     }
+    if (prepareLocal) await prepareLocal();
     return runAuthSwitchMutation(harness, mutation);
   }
 }

package/ts/classes.tui.ts

@@ -1,8 +1,9 @@
 import * as plugins from './plugins.js';
-import type { IAuthHarness, IHarnessOutcome, IHarnessState } from './interfaces.harness.js';
-import { accountDetails, accountPlan, accountQuotaSummary, accountResets, accountState, accountUsageWindows, usagePeriod, until, readAccountRows, type IAccountRow } from './accounts.js';
+import type { IAuthHarness, IHarnessOutcome, IHarnessProcess, IHarnessState, IHarnessStopOutcome } from './interfaces.harness.js';
+import { accountDetails, accountPlan, accountQuotaSummary, accountResets, accountState, accountUsageWindows, usageWindowName, until, readAccountRows, type IAccountRow } from './accounts.js';
 import { plainText } from './formatting.js';
 import { AuthSwitchOperations } from './classes.operations.js';
+import { describeHarnessProcesses, describeStopOutcome } from './classes.harnessprocesses.js';
 
 /** Owns account-management actions; terminal rendering and interaction belong to smartconsole. */
 export class AuthSwitchTui {
@@ -59,6 +60,34 @@ export class AuthSwitchTui {
       catch { footer.setText(`Operation failed. Run authswitch ${harness.id} doctor for diagnostics.`); }
       updateDetails();
     };
+    /**
+     * Name the harness's running instances before a credential write, and stop them only on consent.
+     *
+     * 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.
+     */
+    const settleInstances = (screen: plugins.smartconsole.ITuiContext) => async (): Promise<void> => {
+      const control = harness.processes;
+      if (!control) return;
+      let running: IHarnessProcess[];
+      try { running = control.list(); }
+      catch { ui.logs.append(`Could not check for running ${plainText(harness.label)} processes.`); return; }
+      if (!running.length) return;
+      for (const line of describeHarnessProcesses(harness.label, running)) ui.logs.append(line);
+      if (control.stopUnavailableReason !== null) { ui.logs.append(control.stopUnavailableReason); return; }
+      const stoppable = running.filter(item => !item.isAncestor);
+      if (!stoppable.length || screen.signal.aborted) return;
+      if (!await screen.confirm(`Stop these ${stoppable.length} ${plainText(harness.label)} process(es) first?`, { confirmLabel: 'Stop them' })) return;
+      let outcome: IHarnessStopOutcome;
+      // Stopping re-reads the process table; if that read fails now, the switch is still the safe part.
+      try { outcome = await control.stop(stoppable); }
+      catch (error) {
+        ui.logs.append(`Could not stop the running ${plainText(harness.label)} process(es); leaving them running: ${plainText(error instanceof Error ? error.message : 'the process list could not be read.')}`);
+        return;
+      }
+      for (const line of describeStopOutcome(harness.label, outcome)) ui.logs.append(line);
+    };
     const save = async (screen: plugins.smartconsole.ITuiContext, keepActiveArg: boolean): Promise<void> => {
       const latest = await harness.readState();
       const activeAccounts = latest.accounts.filter(account => account.isActive);
@@ -67,7 +96,8 @@ export class AuthSwitchTui {
       if (!active || latest.saveUnavailableReason) { footer.setText(latest.saveUnavailableReason ?? 'No active login to save.'); return; }
       if (!await screen.confirm(`Save ${plainText(active.label)}${keepActiveArg ? ' and keep it active' : ' and clear the active login'}?`)) return;
       if (screen.signal.aborted) return;
-      const outcome = await this.operations.run(harness, { harnessId: harness.id, action: 'save', keepActive: keepActiveArg, accountId: active.id }, message => screen.confirm(message));
+      const outcome = await this.operations.run(harness, { harnessId: harness.id, action: 'save', keepActive: keepActiveArg, accountId: active.id },
+        message => screen.confirm(message), keepActiveArg ? undefined : settleInstances(screen));
       await refresh(screen); showOutcome(outcome);
     };
     const switchSelected = async (screen: plugins.smartconsole.ITuiContext): Promise<void> => {
@@ -87,7 +117,8 @@ export class AuthSwitchTui {
       }
       if (!await screen.confirm(`Switch ${plainText(harness.label)} to ${plainText(target.label)}?`, { confirmLabel: 'Switch' })) return;
       if (screen.signal.aborted) return;
-      const outcome = await this.operations.run(harness, { harnessId: harness.id, action: 'switch', accountId: target.id }, message => screen.confirm(message));
+      const outcome = await this.operations.run(harness, { harnessId: harness.id, action: 'switch', accountId: target.id },
+        message => screen.confirm(message), settleInstances(screen));
       await refresh(screen); showOutcome(outcome);
     };
     const remove = async (screen: plugins.smartconsole.ITuiContext): Promise<void> => {
@@ -109,9 +140,10 @@ export class AuthSwitchTui {
     const tabs = ui.tabs([{ title: 'Account details', content: details }, { title: 'Activity log', content: ui.logs }]);
     await ui.run({
       view: () => {
-        const usage = accountUsageWindows({ status: table.selected?.status })?.slice(0, 2).map(window => ui.progress(
-          `${usagePeriod(window)} (${window.usedPercent}% used; reset in ${until(window.resetAt, Date.now())})`, Math.min(100, window.usedPercent), 100,
-        )) ?? [];
+        const shown = accountUsageWindows({ status: table.selected?.status }) ?? [];
+        const usage = shown.slice(0, 2).map(window => ui.progress(
+          `${usageWindowName(window, shown)} (${window.usedPercent}% used; reset in ${until(window.resetAt, Date.now())})`, Math.min(100, window.usedPercent), 100,
+        ));
         const accountView = ui.column([
           ui.panel(`${plainText(harness.label)} accounts`, table),
           ui.panel('Status and diagnostics', ui.column([...usage, tabs])),

package/ts/index.ts

@@ -4,6 +4,7 @@ export * from './interfaces.list.js';
 export * from './classes.codexharness.js';
 export * from './classes.opencodeharness.js';
 export * from './classes.claudecodeharness.js';
+export * from './classes.harnessprocesses.js';
 export * from './classes.claudestatus.js';
 export * from './classes.codexstatus.js';
 export * from './classes.codexpreuse.js';

package/ts/interfaces.harness.ts

@@ -12,6 +12,64 @@ export interface IHarnessLoginHandle {
   close(): Promise<void>;
 }
 
+/** One running instance of a harness binary, owned by the current user. */
+export interface IHarnessProcess {
+  pid: number;
+  /** Executable name as the platform reports it, without a path. */
+  command: string;
+  /** Bounded command line, for identifying which instance this is. Never parsed for identity. */
+  commandLine: string;
+  /** Start time, which distinguishes a reused pid from the process we enumerated. */
+  startedAt: string | null;
+  /** An ancestor of the running authswitch command: stopping it would kill this command. */
+  isAncestor: boolean;
+}
+
+export interface IHarnessStopOutcome {
+  /** Instances that exited within the bounded wait. */
+  stopped: IHarnessProcess[];
+  /** Instances that were still running when the wait elapsed. */
+  survivors: IHarnessProcess[];
+  /** Instances that were re-verified and then killed, only ever with an explicit force request. */
+  forced: IHarnessProcess[];
+}
+
+/**
+ * Enumerating and stopping a harness's own running instances.
+ *
+ * Only pids this control enumerated for the current user are ever signalled, and a stop is graceful
+ * unless the caller explicitly forces it. Adapters whose process lifecycle belongs to another
+ * manager (Codex' app-server daemon) expose no control at all.
+ */
+export interface IHarnessProcessControl {
+  readonly binary: string;
+  /** Why enumerated instances cannot be signalled on this platform; null when they can. */
+  readonly stopUnavailableReason: string | null;
+  list(): IHarnessProcess[];
+  stop(processesArg: readonly IHarnessProcess[], optionsArg?: { force?: boolean; timeoutMs?: number }): Promise<IHarnessStopOutcome>;
+}
+
+/**
+ * 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.
+ */
+export interface IHarnessCredentialDrift {
+  slotId?: string;
+  /** The account the recorded switch activated. */
+  expectedAccountId: string;
+  /** Its saved label, or null when that account is no longer saved. */
+  expectedLabel: string | null;
+  /** The account the credential file holds now, or null when the slot has no active login. */
+  currentAccountId: string | null;
+  currentLabel: string | null;
+  /** Whether the current account has a saved copy of its own. */
+  currentIsSaved: boolean;
+  switchedAt: string;
+}
+
 /** Account IDs are opaque and scoped to one harness. Credentials never cross this interface. */
 export interface IHarnessAccount {
   id: string;
@@ -28,6 +86,8 @@ export interface IHarnessState {
   accounts: IHarnessAccount[];
   /** Explains why an active login cannot be saved, when applicable. */
   saveUnavailableReason: string | null;
+  /** Slots whose credential file no longer holds the account the last switch wrote. */
+  credentialDrift?: IHarnessCredentialDrift[];
 }
 
 export interface IHarnessAccountStatus {
@@ -48,20 +108,32 @@ export interface IHarnessStatusFact {
   summaryKey?: 'subscription' | 'billing' | 'usageWindows' | 'resets' | 'resetDetails';
 }
 
+/** The provider's own reading of a usage window. Adapters set it only when the provider reports one of these. */
+export type TUsageSeverity = 'normal' | 'warning' | 'critical';
+
+export interface IHarnessUsageWindow {
+  label: string;
+  /**
+   * Feature-specific quotas (a model, a surface, a product feature) do not determine the general
+   * account summary unless the provider picks one as its headline. Omission means account.
+   */
+  scope?: 'account' | 'feature';
+  durationSeconds: number;
+  usedPercent: number;
+  resetAt: string | null;
+  /** Omitted when the provider gives no reading; consumers then apply their own thresholds. */
+  severity?: TUsageSeverity;
+  /** Set when the provider picks this window as the one a single-value summary shows. */
+  headline?: true;
+}
+
 export interface IHarnessStatusSummary {
   /** A plan name does not imply an active billing status. */
   subscription?: { plan: string; source: 'live' | 'stored' };
   /** 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 };
   /** Missing windows are unknown, not unused. Times are ISO 8601 UTC. */
-  usageWindows?: {
-    label: string;
-    /** Feature-specific quotas do not determine the general account summary. Omission means account. */
-    scope?: 'account' | 'feature';
-    durationSeconds: number;
-    usedPercent: number;
-    resetAt: string | null;
-  }[];
+  usageWindows?: IHarnessUsageWindow[];
   resets?: {
     available: number;
     /** May be a partial list. Omission means the detail lookup was unavailable. */
@@ -97,6 +169,8 @@ export interface IAuthHarness {
   readonly loginHint: string;
   readonly diagnosticsLabel: string;
   readState(): THarnessResult<IHarnessState>;
+  /** Running instances of this harness, when the adapter owns their lifecycle. */
+  readonly processes?: IHarnessProcessControl;
   readAccountStatus(accountIdArg: string): Promise<IHarnessAccountStatus>;
   readonly loginProviders?: IHarnessLoginProvider[];
   beginLogin?(options: IHarnessLoginOptions): Promise<IHarnessLoginHandle>;

package/ts/interfaces.list.ts

@@ -1,4 +1,4 @@
-import type { IHarnessAccount, IHarnessAccountStatus } from './interfaces.harness.js';
+import type { IHarnessAccount, IHarnessAccountStatus, IHarnessCredentialDrift, TUsageSeverity } from './interfaces.harness.js';
 
 /** Credential-free, versioned output of list --json. Missing status fields stay omitted. */
 export interface IAccountList {
@@ -14,6 +14,8 @@ export interface IHarnessAccountList {
   loginHint: string;
   saveUnavailableReason: string | null;
   accounts: (IHarnessAccount & { status: IHarnessAccountStatus })[];
+  /** Slots whose credential file no longer holds the account the last switch wrote. */
+  credentialDrift: IHarnessCredentialDrift[];
   /** A state lookup failure is distinct from an empty account list. */
   problems: string[];
 }
@@ -46,6 +48,10 @@ export interface IAccountLimitRow {
   resetAt: string | null;
   /** Human countdown for the same `resetAt`, relative to `generatedAt`. */
   resetsIn: string;
+  /** The provider's reading of this window; null when it gave none or the row has no window. */
+  severity: TUsageSeverity | null;
+  /** Whether the provider picks this window as the one a single-value summary shows. */
+  headline: boolean;
   unavailableReason: string | null;
 }
 
@@ -71,4 +77,18 @@ export interface IActiveAccountRow {
   /** Where the shown account comes from. Whether it is also saved is the `savedAt` field's answer. */
   source: 'credential file' | 'stash only' | 'none';
   unavailableReason: string | null;
+  /** Set when the credential file no longer holds the account the last switch wrote. */
+  drift: IActiveAccountDrift | null;
+}
+
+/** A credential file that changed underneath a switch, with both accounts named where known. */
+export interface IActiveAccountDrift {
+  expectedAccountId: string;
+  expectedAccount: string | null;
+  currentAccountId: string | null;
+  currentAccount: string | null;
+  currentIsSaved: boolean;
+  switchedAt: string;
+  /** The sentence the table footnotes, for consumers that display one string. */
+  reason: string;
 }