@modelprofile.com/authswitch 6.2.0 → 6.3.0

package/ts/classes.cli.ts

@@ -8,16 +8,17 @@ import { AglAuthSwitchCoordinator, AuthSwitchOperations, authSwitchMutationRepla
 import { readAccountList } from './classes.accountlist.js';
 import { AccountListRenderer } from './classes.listrenderer.js';
 import { accountLimits, activeAccounts, CondensedRenderer } from './classes.limits.js';
-import { consoleTable } from './consoletable.js';
-import { accountName, credentialDriftNote, orderedUsageWindows, readAccountBadges, until, usagePercentText } from './accounts.js';
+import { consoleHeading, consoleTable } from './consoletable.js';
+import { accountName, credentialDriftNote, readAccountBadges, until, usagePercentText } from './accounts.js';
 import { describeHarnessProcesses, describeStopOutcome } from './classes.harnessprocesses.js';
-import { defaultPreusePrompt, PreuseError, validatePreuseOptions } from './preuse.js';
+import { defaultPreusePrompt, preuseAccounts, preuseCountsText, PreuseError, preuseTargets, validatePreuseOptions,
+  type IPreuseRunSummary, type TPreuseAccountResult, type TPreuseOutcome, type TPreuseRunEvent } from './preuse.js';
 import { parseCommandArgs, parseDurationOption, parseIntegerOption, UsageError } from './cliargs.js';
 import { AuthSwitchWatch, watchEventText } from './classes.watch.js';
 import { WatchBusyError, WatchLock } from './classes.watchlock.js';
 import { authSwitchHome } from './classes.credentialstore.js';
 import type { CodexSwitcher } from './classes.codexswitcher.js';
-import type { IAuthHarness, IHarnessAccount, IHarnessOutcome, IHarnessProcess, IHarnessState, IHarnessStopOutcome, IHarnessPreuseResult } from './interfaces.harness.js';
+import type { IAuthHarness, IHarnessAccount, IHarnessOutcome, IHarnessProcess, IHarnessState, IHarnessStopOutcome } from './interfaces.harness.js';
 import { bold, dim, green, orange, plainText, red } from './formatting.js';
 
 const canPrompt = (): boolean =>
@@ -31,9 +32,56 @@ const STOP_COMMANDS = ['use', 'stash'];
 /** Overviews across every registered harness; none of them changes which account is in use, and all support --json. */
 const OVERVIEW_COMMANDS = ['list', 'ls', 'limits', 'active'];
 const WATCH_USAGE = 'Usage: authswitch [harness] watch [harness] [--interval <duration>] [--threshold <percent>] [--dry-run] [--once] [--json]';
+const PREUSE_USAGE = 'Usage: authswitch [harness] preuse <account>|--all [--prompt <text>] [--model <id>]';
+/** How each outcome of a preuse run is titled in its results table. */
+const PREUSE_OUTCOMES: Readonly<Record<TPreuseOutcome, string>> = { completed: 'Completed', skipped: 'Skipped', failed: 'Failed', interrupted: 'Interrupted' };
+/** A cell of a preuse results row that has no value because nothing was sent for that account. */
+const PREUSE_UNSENT = '-';
 const WATCH_INTERVAL = { defaultMs: 120_000, minMs: 60_000, maxMs: 86_400_000 };
 const WATCH_THRESHOLD = { default: 95, min: 50, max: 100 };
 
+/** How one preuse run is asked for and reported; see `AuthSwitchCli.runPreuse`. */
+interface IPreuseRunOptions {
+  prompt: string;
+  model?: string;
+  /** Number each account as it starts and end with the results table, instead of one account's reset schedule. */
+  several: boolean;
+  /** Report a stated refusal as a failure, which is the single named account's own contract. */
+  strict: boolean;
+}
+
+/** One account's row in the results table of a run over several accounts. */
+interface IPreuseSummaryRow {
+  account: string;
+  outcome: string;
+  model: string;
+  tokens: string;
+  reset: string;
+}
+
+/**
+ * One account's results row, from what the run already read.
+ *
+ * An account that sent no prompt has no model, no token count and no deadline of its own, which the row
+ * says rather than filling in a zero. A completed prompt shows the first window of the schedule the run
+ * read afterwards, and says when the provider reported none or the lookup did not answer.
+ */
+const preuseSummaryRow = (resultArg: TPreuseAccountResult, nowArg: number): IPreuseSummaryRow => {
+  const account = accountName(resultArg.account);
+  if (resultArg.outcome !== 'completed') {
+    return { account, outcome: PREUSE_OUTCOMES[resultArg.outcome], model: PREUSE_UNSENT, tokens: PREUSE_UNSENT, reset: PREUSE_UNSENT };
+  }
+  const window = resultArg.schedule.kind === 'reported' ? resultArg.schedule.windows[0] : undefined;
+  return {
+    account,
+    outcome: PREUSE_OUTCOMES.completed,
+    model: plainText(resultArg.result.model),
+    tokens: [resultArg.result.inputTokens, resultArg.result.outputTokens, resultArg.result.totalTokens].map(count => count ?? 'unreported').join('/'),
+    reset: window ? until(window.resetAt, nowArg)
+      : resultArg.schedule.kind === 'reported' ? 'None reported' : resultArg.schedule.kind === 'notRead' ? 'Not read' : 'Unavailable',
+  };
+};
+
 /** The account a command acts on, named as it was offered, with the badge it was offered with. */
 interface IChosenAccount {
   id: string;
@@ -76,8 +124,9 @@ ${bold('Usage')}
   authswitch list --json             print all account information as JSON
   authswitch limits                  one row per account and limit type: used % and reset countdown
   authswitch active                  one row per provider: which account is in use, and since when
-  authswitch <harness> preuse <account> [--prompt <text>] [--model <id>]
-                                    send one prompt through that account without switching
+  authswitch <harness> preuse <account>|--all [--prompt <text>] [--model <id>]
+                                    send one prompt through that account without switching;
+                                    --all does it for every account of the harness, one at a time
   authswitch watch [harness] [--interval <duration>] [--threshold <percent>] [--dry-run] [--once] [--json]
                                     check usage every 2m and switch to a better saved account
                                     when the active one reaches the threshold (95%)
@@ -119,7 +168,10 @@ account is used up, to the one usable again first. No session of yours is stoppe
 a Codex switch restarts Codex' own app-server; --dry-run only reports, --once checks once.
 One watch runs per AUTHSWITCH_HOME.
 
-Preuse consumes the selected account's quota. Its default prompt is:
+Preuse consumes the selected account's quota, and --all consumes every account's. Accounts run
+one at a time, each with one request and no retry; Ctrl+C stops before the next account starts.
+It exits 1 when a prompt failed, 130 when it was interrupted, and 2 on a usage error; --all also
+exits 0 when an account was refused for a stated reason. Its default prompt is:
   "${defaultPreusePrompt}"
 
 ${bold('Environment')}
@@ -321,18 +373,28 @@ ${bold('Environment')}
     }
   }
 
