@modelprofile.com/authswitch 2.1.2

package/ts/classes.codexpreuse.ts

@@ -0,0 +1,76 @@
+import * as plugins from './plugins.js';
+import type { ICodexIdentity } from './interfaces.js';
+import type { IHarnessPreuseOptions, IHarnessPreuseResult } from './interfaces.harness.js';
+import { PreuseError, validatePreuseOptions } from './preuse.js';
+
+/** One tool-free request through the FlexHarness ChatGPT provider, with no credential writes. */
+export class CodexPreuse {
+  constructor(private readonly fetcher: typeof fetch = globalThis.fetch) {}
+
+  public async run(rawArg: string, identityArg: ICodexIdentity, optionsArg: IHarnessPreuseOptions): Promise<IHarnessPreuseResult> {
+    validatePreuseOptions(optionsArg);
+    if (identityArg.kind !== 'chatgpt') throw new PreuseError('Codex preuse requires a ChatGPT subscription login; API-key logins have no subscription reset window.');
+    if (!identityArg.accountId) throw new PreuseError('This login has no account ID for preuse.');
+    const signal = optionsArg.signal
+      ? AbortSignal.any([optionsArg.signal, AbortSignal.timeout(180_000)])
+      : AbortSignal.timeout(180_000);
+    let credentials: plugins.flexAuth.IOpenAiChatGptAuthCredentials;
+    let oauth: plugins.flexAccounts.IOpenAiChatGptOAuthCredential;
+    try {
+      const tokens = JSON.parse(rawArg).tokens;
+      oauth = { kind: 'chatgptOAuth', providerId: 'openai', accessToken: tokens.access_token, refreshToken: tokens.refresh_token, idToken: tokens.id_token };
+      credentials = plugins.flexAccounts.toOpenAiChatGptAuthCredentials(oauth);
+      if (credentials.accountId !== identityArg.accountId) throw new Error('Identity mismatch');
+    } catch {
+      throw new PreuseError('No complete, matching Codex login is available for preuse. Log in again with Codex and save the account.');
+    }
+    let model = optionsArg.model;
+    let reasoningEffort: string | undefined;
+    if (!model) {
+      const adapter = new plugins.flexAccounts.OpenAiProviderAdapter({ fetch: this.fetcher });
+      try {
+        const catalog = await adapter.listModels(oauth, { signal, timeoutMs: 10_000 });
+        if (!catalog.success) throw new PreuseError(catalog.errorCode === 'CREDENTIAL_REFRESH_REQUIRED'
+          ? 'The saved login has expired. Log in again with Codex and save it before preuse.'
+          : 'Could not read the account model catalog. No preuse prompt was sent.');
+        const selected = catalog.models.find(item => item.isDefault && item.inputModalities.includes('text'));
+        if (!selected) throw new PreuseError('The account catalog has no default text model. Specify --model explicitly.');
+        model = selected.wireModel;
+        reasoningEffort = ['none', 'minimal', 'low'].find(effort => selected.reasoningEfforts.some(item => item.effort === effort)) ?? selected.defaultReasoningEffort;
+      } catch (error) {
+        if (error instanceof PreuseError) throw error;
+        throw new PreuseError('Could not read the account model catalog. No preuse prompt was sent.');
+      } finally { await adapter.dispose(); }
+    }
+    let requestStarted = false;
+    try {
+      signal.throwIfAborted();
+      const connection = plugins.flexAuth.createOpenAiChatGptModelConnection(credentials);
+      connection.settings.fetch = this.fetcher;
+      const languageModel = plugins.flexOpenAi.createOpenAiModelProvider().getModel({ provider: 'openai', model, connection });
+      requestStarted = true;
+      const stream = plugins.flexModels.streamText({
+        model: languageModel,
+        instructions: 'Answer the user prompt with plain text. Do not use tools.',
+        prompt: optionsArg.prompt,
+        providerOptions: { openai: { store: false, ...(reasoningEffort ? { reasoningEffort } : {}) } },
+        abortSignal: signal,
+        maxRetries: 0,
+        // Handle errors here without the SDK's default raw-error console output.
+        onError: () => {},
+      });
+      // Drain the stream; generated prose is neither printed nor persisted.
+      for await (const part of stream.fullStream) {
+        if (part.type === 'error' || part.type === 'abort') throw new Error('Inference did not complete');
+      }
+      const [finishReason, usage] = await Promise.all([stream.finishReason, stream.totalUsage]);
+      if (finishReason !== 'stop' && finishReason !== 'length') throw new Error('Inference did not complete');
+      const count = (value: number | undefined) => Number.isSafeInteger(value) && value! >= 0 ? value : undefined;
+      return { model, inputTokens: count(usage.inputTokens), outputTokens: count(usage.outputTokens), totalTokens: count(usage.totalTokens) };
+    } catch {
+      throw new PreuseError(requestStarted
+        ? 'Preuse did not complete. Tokens may already have been consumed; no automatic retry was made. Check the account status before trying again.'
+        : 'Preuse was cancelled before the prompt was sent.');
+    }
+  }
+}

