@victor-software-house/pi-multicodex 2.2.1 → 2.3.1

package/account-manager.ts

@@ -23,17 +23,40 @@ type StateChangeHandler = () => void;
 
 export class AccountManager {
 	private data: StorageData;
+	private piAuthAccount?: Account;
 	private usageCache = new Map<string, CodexUsageSnapshot>();
 	private refreshPromises = new Map<string, Promise<string>>();
 	private warningHandler?: WarningHandler;
 	private manualEmail?: string;
 	private stateChangeHandlers = new Set<StateChangeHandler>();
 	private warnedAuthFailureEmails = new Set<string>();
+	private readyPromise: Promise<void> = Promise.resolve();
+	private readyResolve?: () => void;
 
 	constructor() {
 		this.data = loadStorage();
 	}
 
+	/**
+	 * Mark the account manager as initializing. The returned promise
+	 * resolves when {@link markReady} is called. Stream requests wait
+	 * on {@link waitUntilReady} so they don't race the startup refresh.
+	 */
+	beginInitialization(): void {
+		this.readyPromise = new Promise<void>((resolve) => {
+			this.readyResolve = resolve;
+		});
+	}
+
+	markReady(): void {
+		this.readyResolve?.();
+		this.readyResolve = undefined;
+	}
+
+	waitUntilReady(): Promise<void> {
+		return this.readyPromise;
+	}
+
 	private save(): void {
 		saveStorage(this.data);
 	}
@@ -52,13 +75,21 @@ export class AccountManager {
 	}
 
 	getAccounts(): Account[] {
+		if (this.piAuthAccount) {
+			return [...this.data.accounts, this.piAuthAccount];
+		}
 		return this.data.accounts;
 	}
 
 	getAccount(email: string): Account | undefined {
+		if (this.piAuthAccount?.email === email) return this.piAuthAccount;
 		return this.data.accounts.find((a) => a.email === email);
 	}
 
+	isPiAuthAccount(account: Account): boolean {
+		return this.piAuthAccount !== undefined && account === this.piAuthAccount;
+	}
+
 	setWarningHandler(handler?: WarningHandler): void {
 		this.warningHandler = handler;
 	}
@@ -72,32 +103,14 @@ export class AccountManager {
 			return;
 		}
 		this.warnedAuthFailureEmails.add(account.email);
-		const hint = account.importSource
-			? "/multicodex reauth"
+		const hint = this.isPiAuthAccount(account)
+			? "/login openai-codex"
 			: `/multicodex reauth ${account.email}`;
 		this.warningHandler?.(
 			`Multicodex skipped ${account.email} during rotation: ${normalizeUnknownError(error)}. Account is flagged in /multicodex accounts. Run ${hint} to repair it.`,
 		);
 	}
 
