feat: v4.5.0 - Queued token refresh, enhanced logging, auto-update checker

- Add RefreshQueue to prevent race conditions on concurrent token refreshes
- Enhance logger with log levels (debug/info/warn/error), timing utilities
- Add CODEX_PLUGIN_LOG_LEVEL environment variable for log configuration
- Add auto-update checker that notifies when new version is available
- Add health-based account rotation with token bucket rate limiting
- Add reason-aware backoff for smarter retry behavior
- 13 new tests for RefreshQueue (345 total tests pass)

New files:
- lib/refresh-queue.ts - Queued token refresh with deduplication
- lib/rotation.ts - Health scoring and token bucket tracking
- lib/auto-update-checker.ts - npm registry check with 24h cache
- test/refresh-queue.test.ts - RefreshQueue test suite

Author: ndycode

CHANGELOG.md

@@ -18,6 +18,83 @@ All notable changes to this project are documented here. Dates use the ISO forma
 - Stored account emails are trimmed/lowercased when present.
 - Dependency refresh: @opencode-ai plugin/sdk 1.1.34, hono 4.11.5, vitest 4.0.18, @types/node 25.0.10, @typescript-eslint 8.53.1.
 
+## [4.5.0] - 2026-01-25
+
+**Feature release**: Queued token refresh, enhanced logging, and auto-update notifications.
+
+### Added
+- **Queued Token Refresh**: New `RefreshQueue` class prevents race conditions when multiple concurrent requests try to refresh the same account's token simultaneously:
+  - Deduplicates concurrent refresh calls per account
+  - Subsequent callers await the existing in-flight refresh promise
+  - Automatic cleanup of stale entries after 30 seconds
+  - New module: `lib/refresh-queue.ts`
+- **Enhanced Logging System**: Upgraded logger with proper log levels and timing utilities:
+  - Log levels: `debug`, `info`, `warn`, `error`
+  - Configurable via `CODEX_PLUGIN_LOG_LEVEL` environment variable
+  - Scoped loggers with timing functions (`time()`, `timeEnd()`)
+  - Duration formatting utilities
+- **Auto-Update Notifications**: Plugin now checks npm for newer versions on load:
+  - Checks npm registry once per 24 hours (cached)
+  - Shows toast notification when update is available
+  - New module: `lib/auto-update-checker.ts`
+- **13 new unit tests** for RefreshQueue (now 345 total tests)
+
+### Changed
+- Token refresh calls now use `queuedRefresh()` instead of direct `refreshAccessToken()` for race condition safety
+- Logger exports expanded: `logInfo()`, `logError()`, `ScopedLogger` interface, `formatDuration()`
+
+### Technical Details
+- RefreshQueue uses a Map to track in-flight refresh promises, keyed by refresh token
+- Stale entries (>30s) are automatically cleaned up to prevent memory leaks
+- Auto-update check is non-blocking and fails silently to avoid disrupting plugin operation
+
+## [4.4.0] - 2026-01-25
+
+**Feature release**: Intelligent rate-limit rotation with health-based account selection.
+
+### Added
+- **Health Score Tracking**: Accounts now track health scores based on success/failure history:
+  - +1 point on successful request
+  - -10 points on rate limit
+  - -20 points on other failures
+  - +2 points/hour passive recovery
+- **Token Bucket Rate Limiting**: Client-side rate limiting (50 max tokens, 6 tokens/min regeneration) to prevent hitting rate limits.
+- **Hybrid Account Selection**: New scoring algorithm selects optimal account:
+  - Score = (health × 2) + (tokens × 5) + (freshness × 0.1)
+  - Prefers healthy accounts with available tokens that haven't been used recently
+- **Reason-Aware Backoff**: Different rate limit reasons use different backoff multipliers:
+  - `quota`: 3.0× (daily quota exhausted - longer wait)
+  - `tokens`: 1.5× (token limit - moderate wait)
+  - `concurrent`: 0.5× (concurrent requests - short wait)
+  - `unknown`: 1.0× (default)
+- **New AccountManager methods**: `getCurrentOrNextForFamilyHybrid()`, `recordSuccess()`, `recordRateLimit()`, `recordFailure()`, `markRateLimitedWithReason()`
+- **New module**: `lib/rotation.ts` with `HealthScoreTracker`, `TokenBucketTracker`, `selectHybridAccount`
+
+### Changed
+- **BREAKING: Default retry behavior changed** - Plugin now **always waits and retries** when all accounts are rate-limited:
+  - `retryAllAccountsRateLimited`: `false` → `true`
+  - `retryAllAccountsMaxWaitMs`: `30000` → `0` (no limit)
+  - `retryAllAccountsMaxRetries`: `1` → `Infinity` (unlimited)
+- **Account selection strategy**: Uses hybrid health-based selection instead of simple round-robin
+- **Rate limit handling**: Records health metrics on success/failure for smarter future selections
+
+### Migration Notes
+If you need the old behavior (give up when all accounts are rate-limited), add to `~/.opencode/openai-codex-auth-config.json`:
+```json
+{
+  "retryAllAccountsRateLimited": false,
+  "retryAllAccountsMaxWaitMs": 30000,
+  "retryAllAccountsMaxRetries": 1
+}
+```
+
+Or use environment variables:
+```bash
+export CODEX_AUTH_RETRY_ALL_RATE_LIMITED=0
+export CODEX_AUTH_RETRY_ALL_MAX_WAIT_MS=30000
+export CODEX_AUTH_RETRY_ALL_MAX_RETRIES=1
+```
+
 ## [4.3.0] - 2026-01-04
 
 **Feature + reliability release**: variants support, one-command installer, and auth/error handling fixes.