+  /**
+   * Send the preuse prompt through one named account, through an account chosen here, or through every
+   * account of the harness.
+   *
+   * `--all` walks the harness's own account list, one request at a time, and ends with a table of what
+   * each account did; a single named account keeps its own contract, in which anything but a completed
+   * prompt is a failure. Neither form switches, refreshes or writes a login.
+   */
   private async commandPreuse(harnessArg: IAuthHarness | undefined, argsArg: string[]): Promise<number> {
     let reference: string | undefined;
+    let all: boolean;
     let prompt: string;
     let model: string | undefined;
     try {
-      const parsed = parseCommandArgs(argsArg, { values: ['--prompt', '--model'], flags: [], maxPositionals: 1,
-        usage: 'Usage: authswitch [harness] preuse <account> [--prompt <text>] [--model <id>]' });
+      const parsed = parseCommandArgs(argsArg, { values: ['--prompt', '--model'], flags: ['--all'], maxPositionals: 1, usage: PREUSE_USAGE });
       [reference] = parsed.positionals;
+      all = parsed.flags.has('--all');
       prompt = parsed.values.get('--prompt') ?? defaultPreusePrompt;
       model = parsed.values.get('--model');
       validatePreuseOptions({ prompt, model });
-      if (!reference && !canPrompt()) throw new UsageError('preuse requires an account outside an interactive terminal.');
+      if (all && reference !== undefined) throw new UsageError(`--all preuses every account of the harness, so it takes no account. ${PREUSE_USAGE}`);
+      if (!all && !reference && !canPrompt()) throw new UsageError('preuse requires an account or --all outside an interactive terminal.');
     } catch (error) {
       process.stderr.write(`${error instanceof UsageError || error instanceof PreuseError ? error.message : 'Invalid preuse arguments.'}\n`);
       return 2;
@@ -341,63 +403,159 @@ ${bold('Environment')}
     if (!harness) return canPrompt() ? 0 : 2;
     if (!harness.preuseAccount) { process.stderr.write(`Preuse is not supported by ${plainText(harness.label)}.\n`); return 2; }
     const state = await harness.readState();
-    let account: IHarnessAccount | undefined;
-    if (reference) {
-      const matches = state.accounts.filter(item => item.id === reference || item.label === reference);
-      if (matches.length > 1) { process.stderr.write('That account reference is ambiguous; use an exact account ID.\n'); return 1; }
-      account = matches[0];
-      if (!account) {
-        const id = await this.resolveAccount(harness, reference);
-        if (id === null) return 1;
-        account = state.accounts.find(item => item.id === id);
-      }
-    } else {
-      const answer = await this.out.prompts.ask({
-        name: 'preuseAccount', type: 'list', message: `Which ${harness.label} account should receive the preuse prompt? This consumes quota.`,
-        choices: [...state.accounts.map(item => ({ name: plainText(item.label), value: item.id })), { name: 'Back', value: '' }],
-      });
-      if (!answer) return 0;
-      account = state.accounts.find(item => item.id === answer);
+    if (all) {
+      const accounts = preuseTargets(state.accounts);
+      if (!accounts.length) { process.stderr.write(`${plainText(harness.label)} has no accounts to preuse.\n`); return 1; }
+      return await this.runPreuse(harness, accounts, { prompt, model, several: true, strict: false });
+    }
+    if (!reference) return await this.preuseFromPicker(harness, state, { prompt, model });
+    const matches = state.accounts.filter(item => item.id === reference || item.label === reference);
+    if (matches.length > 1) { process.stderr.write('That account reference is ambiguous; use an exact account ID.\n'); return 1; }
+    let account: IHarnessAccount | undefined = matches[0];
+    if (!account) {
+      const id = await this.resolveAccount(harness, reference);
+      if (id === null) return 1;
+      account = state.accounts.find(item => item.id === id);
     }
     if (!account) { process.stderr.write('The selected account is no longer available.\n'); return 1; }
+    return await this.runPreuse(harness, [account], { prompt, model, several: false, strict: true });
+  }
+
+  /**
+   * The account picker `preuse` shows without an account reference: one account, all of them, or Back.
+   *
+   * Choosing one account here is that account's consent, exactly as naming it on the command line is, and
+   * it keeps that command's contract. Choosing all of them spends quota on accounts the chooser did not
+   * name, so that answer is confirmed once and then runs as `--all` does, table and exit status included.
+   */
+  private async preuseFromPicker(harnessArg: IAuthHarness, stateArg: IHarnessState, optionsArg: { prompt: string; model?: string }): Promise<number> {
+    const accounts = preuseTargets(stateArg.accounts);
+    const answer = await this.out.prompts.ask({
+      name: 'preuseAccount', type: 'list', message: `Which ${harnessArg.label} account should receive the preuse prompt? This consumes quota.`,
+      choices: this.preuseChoices(accounts),
+    });
+    if (!answer) return 0;
+    const selected = this.preuseSelection(answer, accounts);
+    if (!selected.length) { process.stderr.write('The selected account is no longer available.\n'); return 1; }
+    const several = selected.length > 1;
+    if (several && !await this.confirmPreuse(selected)) return 0;
+    return await this.runPreuse(harnessArg, selected, { ...optionsArg, several, strict: !several });
+  }
+
+  /**
+   * The choices an interactive preuse offers: every account, one of them, or Back.
+   *
+   * The guide and the bare `preuse` command offer the same list with the same wording. An account id is an
+   * opaque string, so every choice says which kind of answer it carries instead of relying on a sentinel an
+   * id could collide with. A single account is offered alone: "all" of one account is that same account.
+   */
+  private preuseChoices(accountsArg: readonly IHarnessAccount[]): { name: string; value: string }[] {
+    return [
+      ...(accountsArg.length > 1 ? [{ name: `All accounts (${accountsArg.length})`, value: 'all' }] : []),
+      ...accountsArg.map(account => ({ name: accountName(account), value: `one:${account.id}` })),
+      { name: 'Back', value: '' },
+    ];
+  }
+
+  /** The accounts an answer names; empty when the chosen account is no longer there. */
+  private preuseSelection(answerArg: string, accountsArg: readonly IHarnessAccount[]): IHarnessAccount[] {
+    return answerArg === 'all' ? [...accountsArg] : accountsArg.filter(account => `one:${account.id}` === answerArg);
+  }
+
+  /** One confirmation, naming what the prompt goes to and that it consumes quota. */
+  private async confirmPreuse(accountsArg: readonly IHarnessAccount[]): Promise<boolean> {
+    return await this.out.prompts.ask({
+      name: 'confirmPreuse', type: 'confirm', default: false,
+      message: accountsArg.length === 1
+        ? `Send one preuse prompt through ${plainText(accountsArg[0].label)}? This consumes its quota.`
+        : `Send one preuse prompt through each of these ${accountsArg.length} accounts? This consumes quota on every one of them.`,
+    }) === true;
+  }
+
+  /**
+   * One preuse run and its report, for the command line and for the guide.
+   *
+   * Ctrl+C aborts the run: the account in flight is reported as interrupted and no further account is
+   * started, because a prompt that may already have been sent is never repeated. The exit status is 130
+   * for an interrupted run, 1 when an account failed -- and, for a single named account, when it was
+   * refused -- and 0 otherwise. Usage errors return 2 before anything reaches this.
+   */
+  private async runPreuse(harnessArg: IAuthHarness, accountsArg: readonly IHarnessAccount[], optionsArg: IPreuseRunOptions): Promise<number> {
     const controller = new AbortController();
     const cancel = () => controller.abort();
     process.once('SIGINT', cancel);
     process.once('SIGTERM', cancel);
     try {
-      let result: IHarnessPreuseResult;
-      try {
-        process.stdout.write(`Preusing ${plainText(account.label)} (${plainText(harness.label)})…\n`);
-        result = await harness.preuseAccount(account.id, { prompt, model, signal: controller.signal });
-      } catch (error) {
-        process.stderr.write(`${error instanceof PreuseError ? error.message : 'Preuse failed. Tokens may already have been consumed; check account status before trying again.'}\n`);
-        return controller.signal.aborted ? 130 : 1;
-      }
-      // Once inference completes, status or presentation failures must not report it as failed.
-      try {
-        process.stdout.write(`Prompt completed with ${plainText(result.model)}. Tokens: ${result.inputTokens ?? 'unreported'} input, ${result.outputTokens ?? 'unreported'} output, ${result.totalTokens ?? 'unreported'} total.\n`);
-        if (controller.signal.aborted) return 0;
-        const windows = orderedUsageWindows((await harness.readAccountStatus(account.id)).summary?.usageWindows);
-        if (windows?.length) {
-          const now = Date.now();
-          process.stdout.write('Reset schedule reported after the prompt:\n');
-          await consoleTable(this.out, windows, [
-            // The label already names the window by its length, so the column never repeats it.
-            { key: 'window', title: 'Window', value: row => plainText(row.label) },
-            { key: 'usage', title: 'Used', value: row => usagePercentText(row.usedPercent) },
-            { key: 'reset', title: 'Reset in', value: row => until(row.resetAt, now) },
-          ]);
-        } else process.stdout.write('Reset schedule could not be verified; the completed prompt will not be repeated.\n');
-      } catch {
-        process.stderr.write('Prompt completed, but its reset schedule could not be verified or displayed. The prompt will not be repeated.\n');
-      }
-      return 0;
+      const summary = await preuseAccounts(harnessArg, accountsArg, { prompt: optionsArg.prompt, model: optionsArg.model, signal: controller.signal },
+        event => this.writePreuseEvent(harnessArg, event, optionsArg.several));
+      if (optionsArg.several) await this.writePreuseSummary(summary);
+      else if (summary.results[0]) await this.writePreuseSchedule(summary.results[0]);
+      if (summary.counts.interrupted || summary.notRun.length) return 130;
+      return summary.counts.failed || (optionsArg.strict && summary.counts.skipped) ? 1 : 0;
     } finally {
       process.removeListener('SIGINT', cancel);
       process.removeListener('SIGTERM', cancel);
     }
   }
 
+  /** One line per event; a run over several accounts numbers each account as it starts. */
+  private writePreuseEvent(harnessArg: IAuthHarness, eventArg: TPreuseRunEvent, severalArg: boolean): void {
+    if (eventArg.kind === 'started') {
+      const position = severalArg ? `[${eventArg.index + 1}/${eventArg.total}] ` : '';
+      process.stdout.write(`${position}Preusing ${plainText(eventArg.account.label)} (${plainText(harnessArg.label)})…\n`);
+      return;
+    }
+    if (eventArg.result.outcome !== 'completed') { process.stderr.write(`${eventArg.result.reason}\n`); return; }
+    const result = eventArg.result.result;
+    process.stdout.write(`Prompt completed with ${plainText(result.model)}. Tokens: ${result.inputTokens ?? 'unreported'} input, ${result.outputTokens ?? 'unreported'} output, ${result.totalTokens ?? 'unreported'} total.\n`);
+  }
+
+  /**
+   * The reset schedule one completed prompt reported.
+   *
+   * Once inference completes, a schedule that could not be read or displayed is reported as exactly that:
+   * a completed prompt is never repeated over a lookup or presentation failure.
+   */
+  private async writePreuseSchedule(resultArg: TPreuseAccountResult): Promise<void> {
+    if (resultArg.outcome !== 'completed' || resultArg.schedule.kind === 'notRead') return;
+    if (resultArg.schedule.kind === 'reported') {
+      const windows = [...resultArg.schedule.windows];
+      try {
+        if (!windows.length) { process.stdout.write('Reset schedule could not be verified; the completed prompt will not be repeated.\n'); return; }
+        const now = Date.now();
+        process.stdout.write('Reset schedule reported after the prompt:\n');
+        await consoleTable(this.out, windows, [
+          // The label already names the window by its length, so the column never repeats it.
+          { key: 'window', title: 'Window', value: row => plainText(row.label) },
+          { key: 'usage', title: 'Used', value: row => usagePercentText(row.usedPercent) },
+          { key: 'reset', title: 'Reset in', value: row => until(row.resetAt, now) },
+        ]);
+        return;
+      } catch { /* A schedule that could not be displayed is reported below, like one that could not be read. */ }
+    }
+    process.stderr.write('Prompt completed, but its reset schedule could not be verified or displayed. The prompt will not be repeated.\n');
+  }
+
+  /** What every account of a run did, in one table. The rows repeat readings the run already took. */
+  private async writePreuseSummary(summaryArg: IPreuseRunSummary): Promise<void> {
+    const now = Date.now();
+    const rows: IPreuseSummaryRow[] = [
+      ...summaryArg.results.map(result => preuseSummaryRow(result, now)),
+      ...summaryArg.notRun.map((account): IPreuseSummaryRow => ({
+        account: accountName(account), outcome: 'Not run', model: PREUSE_UNSENT, tokens: PREUSE_UNSENT, reset: PREUSE_UNSENT,
+      })),
+    ];
+    consoleHeading('Preuse results');
+    await consoleTable(this.out, rows, [
+      { key: 'account', title: 'Account', value: row => row.account },
+      { key: 'outcome', title: 'Outcome', value: row => row.outcome },
+      { key: 'model', title: 'Model', value: row => row.model },
+      { key: 'tokens', title: 'Tokens in/out/total', value: row => row.tokens },
+      { key: 'reset', title: 'Next reset', value: row => row.reset },
+    ]);
+    process.stdout.write(`${preuseCountsText(summaryArg)}.\n`);
+  }
+
   /**
    * Watch usage and switch automatically; see `AuthSwitchWatch`. SIGINT and SIGTERM end it cleanly with status 0.
    * `--once` runs one check and exits 1 when a switch it attempted did not complete.
@@ -505,6 +663,7 @@ ${bold('Environment')}
           { name: 'Switch to a saved account', value: 'use' },
           { name: 'Save the current login', value: 'stash' },
           ...(harnessArg.beginLogin ? [{ name: 'Log in and save another account', value: 'login' }] : []),
+          ...(harnessArg.preuseAccount ? [{ name: 'Preuse an account or all accounts (consumes quota)', value: 'preuse' }] : []),
           { name: 'List accounts, subscription, usage and resets', value: 'list' },
           { name: harnessArg.diagnosticsLabel, value: 'doctor' },
           { name: 'Remove a saved account', value: 'drop' },
@@ -531,6 +690,7 @@ ${bold('Environment')}
           if (mode === 'keep' || mode === 'clear') code = this.reportOutcome(await this.mutate(harnessArg, { harnessId: harnessArg.id, action: 'save', keepActive: mode === 'keep', accountId: active.id }));
           break;
         }
+        case 'preuse': code = await this.guidePreuse(harnessArg); break;
         case 'list': code = await this.commandList([harnessArg]); break;
         case 'doctor': code = this.reportOutcome(await harnessArg.diagnose()); break;
         case 'drop': {
@@ -550,6 +710,28 @@ ${bold('Environment')}
     }
   }
 
+  /**
+   * Preuse from the guide: one account or all of them, confirmed once before anything is sent.
+   *
+   * The prompt consumes quota, so the confirmation names what it will be sent to, and Back or a declined
+   * confirmation returns to the menu having sent nothing. A refusal an adapter states is not a guide
+   * failure, so the guide stays open; a failed prompt ends it, as every other failed action does.
+   */
+  private async guidePreuse(harnessArg: IAuthHarness): Promise<number> {
+    const accounts = preuseTargets((await harnessArg.readState()).accounts);
+    if (!accounts.length) { process.stderr.write(`${red('no accounts to preuse')} - run \`authswitch ${harnessArg.id} stash\` first\n`); return 0; }
+    const answer = await this.out.prompts.ask({
+      name: 'preuseTarget', type: 'list', message: `Which ${harnessArg.label} account should receive the preuse prompt? This consumes quota.`,
+      choices: this.preuseChoices(accounts),
+    });
+    if (!answer) return 0;
+    const selected = this.preuseSelection(answer, accounts);
+    if (!selected.length) { process.stderr.write('The selected account is no longer available.\n'); return 0; }
+    // The guide confirms either answer: it is a menu one lands in, not a command that named its account.
+    if (!await this.confirmPreuse(selected)) return 0;
+    return await this.runPreuse(harnessArg, selected, { prompt: defaultPreusePrompt, several: selected.length > 1, strict: false });
+  }
+
   private printCurrent(harnessArg: IAuthHarness, stateArg: IHarnessState): void {
     process.stdout.write(`\n${bold(`Current ${harnessArg.label} account`)}\n`);
     const active = stateArg.accounts.filter(account => account.isActive);

package/ts/classes.codexpreuse.ts

@@ -70,7 +70,7 @@ export class CodexPreuse {
     } 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.');
+        : 'Preuse was cancelled before the prompt was sent.', requestStarted);
     }
   }
 }