package/ts/classes.codexstatus.ts

@@ -0,0 +1,257 @@
+import type { ICodexIdentity } from './interfaces.js';
+import type { IHarnessAccountStatus, IHarnessStatusSummary } from './interfaces.harness.js';
+import { commitinfo } from './00_commitinfo_data.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';
+
+const record = (valueArg: unknown): Record<string, unknown> => {
+  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) throw new Error('Unexpected status response.');
+  return valueArg as Record<string, unknown>;
+};
+const numeric = (valueArg: unknown): number => {
+  if (typeof valueArg !== 'number' || !Number.isFinite(valueArg) || valueArg < 0) throw new Error('Unexpected numeric status field.');
+  return valueArg;
+};
+const text = (valueArg: unknown): string => {
+  if (typeof valueArg !== 'string' || !valueArg.trim()) throw new Error('Unexpected text status field.');
+  return valueArg;
+};
+const boolean = (valueArg: unknown): boolean => {
+  if (typeof valueArg !== 'boolean') throw new Error('Unexpected boolean status field.');
+  return valueArg;
+};
+const timestamp = (secondsArg: unknown): string => new Date(numeric(secondsArg) * 1000).toISOString();
+const count = (valueArg: unknown): number => {
+  const value = numeric(valueArg);
+  if (!Number.isSafeInteger(value)) throw new Error('Invalid status count.');
+  return value;
+};
+
+/** Only fixed, local diagnostics may cross the HTTP error boundary. */
+class StatusRequestError extends Error {}
+
+/**
+ * Read-only ChatGPT status contract verified against Codex 0.154.0.
+ * These source-defined backend routes are isolated here. No token refresh,
+ * credential writes, app-server lifecycle changes or reset consumption occur.
+ */
+export class CodexAccountStatus {
+  constructor(private readonly fetcher: typeof fetch = globalThis.fetch) {}
+
+  public async read(rawArg: string, identityArg: ICodexIdentity): Promise<IHarnessAccountStatus> {
+    if (identityArg.kind !== 'chatgpt') return {
+      facts: [{ label: 'Authentication', value: 'API key' }, { label: 'Subscription and usage', value: 'Not exposed by Codex for API-key logins' }], problems: [],
+    };
+    let accessToken: string;
+    try { accessToken = text(record(record(JSON.parse(rawArg)).tokens).access_token); }
+    catch { return { facts: [], problems: ['The login has no usable access token. Log in again with Codex, then save the account.'] }; }
+    if (!identityArg.accountId) return { facts: [], problems: ['The login has no account ID for a status lookup.'] };
+    return this.readCredential(accessToken, identityArg.accountId, identityArg.planType);
+  }
+
+  /** Read the ChatGPT account directly, independent of a harness's on-disk format. */
+  public async readCredential(accessToken: string, accountId: string, planType?: string | null): Promise<IHarnessAccountStatus> {
+    const result: IHarnessAccountStatus = { facts: [], problems: [] };
+    const identityArg = { accountId, planType };
+    const sections = await Promise.allSettled([
+      this.get('wham/usage', accessToken, identityArg.accountId),
+      this.get('wham/rate-limit-reset-credits', accessToken, identityArg.accountId),
+      this.get('wham/profiles/me', accessToken, identityArg.accountId),
+      this.get('accounts/check/v4-2023-04-27', accessToken, identityArg.accountId),
+    ]);
+    const usage = sections[0];
+    if (usage.status === 'fulfilled' && usage.value.account_id != null && usage.value.account_id !== identityArg.accountId) {
+      return { facts: [], problems: ['The status service returned a different account ID; no account data was displayed.'] };
+    }
+    const parsers = [
+      (bodyArg: Record<string, unknown>) => this.limits(bodyArg, identityArg.accountId!),
+      (bodyArg: Record<string, unknown>) => this.resets(bodyArg),
+      (bodyArg: Record<string, unknown>) => ({ facts: this.activity(bodyArg), summary: undefined }),
+      (bodyArg: Record<string, unknown>) => this.billing(bodyArg, identityArg.accountId!),
+    ];
+    const labels = ['Subscription and limits', 'Earned reset details', 'Token usage', 'Billing'];
+    for (let index = 0; index < sections.length; index++) {
+      const section = sections[index];
+      if (section.status === 'rejected') {
+        result.problems.push(`${labels[index]}: ${section.reason instanceof Error ? section.reason.message : 'Request failed.'}`);
+        continue;
+      }
+      try {
+        // Each parser validates its whole section before returning any facts or summary.
+        const parsed = parsers[index](section.value);
+        result.facts.push(...parsed.facts);
+        if (parsed.summary) result.summary = { ...result.summary, ...parsed.summary };
+      }
+      catch { result.problems.push(`${labels[index]}: the service returned an unsupported response; no values were inferred.`); }
+    }
+    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' } };
+    }
+    return result;
+  }
+
+  private async get(pathArg: string, tokenArg: string, accountIdArg: string): Promise<Record<string, unknown>> {
+    const signal = AbortSignal.timeout(10_000);
+    try {
+      const response = await this.fetcher(`https://chatgpt.com/backend-api/${pathArg}`, {
+        method: 'GET', redirect: 'error', signal,
+        headers: { Authorization: `Bearer ${tokenArg}`, 'ChatGPT-Account-ID': accountIdArg,
+          'User-Agent': `authswitch/${commitinfo.version}`, Accept: 'application/json',
+          ...(pathArg === 'accounts/check/v4-2023-04-27' ? { originator: 'Codex Desktop', 'OAI-Language': 'en', 'User-Agent': billingUserAgent } : {}) },
+      });
+      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 === 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}.`);
+      }
+      const reader = response.body?.getReader();
+      if (!reader) throw new StatusRequestError('The service returned an empty response.');
+      const chunks: Uint8Array[] = [];
+      let size = 0;
+      try {
+        while (true) {
+          const part = await reader.read();
+          if (part.done) break;
+          size += part.value.byteLength;
+          if (size > 1024 * 1024) { await reader.cancel(); throw new StatusRequestError('The status response is too large.'); }
+          chunks.push(part.value);
+        }
+      } finally { reader.releaseLock(); }
+      try { return record(JSON.parse(Buffer.concat(chunks).toString('utf8'))); }
+      catch { throw new StatusRequestError('The service returned invalid status data.'); }
+    } catch (errorArg) {
+      // Never surface remote bodies, request headers, token strings or arbitrary fetch errors.
+      if (signal.aborted) throw new Error('The status request timed out.');
+      if (errorArg instanceof StatusRequestError) throw errorArg;
+      throw new Error('The status service could not be reached.');
+    }
+  }
+
+  /** Desktop 26.908.40834 account-check contract; select the credential's exact account. */
+  private billing(bodyArg: Record<string, unknown>, accountIdArg: string): Pick<IHarnessAccountStatus, 'facts' | 'summary'> {
+    const accounts = record(bodyArg.accounts);
+    const match = (valueArg: unknown) => {
+      const value = record(valueArg);
+      return record(value.account).account_id === accountIdArg;
+    };
+    // A default workspace must never supply another account's billing information.
+    const selected = Object.hasOwn(accounts, accountIdArg) ? accounts[accountIdArg]
+      : Object.values(accounts).find(value => match(value));
+    if (selected === undefined || !match(selected)) throw new Error('No matching billing account.');
+    const account = record(selected);
+    const entitlement = record(account.entitlement);
+    const subscription = record(account.last_active_subscription);
+    const billing: NonNullable<IHarnessStatusSummary['billing']> = {};
+    if (entitlement.has_active_subscription != null) billing.hasActiveSubscription = boolean(entitlement.has_active_subscription);
+    if (subscription.will_renew != null) billing.autoRenew = boolean(subscription.will_renew) && entitlement.cancels_at == null;
+    for (const [field, key] of [['renews_at', 'renewsAt'], ['cancels_at', 'cancelsAt'], ['expires_at', 'expiresAt']] as const) {
+      if (entitlement[field] != null) billing[key] = new Date(text(entitlement[field])).toISOString();
+    }
+    if (!Object.keys(billing).length) throw new Error('No billing fields returned.');
+    const facts: IHarnessAccountStatus['facts'] = [];
+    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);
+    return { facts, summary: { billing } };
+  }
+
+  private limits(bodyArg: Record<string, unknown>, accountIdArg: string): Pick<IHarnessAccountStatus, 'facts' | 'summary'> {
+    if (bodyArg.account_id != null && bodyArg.account_id !== accountIdArg) throw new Error('Account mismatch.');
+    const plan = text(bodyArg.plan_type);
+    const facts: IHarnessAccountStatus['facts'] = [{ section: 'Subscription', summaryKey: 'subscription', label: 'Subscription plan', value: `${plan} (live)` }];
+    const usageWindows: NonNullable<IHarnessStatusSummary['usageWindows']> = [];
+    const summary: IHarnessStatusSummary = { subscription: { plan, source: 'live' }, usageWindows };
+    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}` });
+      }
+    };
+    appendLimit('Codex', bodyArg.rate_limit, 'account');
+    if (bodyArg.additional_rate_limits != null) {
+      if (!Array.isArray(bodyArg.additional_rate_limits)) throw new Error('Invalid additional limits.');
+      for (const value of bodyArg.additional_rate_limits) {
+        const limit = record(value);
+        appendLimit(text(limit.limit_name), limit.rate_limit, 'feature');
+      }
+    }
+    if (bodyArg.credits != null) {
+      const credits = record(bodyArg.credits);
+      const unlimited = boolean(credits.unlimited);
+      const hasCredits = boolean(credits.has_credits);
+      facts.push({ section: 'Limits & credits', label: 'Credits', value: unlimited ? 'unlimited' : credits.balance != null ? text(credits.balance) : hasCredits ? 'available (balance not returned)' : 'none available' });
+    }
+    if (bodyArg.spend_control != null) {
+      const spend = record(bodyArg.spend_control);
+      facts.push({ section: 'Limits & credits', label: 'Spend limit reached', value: boolean(spend.reached) ? 'yes' : 'no' });
+      if (spend.individual_limit != null) {
+        const limit = record(spend.individual_limit);
+        facts.push({ section: 'Limits & credits', label: 'Individual spend', value: `${text(limit.used)} used of ${text(limit.limit)}; ${text(limit.remaining)} remaining; resets ${timestamp(limit.reset_at)}` });
+      }
+    }
+    if (bodyArg.rate_limit_reached_type != null) facts.push({ section: 'Limits & credits', label: 'Limit state', value: text(record(bodyArg.rate_limit_reached_type).type) });
+    if (bodyArg.rate_limit_reset_credits != null) {
+      summary.resets = { available: count(record(bodyArg.rate_limit_reset_credits).available_count) };
+      facts.push({ section: 'Earned resets', summaryKey: 'resets', label: 'Available earned resets', value: String(summary.resets.available) });
+    }
+    else facts.push({ section: 'Earned resets', summaryKey: 'resets', label: 'Available earned resets', value: 'Not returned by the limits service' });
+    return { facts, summary };
+  }
+
+  private resets(bodyArg: Record<string, unknown>): Pick<IHarnessAccountStatus, 'facts' | 'summary'> {
+    const availableCount = count(bodyArg.available_count);
+    if (!Array.isArray(bodyArg.credits)) throw new Error('Invalid reset details.');
+    const facts: IHarnessAccountStatus['facts'] = [{ section: 'Earned resets', summaryKey: 'resets', label: 'Earned resets (detail lookup)', value: `${availableCount} available` }];
+    const details: NonNullable<NonNullable<IHarnessStatusSummary['resets']>['details']> = [];
+    for (const raw of bodyArg.credits) {
+      const credit = record(raw);
+      const expiresAt = credit.expires_at == null ? null : new Date(text(credit.expires_at)).toISOString();
+      const status = text(credit.status);
+      const kind = text(credit.reset_type);
+      details.push({ status, kind, expiresAt });
+      facts.push({ section: 'Earned resets', summaryKey: 'resetDetails', label: 'Earned reset', value: `${status}; ${kind}; ${expiresAt === null ? 'no expiry reported' : 'expires ' + expiresAt}` });
+    }
+    if (bodyArg.credits.length < availableCount) facts.push({ section: 'Earned resets', label: 'Reset details', value: `${bodyArg.credits.length} shown; the available count includes all credits` });
+    // A successful detail lookup supersedes the count from the limits response.
+    return { facts, summary: { resets: { available: availableCount, details } } };
+  }
+
+  private activity(bodyArg: Record<string, unknown>): IHarnessAccountStatus['facts'] {
+    const stats = record(bodyArg.stats);
+    const facts: IHarnessAccountStatus['facts'] = [];
+    for (const [key, label] of [
+      ['lifetime_tokens', 'Lifetime tokens'], ['peak_daily_tokens', 'Peak daily tokens'],
+      ['longest_running_turn_sec', 'Longest turn (seconds)'], ['current_streak_days', 'Current streak (days)'], ['longest_streak_days', 'Longest streak (days)'],
+    ]) facts.push({ section: 'Activity', label, value: stats[key] == null ? 'Not returned' : numeric(stats[key]).toLocaleString('en-US') });
+    if (stats.daily_usage_buckets != null) {
+      if (!Array.isArray(stats.daily_usage_buckets)) throw new Error('Invalid daily usage.');
+      const days = stats.daily_usage_buckets.map((valueArg) => {
+        const day = record(valueArg);
+        const date = text(day.start_date);
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) throw new Error('Invalid daily date.');
+        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` });
+    }
+    return facts;
+  }
+}

package/ts/classes.codexswitcher.ts

@@ -0,0 +1,272 @@
+import type {
+  IActiveAuth,
+  ICodexSwitcherOptions,
+  IStashResult,
+  IStashListing,
+  ISwitchResult,
+} from './interfaces.js';
+import { CodexAuth } from './classes.codexauth.js';
+import { CodexDaemon } from './classes.codexdaemon.js';
+import { CodexHome } from './classes.codexhome.js';
+import { RemoteControlStore } from './classes.remotecontrol.js';
+import { StashStore } from './classes.stashstore.js';
+import { countPaired } from './helpers.js';
+
+const KEYRING_MESSAGE =
+  'the active Codex credential is held in an OS keyring, which authswitch cannot move.\n' +
+  'Set `auth_credentials_store_mode` to file storage in ~/.codex/config.toml and log in again to use authswitch.';
+
+/**
+ * Orchestrates stashing and restoring Codex credentials.
+ *
+ * Two invariants this class defends:
+ *
+ * 1. A credential is never destroyed or overwritten until a copy has been
+ *    written to the stash *and read back*.
+ * 2. Every operation that stops the app-server starts it again, including when
+ *    the operation fails partway. Leaving remote control down would turn a
+ *    failed switch into a broken machine.
+ *
+ * Both stash and use quiesce the app-server first. It refreshes tokens on its
+ * own schedule, so reading or writing `auth.json` while it runs races that
+ * refresh: the copy taken could be a token the daemon has already rotated away,
+ * and a credential the daemon wrote after the copy would be destroyed unstashed.
+ */
+export class CodexSwitcher {
+  public readonly home: CodexHome;
+  public readonly auth: CodexAuth;
+  public readonly remoteControl: RemoteControlStore;
+  public readonly stashes: StashStore;
+  public readonly daemon: CodexDaemon;
+
+  constructor(optionsArg: ICodexSwitcherOptions = {}) {
+    this.home = new CodexHome(optionsArg.codexHome);
+    this.auth = new CodexAuth(this.home);
+    this.remoteControl = new RemoteControlStore(this.home);
+    this.stashes = new StashStore('codex', optionsArg.stashRoot);
+    this.daemon = new CodexDaemon(this.home, optionsArg.codexBinary);
+  }
+
+  public readActive(): IActiveAuth {
+    return this.auth.readActive();
+  }
+
+  /**
+   * Saves the active credential under its account email, together with the
+   * remote-control enrollments belonging to that account, then clears the active
+   * slot so a different account can be logged in.
+   *
+   * `keepActive` saves without clearing, for taking a checkpoint.
+   */
+  public stash(optionsArg: { keepActive?: boolean } = {}): IStashResult {
+    const notes: string[] = [];
+    const problems: string[] = [];
+
+    const before = this.auth.readActive();
+    this.assertNotKeyring(before);
+    if (before.source === 'none') {
+      // Nothing on disk means nothing to save, and a daemon holding no
+      // credential cannot produce one. Fail here rather than bouncing the
+      // app-server -- and remote control with it -- to learn the same thing.
+      throw new Error(
+        `no active Codex credential found at ${before.authFilePath}; run \`codex login\` first`,
+      );
+    }
+
+    const daemonWasRunning = this.quiesceDaemon(notes);
+    let daemonRestarted = false;
+    let entry;
+    try {
+      // Re-read only now that the daemon is down: whatever it may have refreshed
+      // between the check above and the stop is the credential we must save.
+      const active = this.auth.readActive();
+      this.assertNotKeyring(active);
+      if (!active.raw) {
+        throw new Error(`no active Codex credential found at ${active.authFilePath}`);
+      }
+      if (!active.identity) {
+        throw new Error(
+          `could not identify the account behind ${active.authFilePath}; refusing to stash an unlabelled credential`,
+        );
+      }
+
+      const enrollments = this.remoteControl.read(active.identity.accountId);
+      entry = this.stashes.write(active.identity, active.raw, enrollments, this.home.dir);
+
+      if (!this.stashes.readBack(entry.email, active.raw)) {
+        throw new Error(
+          `the stash for ${entry.email} could not be read back from ${this.stashes.entryDir(entry.email)}; leaving the active credential in place`,
+        );
+      }
+
+      if (!optionsArg.keepActive) {
+        this.auth.clearActive();
+      }
+      if (enrollments.length === 0) {
+        notes.push('no remote-control enrollment found for this account');
+      }
+    } finally {
+      daemonRestarted = this.resumeDaemon(daemonWasRunning, notes, problems);
+    }
+
+    return {
+      entry,
+      daemonRestarted,
+      complete: problems.length === 0,
+      notes,
+      problems,
+    };
+  }
+
+  /** Every stash, annotated with whether it is the account currently in use. */
+  public list(): IStashListing[] {
+    const active = this.auth.readActive();
+    return this.stashes.list().map((entryArg) => {
+      const paired = countPaired(entryArg.enrollments);
+      return {
+        ...entryArg,
+        slug: this.stashes.slugFor(entryArg.email),
+        isActive: active.identity !== null && active.identity.email === entryArg.email && active.identity.accountId === entryArg.accountId && active.identity.kind === entryArg.kind,
+        enrollmentsTotal: entryArg.enrollments.length,
+        enrollmentsPaired: paired,
+        hasRemoteControl: paired > 0,
+      };
+    });
+  }
+
+  /**
+   * Makes a stashed account the active one.
+   *
+   * Re-running it for the account that is already active is not a no-op: it
+   * restores that account's enrollments, which is the repair path when remote
+   * control has stopped working for the current login.
+   */
+  public use(emailArg: string): ISwitchResult {
+    const target = this.stashes.readMeta(emailArg);
+    let targetAuth = this.stashes.readAuth(emailArg);
+    if (!target || targetAuth === null) {
+      throw new Error(`no stash for "${emailArg}"`);
+    }
+    const targetIdentity = this.auth.identityFromRaw(targetAuth);
+    if (!targetIdentity || targetIdentity.email !== target.email || targetIdentity.accountId !== target.accountId || targetIdentity.kind !== target.kind) {
+      throw new Error('the saved Codex credential does not match its metadata; refusing to switch');
+    }
+
+    const notes: string[] = [];
+    const problems: string[] = [];
+
+    this.assertNotKeyring(this.auth.readActive());
+
+    const daemonWasRunning = this.quiesceDaemon(notes);
+    let enrollmentsRestored = 0;
+    let fromEmail: string | null = null;
+    let daemonRestarted = false;
+
+    try {
+      // Everything below reads the credential state only after the daemon is
+      // down, so nothing it refreshed mid-command is missed or overwritten.
+      const active = this.auth.readActive();
+      this.assertNotKeyring(active);
+      fromEmail = active.identity?.email ?? null;
+
+      if (fromEmail !== null && fromEmail !== target.email) {
+        // Never drop a credential on the floor: check the outgoing one into the
+        // stash, and prove it landed, before the incoming one overwrites it.
+        const outgoingEnrollments = this.remoteControl.read(active.identity!.accountId);
+        this.stashes.write(active.identity!, active.raw!, outgoingEnrollments, this.home.dir);
+        if (!this.stashes.readBack(fromEmail, active.raw!)) {
+          throw new Error(
+            `could not save the outgoing credential for ${fromEmail}; aborting before it would be overwritten`,
+          );
+        }
+        notes.push(`stashed the outgoing credential for ${fromEmail}`);
+      } else if (fromEmail === null && active.raw) {
+        throw new Error(
+          `refusing to overwrite the unidentifiable credential at ${active.authFilePath}; move it aside manually first`,
+        );
+      }
+
+      if (fromEmail === target.email) {
+        if (active.identity!.accountId !== target.accountId || active.identity!.kind !== target.kind) {
+          throw new Error('the active and saved Codex accounts share an email but have different identities; refusing to overwrite either credential');
+        }
+        // A daemon refresh may have made the saved tokens obsolete. Keep the current
+        // login while restoring the saved pairing, and verify its updated stash.
+        targetAuth = active.raw!;
+        this.stashes.write(active.identity!, targetAuth, target.enrollments, this.home.dir);
+        if (!this.stashes.readBack(target.email, targetAuth)) throw new Error('could not verify the current credential in its stash; refusing to overwrite it');
+        notes.push(`${target.email} was already active; refreshing its remote-control enrollments`);
+      }
+
+      this.auth.writeActive(targetAuth);
+
+      if (target.enrollments.length > 0) {
+        enrollmentsRestored = this.remoteControl.restore(target.enrollments);
+        notes.push(`restored ${enrollmentsRestored} remote-control enrollment(s)`);
+      } else {
+        notes.push('no remote-control enrollment was stashed for this account');
+      }
+    } finally {
+      daemonRestarted = this.resumeDaemon(daemonWasRunning, notes, problems);
+    }
+
+    return {
+      from: fromEmail,
+      to: target.email,
+      enrollmentsRestored,
+      daemonRestarted,
+      complete: problems.length === 0,
+      notes,
+      problems,
+    };
+  }
+
+  public drop(emailArg: string): boolean {
+    return this.stashes.remove(emailArg);
+  }
+
+  private assertNotKeyring(activeArg: IActiveAuth): void {
+    if (activeArg.source === 'keyring') {
+      throw new Error(KEYRING_MESSAGE);
+    }
+  }
+
+  /**
+   * Stops the app-server if it is up. Returns whether it was running, which is
+   * also the signal for whether to start it again afterwards -- a daemon that
+   * was down before a command stays down after it.
+   */
+  private quiesceDaemon(notesArg: string[]): boolean {
+    if (!this.daemon.isDaemonRunning()) {
+      notesArg.push('app-server was not running');
+      return false;
+    }
+    const stopResult = this.daemon.stop();
+    if (!stopResult.ok) {
+      throw new Error(
+        `could not stop the Codex app-server, refusing to touch credentials underneath it: ${this.daemon.describeFailure(stopResult)}`,
+      );
+    }
+    return true;
+  }
+
+  /** Brings the app-server back, on the success path and the failure path alike. */
+  private resumeDaemon(
+    wasRunningArg: boolean,
+    notesArg: string[],
+    problemsArg: string[],
+  ): boolean {
+    if (!wasRunningArg) {
+      return false;
+    }
+    const startResult = this.daemon.start();
+    if (!startResult.ok) {
+      problemsArg.push(
+        `the app-server did not come back up (${this.daemon.describeFailure(startResult)}); remote control is down until you run \`codex app-server daemon start\``,
+      );
+      return false;
+    }
+    notesArg.push('app-server restarted');
+    return true;
+  }
+}