README.md

@@ -10,7 +10,8 @@ Enable OpenCode to authenticate against **OpenAI's Codex backend** via OAuth so
 ## What You Get
 
 - **GPT-5.2, GPT-5.2 Codex, GPT-5.1 Codex Max** and all GPT-5.x variants via ChatGPT OAuth
-- **Multi-account support** — add multiple ChatGPT accounts, auto-rotates when rate-limited
+- **Multi-account support** — add multiple ChatGPT accounts, health-aware rotation with automatic failover
+- **Auto-update notifications** — get notified when a new version is available
 - **22 model presets** — full variant system with reasoning levels (none/low/medium/high/xhigh)
 - **Prompt caching** — session-based caching for faster multi-turn conversations
 - **Usage-aware errors** — friendly messages with rate limit reset timing
@@ -438,6 +439,7 @@ Create `~/.opencode/openai-codex-auth-config.json` for optional settings:
 ```bash
 DEBUG_CODEX_PLUGIN=1 opencode                    # Enable debug logging
 ENABLE_PLUGIN_REQUEST_LOGGING=1 opencode         # Log all API requests
+CODEX_PLUGIN_LOG_LEVEL=debug opencode            # Set log level (debug|info|warn|error)
 CODEX_MODE=0 opencode                            # Temporarily disable bridge prompt
 ```
 

index.ts

@@ -30,8 +30,8 @@ import {
         exchangeAuthorizationCode,
         parseAuthorizationInput,
         REDIRECT_URI,
-        refreshAccessToken,
 } from "./lib/auth/auth.js";
+import { queuedRefresh } from "./lib/refresh-queue.js";
 import { openBrowserUrl } from "./lib/auth/browser.js";
 import { startLocalOAuthServer } from "./lib/auth/server.js";
 import { promptAddAnotherAccount, promptLoginMode } from "./lib/cli.js";
@@ -54,6 +54,7 @@ import {
         ACCOUNT_LIMITS,
 } from "./lib/constants.js";
 import { logRequest, logDebug } from "./lib/logger.js";
