@modelprofile.com/authswitch 3.3.0 → 5.0.0

package/ts/classes.codexstatus.ts

@@ -1,6 +1,8 @@
 import type { ICodexIdentity } from './interfaces.js';
 import type { IHarnessAccountStatus, IHarnessStatusOptions, IHarnessStatusSummary } from './interfaces.harness.js';
 import { commitinfo } from './00_commitinfo_data.js';
+import { usageWindowPeriod } from './accounts.js';
+import { latestRetryAt, retryAtFrom } from './ratelimit.js';
 
 // Verified Chromium-compatible billing request profile, independent of any locally installed browser.
 const billingUserAgent = 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36';
@@ -31,13 +33,22 @@ const count = (valueArg: unknown): number => {
 /** Only fixed, local diagnostics may cross the HTTP error boundary. */
 class StatusRequestError extends Error {}
 
+/** The service refused a section for too many requests; that says nothing about the account's usage. */
+class StatusRateLimitError extends StatusRequestError {
+  constructor(public readonly retryAt: string | null) { super('The service is rate limiting requests (HTTP 429); try again later.'); }
+}
+
 /**
- * Read-only ChatGPT status contract verified against Codex 0.154.0.
+ * Read-only ChatGPT status contract verified against Codex 0.155.0.
  * These source-defined backend routes are isolated here. No token refresh,
  * credential writes, app-server lifecycle changes or reset consumption occur.
+ *
+ * The service decides how many usage windows an account has: it sends the ones it keeps for that
+ * account, leaving the other slot `null`, so a login whose general quota is a single weekly window is
+ * reported with that one window and no five-hour limit is invented to fill the gap.
  */
 export class CodexAccountStatus {
-  constructor(private readonly fetcher: typeof fetch = globalThis.fetch) {}
+  constructor(private readonly fetcher: typeof fetch = globalThis.fetch, private readonly now: () => number = Date.now) {}
 
   public async read(rawArg: string, identityArg: ICodexIdentity, optionsArg: IHarnessStatusOptions = {}): Promise<IHarnessAccountStatus> {
     if (identityArg.kind !== 'chatgpt') return {
@@ -85,6 +96,8 @@ export class CodexAccountStatus {
       }
       catch { result.problems.push(`${labels[index]}: the service returned an unsupported response; no values were inferred.`); }
     }
+    const limited = sections.flatMap(section => section.status === 'rejected' && section.reason instanceof StatusRateLimitError ? [section.reason] : []);
+    if (limited.length) result.rateLimit = { retryAt: latestRetryAt(limited.map(error => error.retryAt)) };
     if (!result.summary?.subscription && identityArg.planType) {
       result.facts.unshift({ section: 'Subscription', summaryKey: 'subscription', label: 'Last known plan', value: `${identityArg.planType} (from stored login; not verified live)` });
       result.summary = { ...result.summary, subscription: { plan: identityArg.planType, source: 'stored' } };
@@ -105,6 +118,7 @@ export class CodexAccountStatus {
       if (!response.ok) {
         await response.body?.cancel();
         if (response.headers.get('cf-mitigated') === 'challenge') throw new StatusRequestError('Blocked by a service verification challenge (Cloudflare); this lookup is unavailable to the current HTTP client.');
+        if (response.status === 429) throw new StatusRateLimitError(retryAtFrom(response.headers.get('retry-after'), this.now()));
         if (response.status === 401) throw new StatusRequestError('Login expired or was rejected. Log in again with the account’s harness, then save the account.');
         if (response.status === 403) throw new StatusRequestError('Access denied by the service (HTTP 403).');
         throw new StatusRequestError(`Service returned HTTP ${response.status}.`);
@@ -157,9 +171,9 @@ export class CodexAccountStatus {
     const append = (label: string, value: string) => facts.push({ section: 'Billing', summaryKey: 'billing', label, value });
     if (billing.hasActiveSubscription !== undefined) append('Active subscription', billing.hasActiveSubscription ? 'yes' : 'no');
     if (billing.autoRenew !== undefined) append('Automatic renewal', billing.autoRenew ? 'on' : 'off');
-    if (billing.renewsAt) append('Renewal date (UTC)', billing.renewsAt);
-    if (billing.cancelsAt) append('Cancellation date (UTC)', billing.cancelsAt);
-    if (billing.expiresAt) append('Subscription expiry (UTC)', billing.expiresAt);
+    if (billing.renewsAt) append('Renewal date', billing.renewsAt);
+    if (billing.cancelsAt) append('Cancellation date', billing.cancelsAt);
+    if (billing.expiresAt) append('Subscription expiry', billing.expiresAt);
     return { facts, summary: { billing } };
   }
 
@@ -172,18 +186,26 @@ export class CodexAccountStatus {
     const appendLimit = (nameArg: string, valueArg: unknown, scopeArg: 'account' | 'feature') => {
       if (valueArg == null) return;
       const limit = record(valueArg);
-      facts.push({ section: 'Limits & credits', label: `${nameArg} usage allowed`, value: boolean(limit.allowed) ? 'yes' : 'no' });
-      facts.push({ section: 'Limits & credits', label: `${nameArg} limit reached`, value: boolean(limit.limit_reached) ? 'yes' : 'no' });
-      for (const [key, name] of [['primary_window', 'primary'], ['secondary_window', 'secondary']]) {
-        if (limit[key] == null) continue;
-        const window = record(limit[key]);
-        const used = numeric(window.used_percent);
-        const durationSeconds = numeric(window.limit_window_seconds);
-        const minutes = durationSeconds / 60;
-        const duration = minutes % 1440 === 0 ? `${minutes / 1440}d` : minutes % 60 === 0 ? `${minutes / 60}h` : `${minutes}m`;
-        const resetAt = timestamp(window.reset_at);
-        usageWindows.push({ label: `${nameArg} ${name}`, scope: scopeArg, durationSeconds, usedPercent: used, resetAt });
-        facts.push({ section: 'Usage', summaryKey: 'usageWindows', label: `${nameArg} ${name} (${duration})`, value: `${used}% used, ${Math.max(0, 100 - used)}% remaining; resets ${resetAt}` });
+      // The service's own reading of the same windows, so a view that shows the windows need not repeat it.
+      facts.push({ section: 'Limits & credits', summaryKey: 'usageWindows', label: `${nameArg} usage allowed`, value: boolean(limit.allowed) ? 'yes' : 'no' });
+      facts.push({ section: 'Limits & credits', summaryKey: 'usageWindows', label: `${nameArg} limit reached`, value: boolean(limit.limit_reached) ? 'yes' : 'no' });
+      // Both slots are read before either is named: only a second window of the same length makes the
+      // vendor's slot worth showing, and that is decided from the pair.
+      const windows = (['primary_window', 'secondary_window'] as const).flatMap((slotArg) => {
+        if (limit[slotArg] == null) return [];
+        const window = record(limit[slotArg]);
+        return [{
+          slot: slotArg === 'primary_window' ? 'primary' : 'secondary',
+          usedPercent: numeric(window.used_percent), durationSeconds: numeric(window.limit_window_seconds), resetAt: timestamp(window.reset_at),
+        }];
+      });
+      for (const window of windows) {
+        // Named by its length, as Codex names its own windows: a slot carries no length, and which
+        // window the service puts in it varies by plan and by which limit is currently binding.
+        const shared = windows.some(other => other !== window && other.durationSeconds === window.durationSeconds);
+        const label = `${nameArg} ${usageWindowPeriod(window.durationSeconds)}${shared ? ` (${window.slot})` : ''}`;
+        usageWindows.push({ label, scope: scopeArg, durationSeconds: window.durationSeconds, usedPercent: window.usedPercent, resetAt: window.resetAt });
+        facts.push({ section: 'Usage', summaryKey: 'usageWindows', label, value: `${window.usedPercent}% used, ${Math.max(0, 100 - window.usedPercent)}% remaining; resets ${window.resetAt}` });
       }
     };
     appendLimit('Codex', bodyArg.rate_limit, 'account');
@@ -251,7 +273,7 @@ export class CodexAccountStatus {
         return { date, tokens: numeric(day.tokens) };
       }).sort((leftArg, rightArg) => rightArg.date.localeCompare(leftArg.date));
       for (const day of days.slice(0, 7)) facts.push({ section: 'Daily tokens', label: `Tokens ${day.date}`, value: day.tokens.toLocaleString('en-US') });
-      if (days.length > 7) facts.push({ section: 'Daily tokens', label: 'Daily activity', value: `Showing the latest 7 of ${days.length} reported days` });
+      facts.push({ section: 'Daily tokens', label: 'Reported days', value: String(days.length) });
     }
     return facts;
   }

package/ts/classes.credentialstore.ts

@@ -1,5 +1,5 @@
 import * as plugins from './plugins.js';
-import { writeSecretFileAtomically } from './helpers.js';
+import { errorCode, pause, writeSecretFileAtomically } from './helpers.js';
 
 export const credentialRecord = (value: unknown): Record<string, unknown> => {
   if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Unsupported credential document.');
@@ -62,17 +62,45 @@ export interface IStoredCredential {
   savedAt: string;
   /** Harness-owned payload. This object must never cross the public account interface. */
   credential: Record<string, unknown>;
+  /**
+   * A refresh token of this credential that the provider refused, as a hash -- never the token.
+   *
+   * A grant the provider rejected stays rejected, so replaying it only adds traffic to an auth endpoint, once per
+   * status read for as long as the record holds that token. Remembering it in the record instead of in memory is
+   * what makes that true for the next process too. Every write that replaces the credential drops it.
+   */
+  rejectedGrant?: string;
 }
 
+/** The root of authswitch's own state: `AUTHSWITCH_HOME`, or `~/.authswitch`. */
+export const authSwitchHome = (envArg: NodeJS.ProcessEnv = process.env): string =>
+  envArg.AUTHSWITCH_HOME || plugins.path.join(plugins.os.homedir(), '.authswitch');
+
+export interface ICredentialStoreOptions {
+  /**
+   * How long an operation waits for another authswitch operation on the same store, 45 seconds by default: longer
+   * than the longest operation that holds the lock -- a Claude Code login refresh (30 s) plus the 15 s a native
+   * write waits for Claude Code's own locks -- so such operations queue instead of being told the store is locked.
+   */
+  lockTimeoutMs?: number;
+}
+
+const DEFAULT_LOCK_TIMEOUT_MS = 45_000;
+const LOCK_RETRY_MS = 50;
+
 /** A single atomic, owner-only record keeps the saved credential and its identity together. */
 export class CredentialStore {
   public readonly dir: string;
-  constructor(harness: string, root = process.env.AUTHSWITCH_HOME || plugins.path.join(plugins.os.homedir(), '.authswitch')) {
+  private readonly lockTimeoutMs: number;
+  constructor(harness: string, root = authSwitchHome(), optionsArg: ICredentialStoreOptions = {}) {
     this.dir = plugins.path.join(root, harness);
+    this.lockTimeoutMs = optionsArg.lockTimeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS;
   }
   public id(slot: string, identity: string): string { return credentialHash(JSON.stringify([slot, identity])); }
+  /** Whether a value names a credential hash: a rejected grant, or an account id. */
+  private isHash(value: unknown): boolean { return typeof value === 'string' && /^[a-f0-9]{64}$/.test(value); }
   private file(id: string): string {
-    if (!/^[a-f0-9]{64}$/.test(id)) throw new Error('Invalid saved account ID.');
+    if (!this.isHash(id)) throw new Error('Invalid saved account ID.');
     return plugins.path.join(this.dir, `${id}.json`);
   }
   public read(id: string): IStoredCredential {
@@ -81,6 +109,9 @@ export class CredentialStore {
       || !credentialText(value.label) || typeof value.savedAt !== 'string' || !Number.isFinite(Date.parse(value.savedAt))
       || this.id(value.slotId as string, value.identity as string) !== id) throw new Error('Saved account metadata is invalid; restore it from a verified backup.');
     credentialRecord(value.credential);
+    // Advisory state: a rejected grant that is not a hash says nothing about the login and is dropped, never made
+    // the record's problem -- the grant is sent once more instead, which is what a record without one means anyway.
+    if (!this.isHash(value.rejectedGrant)) delete value.rejectedGrant;
     return value as unknown as IStoredCredential;
   }
   public list(): IStoredCredential[] {
@@ -89,12 +120,33 @@ export class CredentialStore {
       .map(name => this.read(name.slice(0, -5))).sort((a, b) => b.savedAt.localeCompare(a.savedAt));
   }
   public save(entry: Omit<IStoredCredential, 'schemaVersion' | 'id' | 'savedAt'>): IStoredCredential {
-    const record: IStoredCredential = { ...entry, schemaVersion: 1, id: this.id(entry.slotId, entry.identity), savedAt: new Date().toISOString() };
+    return this.write({ ...entry, schemaVersion: 1, id: this.id(entry.slotId, entry.identity), savedAt: new Date().toISOString() },
+      'Saved credential verification failed; the active login was preserved.');
+  }
+  /**
+   * Replaces a saved login's credential in place, such as with refreshed tokens: the account, its identity and when
+   * it was saved stay as they are. The caller holds the lock and has checked the record it replaces.
+   */
+  public replaceCredential(id: string, credential: Record<string, unknown>): IStoredCredential {
+    const record = this.read(id);
+    // A remembered rejection belongs to the credential it was taken from; the new one has not been refused.
+    delete record.rejectedGrant;
+    return this.write({ ...record, credential }, 'The refreshed login could not be verified after saving it.');
+  }
+  /**
+   * Remembers that the provider refused the refresh token this record holds, as `grantHashArg`. The caller holds the
+   * lock and has checked that the record still holds the token it sent.
+   */
+  public rememberRejectedGrant(id: string, grantHashArg: string): IStoredCredential {
+    if (!this.isHash(grantHashArg)) throw new Error('A rejected grant is remembered as a credential hash.');
+    return this.write({ ...this.read(id), rejectedGrant: grantHashArg }, 'The refused sign-in could not be recorded.');
+  }
+  private write(record: IStoredCredential, failureArg: string): IStoredCredential {
     plugins.fs.mkdirSync(this.dir, { recursive: true, mode: 0o700 });
     plugins.fs.chmodSync(this.dir, 0o700);
     const raw = JSON.stringify(record, null, 2) + '\n';
     writeSecretFileAtomically(this.file(record.id), raw);
-    if (readCredentialDocument(this.file(record.id)).raw !== raw) throw new Error('Saved credential verification failed; the active login was preserved.');
+    if (readCredentialDocument(this.file(record.id)).raw !== raw) throw new Error(failureArg);
     return this.read(record.id);
   }
   public remove(id: string): void { this.read(id); plugins.fs.unlinkSync(this.file(id)); }
@@ -124,13 +176,29 @@ export class CredentialStore {
     plugins.fs.mkdirSync(this.dir, { recursive: true, mode: 0o700 });
     writeSecretFileAtomically(this.switchFile, JSON.stringify({ schemaVersion: 1, switches: records }, null, 2) + '\n');
   }
-  public locked<T>(action: () => T): T {
+  /**
+   * Runs `action` as the only authswitch operation on this store; the lock is held until an asynchronous action settles.
+   *
+   * An operation that finds the store locked waits for it, up to the store's lock timeout, so concurrent operations
+   * (a manual switch and a watch refreshing a saved login) run one after the other instead of failing. The signal
+   * ends the wait early; an action that has started is never interrupted by it.
+   */
+  public async locked<T>(action: () => T | Promise<T>, optionsArg: { signal?: AbortSignal } = {}): Promise<T> {
     plugins.fs.mkdirSync(this.dir, { recursive: true, mode: 0o700 });
     const file = plugins.path.join(this.dir, '.lock');
-    let fd: number;
-    try { fd = plugins.fs.openSync(file, 'wx', 0o600); }
-    catch { throw new Error(`Account storage is locked. Close other authswitch operations; if none remain, remove ${file}.`); }
-    try { return action(); }
+    const deadline = Date.now() + this.lockTimeoutMs;
+    let fd: number | undefined;
+    while (fd === undefined) {
+      optionsArg.signal?.throwIfAborted();
+      try { fd = plugins.fs.openSync(file, 'wx', 0o600); }
+      catch (error) {
+        if (errorCode(error) !== 'EEXIST' || Date.now() >= deadline) {
+          throw new Error(`Account storage is locked. Close other authswitch operations; if none remain, remove ${file}.`);
+        }
+        await pause(Math.min(LOCK_RETRY_MS, deadline - Date.now()), optionsArg.signal);
+      }
+    }
+    try { return await action(); }
     finally { plugins.fs.closeSync(fd); plugins.fs.unlinkSync(file); }
   }
 }

package/ts/classes.fileharness.ts

@@ -1,4 +1,4 @@
-import type { IAuthHarness, IHarnessAccountStatus, IHarnessCredentialDrift, IHarnessOutcome, IHarnessProcessControl, IHarnessState, IHarnessStatusOptions } from './interfaces.harness.js';
+import type { IAuthHarness, IHarnessAccountStatus, IHarnessCredentialDrift, IHarnessOutcome, IHarnessProcessControl, IHarnessState, IHarnessStatusOptions, THarnessResult } from './interfaces.harness.js';
 import { credentialHash, CredentialStore, type IStoredCredential, type ISwitchRecord } from './classes.credentialstore.js';
 import { pauseSynchronously } from './helpers.js';
 import { plainText } from './formatting.js';
@@ -25,22 +25,34 @@ export abstract class FileHarness implements IAuthHarness {
   protected abstract apply(slotId: string, previous: IFileAccount | undefined, target: IFileAccount | undefined): void;
   /** The harness's own running instances. Detection informs the caller; it never blocks a write. */
   public abstract readonly processes: IHarnessProcessControl;
+  /** Whether running instances pick up a swapped login by themselves; see `IAuthHarness.liveSwap`. */
+  public abstract readonly liveSwap: boolean;
+  /** Whether `authswitch watch` may switch this harness by itself; see `IAuthHarness.autoSwitch`. */
+  public abstract readonly autoSwitch: boolean;
   /** Raw bytes of the native files a snapshot's credentials are taken from, in a fixed order. */
   protected abstract nativeSources(): (string | null)[];
   protected abstract inspect(credential: Record<string, unknown>, slotId: string): IFileAccount;
   public abstract readAccountStatus(id: string, optionsArg?: IHarnessStatusOptions): Promise<IHarnessAccountStatus>;
 
+  /**
+   * Runs a read and write of the native login under the harness's own write locks, so it never interleaves
+   * with a running instance's token refresh or save. A harness without such a protocol runs the action as it is.
+   */
+  protected async nativeTransaction(actionArg: () => string[]): Promise<string[]> {
+    return actionArg();
+  }
+
   /**
    * A snapshot proven not to have been taken across a native write.
    *
    * Saving a login without replacing it writes no native file, so it must not require the harness
-   * to be stopped. A running harness does rotate its tokens on its own schedule, and its fallback
-   * writer truncates the file in place, so reading the same sources before and after the snapshot
-   * and requiring identical bytes is what keeps a torn or half-rotated credential out of the stash.
-   * Both the retry count and the pause between attempts are bounded; an unstable file is reported,
-   * never guessed at.
+   * to be stopped. A running harness does rotate its tokens on its own schedule, and a native writer
+   * that is not transactional can leave a partial file for a moment, so reading the same sources
+   * before and after the snapshot and requiring identical bytes is what keeps a torn or half-rotated
+   * credential out of the stash. Both the retry count and the pause between attempts are bounded; an
+   * unstable file is reported, never guessed at.
    */
-  private stableSnapshot(): IFileHarnessSnapshot {
+  protected stableSnapshot(): IFileHarnessSnapshot {
     let failure: unknown;
     for (let attempt = 0; attempt < 5; attempt++) {
       if (attempt) pauseSynchronously(20);
@@ -60,7 +72,11 @@ export abstract class FileHarness implements IAuthHarness {
     if (account.identity !== entry.identity) throw new Error('Saved credential does not match its account identity.');
     return account;
   }
-  public readState(): IHarnessState {
+  /**
+   * The harness's accounts. A subclass may have to bring its own state up to date first -- the Claude Code adapter
+   * mirrors the active login into its saved copy -- which is why this is the interface's `THarnessResult`.
+   */
+  public readState(): THarnessResult<IHarnessState> {
     const snapshot = this.snapshot();
     const saved = this.store.list();
     const accounts: IHarnessState['accounts'] = saved.map(entry => {
@@ -82,11 +98,11 @@ export abstract class FileHarness implements IAuthHarness {
   /**
    * Credential slots that no longer hold the account the last switch wrote.
    *
-   * A running harness refreshes its login on its own schedule and writes the result to the same
-   * file, so a switch performed underneath one can be undone minutes later without any error. The
-   * recorded hash detects that the file changed at all; comparing the account distinguishes the
-   * benign case -- the switched-in account rotating its own token -- from the previous login coming
-   * back. Detection is advisory and never turns a read into a failure.
+   * The login can change outside authswitch -- a new native login, or, for a harness that does not pick
+   * up swaps live, a running instance writing its previous login back at its next refresh. The recorded
+   * hash detects that the file changed at all; comparing the account distinguishes the benign case -- the
+   * switched-in account rotating its own token -- from a different account. Detection is advisory and
+   * never turns a read into a failure.
    */
   private credentialDrift(snapshotArg: IFileHarnessSnapshot): IHarnessCredentialDrift[] {
     let records: ISwitchRecord[];
@@ -111,8 +127,9 @@ export abstract class FileHarness implements IAuthHarness {
   private savedLabel(accountIdArg: string): string | null {
     try { return this.store.read(accountIdArg).label; } catch { return null; }
   }
-  /** Instances that keep a replaced or cleared login in memory until they are restarted. */
+  /** Instances that keep a replaced or cleared login in memory until they are restarted; none for a live-swap harness. */
   private runningCaveat(kindArg: 'replaced' | 'cleared'): string[] {
+    if (this.liveSwap) return [];
     let count: number;
     try { count = this.processes.list().length; }
     catch { return [`Could not check for running ${this.label} processes. If any are running, restart them: an unrestarted instance can write its previous login back.`]; }
@@ -137,16 +154,24 @@ export abstract class FileHarness implements IAuthHarness {
       return [];
     } catch { return [`The login was written, but this switch could not be recorded for later credential checks.`]; }
   }
+  /** The active login with this account id, read from the native files; undefined when the account is not active. */
+  protected activeCredential(id: string): IFileAccount | undefined {
+    return this.snapshot().accounts.find(account => this.store.id(account.slotId, account.identity) === id);
+  }
+  /** The saved copy of this account, verified against its identity. */
+  protected savedCredential(id: string): IFileAccount {
+    return this.saved(this.store.read(id));
+  }
+  /** The account's current credential: the active login when it is active, which may be newer than its saved copy. */
   protected readCredential(id: string): IFileAccount {
-    const active = this.snapshot().accounts.find(account => this.store.id(account.slotId, account.identity) === id);
-    return active ?? this.saved(this.store.read(id));
+    return this.activeCredential(id) ?? this.savedCredential(id);
   }
   /** Save a newly authenticated credential without changing a native harness's login. */
-  public importCredential(slotId: string, credential: Record<string, unknown>): { accountId: string } {
+  public importCredential(slotId: string, credential: Record<string, unknown>): Promise<{ accountId: string }> {
     return this.store.locked(() => ({ accountId: this.store.save(this.inspect(credential, slotId)).id }));
   }
   /** Backend-only login handoff. Preserve the outgoing credential before replacing its slot. */
-  public activateCredential(slotId: string, credential: Record<string, unknown>): IHarnessOutcome {
+  public activateCredential(slotId: string, credential: Record<string, unknown>): Promise<IHarnessOutcome> {
     return this.outcome(() => {
       const target = this.inspect(credential, slotId);
       const snapshot = this.snapshot();
@@ -154,9 +179,15 @@ export abstract class FileHarness implements IAuthHarness {
       const previous = snapshot.accounts.find(account => account.slotId === slotId);
       if (previous) this.store.save(previous);
       this.apply(slotId, previous, target);
-      return [`Activated ${plainText(target.label)} (${plainText(slotId)}).`,
+      return [`Activated ${plainText(target.label)} (${plainText(slotId)}).`, ...this.liveSwapNote('replaced'),
         ...this.recordActivation(slotId, this.store.id(slotId, target.identity)), ...this.runningCaveat('replaced')];
-    });
+    }, true);
+  }
+  /** What a live-swap harness's running sessions do with the change; they need no restart either way. */
+  private liveSwapNote(kindArg: 'replaced' | 'cleared'): string[] {
+    if (!this.liveSwap) return [];
+    return [kindArg === 'replaced' ? `Running ${this.label} sessions use it from their next request.`
+      : `Running ${this.label} sessions have no login from their next request.`];
   }
   public resolveAccount(reference: string): { id: string } | { candidates: string[] } {
     const accounts = this.store.list();
@@ -165,11 +196,18 @@ export abstract class FileHarness implements IAuthHarness {
     const matches = exact.length ? exact : accounts.filter(account => account.label.toLowerCase().startsWith(reference.toLowerCase()));
     return matches.length === 1 ? { id: matches[0].id } : { candidates: matches.map(account => `${account.slotId}:${account.label} (${account.id})`) };
   }
-  private outcome(action: () => string | string[]): IHarnessOutcome {
-    try { return this.store.locked(() => { const lines = action(); return { lines: Array.isArray(lines) ? lines : [lines], problems: [] }; }); }
-    catch (error) { return { lines: [], problems: [error instanceof Error ? error.message : 'Credential operation failed.'] }; }
+  /**
+   * Runs one credential operation as the only authswitch operation on this harness's store. An operation that reads
+   * or writes the native login (`nativeArg`) also runs inside the harness's native transaction.
+   */
+  private async outcome(actionArg: () => string | string[], nativeArg: boolean): Promise<IHarnessOutcome> {
+    const run = (): string[] => [actionArg()].flat();
+    try {
+      const lines = await this.store.locked(() => nativeArg ? this.nativeTransaction(run) : run());
+      return { lines, problems: [] };
+    } catch (error) { return { lines: [], problems: [error instanceof Error ? error.message : 'Credential operation failed.'] }; }
   }
-  public saveCurrent(options: { keepActive: boolean; accountId?: string }): IHarnessOutcome {
+  public saveCurrent(options: { keepActive: boolean; accountId?: string }): Promise<IHarnessOutcome> {
     return this.outcome(() => {
       const snapshot = this.stableSnapshot();
       if (snapshot.unavailable) throw new Error(snapshot.unavailable);
@@ -182,10 +220,13 @@ export abstract class FileHarness implements IAuthHarness {
       const cleared: string[] = [];
       try { this.store.clearSwitch(active.slotId); }
       catch { cleared.push('The login was cleared, but its switch record could not be removed.'); }
-      return [`Saved ${plainText(active.label)} (${plainText(active.slotId)}). Start ${this.label} to log in again.`, ...cleared, ...this.runningCaveat('cleared')];
-    });
+      return [this.liveSwap
+        ? `Saved ${plainText(active.label)} (${plainText(active.slotId)}) and cleared the active login. ${this.loginHint}`
+        : `Saved ${plainText(active.label)} (${plainText(active.slotId)}). Start ${this.label} to log in again.`,
+        ...this.liveSwapNote('cleared'), ...cleared, ...this.runningCaveat('cleared')];
+    }, true);
   }
-  public switchAccount(id: string): IHarnessOutcome {
+  public switchAccount(id: string): Promise<IHarnessOutcome> {
     return this.outcome(() => {
       const target = this.saved(this.store.read(id));
       const snapshot = this.snapshot();
@@ -198,16 +239,17 @@ export abstract class FileHarness implements IAuthHarness {
         return [`${plainText(target.label)} is already active; its latest credential is saved.`, ...this.recordActivation(target.slotId, id)];
       }
       this.apply(target.slotId, previous, target);
-      return [`Activated ${plainText(target.label)} (${plainText(target.slotId)}). Start ${this.label} to use it.`,
-        ...this.recordActivation(target.slotId, id), ...this.runningCaveat('replaced')];
-    });
+      const activated = `Activated ${plainText(target.label)} (${plainText(target.slotId)}).`;
+      return [this.liveSwap ? activated : `${activated} Start ${this.label} to use it.`,
+        ...this.liveSwapNote('replaced'), ...this.recordActivation(target.slotId, id), ...this.runningCaveat('replaced')];
+    }, true);
   }
-  public removeAccount(id: string): IHarnessOutcome {
-    return this.outcome(() => { const account = this.store.read(id); this.store.remove(id); return `Removed saved login for ${plainText(account.label)}; the active login is preserved.`; });
+  public removeAccount(id: string): Promise<IHarnessOutcome> {
+    return this.outcome(() => { const account = this.store.read(id); this.store.remove(id); return `Removed saved login for ${plainText(account.label)}; the active login is preserved.`; }, false);
   }
-  public diagnose(): IHarnessOutcome {
+  public async diagnose(): Promise<IHarnessOutcome> {
     try {
-      const state = this.readState();
+      const state = await this.readState();
       return { lines: [`${this.label}: ${state.accounts.filter(account => account.isActive).length} active login(s), ${state.accounts.filter(account => account.isStashed).length} saved account(s).`, this.loginHint], problems: state.saveUnavailableReason ? [state.saveUnavailableReason] : [] };
     } catch { return { lines: [], problems: ['Credential storage could not be verified. Check file permissions and saved credential records.'] }; }
   }