package/ts/classes.tui.ts

@@ -1,10 +1,16 @@
 import * as plugins from './plugins.js';
-import type { IAuthHarness, IHarnessOutcome, IHarnessProcess, IHarnessState, IHarnessStopOutcome } from './interfaces.harness.js';
+import type { IAuthHarness, IHarnessAccount, IHarnessOutcome, IHarnessProcess, IHarnessState, IHarnessStopOutcome } from './interfaces.harness.js';
 import { accountBadge, accountDetails, accountPlan, accountQuotaSummary, accountResets, accountState, accountUsageWindows, usageWindowName, until, readAccountRows, type IAccountRow } from './accounts.js';
+import { defaultPreusePrompt, preuseAccounts, preuseCountsText, preuseTargets, type TPreuseAccountResult } from './preuse.js';
 import { plainText } from './formatting.js';
 import { AuthSwitchOperations, authSwitchMutationReplacesLogin, type TAuthSwitchMutation } from './classes.operations.js';
 import { describeHarnessProcesses, describeStopOutcome } from './classes.harnessprocesses.js';
 
+/** One account's preuse result, as the dashboard's activity log and footer report it. */
+const preuseResultLine = (resultArg: TPreuseAccountResult): string => resultArg.outcome === 'completed'
+  ? `${plainText(resultArg.account.label)}: completed with ${plainText(resultArg.result.model)}, ${resultArg.result.totalTokens ?? 'unreported'} tokens.`
+  : `${plainText(resultArg.account.label)}: ${resultArg.reason}`;
+
 /** Owns account-management actions; terminal rendering and interaction belong to smartconsole. */
 export class AuthSwitchTui {
   constructor(private readonly harnesses: readonly IAuthHarness[], private readonly out: plugins.smartconsole.SmartConsole, private readonly operations = new AuthSwitchOperations()) {}
@@ -126,6 +132,30 @@ export class AuthSwitchTui {
       await refresh(screen);
       if (showOutcome(outcome)) ui.logs.append(`Now active: ${plainText(target.label)}${badge}`);
     };
+    /**
+     * Send one preuse prompt through each of these accounts, after one confirmation that names the cost.
+     *
+     * The prompt consumes the account's own quota, so nothing is sent before consent, the accounts run
+     * one at a time through the shared runner, and the footer follows the run account by account. Closing
+     * the dashboard aborts it before the next account starts. Nothing is switched, saved or written.
+     */
+    const preuse = async (screen: plugins.smartconsole.ITuiContext, accountsArg: readonly IHarnessAccount[]): Promise<void> => {
+      if (!harness.preuseAccount) { footer.setText(`${plainText(harness.label)} does not support preuse.`); return; }
+      if (!accountsArg.length) { footer.setText('Select an account to preuse.'); return; }
+      const message = accountsArg.length === 1
+        ? `Send one preuse prompt through ${plainText(accountsArg[0].label)}? This consumes its quota.`
+        : `Send one preuse prompt through each of these ${accountsArg.length} ${plainText(harness.label)} accounts? This consumes quota on every one of them.`;
+      if (!await screen.confirm(message, { confirmLabel: 'Preuse' })) return;
+      if (screen.signal.aborted) return;
+      const summary = await preuseAccounts(harness, accountsArg, { prompt: defaultPreusePrompt, signal: screen.signal }, event => {
+        if (event.kind === 'started') footer.setText(`Preusing ${plainText(event.account.label)} (${event.index + 1}/${event.total})…`);
+        else { const line = preuseResultLine(event.result); ui.logs.append(line); footer.setText(line); }
+        void screen.invalidate();
+      });
+      // The prompts moved usage and reset deadlines, so the table is read again before the counts are shown.
+      await refresh(screen);
+      footer.setText(`Preuse: ${preuseCountsText(summary)}.`);
+    };
     const remove = async (screen: plugins.smartconsole.ITuiContext): Promise<void> => {
       const selected = table.selected;
       if (!selected || (!selected.account.isStashed && selected.account.savedAt === null)) { footer.setText('Select an account with a saved copy.'); return; }
@@ -156,7 +186,7 @@ export class AuthSwitchTui {
         return ui.column([
           ui.text('authswitch · account management', { height: 1 }),
           this.harnesses.length > 1 ? ui.row([ui.panel('Harnesses', harnessTable, { width: 23 }), accountView]) : accountView,
-          ui.text('Enter switch · a save · c save+clear · d remove · r refresh · g diagnose · Tab focus · q quit', { height: 2 }),
+          ui.text(`Enter switch · a save · c save+clear · d remove${harness.preuseAccount ? ' · p preuse · P preuse all' : ''} · r refresh · g diagnose · Tab focus · q quit`, { height: 2 }),
           footer,
         ]);
       },
@@ -167,6 +197,13 @@ export class AuthSwitchTui {
         a: screen => perform(screen, () => save(screen, true)),
         c: screen => perform(screen, () => save(screen, false)),
         d: screen => perform(screen, () => remove(screen)),
+        // The key map is fixed for the session while the harness selector can change the harness, so both
+        // preuse keys are always bound and the action itself reports a harness that does not support it.
+        p: screen => perform(screen, async () => {
+          const selected = table.selected?.account.id;
+          await preuse(screen, preuseTargets((await harness.readState()).accounts).filter(account => account.id === selected));
+        }),
+        P: screen => perform(screen, async () => { await preuse(screen, preuseTargets((await harness.readState()).accounts)); }),
         g: screen => perform(screen, async () => { showOutcome(await harness.diagnose()); }),
       },
     });