+import { checkAndNotify } from "./lib/auto-update-checker.js";
 import {
         AccountManager,
         extractAccountEmail,
@@ -370,7 +371,7 @@ export const OpenAIAuthPlugin: Plugin = async ({ client }: PluginInput) => {
                 await Promise.all(
                         accountsToHydrate.map(async (account) => {
                                 try {
-                                        const refreshed = await refreshAccessToken(account.refreshToken);
+                                        const refreshed = await queuedRefresh(account.refreshToken);
                                         if (refreshed.type !== "success") return;
                                         const id = extractAccountId(refreshed.access);
                                         const email = sanitizeEmail(extractAccountEmail(refreshed.access));
@@ -495,6 +496,10 @@ export const OpenAIAuthPlugin: Plugin = async ({ client }: PluginInput) => {
 				const retryAllAccountsMaxWaitMs = getRetryAllAccountsMaxWaitMs(pluginConfig);
 				const retryAllAccountsMaxRetries = getRetryAllAccountsMaxRetries(pluginConfig);
 
+				checkAndNotify(async (message, variant) => {
+					await showToast(message, variant);
+				}).catch(() => {});
+
 
 				// Return SDK configuration
 				return {
@@ -574,11 +579,11 @@ export const OpenAIAuthPlugin: Plugin = async ({ client }: PluginInput) => {
 										const accountCount = accountManager.getAccountCount();
 										const attempted = new Set<number>();
 
-										while (attempted.size < Math.max(1, accountCount)) {
-											const account = accountManager.getCurrentOrNextForFamily(modelFamily, model);
-											if (!account || attempted.has(account.index)) {
-												break;
-											}
+							while (attempted.size < Math.max(1, accountCount)) {
+								const account = accountManager.getCurrentOrNextForFamilyHybrid(modelFamily, model);
+								if (!account || attempted.has(account.index)) {
+									break;
+								}
 											attempted.add(account.index);
 
 											let accountAuth = accountManager.toAuthDetails(account) as OAuthAuthDetails;
@@ -690,6 +695,7 @@ export const OpenAIAuthPlugin: Plugin = async ({ client }: PluginInput) => {
 						modelFamily,
 						model,
 					);
+					accountManager.recordRateLimit(account, modelFamily, model);
 					account.lastSwitchReason = "rate-limit";
 					accountManager.saveToDiskDebounced();
 
@@ -711,8 +717,9 @@ export const OpenAIAuthPlugin: Plugin = async ({ client }: PluginInput) => {
 																													return errorResponse;
 																											}
 
-																						resetRateLimitBackoff(account.index, quotaKey);
-																								return await handleSuccessResponse(response, isStreaming);
+								resetRateLimitBackoff(account.index, quotaKey);
+								accountManager.recordSuccess(account, modelFamily, model);
+									return await handleSuccessResponse(response, isStreaming);
 																								}
 										}
 
@@ -1200,7 +1207,7 @@ export const OpenAIAuthPlugin: Plugin = async ({ client }: PluginInput) => {
 
                                                 const label = formatAccountLabel(account, i);
                                                 try {
-                                                        const refreshResult = await refreshAccessToken(account.refreshToken);
+								const refreshResult = await queuedRefresh(account.refreshToken);
                                                         if (refreshResult.type === "success") {
                                                                 results.push(`  ✓ ${label}: Healthy`);
                                                                 healthyCount++;

lib/accounts.ts

@@ -10,10 +10,18 @@ import {
 } from "./storage.js";
 import type { OAuthAuthDetails } from "./types.js";
 import { MODEL_FAMILIES, type ModelFamily } from "./prompts/codex.js";
+import {
+  getHealthTracker,
+  getTokenTracker,
+  selectHybridAccount,
+  type AccountWithMetrics,
+} from "./rotation.js";
 
 export type BaseQuotaKey = ModelFamily;
 export type QuotaKey = BaseQuotaKey | `${BaseQuotaKey}:${string}`;
 
+export type RateLimitReason = "quota" | "tokens" | "concurrent" | "unknown";
+
 function nowMs(): number {
   return Date.now();
 }
@@ -90,6 +98,7 @@ export interface ManagedAccount {
   addedAt: number;
   lastUsed: number;
   lastSwitchReason?: "rate-limit" | "initial" | "rotation";
+  lastRateLimitReason?: RateLimitReason;
   rateLimitResetTimes: RateLimitStateV3;
   coolingDownUntil?: number;
   cooldownReason?: CooldownReason;
@@ -370,12 +379,76 @@ export class AccountManager {
     return null;
   }
 
+  getCurrentOrNextForFamilyHybrid(family: ModelFamily, model?: string | null): ManagedAccount | null {
+    const count = this.accounts.length;
+    if (count === 0) return null;
+
+    const quotaKey = model ? `${family}:${model}` : family;
+    const healthTracker = getHealthTracker();
+    const tokenTracker = getTokenTracker();
+
+    const accountsWithMetrics: AccountWithMetrics[] = this.accounts
+      .map((account): AccountWithMetrics | null => {
+        if (!account) return null;
+        clearExpiredRateLimits(account);
+        const isAvailable =
+          !isRateLimitedForFamily(account, family, model) && !this.isAccountCoolingDown(account);
+        return {
+          index: account.index,
+          isAvailable,
+          lastUsed: account.lastUsed,
+        };
+      })
+      .filter((a): a is AccountWithMetrics => a !== null);
+
+    const selected = selectHybridAccount(accountsWithMetrics, healthTracker, tokenTracker, quotaKey);
+    if (!selected) return null;
+
+    const account = this.accounts[selected.index];
+    if (!account) return null;
+
+    this.currentAccountIndexByFamily[family] = account.index;
+    this.cursorByFamily[family] = (account.index + 1) % count;
+    account.lastUsed = nowMs();
+    return account;
+  }
+
+  recordSuccess(account: ManagedAccount, family: ModelFamily, model?: string | null): void {
+    const quotaKey = model ? `${family}:${model}` : family;
+    const healthTracker = getHealthTracker();
+    healthTracker.recordSuccess(account.index, quotaKey);
+  }
+
+  recordRateLimit(account: ManagedAccount, family: ModelFamily, model?: string | null): void {
+    const quotaKey = model ? `${family}:${model}` : family;
+    const healthTracker = getHealthTracker();
+    const tokenTracker = getTokenTracker();
+    healthTracker.recordRateLimit(account.index, quotaKey);
+    tokenTracker.drain(account.index, quotaKey);
+  }
+
+  recordFailure(account: ManagedAccount, family: ModelFamily, model?: string | null): void {
+    const quotaKey = model ? `${family}:${model}` : family;
+    const healthTracker = getHealthTracker();
+    healthTracker.recordFailure(account.index, quotaKey);
+  }
+
   markSwitched(account: ManagedAccount, reason: "rate-limit" | "initial" | "rotation", family: ModelFamily): void {
     account.lastSwitchReason = reason;
     this.currentAccountIndexByFamily[family] = account.index;
   }
 
   markRateLimited(account: ManagedAccount, retryAfterMs: number, family: ModelFamily, model?: string | null): void {
+    this.markRateLimitedWithReason(account, retryAfterMs, family, "unknown", model);
+  }
+
+  markRateLimitedWithReason(
+    account: ManagedAccount,
+    retryAfterMs: number,
+    family: ModelFamily,
+    reason: RateLimitReason,
+    model?: string | null,
+  ): void {
     const retryMs = Math.max(0, Math.floor(retryAfterMs));
     const resetAt = nowMs() + retryMs;
 
@@ -386,6 +459,8 @@ export class AccountManager {
       const modelKey = getQuotaKey(family, model);
       account.rateLimitResetTimes[modelKey] = resetAt;
     }
+
+    account.lastRateLimitReason = reason;
   }
 
   markAccountCoolingDown(account: ManagedAccount, cooldownMs: number, reason: CooldownReason): void {