@victor-software-house/pi-multicodex 2.0.12 → 2.1.0

package/README.md

@@ -23,12 +23,13 @@ To manage your accounts inside a session, type `/multicodex`.
 When you start a session, MultiCodex:
 
 1. Imports your existing pi Codex auth automatically (if present).
-2. Checks usage data across all managed accounts.
-3. Picks the best available account — untouched accounts first, then the one whose weekly reset window ends soonest, then a random available account as fallback.
+2. Merges duplicate imported credentials into the managed pool so one account does not consume multiple rotation slots.
+3. Checks usage data across all managed accounts.
+4. Picks the best available account — untouched accounts first, then the one whose weekly reset window ends soonest, then a random available account as fallback.
 
-If you pin a specific account with `/multicodex use`, that account is used until it hits quota or you clear the override.
+If you pin a specific account from `/multicodex accounts` or `/multicodex use`, that account is used until it hits quota, fails auth validation, or you clear the override.
 
-When a request hits a quota or rate limit **before** any output is streamed, MultiCodex marks that account exhausted, picks the next available one, and retries. This happens up to 5 times transparently. If the manual override account fails, the override is cleared and rotation continues with the remaining accounts. Once output has started streaming, the error is surfaced as-is — no mid-stream account switching.
+When a request hits a quota or rate limit **before** any output is streamed, MultiCodex marks that account exhausted, picks the next available one, and retries. This happens up to 5 times transparently. If token validation or token refresh fails before the request starts, MultiCodex skips that account and retries another healthy one. If the manual override account fails, the override is cleared and rotation continues with the remaining accounts. Once output has started streaming, the error is surfaced as-is — no mid-stream account switching.
 
 ## Commands
 
@@ -37,27 +38,35 @@ Everything lives under one command: `/multicodex`.
 | Command | What it does |
 |---|---|
 | `/multicodex` | Open the main interactive menu |
-| `/multicodex show` | Print account status and cached usage |
-| `/multicodex use [identifier]` | Activate an account, or open the picker if no identifier given |
+| `/multicodex accounts [identifier]` | Inspect account health, select an account, add one, or directly activate/login by identifier |
+| `/multicodex use [identifier]` | Alias for `/multicodex accounts [identifier]` |
+| `/multicodex show` | Alias for the account-management view; in non-interactive mode it prints per-account health lines |
+| `/multicodex refresh [identifier\|all]` | Refresh token validity and usage data for one account or all accounts |
+| `/multicodex reauth [identifier]` | Re-authenticate one account explicitly |
 | `/multicodex footer` | Configure the usage footer display |
 | `/multicodex rotation` | Show the current rotation policy |
-| `/multicodex verify` | Check that local storage paths are writable |
+| `/multicodex verify` | Check storage, settings, auth import, and reauth health |
 | `/multicodex path` | Print storage and settings file locations |
 | `/multicodex reset [manual\|quota\|all]` | Clear manual override, quota cooldowns, or both |
 | `/multicodex help` | Print a compact usage line |
 
-All subcommands support dynamic autocomplete. `/multicodex use` also autocompletes from your managed account list.
+All subcommands support dynamic autocomplete. Account-focused subcommands autocomplete from the managed account list.
 
-Commands that do not need a UI panel (`show`, `verify`, `path`, `reset`, `help`) work in non-interactive mode too.
+Commands that do not need a UI panel (`show`, `refresh`, `verify`, `path`, `reset`, `help`) work in non-interactive mode too.
 
-## Account picker
+## Account manager
 
-The `/multicodex use` picker lets you select, add, and remove accounts in one place.
+The `/multicodex accounts` panel merges the old `show` and `use` flows into one place.
 
 ![MultiCodex use picker](./assets/multicodex-use-picker.png)
 
 - **Enter** activates the highlighted account.
-- **Backspace** removes it (after confirmation).
+- **U** refreshes token and usage health for the selected account.
+- **R** re-authenticates the selected account.
+- **N** starts login for a new managed account.
+- **Backspace** removes the selected account after confirmation.
+
+Each row shows the account identifier, active/manual state, reauth state, quota state, linked imported auth state, and cached 5-hour and weekly usage windows.
 
 When you remove an active account, MultiCodex switches to the next available one automatically.
 
