@coseung2/opencodex 2.8.0-cs.12 → 2.8.0-cs.14

package/src/oauth/index.ts

@@ -249,12 +249,61 @@ export class UnsupportedOAuthProviderError extends Error {
 }
 
 export class OAuthLoginRequiredError extends Error {
+  readonly provider: string;
+
   constructor(provider: string) {
     super(`Not logged in to ${provider}. Run: ocx login ${provider}`);
     this.name = "OAuthLoginRequiredError";
+    this.provider = provider;
+  }
+}
+
+export class OAuthProviderPublicationError extends Error {
+  constructor() {
+    super("OAuth credential was saved, but the provider entry was not written. Resolve the account namespace collision, then retry login.");
+    this.name = "OAuthProviderPublicationError";
+  }
+}
+
+export class OAuthReauthIdentityMismatchError extends Error {
+  constructor() {
+    super("Signed-in account does not match the selected account. Sign in with the same account.");
+    this.name = "OAuthReauthIdentityMismatchError";
+  }
+}
+
+export class OAuthReauthIdentityUnverifiedError extends Error {
+  constructor() {
+    super("Could not verify signed-in account identity for reauth.");
+    this.name = "OAuthReauthIdentityUnverifiedError";
   }
 }
 
+class OAuthLoginSupersededError extends Error {
+  constructor() {
+    super("OAuth login was superseded before credential persistence");
+    this.name = "OAuthLoginSupersededError";
+  }
+}
+
+/** Project arbitrary OAuth failures onto the small, stable public error vocabulary. */
+export function publicOAuthAuthenticationErrorMessage(error: unknown): string {
+  if (error instanceof OAuthMutationBusyError) {
+    return error.message === "OAuth mutation queue wait timed out"
+      ? "OAuth mutation queue wait timed out"
+      : "OAuth mutation queue is busy";
+  }
+  if (
+    (error instanceof OAuthLoginRequiredError && isOAuthProvider(error.provider))
+    || error instanceof OAuthProviderPublicationError
+    || error instanceof OAuthReauthIdentityMismatchError
+    || error instanceof OAuthReauthIdentityUnverifiedError
+    || error instanceof OAuthTokenRefreshBusyError
+    || error instanceof OAuthTokenRefreshStaleError
+  ) return error.message;
+  return "OAuth authentication failed. Check the OpenCodex account status and retry.";
+}
+
 function accessSnapshot(provider: string, accountId: string, cred: OAuthCredentials): OAuthAccessSnapshot {
   const storedKiroRouting = {
     ...(cred.kiro?.profileArn ? { profileArn: cred.kiro.profileArn } : {}),
@@ -817,6 +866,7 @@ interface RunLoginDeps {
   settleKiroLoginTransaction?: typeof settleKiroLoginTransaction;
   removeAccount?: typeof removeAccount;
   setActiveAccount?: typeof setActiveAccount;
+  assertCurrentOwner?: () => void;
 }
 
 /** Roll back only accounts created by this forced login, preserving concurrent refreshes of others. */
@@ -866,6 +916,7 @@ export async function runLogin(
   const cred: OAuthCredentials = rawCred.source ? rawCred : { ...rawCred, source: "oauth" };
   const settleKiroTransaction = deps.settleKiroLoginTransaction ?? settleKiroLoginTransaction;
   try {
+    deps.assertCurrentOwner?.();
     // Validate the provider row before credential persistence. A namespace claimed during the
     // credential write is handled again below before the latest row is re-upserted.
     if (provider !== "chatgpt") {
@@ -876,7 +927,7 @@ export async function runLogin(
       const existing = getAccountCredential(provider, opts.reauthAccountId);
       if (!existing) throw new Error(`Unknown account for reauth: ${opts.reauthAccountId}`);
       if (!existing.accountId && !existing.email) {
-        throw new Error("Could not verify signed-in account identity for reauth.");
+        throw new OAuthReauthIdentityUnverifiedError();
       }
       // Kiro social accounts share one device-scoped profile ARN, so reauth identity
       // must compare the signed-in email first; otherwise reauthenticating a different
@@ -890,12 +941,15 @@ export async function runLogin(
             ? existing.email.toLowerCase() === cred.email.toLowerCase()
             : false;
       if (!identityMatches) {
-        throw new Error("Signed-in account does not match the selected account. Sign in with the same account.");
+        throw new OAuthReauthIdentityMismatchError();
       }
-      await (deps.saveAccountCredential ?? saveAccountCredential)(provider, opts.reauthAccountId, cred);
+      await (deps.saveAccountCredential ?? saveAccountCredential)(provider, opts.reauthAccountId, cred, {
+        assertBeforePersist: deps.assertCurrentOwner,
+      });
     } else {
       await (deps.saveCredential ?? saveCredential)(provider, cred, {
-        preserveIdentityless: provider === "kiro" && opts?.forceLogin === true,
+        preserveIdentityless: opts?.forceLogin === true,
+        assertBeforePersist: deps.assertCurrentOwner,
       });
     }
     if (provider !== "chatgpt") {
@@ -907,10 +961,7 @@ export async function runLogin(
         provider,
       );
       if (lateCollision) {
-        throw new Error(
-          `${lateCollision}. The credential for "${provider}" was saved, but the provider entry was not written. `
-          + "Rename the account selector, then re-run the login.",
-        );
+        throw new OAuthProviderPublicationError();
       }
       upsertOAuthProvider(latestConfig, provider);
       saveLatestConfig(latestConfig);
@@ -961,6 +1012,7 @@ export async function runLogin(
  */
 const loginState = new Map<string, { error?: string; done: boolean }>();
 const loginAbort = new Map<string, AbortController>();
+const kiroLoginSettling = new Set<string>();
 
 /** Pending paste for a login in progress: either a waiter or a stashed early submission. */
 interface ManualCodeSlot {
@@ -1117,13 +1169,14 @@ export async function startLoginFlow(
   const def = OAUTH_PROVIDERS[provider];
   if (!def) throw new UnsupportedOAuthProviderError(provider);
   const existing = loginState.get(provider);
-  if (existing && !existing.done) {
+  if ((existing && !existing.done) || (provider === "kiro" && kiroLoginSettling.has(provider))) {
     throw new Error(`A login for ${provider} is already in progress`);
   }
   clearManualCodeSlot(provider);
   loginState.set(provider, { done: false });
   const abort = new AbortController();
   loginAbort.set(provider, abort);
+  if (provider === "kiro") kiroLoginSettling.add(provider);
   return new Promise((resolve, reject) => {
     let urlResolved = false;
     const ctrl: OAuthController = {
@@ -1136,7 +1189,14 @@ export async function startLoginFlow(
       onManualCodeInput: (expectedState?: string) => waitForManualLoginCode(provider, abort.signal, expectedState),
       signal: abort.signal,
     };
+    const abandonIfNotOwner = (error?: unknown): boolean => {
+      if (loginAbort.get(provider) === abort) return false;
+      if (!urlResolved) reject(error ?? new Error("OAuth login was superseded"));
+      return true;
+    };
     const settle = async (error?: unknown): Promise<void> => {
+      // A cancelled or superseded flow must not overwrite the newer owner's terminal state.
+      if (abandonIfNotOwner(error)) return;
       let finalError = error;
       try {
         await lifecycle?.onSettled?.();
@@ -1145,6 +1205,7 @@ export async function startLoginFlow(
         // runtime config. For an already-failed login, keep the original recovery error.
         if (finalError === undefined) finalError = settleError;
       }
+      if (abandonIfNotOwner(finalError)) return;
       if (finalError === undefined) {
         loginAbort.delete(provider);
         clearManualCodeSlot(provider);
@@ -1158,22 +1219,28 @@ export async function startLoginFlow(
       const e = finalError;
       loginAbort.delete(provider);
       clearManualCodeSlot(provider);
-      const msg = e instanceof Error ? e.message : String(e);
+      const msg = publicOAuthAuthenticationErrorMessage(e);
       loginState.set(provider, { done: true, error: msg });
       if (!urlResolved) reject(e);
     };
     // Background: runLogin persists the credential + provider entry to disk. The lifecycle hook
     // lets a long-lived server config adopt that settled state before clients observe done=true.
-    void runLogin(provider, ctrl, opts).then(
+    const assertCurrentOwner = (): void => {
+      if (loginAbort.get(provider) !== abort) throw new OAuthLoginSupersededError();
+    };
+    void runLogin(provider, ctrl, opts, { assertCurrentOwner }).then(
       () => settle(),
       (e: unknown) => settle(e),
     ).catch((e: unknown) => {
       // settle catches lifecycle failures, so this is only a defensive promise-boundary guard.
+      if (abandonIfNotOwner(e)) return;
       loginAbort.delete(provider);
       clearManualCodeSlot(provider);
-      const msg = e instanceof Error ? e.message : String(e);
+      const msg = publicOAuthAuthenticationErrorMessage(e);
       loginState.set(provider, { done: true, error: msg });
       if (!urlResolved) reject(e);
+    }).finally(() => {
+      if (provider === "kiro") kiroLoginSettling.delete(provider);
     });
   });
 }

package/src/oauth/log.ts

@@ -1,5 +1,6 @@
 // src/oauth/log.ts
 import { maskAccountId } from "../lib/privacy";
+import { redactSecretString } from "../lib/redact";
 
 /** Normalize camelCase / snake_case / kebab-case field names before secret checks. */
 function normalizeFieldKey(key: string): string {
@@ -20,6 +21,7 @@ const FORBIDDEN_NORMALIZED = new Set([
   "id_token",
   "client_secret",
   "oauth_code",
+  "code_verifier",
   "clientsecret",
 ]);
 
@@ -44,5 +46,5 @@ export function logOAuthEvent(
     if (value === undefined) continue;
     parts.push(`${key}=${String(value)}`);
   }
-  console.info(parts.join(" "));
+  console.info(redactSecretString(parts.join(" ")));
 }

package/src/oauth/store.ts

@@ -272,6 +272,17 @@ function newAccountId(cred: OAuthCredentials): string {
   return createHash("sha256").update(identity).digest("hex").slice(0, 8);
 }
 
+/** Allocate a persisted slot id without reusing any existing account's ownership key. */
+function distinctAccountId(cred: OAuthCredentials, accounts: readonly ProviderAccount[]): string {
+  const base = newAccountId(cred);
+  const occupied = new Set(accounts.map(account => account.id));
+  if (!occupied.has(base)) return base;
+  for (let suffix = 1; ; suffix += 1) {
+    const candidate = `${base}-${suffix}`;
+    if (!occupied.has(candidate)) return candidate;
+  }
+}
+
 function normalizeAccount(value: unknown): ProviderAccount | null {
   if (!value || typeof value !== "object") return null;
   const candidate = value as Partial<ProviderAccount>;
@@ -425,10 +436,11 @@ function serializeMutation<T>(work: () => Promise<T>, retainedValues: readonly u
   drainOAuthMutations();
   return result;
 }
-export function mutateStore<T>(fn:(store:AuthStore)=>T|Promise<T>, retainedValues: readonly unknown[] = [], options?: { waitMs?: number }):Promise<T>{return serializeMutation(async()=>{const guard=await createOAuthFileLock({path:getAuthStoreLockPath(),staleAfterMs:30000}).acquire();try{
+export function mutateStore<T>(fn:(store:AuthStore)=>T|Promise<T>, retainedValues: readonly unknown[] = [], options?: { waitMs?: number; assertBeforePersist?: () => void }):Promise<T>{return serializeMutation(async()=>{const guard=await createOAuthFileLock({path:getAuthStoreLockPath(),staleAfterMs:30000}).acquire();try{
     const { store, hadLegacy } = loadAuthStoreInternal();
     if (hadLegacy) backupLegacyOnce();
     const result = await fn(store);
+    options?.assertBeforePersist?.();
     persist(store);
     return result;
   }finally{guard.release();}}, retainedValues, options?.waitMs);
@@ -450,7 +462,7 @@ export function getCredential(provider: string): OAuthCredentials | null {
 export async function saveCredential(
   provider: string,
   cred: OAuthCredentials,
-  opts: { preserveIdentityless?: boolean } = {},
+  opts: { preserveIdentityless?: boolean; assertBeforePersist?: () => void } = {},
 ): Promise<void> {
   const safe = normalizeCredential(cred);
   if (!safe) return;
@@ -503,22 +515,28 @@ export async function saveCredential(
         delete active.needsReauth;
         return;
       }
-      const id = newAccountId(safe);
+      const id = distinctAccountId(safe, set.accounts);
       set.accounts.push({ id, credential: safe, addedAt: Date.now() });
       set.activeAccountId = id;
       return;
     }
-    // No identity: replace the active slot in place (single-account semantics).
+    if (opts.preserveIdentityless) {
+      const id = distinctAccountId(safe, set.accounts);
+      set.accounts.push({ id, credential: safe, addedAt: Date.now() });
+      set.activeAccountId = id;
+      return;
+    }
+    // No identity during a normal login: replace the active slot in place.
     const active = set.accounts.find(a => a.id === set.activeAccountId);
     if (active) {
       active.credential = safe;
       delete active.needsReauth;
     } else {
-      const id = newAccountId(safe);
+      const id = distinctAccountId(safe, set.accounts);
       set.accounts.push({ id, credential: safe, addedAt: Date.now() });
       set.activeAccountId = id;
     }
-  }, [provider, safe]);
+  }, [provider, safe], { assertBeforePersist: opts.assertBeforePersist });
 }
 
 /** Remove the ACTIVE account; remaining accounts promote the first one. */
@@ -563,7 +581,12 @@ export function getAccountCredential(provider: string, accountId: string): OAuth
 }
 
 /** Persist a refreshed credential for a SPECIFIC account without touching activeAccountId. */
-export async function saveAccountCredential(provider: string, accountId: string, cred: OAuthCredentials): Promise<void> {
+export async function saveAccountCredential(
+  provider: string,
+  accountId: string,
+  cred: OAuthCredentials,
+  opts: { assertBeforePersist?: () => void } = {},
+): Promise<void> {
   const safe = normalizeCredential(cred);
   if (!safe) return;
   await mutateStore(store => {
@@ -571,7 +594,7 @@ export async function saveAccountCredential(provider: string, accountId: string,
     if (!account) return;
     account.credential = safe;
     delete account.needsReauth;
-  }, [provider, accountId, safe]);
+  }, [provider, accountId, safe], { assertBeforePersist: opts.assertBeforePersist });
 }
 
 export async function setActiveAccount(provider: string, accountId: string): Promise<boolean> {

package/src/oauth/token-guardian.ts

@@ -11,12 +11,13 @@
  * "proactive", and the global switch (config.tokenGuardian.enabled) defaults OFF, so a default
  * install adds zero ToS-detection surface. See devlog 260703_oauth-multi-account-refresh-and-tos.
  */
-import { loadConfig } from "../config";
+import { loadConfig, mutatePersistedConfig } from "../config";
 import type { OcxConfig, OcxTokenGuardianConfig } from "../types";
 import { listAccounts } from "./store";
 import { getValidAccessTokenForAccount, listOAuthProviders, OAuthLoginRequiredError, resolveRefreshPolicy } from "./index";
 import {
   getValidCodexToken,
+  isCodexAccountGenerationLive,
   listCodexAccountIds,
   markCodexAccountValidated,
   markCodexAccountValidationFailed,
@@ -25,11 +26,14 @@ import {
   CodexCredentialRefreshBusyError,
   CodexCredentialRefreshStaleError,
 } from "../codex/account-store";
-import { codexWarmupFailureReason, warmCodexAccount } from "../codex/warmup";
+import { CodexWarmupError, codexWarmupFailureReason, isCodexWarmupQuotaFailure, warmCodexAccount } from "../codex/warmup";
 import { getMainAccountToken, MAIN_CODEX_ACCOUNT_ID } from "../codex/main-account";
 import { isCanonicalOpenAiForwardProvider, OPENAI_CODEX_PROVIDER_ID } from "../providers/openai-tiers";
 import { providerCodexAccountMode } from "../providers/registry";
 import { captureConfigGeneration, type GenerationContext } from "../lib/state-store-sweeper";
+import { setCodexAccountPaused } from "../codex/account-pause";
+import { reconcileLiveStateStores } from "../lib/state-store-registrations";
+import { markAccountNeedsReauth } from "../codex/account-runtime-state";
 
 export interface TokenGuardianHandle {
   stop(): void;
@@ -63,12 +67,44 @@ interface BackoffEntry {
 const backoff = new Map<string, BackoffEntry>();
 let lastReconciledGeneration = 0;
 let liveBackoffKeys = new Set<string>();
+let wakeQuotaRetryLoop: (() => void) | null = null;
+const MIN_QUOTA_RETRY_TIMER_MS = 1_000;
 
 /** Test hook: clear backoff state between cases. */
 export function __resetGuardianState(): void {
   backoff.clear();
 }
 
+function quotaPendingSweepEligible(config: OcxConfig): boolean {
+  const openai = config.providers[OPENAI_CODEX_PROVIDER_ID];
+  return openai?.disabled !== true
+    && openai !== undefined
+    && isCanonicalOpenAiForwardProvider(openai)
+    && (providerCodexAccountMode(OPENAI_CODEX_PROVIDER_ID, openai) ?? "pool") === "pool";
+}
+
+function nextPendingQuotaRetryDelayMs(config: OcxConfig, nowMs = Date.now()): number | undefined {
+  if (!quotaPendingSweepEligible(config)) return undefined;
+  let earliest: number | undefined;
+  for (const id of listCodexAccountIds()) {
+    const record = readCodexAccountRecord(id);
+    if (record?.lastCodexValidationStatus !== "quota_pending" || !record.credential) continue;
+    const retryAt = Math.max(
+      record.codexQuotaRetryAt ?? nowMs,
+      backoff.get(`codex:${id}`)?.retryAfterMs ?? nowMs,
+    );
+    if (earliest === undefined || retryAt < earliest) earliest = retryAt;
+  }
+  return earliest === undefined
+    ? undefined
+    : Math.max(MIN_QUOTA_RETRY_TIMER_MS, earliest - nowMs);
+}
+
+/** Wake the background loop after registration creates a new quota-pending account. */
+export function requestCodexQuotaWarmupRetry(): void {
+  wakeQuotaRetryLoop?.();
+}
+
 function num(value: number | undefined, fallback: number, min: number): number {
   return typeof value === "number" && Number.isFinite(value) && value >= min ? value : fallback;
 }
@@ -133,12 +169,77 @@ export async function guardianSweep(nowMs: number = Date.now()): Promise<Guardia
   const config: OcxConfig = loadConfig();
   const g = config.tokenGuardian;
   const result: GuardianSweepResult = { enabled: !!g?.enabled, refreshed: [], warmed: [], failed: [], skippedBackoff: [] };
-  if (!g?.enabled) return result;
-
   const opts = resolved(g);
   const horizonMs = (opts.tickSeconds + opts.leadSeconds) * 1000;
   const tasks: Array<() => Promise<void>> = [];
 
+  // Registration-time quota deferrals are a safety invariant, not an optional keep-alive
+  // feature. Retry them after their freshly observed WHAM reset even when Token Guardian's
+  // user-facing refresh/warmup switches are off.
+  const openai = config.providers[OPENAI_CODEX_PROVIDER_ID];
+  if (quotaPendingSweepEligible(config)) {
+    for (const id of listCodexAccountIds()) {
+      const record = readCodexAccountRecord(id);
+      if (record?.lastCodexValidationStatus !== "quota_pending" || !record.credential) continue;
+      if (record.codexQuotaRetryAt !== undefined && record.codexQuotaRetryAt > nowMs) continue;
+      const key = `codex:${id}`;
+      if (inBackoff(key, nowMs)) { result.skippedBackoff.push(key); continue; }
+      tasks.push(async () => {
+        let attemptedGeneration = record.generation;
+        try {
+          const token = await getValidCodexToken(id);
+          attemptedGeneration = token.generation;
+          await warmCodexAccount({
+            accessToken: token.accessToken,
+            chatgptAccountId: token.chatgptAccountId,
+            model: opts.codexWarmupModel,
+          });
+          if (!isCodexAccountGenerationLive(id, token.generation)) return;
+          if (readCodexAccountRecord(id)?.codexQuotaPauseOwned === true) {
+            const outcome = mutatePersistedConfig(persisted => {
+              const current = readCodexAccountRecord(id);
+              if (!current || current.generation !== token.generation || current.codexQuotaPauseOwned !== true) {
+                return { changed: false, value: false };
+              }
+              const wasPaused = persisted.pausedCodexAccountIds?.includes(id) ?? false;
+              setCodexAccountPaused(persisted, id, false);
+              return { changed: wasPaused, value: true };
+            });
+            if (outcome.status === "unavailable" || outcome.value !== true) {
+              throw new Error("Codex quota-deferred pause could not be released");
+            }
+          }
+          if (!markCodexAccountValidated(id, Date.now(), token.generation)) {
+            throw new Error("Codex account changed while quota validation completed");
+          }
+          reconcileLiveStateStores();
+          backoff.delete(key);
+          result.warmed.push(key);
+        } catch (err) {
+          const terminalWarmupFailure = err instanceof CodexWarmupError
+            && err.code === "http_status"
+            && (err.status === 401 || err.status === 403)
+            && !isCodexWarmupQuotaFailure(err);
+          const terminalTokenFailure = err instanceof TokenRefreshError
+            && (err.reason === "revoked" || err.reason === "expired");
+          if (terminalWarmupFailure || terminalTokenFailure) {
+            if (markCodexAccountValidationFailed(id, codexWarmupFailureReason(err), attemptedGeneration)) {
+              markAccountNeedsReauth(id, writerGeneration);
+            }
+          }
+          const permanent = terminalWarmupFailure || terminalTokenFailure;
+          recordFailure(key, nowMs, opts.backoffBaseSeconds, opts.backoffMaxSeconds, permanent, writerGeneration);
+          result.failed.push(key);
+        }
+      });
+    }
+  }
+
+  if (!g?.enabled) {
+    await runWithConcurrency(tasks, opts.concurrency);
+    return result;
+  }
+
   // A) OAuth providers — every account in each provider's set (multiauth keep-alive),
   // skipping accounts already marked needsReauth (terminal; only a re-login fixes them).
   for (const provider of listOAuthProviders()) {
@@ -166,14 +267,13 @@ export async function guardianSweep(nowMs: number = Date.now()): Promise<Guardia
 
   // B) canonical OpenAI Codex login. Direct warms main only; pool additionally maintains every
   // added account. The direct branch returns before the managed account store is enumerated.
-  const openai = config.providers[OPENAI_CODEX_PROVIDER_ID];
   if (
     openai
     && openai.disabled !== true
     && isCanonicalOpenAiForwardProvider(openai)
     && resolveRefreshPolicy(OPENAI_CODEX_PROVIDER_ID, config) === "proactive"
   ) {
-    const mode = providerCodexAccountMode(OPENAI_CODEX_PROVIDER_ID, openai) ?? "pool";
+    const configuredMode = providerCodexAccountMode(OPENAI_CODEX_PROVIDER_ID, openai) ?? "pool";
     if (opts.codexWarmupEnabled) {
       const mainToken = getMainAccountToken();
       const key = `codex:${MAIN_CODEX_ACCOUNT_ID}`;
@@ -197,10 +297,11 @@ export async function guardianSweep(nowMs: number = Date.now()): Promise<Guardia
       }
     }
 
-    const addedAccountIds = mode === "pool" ? listCodexAccountIds() : [];
+    const addedAccountIds = configuredMode === "pool" ? listCodexAccountIds() : [];
     for (const id of addedAccountIds) {
       const record = readCodexAccountRecord(id);
       if (!record || record.deletedAt != null) continue;
+      if (record.lastCodexValidationStatus === "quota_pending") continue;
       const cred = record.credential;
       if (!cred) continue;
       const needsRefresh = cred.expiresAt <= nowMs + horizonMs;
@@ -273,16 +374,24 @@ export function reconcileGuardianBackoff(context: GenerationContext): number {
 export function startTokenGuardian(): TokenGuardianHandle {
   let stopped = false;
   let timer: ReturnType<typeof setTimeout> | undefined;
+  let sweepRunning = false;
 
   const scheduleNext = () => {
     if (stopped) return;
     const opts = resolved(loadConfig().tokenGuardian);
-    const delayMs = (opts.tickSeconds + Math.random() * opts.jitterSeconds) * 1000;
+    const regularDelayMs = (opts.tickSeconds + Math.random() * opts.jitterSeconds) * 1000;
+    const pendingDelayMs = nextPendingQuotaRetryDelayMs(loadConfig());
+    const delayMs = pendingDelayMs === undefined
+      ? regularDelayMs
+      : Math.min(regularDelayMs, pendingDelayMs);
     timer = setTimeout(runSweep, delayMs);
     if (typeof timer.unref === "function") timer.unref(); // never keep the process alive for a sweep
   };
 
   const runSweep = () => {
+    timer = undefined;
+    if (stopped || sweepRunning) return;
+    sweepRunning = true;
     void guardianSweep()
       .then(r => {
         if (r.enabled && (r.refreshed.length || r.warmed.length || r.failed.length)) {
@@ -290,14 +399,26 @@ export function startTokenGuardian(): TokenGuardianHandle {
         }
       })
       .catch(err => console.log(`token-guardian sweep error: ${err instanceof Error ? err.message : String(err)}`))
-      .finally(scheduleNext);
+      .finally(() => {
+        sweepRunning = false;
+        scheduleNext();
+      });
+  };
+
+  const wake = () => {
+    if (stopped || sweepRunning) return;
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(runSweep, 0);
+    if (typeof timer.unref === "function") timer.unref();
   };
 
+  wakeQuotaRetryLoop = wake;
   scheduleNext();
   return {
     stop() {
       stopped = true;
       if (timer) clearTimeout(timer);
+      if (wakeQuotaRetryLoop === wake) wakeQuotaRetryLoop = null;
     },
   };
 }