package/ts/preuse.ts

@@ -1,9 +1,19 @@
-import type { IHarnessPreuseOptions } from './interfaces.harness.js';
+import { orderedUsageWindows } from './accounts.js';
+import type { IAuthHarness, IHarnessAccount, IHarnessPreuseOptions, IHarnessPreuseResult, IHarnessUsageWindow } from './interfaces.harness.js';
 
 export const defaultPreusePrompt = 'Write 2000 words about strawberries.';
 
-/** Only fixed local messages may cross the inference error boundary. */
-export class PreuseError extends Error {}
+/**
+ * Only fixed local messages may cross the inference error boundary.
+ *
+ * `requestStarted` says whether the prompt may already have reached the provider. False is a refusal that
+ * sent nothing -- an unsupported login, a missing credential, a model catalog that could not be read before
+ * the prompt -- so the account's quota is untouched. True, and any error that is not a `PreuseError` at all,
+ * means tokens may have been consumed, and such a request is never repeated automatically.
+ */
+export class PreuseError extends Error {
+  constructor(messageArg: string, public readonly requestStarted = false) { super(messageArg); }
+}
 
 export const validatePreuseOptions = (optionsArg: IHarnessPreuseOptions): void => {
   if (typeof optionsArg.prompt !== 'string' || !optionsArg.prompt.trim() || Buffer.byteLength(optionsArg.prompt, 'utf8') > 16_384) {
@@ -13,3 +23,131 @@ export const validatePreuseOptions = (optionsArg: IHarnessPreuseOptions): void =
     throw new PreuseError('The preuse model must be a valid model identifier of at most 128 characters.');
   }
 };