@@ -74,8 +83,8 @@ You can customize which fields appear and their ordering with `/multicodex foote
 ## What it does under the hood
 
 - **Provider override.** MultiCodex registers itself as the `openai-codex` provider. You do not need to select a different provider or change your model — it works with whatever Codex model you already use.
-- **Auth import.** When pi has stored Codex OAuth credentials, MultiCodex imports them automatically. You can also add accounts manually with `/multicodex use <email>`.
-- **Token refresh.** OAuth tokens are refreshed before expiry so requests do not fail due to stale credentials.
+- **Auth import.** When pi has stored Codex OAuth credentials, MultiCodex imports them automatically and merges duplicate credentials into existing managed accounts when possible.
+- **Token refresh.** OAuth tokens are refreshed before expiry so requests do not fail due to stale credentials. You can also force a health refresh with `/multicodex refresh` or re-authenticate explicitly with `/multicodex reauth`.
 - **Usage tracking.** Usage data is fetched from the Codex API and cached for 5 minutes per account. The footer renders cached data immediately and refreshes in the background.
 - **Quota cooldown.** When an account is exhausted, it stays on cooldown until its next known reset time (or 1 hour if the reset time is unknown).
 - **Shared utility seams.** Provider mirroring, stream primitives, and `~/.pi/agent/*` path helpers are shared with `pi-credential-vault` through `@victor-software-house/pi-provider-utils`. MultiCodex still owns account storage, token policy, footer behavior, and command UX.

package/account-manager.ts

@@ -83,39 +83,153 @@ export class AccountManager {
 		this.warningHandler = handler;
 	}
 
+	private updateAccountEmail(account: Account, email: string): boolean {
+		if (account.email === email) return false;
+		const previousEmail = account.email;
+		account.email = email;
+		if (this.data.activeEmail === previousEmail) {
+			this.data.activeEmail = email;
+		}
+		if (this.manualEmail === previousEmail) {
+			this.manualEmail = email;
+		}
+		const cached = this.usageCache.get(previousEmail);
+		if (cached) {
+			this.usageCache.delete(previousEmail);
+			this.usageCache.set(email, cached);
+		}
+		return true;
+	}
+
+	private removeAccountRecord(account: Account): boolean {
+		const index = this.data.accounts.findIndex(
+			(candidate) => candidate.email === account.email,
+		);
+		if (index < 0) return false;
+		const removedEmail = this.data.accounts[index]?.email;
+		this.data.accounts.splice(index, 1);
+		if (removedEmail) {
+			this.usageCache.delete(removedEmail);
+			if (this.manualEmail === removedEmail) {
+				this.manualEmail = undefined;
+			}
+			if (this.data.activeEmail === removedEmail) {
+				this.data.activeEmail = this.data.accounts[0]?.email;
+			}
+		}
+		return true;
+	}
+
+	private findAccountByRefreshToken(
+		refreshToken: string,
+		excludeEmail?: string,
+	): Account | undefined {
+		return this.data.accounts.find(
+			(account) =>
+				account.refreshToken === refreshToken && account.email !== excludeEmail,
+		);
+	}
+
+	private applyCredentials(
+		account: Account,
+		creds: OAuthCredentials,
+		options?: {
+			importSource?: "pi-openai-codex";
+			importFingerprint?: string;
+		},
+	): boolean {
+		const accountId =
+			typeof creds.accountId === "string" ? creds.accountId : undefined;
+		let changed = false;
+		if (account.accessToken !== creds.access) {
+			account.accessToken = creds.access;
+			changed = true;
+		}
+		if (account.refreshToken !== creds.refresh) {
+			account.refreshToken = creds.refresh;
+			changed = true;
+		}
+		if (account.expiresAt !== creds.expires) {
+			account.expiresAt = creds.expires;
+			changed = true;
+		}
+		if (accountId && account.accountId !== accountId) {
+			account.accountId = accountId;
+			changed = true;
+		}
+		if (
+			options?.importSource &&
+			account.importSource !== options.importSource
+		) {
+			account.importSource = options.importSource;
+			changed = true;
+		}
+		if (
+			options?.importFingerprint &&
+			account.importFingerprint !== options.importFingerprint
+		) {
+			account.importFingerprint = options.importFingerprint;
+			changed = true;
+		}
+		if (account.needsReauth) {
+			account.needsReauth = undefined;
+			changed = true;
+		}
+		return changed;
+	}
+
 	addOrUpdateAccount(
 		email: string,
 		creds: OAuthCredentials,
 		options?: {
 			importSource?: "pi-openai-codex";
 			importFingerprint?: string;
+			preserveActive?: boolean;
 		},
-	): void {
+	): Account {
 		const existing = this.getAccount(email);
-		const accountId =
-			typeof creds.accountId === "string" ? creds.accountId : undefined;
-		if (existing) {
-			existing.accessToken = creds.access;
-			existing.refreshToken = creds.refresh;
-			existing.expiresAt = creds.expires;
-			existing.importSource = options?.importSource;
-			existing.importFingerprint = options?.importFingerprint;
-			existing.needsReauth = undefined;
-			if (accountId) {
-				existing.accountId = accountId;
+		const duplicate = existing
+			? undefined
+			: this.findAccountByRefreshToken(creds.refresh);
+		let target = existing ?? duplicate;
+		let changed = false;
+
+		if (target) {
+			if (
+				duplicate?.importSource === "pi-openai-codex" &&
+				duplicate.email !== email &&
+				!this.getAccount(email)
+			) {
+				changed = this.updateAccountEmail(duplicate, email) || changed;
 			}
+			changed = this.applyCredentials(target, creds, options) || changed;
 		} else {
-			this.data.accounts.push({
+			target = {
 				email,
 				accessToken: creds.access,
 				refreshToken: creds.refresh,
 				expiresAt: creds.expires,
-				accountId,
+				accountId:
+					typeof creds.accountId === "string" ? creds.accountId : undefined,
 				importSource: options?.importSource,
 				importFingerprint: options?.importFingerprint,
-			});
+			};
+			this.data.accounts.push(target);
+			changed = true;
+		}
+
+		if (!options?.preserveActive) {
+			if (this.data.activeEmail !== target.email) {
+				this.setActiveAccount(target.email);
+				return target;
+			}
+		}
+
+		if (changed) {
+			this.save();
+			this.notifyStateChanged();
 		}
-		this.setActiveAccount(email);
+		return target;
 	}
 
 	getActiveAccount(): Account | undefined {
@@ -172,23 +286,68 @@ export class AccountManager {
 		if (!imported) return false;
 
 		const existingImported = this.getImportedAccount();
-		if (
-			existingImported?.importFingerprint === imported.fingerprint &&
-			existingImported.email === imported.identifier
-		) {
+		if (existingImported?.importFingerprint === imported.fingerprint) {
 			return false;
 		}
 
-		if (existingImported && existingImported.email !== imported.identifier) {
+		const matchingAccount = this.findAccountByRefreshToken(
+			imported.credentials.refresh,
+			existingImported?.email,
+		);
+		if (matchingAccount) {
+			const wasActiveImported =
+				existingImported && this.data.activeEmail === existingImported.email;
+			const wasManualImported =
+				existingImported && this.manualEmail === existingImported.email;
+			let changed = this.applyCredentials(
+				matchingAccount,
+				imported.credentials,
+				{
+					importSource: "pi-openai-codex",
+					importFingerprint: imported.fingerprint,
+				},
+			);
+			if (existingImported && existingImported !== matchingAccount) {
+				changed = this.removeAccountRecord(existingImported) || changed;
+				if (wasActiveImported) {
+					this.data.activeEmail = matchingAccount.email;
+				}
+				if (wasManualImported) {
+					this.manualEmail = matchingAccount.email;
+				}
+			}
+			if (changed) {
+				this.save();
+				this.notifyStateChanged();
+			}
+			return changed;
+		}
+
+		if (existingImported) {
 			const target = this.getAccount(imported.identifier);
-			if (!target) {
-				existingImported.email = imported.identifier;
+			let changed = false;
+			if (!target && existingImported.email !== imported.identifier) {
+				changed = this.updateAccountEmail(
+					existingImported,
+					imported.identifier,
+				);
+			}
+			changed =
+				this.applyCredentials(existingImported, imported.credentials, {
+					importSource: "pi-openai-codex",
+					importFingerprint: imported.fingerprint,
+				}) || changed;
+			if (changed) {
+				this.save();
+				this.notifyStateChanged();
 			}
+			return changed;
 		}
 
 		this.addOrUpdateAccount(imported.identifier, imported.credentials, {
 			importSource: "pi-openai-codex",
 			importFingerprint: imported.fingerprint,
+			preserveActive: true,
 		});
 		return true;
 	}
@@ -230,19 +389,10 @@ export class AccountManager {
 	}
 
 	removeAccount(email: string): boolean {
-		const index = this.data.accounts.findIndex(
-			(account) => account.email === email,
-		);
-		if (index < 0) return false;
-
-		this.data.accounts.splice(index, 1);
-		this.usageCache.delete(email);
-		if (this.manualEmail === email) {
-			this.manualEmail = undefined;
-		}
-		if (this.data.activeEmail === email) {
-			this.data.activeEmail = this.data.accounts[0]?.email;
-		}
+		const account = this.getAccount(email);
+		if (!account) return false;
+		const removed = this.removeAccountRecord(account);
+		if (!removed) return false;
 		this.save();
 		this.notifyStateChanged();
 		return true;

package/commands.ts

@@ -17,6 +17,7 @@ import {
 import { getAgentSettingsPath } from "pi-provider-utils/agent-paths";
 import { normalizeUnknownError } from "pi-provider-utils/streams";
 import type { AccountManager } from "./account-manager";
+import { writeActiveTokenToAuthJson } from "./auth";
 import { openLoginInBrowser } from "./browser";
 import type { createUsageStatusController } from "./status";
 import { STORAGE_FILE } from "./storage";
@@ -24,12 +25,15 @@ import { formatResetAt, isUsageUntouched } from "./usage";
 
 const SETTINGS_FILE = getAgentSettingsPath();
 const NO_ACCOUNTS_MESSAGE =
-	"No managed accounts found. Use /multicodex use <identifier> first.";
+	"No managed accounts found. Open /multicodex accounts to add one.";
 const HELP_TEXT =
-	"Usage: /multicodex [show|use [identifier]|footer|rotation|verify|path|reset [manual|quota|all]|help]";
+	"Usage: /multicodex [accounts [identifier]|use [identifier]|show|refresh [identifier|all]|reauth [identifier]|footer|rotation|verify|path|reset [manual|quota|all]|help]";
 const SUBCOMMANDS = [
-	"show",
+	"accounts",
 	"use",
+	"show",
+	"refresh",
+	"reauth",
 	"footer",
 	"rotation",
 	"verify",
@@ -44,7 +48,10 @@ type ResetTarget = (typeof RESET_TARGETS)[number];
 
 type AccountPanelResult =
 	| { action: "select"; email: string }
+	| { action: "refresh"; email: string }
+	| { action: "reauth"; email: string }
 	| { action: "remove"; email: string }
+	| { action: "add" }
 	| undefined;
 
 function toAutocompleteItems(values: readonly string[]): AutocompleteItem[] {
@@ -80,18 +87,6 @@ function parseResetTarget(value: string): ResetTarget | undefined {
 	return undefined;
 }
 
-function getAccountLabel(
-	email: string,
-	options?: { quotaExhaustedUntil?: number; needsReauth?: boolean },
-): string {
-	const tags: string[] = [];
-	if (options?.needsReauth) tags.push("Reauth");
-	if (options?.quotaExhaustedUntil && options.quotaExhaustedUntil > Date.now())
-		tags.push("Quota");
-	if (tags.length === 0) return email;
-	return `${email} (${tags.join(", ")})`;
-}
-
 function formatAccountStatusLine(
 	accountManager: AccountManager,
 	email: string,
@@ -104,7 +99,7 @@ function formatAccountStatusLine(
 	const quotaHit =
 		account.quotaExhaustedUntil && account.quotaExhaustedUntil > Date.now();
 	const untouched = isUsageUntouched(usage) ? "untouched" : null;
-	const imported = account.importSource ? "imported" : null;
+	const imported = account.importSource ? "linked-auth" : null;
 	const reauth = account.needsReauth ? "needs reauth" : null;
 	const tags = [
 		active?.email === account.email ? "active" : null,
@@ -134,7 +129,8 @@ function getSubcommandCompletions(prefix: string): AutocompleteItem[] | null {
 	return matches.length > 0 ? toAutocompleteItems(matches) : null;
 }
 
-function getUseCompletions(
+function getAccountCompletions(
+	subcommand: "accounts" | "use" | "reauth",
 	prefix: string,
 	accountManager: AccountManager,
 ): AutocompleteItem[] | null {
@@ -143,7 +139,26 @@ function getUseCompletions(
 		.map((account) => account.email)
 		.filter((value) => value.startsWith(prefix));
 	if (matches.length === 0) return null;
-	return matches.map((value) => ({ value: `use ${value}`, label: value }));
+	return matches.map((value) => ({
+		value: `${subcommand} ${value}`,
+		label: value,
+	}));
+}
+
+function getRefreshCompletions(
+	prefix: string,
+	accountManager: AccountManager,
+): AutocompleteItem[] | null {
+	const values = [
+		"all",
+		...accountManager.getAccounts().map((account) => account.email),
+	].filter((value, index, array) => array.indexOf(value) === index);
+	const matches = values.filter((value) => value.startsWith(prefix));
+	if (matches.length === 0) return null;
+	return matches.map((value) => ({
+		value: `refresh ${value}`,
+		label: value,
+	}));
 }
 
 function getResetCompletions(prefix: string): AutocompleteItem[] | null {
@@ -169,8 +184,17 @@ function getCommandCompletions(
 	const subcommand = trimmedStart.slice(0, firstSpaceIndex).toLowerCase();
 	const rest = trimmedStart.slice(firstSpaceIndex + 1).trimStart();
 
+	if (subcommand === "accounts") {
+		return getAccountCompletions("accounts", rest, accountManager);
+	}
 	if (subcommand === "use") {
-		return getUseCompletions(rest, accountManager);
+		return getAccountCompletions("use", rest, accountManager);
+	}
+	if (subcommand === "reauth") {
+		return getAccountCompletions("reauth", rest, accountManager);
+	}
+	if (subcommand === "refresh") {
+		return getRefreshCompletions(rest, accountManager);
 	}
 	if (subcommand === "reset") {
 		return getResetCompletions(rest);
@@ -184,7 +208,7 @@ async function loginAndActivateAccount(
 	ctx: ExtensionCommandContext,
 	accountManager: AccountManager,
 	identifier: string,
-): Promise<boolean> {
+): Promise<string | undefined> {
 	try {
 		ctx.ui.notify(
 			`Starting login for ${identifier}... Check your browser.`,
@@ -200,13 +224,23 @@ async function loginAndActivateAccount(
 			onPrompt: async ({ message }) => (await ctx.ui.input(message)) || "",
 		});
 
-		accountManager.addOrUpdateAccount(identifier, creds);
-		accountManager.setManualAccount(identifier);
-		ctx.ui.notify(`Now using ${identifier}`, "info");
-		return true;
+		const account = accountManager.addOrUpdateAccount(identifier, creds);
+		if (account.importSource) {
+			writeActiveTokenToAuthJson({
+				access: creds.access,
+				refresh: creds.refresh,
+				expires: creds.expires,
+				accountId:
+					typeof creds.accountId === "string" ? creds.accountId : undefined,
+			});
+			await accountManager.syncImportedOpenAICodexAuth();
+		}
+		accountManager.setManualAccount(account.email);
+		ctx.ui.notify(`Now using ${account.email}`, "info");
+		return account.email;
 	} catch (error) {
 		ctx.ui.notify(`Login failed: ${normalizeUnknownError(error)}`, "error");
-		return false;
+		return undefined;
 	}
 }
 
@@ -220,12 +254,12 @@ async function useOrLoginAccount(
 	if (existing) {
 		try {
 			await accountManager.ensureValidToken(existing);
-			accountManager.setManualAccount(identifier);
-			ctx.ui.notify(`Now using ${identifier}`, "info");
+			accountManager.setManualAccount(existing.email);
+			ctx.ui.notify(`Now using ${existing.email}`, "info");
 			return;
 		} catch {
 			ctx.ui.notify(
-				`Stored auth for ${identifier} is no longer valid. Starting login again.`,
+				`Stored auth for ${existing.email} is no longer valid. Starting login again.`,
 				"warning",
 			);
 		}
@@ -234,33 +268,100 @@ async function useOrLoginAccount(
 	await loginAndActivateAccount(pi, ctx, accountManager, identifier);
 }
 
-async function openAccountSelectionPanel(
+async function refreshSingleAccount(
+	ctx: ExtensionCommandContext,
+	accountManager: AccountManager,
+	email: string,
+): Promise<void> {
+	const account = accountManager.getAccount(email);
+	if (!account) {
+		ctx.ui.notify(`Unknown account: ${email}`, "warning");
+		return;
+	}
+
+	try {
+		await accountManager.ensureValidToken(account);
+	} catch (error) {
+		ctx.ui.notify(
+			`refresh ${email}: ${normalizeUnknownError(error)}`,
+			"warning",
+		);
+		return;
+	}
+
+	await accountManager.refreshUsageForAccount(account, { force: true });
+	ctx.ui.notify(
+		`refreshed ${formatAccountStatusLine(accountManager, email)}`,
+		"info",
+	);
+}
+
+async function refreshAllAccounts(
+	ctx: ExtensionCommandContext,
+	accountManager: AccountManager,
+): Promise<void> {
+	await accountManager.refreshUsageForAllAccounts({ force: true });
+	const accounts = accountManager.getAccounts();
+	const needsReauth = accountManager.getAccountsNeedingReauth().length;
+	const summary =
+		accounts.length === 0
+			? NO_ACCOUNTS_MESSAGE
+			: `refreshed ${accounts.length} account(s); reauth needed=${needsReauth}`;
+	ctx.ui.notify(summary, needsReauth > 0 ? "warning" : "info");
+}
+
+async function reauthenticateAccount(
+	pi: ExtensionAPI,
+	ctx: ExtensionCommandContext,
+	accountManager: AccountManager,
+	email: string,
+): Promise<void> {
+	const account = accountManager.getAccount(email);
+	if (!account) {
+		ctx.ui.notify(`Unknown account: ${email}`, "warning");
+		return;
+	}
+	await loginAndActivateAccount(pi, ctx, accountManager, account.email);
+}
+
+async function promptForNewAccountIdentifier(
+	ctx: ExtensionCommandContext,
+): Promise<string | undefined> {
+	const identifier = (await ctx.ui.input("Account identifier"))?.trim();
+	if (!identifier) {
+		ctx.ui.notify("Account creation cancelled.", "warning");
+		return undefined;
+	}
+	return identifier;
+}
+
+async function openAccountManagementPanel(
 	ctx: ExtensionCommandContext,
 	accountManager: AccountManager,
 ): Promise<AccountPanelResult> {
 	const accounts = accountManager.getAccounts();
 	const items = accounts.map((account) => ({
 		value: account.email,
-		label: getAccountLabel(account.email, {
-			quotaExhaustedUntil: account.quotaExhaustedUntil,
-			needsReauth: account.needsReauth,
-		}),
+		label: formatAccountStatusLine(accountManager, account.email),
 	}));
 
 	return ctx.ui.custom<AccountPanelResult>((_tui, theme, _kb, done) => {
 		const container = new Container();
 		container.addChild(
-			new Text(theme.fg("accent", theme.bold("Select Account")), 1, 0),
+			new Text(theme.fg("accent", theme.bold("MultiCodex Accounts")), 1, 0),
 		);
 		container.addChild(
 			new Text(
-				theme.fg("dim", "Enter: use  Backspace: remove account  Esc: cancel"),
+				theme.fg(
+					"dim",
+					"Enter: use  U: refresh  R: re-auth  N: add  Backspace: remove  Esc: cancel",
+				),
 				1,
 				0,
 			),
 		);
 
-		const selectList = new SelectList(items, 10, getSelectListTheme());
+		const selectList = new SelectList(items, 12, getSelectListTheme());
 		selectList.onSelect = (item) => {
 			done({ action: "select", email: item.value });
 		};
@@ -271,8 +372,20 @@ async function openAccountSelectionPanel(
 			render: (width: number) => container.render(width),
 			invalidate: () => container.invalidate(),
 			handleInput: (data: string) => {
+				if (data.toLowerCase() === "n") {
+					done({ action: "add" });
+					return;
+				}
+				const selected = selectList.getSelectedItem();
+				if (selected && data.toLowerCase() === "u") {
+					done({ action: "refresh", email: selected.value });
+					return;
+				}
+				if (selected && data.toLowerCase() === "r") {
+					done({ action: "reauth", email: selected.value });
+					return;
+				}
 				if (matchesKey(data, Key.backspace)) {
-					const selected = selectList.getSelectedItem();
 					if (selected) {
 						done({ action: "remove", email: selected.value });
 					}
@@ -284,7 +397,8 @@ async function openAccountSelectionPanel(
 	});
 }
 
-async function openAccountSelectionFlow(
+async function openAccountManagementFlow(
+	pi: ExtensionAPI,
 	ctx: ExtensionCommandContext,
 	accountManager: AccountManager,
 	statusController: ReturnType<typeof createUsageStatusController>,
@@ -292,20 +406,42 @@ async function openAccountSelectionFlow(
 	while (true) {
 		const accounts = accountManager.getAccounts();
 		if (accounts.length === 0) {
-			ctx.ui.notify(NO_ACCOUNTS_MESSAGE, "warning");
-			return;
+			const identifier = await promptForNewAccountIdentifier(ctx);
+			if (!identifier) return;
+			await loginAndActivateAccount(pi, ctx, accountManager, identifier);
+			await statusController.refreshFor(ctx);
+			continue;
 		}
 
-		const result = await openAccountSelectionPanel(ctx, accountManager);
+		const result = await openAccountManagementPanel(ctx, accountManager);
 		if (!result) return;
 
+		if (result.action === "add") {
+			const identifier = await promptForNewAccountIdentifier(ctx);
+			if (!identifier) continue;
+			await loginAndActivateAccount(pi, ctx, accountManager, identifier);
+			await statusController.refreshFor(ctx);
+			continue;
+		}
+
 		if (result.action === "select") {
-			accountManager.setManualAccount(result.email);
-			ctx.ui.notify(`Now using ${result.email}`, "info");
+			await useOrLoginAccount(pi, ctx, accountManager, result.email);
 			await statusController.refreshFor(ctx);
 			return;
 		}
 
+		if (result.action === "refresh") {
+			await refreshSingleAccount(ctx, accountManager, result.email);
+			await statusController.refreshFor(ctx);
+			continue;
+		}
+
+		if (result.action === "reauth") {
+			await reauthenticateAccount(pi, ctx, accountManager, result.email);
+			await statusController.refreshFor(ctx);
+			continue;
+		}
+
 		const accountToRemove = accountManager.getAccount(result.email);
 		if (!accountToRemove) continue;
 
@@ -325,32 +461,50 @@ async function openAccountSelectionFlow(
 	}
 }
 
-async function runShowSubcommand(
+async function runAccountsSubcommand(
+	pi: ExtensionAPI,
 	ctx: ExtensionCommandContext,
 	accountManager: AccountManager,
+	statusController: ReturnType<typeof createUsageStatusController>,
+	rest: string,
 ): Promise<void> {
 	await accountManager.syncImportedOpenAICodexAuth();
 	await accountManager.refreshUsageForAllAccounts();
+
+	if (rest) {
+		await useOrLoginAccount(pi, ctx, accountManager, rest);
+		await statusController.refreshFor(ctx);
+		return;
+	}
+
 	const accounts = accountManager.getAccounts();
 	if (accounts.length === 0) {
-		ctx.ui.notify(NO_ACCOUNTS_MESSAGE, "warning");
+		if (!ctx.hasUI) {
+			ctx.ui.notify(NO_ACCOUNTS_MESSAGE, "warning");
+			return;
+		}
+		await openAccountManagementFlow(pi, ctx, accountManager, statusController);
 		return;
 	}
 
 	if (!ctx.hasUI) {
-		const active = accountManager.getActiveAccount()?.email ?? "none";
-		const manual = accountManager.getManualAccount()?.email ?? "none";
-		ctx.ui.notify(
-			`multicodex: accounts=${accounts.length} active=${active} manual=${manual}`,
-			"info",
+		const lines = accounts.map((account) =>
+			formatAccountStatusLine(accountManager, account.email),
 		);
+		ctx.ui.notify(lines.join("\n"), "info");
 		return;
 	}
 
-	const options = accounts.map((account) =>
-		formatAccountStatusLine(accountManager, account.email),
-	);
-	await ctx.ui.select("MultiCodex Accounts", options);
+	await openAccountManagementFlow(pi, ctx, accountManager, statusController);
+}
+
+async function runShowSubcommand(
+	pi: ExtensionAPI,
+	ctx: ExtensionCommandContext,
+	accountManager: AccountManager,
+	statusController: ReturnType<typeof createUsageStatusController>,
+): Promise<void> {
+	await runAccountsSubcommand(pi, ctx, accountManager, statusController, "");
 }
 
 async function runFooterSubcommand(
@@ -374,16 +528,14 @@ async function runRotationSubcommand(
 	ctx: ExtensionCommandContext,
 ): Promise<void> {
 	const lines = [
-		"Rotation settings are not configurable yet.",
-		"Current policy: manual account, then untouched accounts, then earliest weekly reset, then random fallback.",
-		"Quota cooldown uses next known reset time, with 1 hour fallback when unknown.",
+		"Current policy: manual account first, then untouched accounts, then earliest weekly reset, then random fallback.",
+		"If token validation fails before a request starts, MultiCodex skips that account and retries another one.",
+		"If a request hits quota or rate limit before any output streams, MultiCodex marks the account on cooldown and retries.",
+		"Imported pi auth is merged into the managed pool so duplicate credentials do not consume extra rotation slots.",
 	];
 
 	if (!ctx.hasUI) {
-		ctx.ui.notify(
-			"rotation: manual->untouched->earliest-weekly-reset->random, cooldown=next-reset-or-1h",
-			"info",
-		);
+		ctx.ui.notify(lines.join(" "), "info");
 		return;
 	}
 
@@ -412,11 +564,12 @@ async function runVerifySubcommand(
 	await statusController.loadPreferences(ctx);
 	const accounts = accountManager.getAccounts().length;
 	const active = accountManager.getActiveAccount()?.email ?? "none";
-	const ok = storageWritable && settingsWritable;
+	const needsReauth = accountManager.getAccountsNeedingReauth().length;
+	const ok = storageWritable && settingsWritable && needsReauth === 0;
 
 	if (!ctx.hasUI) {
 		ctx.ui.notify(
-			`verify: ${ok ? "PASS" : "WARN"} storage=${storageWritable ? "ok" : "fail"} settings=${settingsWritable ? "ok" : "fail"} accounts=${accounts} active=${active} authImport=${authImported ? "updated" : "unchanged"}`,
+			`verify: ${ok ? "PASS" : "WARN"} storage=${storageWritable ? "ok" : "fail"} settings=${settingsWritable ? "ok" : "fail"} accounts=${accounts} active=${active} authImport=${authImported ? "updated" : "unchanged"} needsReauth=${needsReauth}`,
 			ok ? "info" : "warning",
 		);
 		return;
@@ -427,6 +580,7 @@ async function runVerifySubcommand(
 		`settings directory writable: ${settingsWritable ? "yes" : "no"}`,
 		`managed accounts: ${accounts}`,
 		`active account: ${active}`,
+		`accounts needing re-authentication: ${needsReauth}`,
 		`auth import changed state: ${authImported ? "yes" : "no"}`,
 	];
 	await ctx.ui.select(`MultiCodex Verify (${ok ? "PASS" : "WARN"})`, lines);
@@ -519,7 +673,7 @@ function runHelpSubcommand(ctx: ExtensionCommandContext): void {
 	ctx.ui.notify(HELP_TEXT, "info");
 }
 
-async function runUseSubcommand(
+async function runRefreshSubcommand(
 	pi: ExtensionAPI,
 	ctx: ExtensionCommandContext,
 	accountManager: AccountManager,
@@ -527,22 +681,42 @@ async function runUseSubcommand(
 	rest: string,
 ): Promise<void> {
 	await accountManager.syncImportedOpenAICodexAuth();
+	if (!rest || rest === "all") {
+		if (!ctx.hasUI || rest === "all") {
+			await refreshAllAccounts(ctx, accountManager);
+			await statusController.refreshFor(ctx);
+			return;
+		}
+		await openAccountManagementFlow(pi, ctx, accountManager, statusController);
+		return;
+	}
+	await refreshSingleAccount(ctx, accountManager, rest);
+	await statusController.refreshFor(ctx);
+}
 
+async function runReauthSubcommand(
+	pi: ExtensionAPI,
+	ctx: ExtensionCommandContext,
+	accountManager: AccountManager,
+	statusController: ReturnType<typeof createUsageStatusController>,
+	rest: string,
+): Promise<void> {
+	await accountManager.syncImportedOpenAICodexAuth();
 	if (rest) {
-		await useOrLoginAccount(pi, ctx, accountManager, rest);
+		await reauthenticateAccount(pi, ctx, accountManager, rest);
 		await statusController.refreshFor(ctx);
 		return;
 	}
-
 	if (!ctx.hasUI) {
-		ctx.ui.notify(
-			"/multicodex use requires an identifier in non-interactive mode.",
-			"warning",
-		);
+		const active = accountManager.getActiveAccount();
+		if (!active) {
+			ctx.ui.notify(NO_ACCOUNTS_MESSAGE, "warning");
+			return;
+		}
+		await reauthenticateAccount(pi, ctx, accountManager, active.email);
 		return;
 	}
-
-	await openAccountSelectionFlow(ctx, accountManager, statusController);
+	await openAccountManagementFlow(pi, ctx, accountManager, statusController);
 }
 
 async function runSubcommand(
@@ -553,12 +727,26 @@ async function runSubcommand(
 	accountManager: AccountManager,
 	statusController: ReturnType<typeof createUsageStatusController>,
 ): Promise<void> {
+	if (subcommand === "accounts" || subcommand === "use") {
+		await runAccountsSubcommand(
+			pi,
+			ctx,
+			accountManager,
+			statusController,
+			rest,
+		);
+		return;
+	}
 	if (subcommand === "show") {
-		await runShowSubcommand(ctx, accountManager);
+		await runShowSubcommand(pi, ctx, accountManager, statusController);
 		return;
 	}
-	if (subcommand === "use") {
-		await runUseSubcommand(pi, ctx, accountManager, statusController, rest);
+	if (subcommand === "refresh") {
+		await runRefreshSubcommand(pi, ctx, accountManager, statusController, rest);
+		return;
+	}
+	if (subcommand === "reauth") {
+		await runReauthSubcommand(pi, ctx, accountManager, statusController, rest);
 		return;
 	}
 	if (subcommand === "footer") {
@@ -592,8 +780,9 @@ async function openMainPanel(
 	statusController: ReturnType<typeof createUsageStatusController>,
 ): Promise<void> {
 	const actions = [
-		"use: select, activate, or remove managed account",
-		"show: managed account and usage summary",
+		"accounts: inspect, select, refresh, re-authenticate, add, or remove managed account",
+		"refresh: force a health and usage refresh",
+		"reauth: re-authenticate an account",
 		"footer: footer settings panel",
 		"rotation: current rotation behavior",
 		"verify: runtime health checks",
@@ -626,7 +815,8 @@ export function registerCommands(
 	statusController: ReturnType<typeof createUsageStatusController>,
 ): void {
 	pi.registerCommand("multicodex", {
-		description: "Manage MultiCodex accounts, rotation, and footer settings",
+		description:
+			"Manage MultiCodex accounts, health, rotation, and footer settings",
 		getArgumentCompletions: (argumentPrefix: string) =>
 			getCommandCompletions(argumentPrefix, accountManager),
 		handler: async (

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@victor-software-house/pi-multicodex",
-	"version": "2.0.12",
+	"version": "2.1.0",
 	"description": "Codex account rotation extension for pi",
 	"license": "MIT",
 	"type": "module",

package/provider.ts

@@ -42,6 +42,22 @@ export function getOpenAICodexMirror(): {
 	};
 }
 
+function getActiveApiKey(accountManager: AccountManager): string {
+	const active = accountManager.getActiveAccount();
+	if (active && !active.needsReauth) {
+		return active.accessToken;
+	}
+	// Fallback: first available account with a valid token.
+	for (const account of accountManager.getAccounts()) {
+		if (!account.needsReauth && account.accessToken) {
+			return account.accessToken;
+		}
+	}
+	// Placeholder — AuthStorage will override on every actual API call
+	// as long as auth.json has valid tokens.
+	return "pending-login";
+}
+
 export function buildMulticodexProviderConfig(accountManager: AccountManager) {
 	const mirror = getOpenAICodexMirror();
 	const baseProvider = getApiProvider("openai-codex-responses");
@@ -53,7 +69,7 @@ export function buildMulticodexProviderConfig(accountManager: AccountManager) {
 
 	return {
 		baseUrl: mirror.baseUrl,
-		apiKey: "managed-by-extension",
+		apiKey: getActiveApiKey(accountManager),
 		api: "openai-codex-responses" as const,
 		streamSimple: createStreamWrapper(accountManager, baseProvider),
 		models: mirror.models,

package/stream-wrapper.ts

@@ -64,7 +64,19 @@ export function createStreamWrapper(
 						);
 					}
 
-					const token = await accountManager.ensureValidToken(account);
+					let token: string;
+					try {
+						token = await accountManager.ensureValidToken(account);
+					} catch (error) {
+						if (usingManual) {
+							accountManager.clearManualAccount();
+						}
+						excludedEmails.add(account.email);
+						if (attempt < MAX_ROTATION_RETRIES) {
+							continue;
+						}
+						throw error;
+					}
 					const abortController = createLinkedAbortController(options?.signal);
 
 					const internalModel: Model<"openai-codex-responses"> = {