-	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,
@@ -117,25 +130,7 @@ export class AccountManager {
 		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";
-			importMode?: "linked" | "synthetic";
-			importFingerprint?: string;
-		},
-	): boolean {
+	private applyCredentials(account: Account, creds: OAuthCredentials): boolean {
 		const accountId =
 			typeof creds.accountId === "string" ? creds.accountId : undefined;
 		let changed = false;
@@ -155,24 +150,6 @@ export class AccountManager {
 			account.accountId = accountId;
 			changed = true;
 		}
-		if (
-			options?.importSource &&
-			account.importSource !== options.importSource
-		) {
-			account.importSource = options.importSource;
-			changed = true;
-		}
-		if (options?.importMode && account.importMode !== options.importMode) {
-			account.importMode = options.importMode;
-			changed = true;
-		}
-		if (
-			options?.importFingerprint &&
-			account.importFingerprint !== options.importFingerprint
-		) {
-			account.importFingerprint = options.importFingerprint;
-			changed = true;
-		}
 		if (account.needsReauth) {
 			account.needsReauth = undefined;
 			this.warnedAuthFailureEmails.delete(account.email);
@@ -181,66 +158,28 @@ export class AccountManager {
 		return changed;
 	}
 
-	addOrUpdateAccount(
-		email: string,
-		creds: OAuthCredentials,
-		options?: {
-			importSource?: "pi-openai-codex";
-			importMode?: "linked" | "synthetic";
-			importFingerprint?: string;
-			preserveActive?: boolean;
-		},
-	): Account {
-		const existing = this.getAccount(email);
-		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,
-					importMode:
-						options?.importMode ??
-						(duplicate?.importMode === "synthetic" ? "linked" : undefined),
-				}) || changed;
-		} else {
-			target = {
-				email,
-				accessToken: creds.access,
-				refreshToken: creds.refresh,
-				expiresAt: creds.expires,
-				accountId:
-					typeof creds.accountId === "string" ? creds.accountId : undefined,
-				importSource: options?.importSource,
-				importMode: options?.importMode,
-				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;
+	addOrUpdateAccount(email: string, creds: OAuthCredentials): Account {
+		const existing = this.data.accounts.find((a) => a.email === email);
+		if (existing) {
+			const changed = this.applyCredentials(existing, creds);
+			if (changed) {
+				this.save();
+				this.notifyStateChanged();
 			}
+			return existing;
 		}
 
-		if (changed) {
-			this.save();
-			this.notifyStateChanged();
-		}
-		return target;
+		const account: Account = {
+			email,
+			accessToken: creds.access,
+			refreshToken: creds.refresh,
+			expiresAt: creds.expires,
+			accountId:
+				typeof creds.accountId === "string" ? creds.accountId : undefined,
+		};
+		this.data.accounts.push(account);
+		this.setActiveAccount(email);
+		return account;
 	}
 
 	getActiveAccount(): Account | undefined {
@@ -286,151 +225,40 @@ export class AccountManager {
 		this.notifyStateChanged();
 	}
 
-	getImportedAccount(): Account | undefined {
-		return this.data.accounts.find(
-			(account) => account.importSource === "pi-openai-codex",
-		);
-	}
-
-	private getLinkedImportedAccount(): Account | undefined {
-		return this.data.accounts.find(
-			(account) =>
-				account.importSource === "pi-openai-codex" &&
-				account.importMode !== "synthetic",
-		);
-	}
-
-	private getSyntheticImportedAccount(): Account | undefined {
-		return this.data.accounts.find(
-			(account) =>
-				account.importSource === "pi-openai-codex" &&
-				account.importMode === "synthetic",
-		);
-	}
-
-	private findManagedImportedTarget(imported: {
-		identifier: string;
-		credentials: OAuthCredentials;
-	}): Account | undefined {
-		const byRefreshToken = this.data.accounts.find(
-			(account) =>
-				account.importMode !== "synthetic" &&
-				account.refreshToken === imported.credentials.refresh,
-		);
-		if (byRefreshToken) {
-			return byRefreshToken;
+	/**
+	 * Read pi's openai-codex auth from auth.json and expose it as a
+	 * memory-only ephemeral account. Never persists to codex-accounts.json.
+	 * If the identity already exists as a managed account, skip it.
+	 */
+	async loadPiAuth(): Promise<void> {
+		const imported = await loadImportedOpenAICodexAuth();
+		if (!imported) {
+			this.piAuthAccount = undefined;
+			this.notifyStateChanged();
+			return;
 		}
 
-		return this.data.accounts.find(
-			(account) =>
-				account.importMode !== "synthetic" &&
-				account.email === imported.identifier,
+		const alreadyManaged = this.data.accounts.find(
+			(a) => a.email === imported.identifier,
 		);
-	}
-
-	private clearImportedLink(account: Account): boolean {
-		let changed = false;
-		if (account.importSource) {
-			account.importSource = undefined;
-			changed = true;
-		}
-		if (account.importMode) {
-			account.importMode = undefined;
-			changed = true;
-		}
-		if (account.importFingerprint) {
-			account.importFingerprint = undefined;
-			changed = true;
-		}
-		return changed;
-	}
 
-	detachImportedAuth(email: string): boolean {
-		const account = this.getAccount(email);
-		if (!account) return false;
-		const changed = this.clearImportedLink(account);
-		if (changed) {
-			this.save();
+		if (alreadyManaged) {
+			this.piAuthAccount = undefined;
 			this.notifyStateChanged();
-		}
-		return changed;
-	}
-
-	async syncImportedOpenAICodexAuth(): Promise<boolean> {
-		const imported = await loadImportedOpenAICodexAuth();
-		if (!imported) return false;
-
-		const linkedImported = this.getLinkedImportedAccount();
-		const syntheticImported = this.getSyntheticImportedAccount();
-		const currentImported = linkedImported ?? syntheticImported;
-		if (
-			currentImported?.importFingerprint === imported.fingerprint &&
-			(currentImported.importMode !== "synthetic" ||
-				currentImported.email === imported.identifier)
-		) {
-			return false;
-		}
-
-		const matchingAccount = this.findManagedImportedTarget(imported);
-		if (matchingAccount) {
-			let changed = this.applyCredentials(
-				matchingAccount,
-				imported.credentials,
-				{
-					importSource: "pi-openai-codex",
-					importMode: "linked",
-					importFingerprint: imported.fingerprint,
-				},
-			);
-			if (linkedImported && linkedImported !== matchingAccount) {
-				changed = this.clearImportedLink(linkedImported) || changed;
-			}
-			if (syntheticImported) {
-				changed = this.removeAccountRecord(syntheticImported) || changed;
-			}
-			if (changed) {
-				this.save();
-				this.notifyStateChanged();
-			}
-			return changed;
-		}
-
-		if (linkedImported) {
-			const changed = this.clearImportedLink(linkedImported);
-			if (changed) {
-				this.save();
-				this.notifyStateChanged();
-			}
-		}
-
-		if (syntheticImported) {
-			let changed = false;
-			if (syntheticImported.email !== imported.identifier) {
-				changed = this.updateAccountEmail(
-					syntheticImported,
-					imported.identifier,
-				);
-			}
-			changed =
-				this.applyCredentials(syntheticImported, imported.credentials, {
-					importSource: "pi-openai-codex",
-					importMode: "synthetic",
-					importFingerprint: imported.fingerprint,
-				}) || changed;
-			if (changed) {
-				this.save();
-				this.notifyStateChanged();
-			}
-			return changed;
+			return;
 		}
 
-		this.addOrUpdateAccount(imported.identifier, imported.credentials, {
-			importSource: "pi-openai-codex",
-			importMode: "synthetic",
-			importFingerprint: imported.fingerprint,
-			preserveActive: true,
-		});
-		return true;
+		this.piAuthAccount = {
+			email: imported.identifier,
+			accessToken: imported.credentials.access,
+			refreshToken: imported.credentials.refresh,
+			expiresAt: imported.credentials.expires,
+			accountId:
+				typeof imported.credentials.accountId === "string"
+					? imported.credentials.accountId
+					: undefined,
+		};
+		this.notifyStateChanged();
 	}
 
 	getAvailableManualAccount(options?: {
@@ -449,21 +277,29 @@ export class AccountManager {
 		const account = this.getAccount(email);
 		if (account) {
 			account.quotaExhaustedUntil = until;
-			this.save();
+			if (!this.isPiAuthAccount(account)) {
+				this.save();
+			}
 			this.notifyStateChanged();
 		}
 	}
 
 	clearAllQuotaExhaustion(): number {
 		let cleared = 0;
-		for (const account of this.data.accounts) {
+		let managedChanged = false;
+		for (const account of this.getAccounts()) {
 			if (account.quotaExhaustedUntil) {
 				account.quotaExhaustedUntil = undefined;
 				cleared += 1;
+				if (!this.isPiAuthAccount(account)) {
+					managedChanged = true;
+				}
 			}
 		}
-		if (cleared > 0) {
+		if (managedChanged) {
 			this.save();
+		}
+		if (cleared > 0) {
 			this.notifyStateChanged();
 		}
 		return cleared;
@@ -489,7 +325,9 @@ export class AccountManager {
 
 	private markNeedsReauth(account: Account): void {
 		account.needsReauth = true;
-		this.save();
+		if (!this.isPiAuthAccount(account)) {
+			this.save();
+		}
 		this.notifyStateChanged();
 	}
 
@@ -561,7 +399,7 @@ export class AccountManager {
 	}): Promise<Account | undefined> {
 		const now = Date.now();
 		this.clearExpiredExhaustion(now);
-		const accounts = this.data.accounts;
+		const accounts = this.getAccounts();
 		await this.refreshUsageIfStale(accounts, options);
 
 		const selected = pickBestAccount(accounts, this.usageCache, {
@@ -569,7 +407,14 @@ export class AccountManager {
 			now,
 		});
 		if (selected) {
-			this.setActiveAccount(selected.email);
+			if (this.isPiAuthAccount(selected)) {
+				// Don't persist ephemeral pi auth email to disk — it would
+				// become a stale activeEmail after restart.
+				this.data.activeEmail = selected.email;
+				this.notifyStateChanged();
+			} else {
+				this.setActiveAccount(selected.email);
+			}
 		}
 		return selected;
 	}
@@ -590,22 +435,28 @@ export class AccountManager {
 	}
 
 	private clearExpiredExhaustion(now: number): void {
-		let changed = false;
-		for (const account of this.data.accounts) {
+		let managedChanged = false;
+		let anyChanged = false;
+		for (const account of this.getAccounts()) {
 			if (account.quotaExhaustedUntil && account.quotaExhaustedUntil <= now) {
 				account.quotaExhaustedUntil = undefined;
-				changed = true;
+				anyChanged = true;
+				if (!this.isPiAuthAccount(account)) {
+					managedChanged = true;
+				}
 			}
 		}
-		if (changed) {
+		if (managedChanged) {
 			this.save();
+		}
+		if (anyChanged) {
 			this.notifyStateChanged();
 		}
 	}
 
 	async ensureValidToken(account: Account): Promise<string> {
 		if (account.needsReauth) {
-			const hint = account.importSource
+			const hint = this.isPiAuthAccount(account)
 				? "/login openai-codex"
 				: `/multicodex use ${account.email}`;
 			throw new Error(
@@ -617,10 +468,8 @@ export class AccountManager {
 			return account.accessToken;
 		}
 
-		// Imported auth is read-only. MultiCodex never refreshes or writes
-		// auth.json and instead requires the user to repair pi auth explicitly.
-		if (account.importSource === "pi-openai-codex") {
-			return this.ensureValidTokenForImportedAccount(account);
+		if (this.isPiAuthAccount(account)) {
+			return this.ensureValidTokenForPiAuth(account);
 		}
 
 		const inflight = this.refreshPromises.get(account.email);
@@ -655,20 +504,15 @@ export class AccountManager {
 	}
 
 	/**
-	 * Read-only path for imported pi auth.
-	 *
-	 * MultiCodex may read auth.json to mirror pi's currently active Codex auth,
-	 * but it must never refresh or write auth.json itself.
+	 * Read-only refresh for the ephemeral pi auth account.
+	 * Re-reads auth.json for fresh tokens. Never writes anything.
 	 */
-	private async ensureValidTokenForImportedAccount(
-		account: Account,
-	): Promise<string> {
+	private async ensureValidTokenForPiAuth(account: Account): Promise<string> {
 		const latest = await loadImportedOpenAICodexAuth();
 		if (latest && Date.now() < latest.credentials.expires - 5 * 60 * 1000) {
 			account.accessToken = latest.credentials.access;
 			account.refreshToken = latest.credentials.refresh;
 			account.expiresAt = latest.credentials.expires;
-			account.importFingerprint = latest.fingerprint;
 			const accountId =
 				typeof latest.credentials.accountId === "string"
 					? latest.credentials.accountId
@@ -676,14 +520,14 @@ export class AccountManager {
 			if (accountId) {
 				account.accountId = accountId;
 			}
-			this.save();
 			this.notifyStateChanged();
 			return account.accessToken;
 		}
 
-		this.markNeedsReauth(account);
+		this.piAuthAccount = undefined;
+		this.notifyStateChanged();
 		throw new Error(
-			`${account.email}: imported pi auth is expired — run /login openai-codex to re-authenticate`,
+			`${account.email}: pi auth expired — run /login openai-codex`,
 		);
 	}
 }

package/commands.ts

@@ -102,19 +102,14 @@ function getAccountTags(
 	const manual = accountManager.getManualAccount();
 	const quotaHit =
 		account.quotaExhaustedUntil && account.quotaExhaustedUntil > Date.now();
-	const imported = account.importSource
-		? account.importMode === "synthetic"
-			? "pi auth only"
-			: "pi auth"
-		: null;
 	return [
 		active?.email === account.email ? "active" : null,
 		manual?.email === account.email ? "manual" : null,
+		accountManager.isPiAuthAccount(account) ? "pi auth" : null,
 		account.needsReauth ? "needs reauth" : null,
 		isPlaceholderAccount(account) ? "placeholder" : null,
 		quotaHit ? "quota" : null,
 		isUsageUntouched(usage) ? "untouched" : null,
-		imported,
 	].filter((value): value is string => Boolean(value));
 }
 
@@ -245,11 +240,7 @@ async function loginAndActivateAccount(
 			onPrompt: async ({ message }) => (await ctx.ui.input(message)) || "",
 		});
 
-		const existing = accountManager.getAccount(identifier);
 		const account = accountManager.addOrUpdateAccount(identifier, creds);
-		if (existing?.importSource) {
-			accountManager.detachImportedAuth(account.email);
-		}
 		accountManager.setManualAccount(account.email);
 		ctx.ui.notify(`Now using ${account.email}`, "info");
 		return account.email;
@@ -659,7 +650,6 @@ async function runAccountsSubcommand(
 	statusController: ReturnType<typeof createUsageStatusController>,
 	rest: string,
 ): Promise<void> {
-	await accountManager.syncImportedOpenAICodexAuth();
 	await accountManager.refreshUsageForAllAccounts();
 
 	if (rest) {
@@ -722,7 +712,7 @@ async function runRotationSubcommand(
 		"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 pi auth is active, it participates in rotation as an ephemeral account without being persisted.",
 	];
 
 	if (!ctx.hasUI) {
@@ -751,8 +741,10 @@ async function runVerifySubcommand(
 ): Promise<void> {
 	const storageWritable = await isWritableDirectoryFor(STORAGE_FILE);
 	const settingsWritable = await isWritableDirectoryFor(SETTINGS_FILE);
-	const authImported = await accountManager.syncImportedOpenAICodexAuth();
 	await statusController.loadPreferences(ctx);
+	const hasPiAuth = accountManager
+		.getAccounts()
+		.some((a) => accountManager.isPiAuthAccount(a));
 	const accounts = accountManager.getAccounts().length;
 	const active = accountManager.getActiveAccount()?.email ?? "none";
 	const needsReauth = accountManager.getAccountsNeedingReauth().length;
@@ -760,7 +752,7 @@ async function runVerifySubcommand(
 
 	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"} needsReauth=${needsReauth}`,
+			`verify: ${ok ? "PASS" : "WARN"} storage=${storageWritable ? "ok" : "fail"} settings=${settingsWritable ? "ok" : "fail"} accounts=${accounts} active=${active} piAuth=${hasPiAuth ? "loaded" : "none"} needsReauth=${needsReauth}`,
 			ok ? "info" : "warning",
 		);
 		return;
@@ -771,8 +763,8 @@ async function runVerifySubcommand(
 		`settings directory writable: ${settingsWritable ? "yes" : "no"}`,
 		`managed accounts: ${accounts}`,
 		`active account: ${active}`,
+		`pi auth (ephemeral): ${hasPiAuth ? "loaded" : "none"}`,
 		`accounts needing re-authentication: ${needsReauth}`,
-		`auth import changed state: ${authImported ? "yes" : "no"}`,
 	];
 	await ctx.ui.select(`MultiCodex Verify (${ok ? "PASS" : "WARN"})`, lines);
 }
@@ -871,7 +863,6 @@ async function runRefreshSubcommand(
 	statusController: ReturnType<typeof createUsageStatusController>,
 	rest: string,
 ): Promise<void> {
-	await accountManager.syncImportedOpenAICodexAuth();
 	if (!rest || rest === "all") {
 		if (!ctx.hasUI || rest === "all") {
 			await refreshAllAccounts(ctx, accountManager);
@@ -892,7 +883,6 @@ async function runReauthSubcommand(
 	statusController: ReturnType<typeof createUsageStatusController>,
 	rest: string,
 ): Promise<void> {
-	await accountManager.syncImportedOpenAICodexAuth();
 	if (rest) {
 		await reauthenticateAccount(pi, ctx, accountManager, rest);
 		await statusController.refreshFor(ctx);

package/hooks.ts

@@ -6,28 +6,33 @@ async function refreshAndActivateBestAccount(
 	accountManager: AccountManager,
 	warningHandler?: WarningHandler,
 ): Promise<void> {
-	await accountManager.syncImportedOpenAICodexAuth();
-	await accountManager.refreshUsageForAllAccounts({ force: true });
+	accountManager.beginInitialization();
+	try {
+		await accountManager.loadPiAuth();
+		await accountManager.refreshUsageForAllAccounts({ force: true });
 
-	const needsReauth = accountManager.getAccountsNeedingReauth();
-	if (needsReauth.length > 0) {
-		const hints = needsReauth.map((a) => {
-			const cmd = a.importSource
-				? "/login openai-codex"
-				: `/multicodex use ${a.email}`;
-			return `${a.email} (${cmd})`;
-		});
-		warningHandler?.(
-			`Multicodex: ${needsReauth.length} account(s) need re-authentication: ${hints.join(", ")}`,
-		);
-	}
+		const needsReauth = accountManager.getAccountsNeedingReauth();
+		if (needsReauth.length > 0) {
+			const hints = needsReauth.map((a) => {
+				const cmd = accountManager.isPiAuthAccount(a)
+					? "/login openai-codex"
+					: `/multicodex use ${a.email}`;
+				return `${a.email} (${cmd})`;
+			});
+			warningHandler?.(
+				`Multicodex: ${needsReauth.length} account(s) need re-authentication: ${hints.join(", ")}`,
+			);
+		}
 
-	const manual = accountManager.getAvailableManualAccount();
-	if (manual) return;
-	if (accountManager.hasManualAccount()) {
-		accountManager.clearManualAccount();
+		const manual = accountManager.getAvailableManualAccount();
+		if (manual) return;
+		if (accountManager.hasManualAccount()) {
+			accountManager.clearManualAccount();
+		}
+		await accountManager.activateBestAccount();
+	} finally {
+		accountManager.markReady();
 	}
-	await accountManager.activateBestAccount();
 }
 
 export function handleSessionStart(
@@ -35,12 +40,12 @@ export function handleSessionStart(
 	warningHandler?: WarningHandler,
 ): void {
 	if (accountManager.getAccounts().length === 0) return;
-	void refreshAndActivateBestAccount(accountManager, warningHandler);
+	refreshAndActivateBestAccount(accountManager, warningHandler).catch(() => {});
 }
 
 export function handleNewSessionSwitch(
 	accountManager: AccountManager,
 	warningHandler?: WarningHandler,
 ): void {
-	void refreshAndActivateBestAccount(accountManager, warningHandler);
+	refreshAndActivateBestAccount(accountManager, warningHandler).catch(() => {});
 }

package/index.ts

@@ -1,8 +1,5 @@
 export { AccountManager } from "./account-manager";
-export {
-	loadImportedOpenAICodexAuth,
-	parseImportedOpenAICodexAuth,
-} from "./auth";
+export { parseImportedOpenAICodexAuth } from "./auth";
 export { default } from "./extension";
 export {
 	buildMulticodexProviderConfig,
@@ -25,6 +22,7 @@ export { createStreamWrapper } from "./stream-wrapper";
 export type { CodexUsageSnapshot } from "./usage";
 export {
 	formatResetAt,
+	getMaxUsedPercent,
 	getNextResetAt,
 	getWeeklyResetAt,
 	isUsageUntouched,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@victor-software-house/pi-multicodex",
-	"version": "2.2.1",
+	"version": "2.3.1",
 	"description": "Codex account rotation extension for pi",
 	"license": "MIT",
 	"type": "module",
@@ -48,12 +48,14 @@
 		"usage.ts",
 		"README.md",
 		"LICENSE",
-		"assets/**"
+		"assets/**",
+		"schemas/**"
 	],
 	"scripts": {
 		"lint": "biome check .",
 		"test": "vitest run -c vitest.config.ts",
 		"tsgo": "tsgo -p tsconfig.json",
+		"generate:schema": "bun scripts/generate-schema.ts",
 		"check": "pnpm lint && pnpm tsgo && pnpm test",
 		"pack:dry": "npm pack --dry-run",
 		"release:dry": "pnpm exec semantic-release --dry-run"
@@ -98,6 +100,7 @@
 		"node": "24.14.0"
 	},
 	"dependencies": {
-		"pi-provider-utils": "^0.0.0"
+		"pi-provider-utils": "^0.0.0",
+		"zod": "^4.3.6"
 	}
 }

package/schemas/codex-accounts.schema.json

@@ -0,0 +1,77 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"type": "object",
+	"properties": {
+		"$schema": {
+			"description": "JSON Schema reference for editor support",
+			"type": "string"
+		},
+		"version": {
+			"type": "integer",
+			"exclusiveMinimum": 0,
+			"maximum": 9007199254740991,
+			"description": "Storage schema version"
+		},
+		"accounts": {
+			"type": "array",
+			"items": {
+				"$ref": "#/$defs/Account"
+			},
+			"description": "Managed account entries"
+		},
+		"activeEmail": {
+			"description": "Currently active account email",
+			"type": "string"
+		}
+	},
+	"required": ["version", "accounts"],
+	"additionalProperties": false,
+	"id": "MultiCodexStorage",
+	"description": "MultiCodex managed account storage",
+	"$defs": {
+		"Account": {
+			"type": "object",
+			"properties": {
+				"email": {
+					"type": "string",
+					"minLength": 1,
+					"description": "Account email identifier"
+				},
+				"accessToken": {
+					"type": "string",
+					"minLength": 1,
+					"description": "OAuth access token (JWT)"
+				},
+				"refreshToken": {
+					"type": "string",
+					"minLength": 1,
+					"description": "OAuth refresh token"
+				},
+				"expiresAt": {
+					"type": "number",
+					"description": "Token expiry timestamp (ms since epoch)"
+				},
+				"accountId": {
+					"description": "OpenAI account ID",
+					"type": "string"
+				},
+				"lastUsed": {
+					"description": "Last manual selection timestamp (ms)",
+					"type": "number"
+				},
+				"quotaExhaustedUntil": {
+					"description": "Quota cooldown expiry (ms)",
+					"type": "number"
+				},
+				"needsReauth": {
+					"description": "Account needs re-authentication",
+					"type": "boolean"
+				}
+			},
+			"required": ["email", "accessToken", "refreshToken", "expiresAt"],
+			"additionalProperties": false,
+			"id": "Account",
+			"description": "A managed OpenAI Codex account"
+		}
+	}
+}

package/selection.ts

@@ -1,6 +1,7 @@
 import type { Account } from "./storage";
 import {
 	type CodexUsageSnapshot,
+	getMaxUsedPercent,
 	getWeeklyResetAt,
 	isUsageUntouched,
 } from "./usage";
@@ -15,20 +16,26 @@ function pickRandomAccount(accounts: Account[]): Account | undefined {
 	return accounts[Math.floor(Math.random() * accounts.length)];
 }
 
-function pickEarliestWeeklyResetAccount(
+function pickLowestUsageAccount(
 	accounts: Account[],
 	usageByEmail: Map<string, CodexUsageSnapshot>,
 ): Account | undefined {
 	const candidates = accounts
-		.map((account) => ({
-			account,
-			resetAt: getWeeklyResetAt(usageByEmail.get(account.email)),
-		}))
-		.filter(
-			(entry): entry is { account: Account; resetAt: number } =>
-				typeof entry.resetAt === "number",
-		)
-		.sort((a, b) => a.resetAt - b.resetAt);
+		.map((account) => {
+			const usage = usageByEmail.get(account.email);
+			return {
+				account,
+				usedPercent: getMaxUsedPercent(usage) ?? 100,
+				resetAt: getWeeklyResetAt(usage) ?? Number.MAX_SAFE_INTEGER,
+			};
+		})
+		.sort((a, b) => {
+			// Primary: lowest usage first
+			const usageDiff = a.usedPercent - b.usedPercent;
+			if (usageDiff !== 0) return usageDiff;
+			// Tiebreaker: earliest weekly reset first
+			return a.resetAt - b.resetAt;
+		});
 
 	return candidates[0]?.account;
 }
@@ -55,16 +62,13 @@ export function pickBestAccount(
 
 	if (untouched.length > 0) {
 		return (
-			pickEarliestWeeklyResetAccount(untouched, usageByEmail) ??
+			pickLowestUsageAccount(untouched, usageByEmail) ??
 			pickRandomAccount(untouched)
 		);
 	}
 
-	const earliestWeeklyReset = pickEarliestWeeklyResetAccount(
-		withUsage,
-		usageByEmail,
-	);
-	if (earliestWeeklyReset) return earliestWeeklyReset;
+	const lowestUsage = pickLowestUsageAccount(withUsage, usageByEmail);
+	if (lowestUsage) return lowestUsage;
 
 	return pickRandomAccount(available);
 }

package/status.ts

@@ -411,11 +411,7 @@ export function createUsageStatusController(accountManager: AccountManager) {
 
 		renderCachedStatus(ctx, livePreviewPreferences ?? preferences);
 
-		let activeAccount = accountManager.getActiveAccount();
-		if (!activeAccount) {
-			await accountManager.syncImportedOpenAICodexAuth();
-			activeAccount = accountManager.getActiveAccount();
-		}
+		const activeAccount = accountManager.getActiveAccount();
 		if (!activeAccount) {
 			ctx.ui.setStatus(
 				STATUS_KEY,

package/storage.ts

@@ -1,38 +1,169 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { getAgentPath } from "pi-provider-utils/agent-paths";
+import { z } from "zod";
 
-export interface Account {
-	email: string;
-	accessToken: string;
-	refreshToken: string;
-	expiresAt: number;
-	accountId?: string;
-	lastUsed?: number;
-	quotaExhaustedUntil?: number;
-	importSource?: "pi-openai-codex";
-	importMode?: "linked" | "synthetic";
-	importFingerprint?: string;
-	needsReauth?: boolean;
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+
+const CURRENT_VERSION = 1;
+
+const SCHEMA_URL =
+	"https://raw.githubusercontent.com/victor-software-house/pi-multicodex/main/schemas/codex-accounts.schema.json";
+
+const AccountSchema = z
+	.object({
+		email: z.string().min(1).meta({ description: "Account email identifier" }),
+		accessToken: z
+			.string()
+			.min(1)
+			.meta({ description: "OAuth access token (JWT)" }),
+		refreshToken: z
+			.string()
+			.min(1)
+			.meta({ description: "OAuth refresh token" }),
+		expiresAt: z
+			.number()
+			.meta({ description: "Token expiry timestamp (ms since epoch)" }),
+		accountId: z.string().optional().meta({ description: "OpenAI account ID" }),
+		lastUsed: z
+			.number()
+			.optional()
+			.meta({ description: "Last manual selection timestamp (ms)" }),
+		quotaExhaustedUntil: z
+			.number()
+			.optional()
+			.meta({ description: "Quota cooldown expiry (ms)" }),
+		needsReauth: z
+			.boolean()
+			.optional()
+			.meta({ description: "Account needs re-authentication" }),
+	})
+	.meta({ id: "Account", description: "A managed OpenAI Codex account" });
+
+export const StorageSchema = z
+	.object({
+		$schema: z
+			.string()
+			.optional()
+			.meta({ description: "JSON Schema reference for editor support" }),
+		version: z
+			.number()
+			.int()
+			.positive()
+			.meta({ description: "Storage schema version" }),
+		accounts: z
+			.array(AccountSchema)
+			.meta({ description: "Managed account entries" }),
+		activeEmail: z
+			.string()
+			.optional()
+			.meta({ description: "Currently active account email" }),
+	})
+	.meta({
+		id: "MultiCodexStorage",
+		description: "MultiCodex managed account storage",
+	});
+
+export type Account = z.infer<typeof AccountSchema>;
+export type StorageData = z.infer<typeof StorageSchema>;
+
+// ---------------------------------------------------------------------------
+// Migration
+// ---------------------------------------------------------------------------
+
+const LEGACY_FIELDS = [
+	"importSource",
+	"importMode",
+	"importFingerprint",
+] as const;
+
+function stripLegacyFields(raw: Record<string, unknown>): boolean {
+	let stripped = false;
+	for (const key of LEGACY_FIELDS) {
+		if (key in raw) {
+			delete raw[key];
+			stripped = true;
+		}
+	}
+	return stripped;
 }
 
-export interface StorageData {
-	accounts: Account[];
-	activeEmail?: string;
+function migrateRawStorage(raw: unknown): StorageData {
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+		return { version: CURRENT_VERSION, accounts: [], activeEmail: undefined };
+	}
+
+	const record = raw as Record<string, unknown>;
+
+	// Strip legacy import fields from each account
+	const rawAccounts = Array.isArray(record.accounts) ? record.accounts : [];
+	for (const entry of rawAccounts) {
+		if (entry && typeof entry === "object" && !Array.isArray(entry)) {
+			stripLegacyFields(entry as Record<string, unknown>);
+		}
+	}
+
+	// Add version if missing (pre-v1 files)
+	if (!("version" in record) || typeof record.version !== "number") {
+		record.version = CURRENT_VERSION;
+	}
+
+	const result = StorageSchema.safeParse(record);
+	if (result.success) {
+		return result.data;
+	}
+
+	// Schema validation failed — salvage what we can
+	const accounts: Account[] = [];
+	for (const entry of rawAccounts) {
+		const parsed = AccountSchema.safeParse(entry);
+		if (parsed.success) {
+			accounts.push(parsed.data);
+		}
+	}
+	return { version: CURRENT_VERSION, accounts, activeEmail: undefined };
 }
 
+// ---------------------------------------------------------------------------
+// I/O
+// ---------------------------------------------------------------------------
+
 export const STORAGE_FILE = getAgentPath("codex-accounts.json");
 
 export function loadStorage(): StorageData {
 	try {
 		if (fs.existsSync(STORAGE_FILE)) {
-			return JSON.parse(fs.readFileSync(STORAGE_FILE, "utf-8")) as StorageData;
+			const text = fs.readFileSync(STORAGE_FILE, "utf-8");
+			const raw = JSON.parse(text) as Record<string, unknown>;
+			const needsMigration =
+				!("version" in raw) ||
+				raw.version !== CURRENT_VERSION ||
+				needsLegacyStrip(raw);
+			const data = migrateRawStorage(raw);
+			if (needsMigration) {
+				saveStorage(data);
+			}
+			return data;
 		}
 	} catch (error) {
 		console.error("Failed to load multicodex accounts:", error);
 	}
 
-	return { accounts: [] };
+	return { version: CURRENT_VERSION, accounts: [], activeEmail: undefined };
+}
+
+function needsLegacyStrip(raw: Record<string, unknown>): boolean {
+	const accounts = Array.isArray(raw.accounts) ? raw.accounts : [];
+	for (const entry of accounts) {
+		if (entry && typeof entry === "object" && !Array.isArray(entry)) {
+			for (const key of LEGACY_FIELDS) {
+				if (key in (entry as Record<string, unknown>)) return true;
+			}
+		}
+	}
+	return false;
 }
 
 export function saveStorage(data: StorageData): void {
@@ -41,7 +172,13 @@ export function saveStorage(data: StorageData): void {
 		if (!fs.existsSync(dir)) {
 			fs.mkdirSync(dir, { recursive: true });
 		}
-		fs.writeFileSync(STORAGE_FILE, JSON.stringify(data, null, 2));
+		const output = {
+			$schema: SCHEMA_URL,
+			version: CURRENT_VERSION,
+			accounts: data.accounts,
+			activeEmail: data.activeEmail,
+		};
+		fs.writeFileSync(STORAGE_FILE, JSON.stringify(output, null, 2));
 	} catch (error) {
 		console.error("Failed to save multicodex accounts:", error);
 	}

package/stream-wrapper.ts

@@ -39,7 +39,7 @@ export function createStreamWrapper(
 
 		(async () => {
 			try {
-				await accountManager.syncImportedOpenAICodexAuth();
+				await accountManager.waitUntilReady();
 				const excludedEmails = new Set<string>();
 				for (let attempt = 0; attempt <= MAX_ROTATION_RETRIES; attempt++) {
 					const now = Date.now();

package/usage.ts

@@ -66,6 +66,17 @@ export function getNextResetAt(usage?: CodexUsageSnapshot): number | undefined {
 	return Math.min(...candidates);
 }
 
+export function getMaxUsedPercent(
+	usage?: CodexUsageSnapshot,
+): number | undefined {
+	const candidates = [
+		usage?.primary?.usedPercent,
+		usage?.secondary?.usedPercent,
+	].filter((value): value is number => typeof value === "number");
+	if (candidates.length === 0) return undefined;
+	return Math.max(...candidates);
+}
+
 export function getWeeklyResetAt(
 	usage?: CodexUsageSnapshot,
 ): number | undefined {