+
+/**
+ * What one account's turn in a run did.
+ *
+ * `skipped` is a refusal that sent nothing and consumed nothing, with the reason the adapter stated.
+ * `failed` and `interrupted` may both have consumed tokens, so neither is ever retried by the runner.
+ */
+export type TPreuseOutcome = 'completed' | 'skipped' | 'failed' | 'interrupted';
+
+/**
+ * The reset schedule read after a prompt completed.
+ *
+ * `reported` carries what the provider answered, which may be no window at all; `unavailable` is a lookup
+ * that failed, and `notRead` is a run the user interrupted before it asked. None of them says anything
+ * about the completed prompt, which is never repeated because its schedule could not be confirmed.
+ */
+export type TPreuseSchedule =
+  | { kind: 'reported'; windows: readonly IHarnessUsageWindow[] }
+  | { kind: 'unavailable' }
+  | { kind: 'notRead' };
+
+export type TPreuseAccountResult =
+  | { account: IHarnessAccount; outcome: 'completed'; result: IHarnessPreuseResult; schedule: TPreuseSchedule }
+  | { account: IHarnessAccount; outcome: Exclude<TPreuseOutcome, 'completed'>; reason: string };
+
+/** One account starting, and that account's result. A run reports nothing else, and never the generated prose. */
+export type TPreuseRunEvent =
+  | { kind: 'started'; index: number; total: number; account: IHarnessAccount }
+  | { kind: 'finished'; index: number; total: number; result: TPreuseAccountResult };
+
+export interface IPreuseRunSummary {
+  results: readonly TPreuseAccountResult[];
+  counts: Readonly<Record<TPreuseOutcome, number>>;
+  /** Accounts an abort kept the run from reaching. Nothing was sent for them. */
+  notRun: readonly IHarnessAccount[];
+}
+
+/**
+ * Every account a run may preuse, in the order the harness lists them, each at most once.
+ *
+ * A harness reports an active login and that login's saved record as one account -- Codex keys both by
+ * email, the file harness merges the active login into its saved record by account id -- so the walk is
+ * the account list itself. The seen set keeps a repeated id from being charged twice regardless.
+ */
+export const preuseTargets = (accountsArg: readonly IHarnessAccount[]): IHarnessAccount[] => {
+  const seen = new Set<string>();
+  const targets: IHarnessAccount[] = [];
+  for (const account of accountsArg) {
+    if (seen.has(account.id)) continue;
+    seen.add(account.id);
+    targets.push(account);
+  }
+  return targets;
+};
+
+/**
+ * A run's counts in one line, for a command's closing line and for the dashboard footer.
+ *
+ * Completed accounts are always named, including none of them; every other count appears only when it
+ * happened, so a clean run reads as one fact rather than as four.
+ */
+export const preuseCountsText = (summaryArg: IPreuseRunSummary): string => [
+  `${summaryArg.counts.completed} completed`,
+  ...(summaryArg.counts.skipped ? [`${summaryArg.counts.skipped} skipped`] : []),
+  ...(summaryArg.counts.failed ? [`${summaryArg.counts.failed} failed`] : []),
+  ...(summaryArg.counts.interrupted ? [`${summaryArg.counts.interrupted} interrupted`] : []),
+  ...(summaryArg.notRun.length ? [`${summaryArg.notRun.length} not run`] : []),
+].join(', ');
+
+/** An adapter's own fixed message, or the fixed local text for an error that crossed the boundary unnamed. */
+const preuseReason = (errorArg: unknown): string => errorArg instanceof PreuseError
+  ? errorArg.message
+  : 'Preuse failed. Tokens may already have been consumed; check account status before trying again.';
+
+/**
+ * The account's reset schedule, read after its prompt completed, exactly as the single-account command reads it.
+ *
+ * The read never activates or writes a login, and its failure never turns a completed prompt into a failed
+ * one: there is nothing to undo and nothing worth repeating. An interrupted run does not ask at all.
+ */
+const readPreuseSchedule = async (harnessArg: IAuthHarness, accountArg: IHarnessAccount, signalArg: AbortSignal): Promise<TPreuseSchedule> => {
+  if (signalArg.aborted) return { kind: 'notRead' };
+  try {
+    const status = await harnessArg.readAccountStatus(accountArg.id, { signal: signalArg });
+    return { kind: 'reported', windows: orderedUsageWindows(status.summary?.usageWindows) };
+  } catch { return { kind: 'unavailable' }; }
+};
+
+/**
+ * Send one preuse prompt through each account in turn, and report what each one did.
+ *
+ * Accounts run strictly one after another, each with exactly one inference request and no retry, because
+ * every request costs the account's own quota. An aborted signal stops the run before the next account
+ * starts, and an account already in flight is reported as interrupted: its tokens may be gone either way,
+ * which is why nothing is repeated. Nothing is switched, refreshed, stopped or written anywhere.
+ */
+export const preuseAccounts = async (
+  harnessArg: IAuthHarness,
+  accountsArg: readonly IHarnessAccount[],
+  optionsArg: { prompt: string; model?: string; signal: AbortSignal },
+  reportArg: (eventArg: TPreuseRunEvent) => void,
+): Promise<IPreuseRunSummary> => {
+  const preuseAccount = harnessArg.preuseAccount?.bind(harnessArg);
+  if (!preuseAccount) throw new PreuseError('This harness does not support preuse.');
+  validatePreuseOptions(optionsArg);
+  const results: TPreuseAccountResult[] = [];
+  const counts: Record<TPreuseOutcome, number> = { completed: 0, skipped: 0, failed: 0, interrupted: 0 };
+  const notRun: IHarnessAccount[] = [];
+  const total = accountsArg.length;
+  for (const [index, account] of accountsArg.entries()) {
+    if (optionsArg.signal.aborted) { notRun.push(account); continue; }
+    reportArg({ kind: 'started', index, total, account });
+    let result: TPreuseAccountResult;
+    try {
+      const completed = await preuseAccount(account.id, { prompt: optionsArg.prompt, model: optionsArg.model, signal: optionsArg.signal });
+      result = { account, outcome: 'completed', result: completed, schedule: await readPreuseSchedule(harnessArg, account, optionsArg.signal) };
+    } catch (error) {
+      // A cancelled account is interrupted whether or not its prompt went out; its reason says which.
+      const outcome = optionsArg.signal.aborted ? 'interrupted'
+        : error instanceof PreuseError && !error.requestStarted ? 'skipped' : 'failed';
+      result = { account, outcome, reason: preuseReason(error) };
+    }
+    results.push(result);
+    counts[result.outcome]++;
+    reportArg({ kind: 'finished', index, total, result });
+  }
+  return { results, counts, notRun };
+};