@bitkyc08/opencodex 2.38.0 → 2.39.0

package/src/cli/uninstall-plan.ts

@@ -0,0 +1,86 @@
+/**
+ * Whether an uninstall may take shared client config down (#3008).
+ *
+ * Extracted from `handleUninstall` because the rule is a decision, and a decision that
+ * only exists inside a long imperative command can only be tested by reading its source —
+ * which is how this shipped wrong twice: first trusting a boolean that collapsed "not
+ * installed" with "still running", then trusting a missing pid file as proof no proxy was
+ * serving.
+ *
+ * Native Codex and the Grok fence are SHARED. Restoring them while something may still be
+ * serving leaves the client and the proxy pointing at each other, so every step that could
+ * leave a live proxy behind has to be accounted for first.
+ */
+export type UninstallObservation = {
+  /** Detailed service-stop outcome, or null when the step threw. */
+  serviceStop: "absent" | "stopped" | "stopped-respawnable" | "failed" | "state-unknown" | null;
+  /**
+   * Did the proxy step PROVE nothing is serving?
+   *
+   * A `findLiveProxy` miss is not that proof: it collapses a timeout and a transport
+   * failure into the same null as a dead endpoint, so an unresponsive proxy read as absent.
+   */
+  proxyProvenDown: boolean;
+  /** Service removal outcome, or null when the step threw. */
+  serviceRemoval: "absent" | "removed" | "failed" | null;
+  /**
+   * For a Task Scheduler backend: was the restart window verified AFTER removal?
+   *
+   * Deleting the registration does not prove an already-running `:loop` wrapper died —
+   * killing it is best-effort (#764). `ocx stop` polls across the window; uninstall has
+   * to do the same before it may take shared config down.
+   */
+  respawnWindowVerified: boolean;
+};
+
+export function sharedTeardownAuthorized(o: UninstallObservation): boolean {
+  if (o.serviceStop === null) return false;
+  // "absent" and a clean stop are the only service states that prove nothing is managing
+  // the proxy.
+  if (o.serviceStop === "failed" || o.serviceStop === "state-unknown") return false;
+  // Removing the registration is not the same as proving the running wrapper is gone.
+  if (o.serviceStop === "stopped-respawnable" && !o.respawnWindowVerified) return false;
+  if (o.serviceRemoval === null || o.serviceRemoval === "failed") return false;
+  return o.proxyProvenDown;
+}
+
+/** An endpoint an uninstall must account for before shared config comes down. */
+export type ProbeEndpoint = { hostname: string; port: number };
+
+/**
+ * Every DISTINCT endpoint this home could be serving on.
+ *
+ * A runtime record and the configured port can disagree — a stale record pointing at a
+ * closed port while the live proxy sits on the configured one. Probing only the runtime
+ * candidate then reports "dead" for a port nobody is using and authorizes the teardown
+ * (#3008). `findLiveProxy` already probes both; the proof has to cover both too.
+ */
+export function endpointsToProve(
+  runtime: { port?: number; hostname?: string } | null,
+  config: { port?: number; hostname?: string },
+): ProbeEndpoint[] {
+  const out: ProbeEndpoint[] = [];
+  const push = (port: number | undefined, hostname: string | undefined) => {
+    if (!port || port <= 0 || port > 65535) return;
+    const endpoint = { hostname: hostname ?? "127.0.0.1", port };
+    if (out.some(e => e.port === endpoint.port && e.hostname === endpoint.hostname)) return;
+    out.push(endpoint);
+  };
+  push(runtime?.port, runtime?.hostname);
+  push(typeof config.port === "number" && config.port > 0 ? config.port : 10100, config.hostname);
+  return out;
+}
+
+/**
+ * Proof requires EVERY candidate to be definitively dead.
+ *
+ * "unknown" is not absence: a listener that accepts connections but withholds /healthz, or
+ * one that times out, is exactly the state where restoring shared config is most harmful.
+ */
+export function everyEndpointProvenDown(
+  endpoints: readonly ProbeEndpoint[],
+  probe: (e: ProbeEndpoint) => "live" | "dead" | "unknown",
+): boolean {
+  if (endpoints.length === 0) return false;
+  return endpoints.every(e => probe(e) === "dead");
+}

package/src/codex/account-store.ts

@@ -13,6 +13,7 @@ import {
 import { assertNotRealHomeUnderTest } from "../lib/test-home-guard";
 import type { CodexAccountCredentialRecord, CodexAccountCredentials } from "../types";
 import { advanceCodexCredentialMutationEpoch } from "./credential-mutation-epoch";
+import { CODEX_REFRESH_FLIGHT_CEILING_MS } from "./quota-recovery-timing";
 
 type LegacyCodexAccountStore = Record<string, CodexAccountCredentials>;
 type CodexAccountStore = Record<string, CodexAccountCredentialRecord>;
@@ -407,7 +408,29 @@ type CodexRefreshResult = CodexTokenResult & {
    * refresh of the one the caller was holding, not somebody else's replacement.
    */
   selfRefreshed?: boolean;
+  /**
+   * Three-way form of {@link selfRefreshed}, kept alongside it so existing callers are
+   * unaffected (#3019). `selfRefreshed` is `provenance === "self-refresh"`.
+   */
+  provenance?: CodexRefreshProvenance;
 };
+
+/**
+ * How THIS caller arrived at the credential it is returning (#3019).
+ *
+ * `selfRefreshed` is a boolean, and a boolean cannot carry three cases. Its `false` means
+ * both "somebody else replaced the credential" and "I joined an in-flight refresh of the
+ * same grant and adopted its result" — and a recovery budget has to treat those opposite
+ * ways. Joining is the same lineage getting its one refresh; replacement is a NEW lineage
+ * that has not had one yet, and charging it for somebody else's attempt would deny the
+ * fresh credential the recovery this exists to grant.
+ */
+export type CodexRefreshProvenance = "self-refresh" | "joined-lineage" | "external-replacement";
+
+/** Terminal outcome of one forced refresh, as seen by the caller that requested it. */
+export type ForcedRefreshOutcome =
+  | { kind: "resolved"; provenance: CodexRefreshProvenance; generation: number; rotated: boolean }
+  | { kind: "failed"; error: unknown };
 const MAX_CODEX_REFRESH_FLIGHTS = 32;
 const CODEX_REFRESH_FLIGHT_STALE_MS = 120_000;
 interface RefreshFlight {
@@ -587,22 +610,81 @@ function awaitOwnCancellation<T>(work: Promise<T>, callerSignal?: AbortSignal):
  */
 export async function forceRefreshCodexPoolToken(
   id: string,
-  options: { rejectedGeneration: number; rejectedAccessToken: string; signal?: AbortSignal },
-): Promise<CodexTokenResult & { rotated: boolean; selfRefreshed: boolean }> {
-  const result = await resolveCodexToken(
+  options: {
+    rejectedGeneration: number;
+    rejectedAccessToken: string;
+    signal?: AbortSignal;
+    /**
+     * Fires with THIS caller's classified outcome, regardless of `signal` (#3019).
+     *
+     * Cancellation rejects what the caller awaits; the shared flight keeps running and
+     * commits. A recovery budget claimed before the refresh therefore has no one left to
+     * settle it — the claim expires and the already-refreshed lineage gets a second
+     * refresh, which is the loop the budget exists to close. This callback is attached to
+     * the resolution itself, so it fires with no waiter present.
+     *
+     * It is called exactly once per call, for both success and failure, and its own
+     * failures are swallowed: settlement bookkeeping must never reject a credential the
+     * caller successfully obtained, nor disturb another waiter on the same flight.
+     */
+    onSettled?: (outcome: ForcedRefreshOutcome) => void | Promise<void>;
+  },
+): Promise<CodexTokenResult & { rotated: boolean; selfRefreshed: boolean; provenance: CodexRefreshProvenance }> {
+  const settle = (outcome: ForcedRefreshOutcome) => {
+    // Both halves matter: a synchronous throw and a rejected thenable are equally capable
+    // of turning settlement bookkeeping into an unhandled rejection that fails the process.
+    try { void Promise.resolve(options.onSettled?.(outcome)).catch(() => {}); } catch { /* ignore */ }
+  };
+  const classify = (result: CodexRefreshResult): CodexRefreshProvenance =>
+    // Default to the conservative reading. A path that did not classify itself is not
+    // assumed to be this caller's own lineage: charging a replacement for somebody else's
+    // attempt is the failure mode, so an unlabelled path leaves the returned lineage its
+    // own budget.
+    result.provenance ?? (result.selfRefreshed === true ? "self-refresh" : "external-replacement");
+
+  // The completion is NOT the caller's await.
+  //
+  // `options.signal` cancels what this function returns, while the shared flight keeps
+  // running and commits. Settling from the cancelled await therefore reported "failed" for
+  // a refresh that was about to succeed — releasing the budget, and letting the newly
+  // refreshed lineage claim again moments later. So the settlement rides an uncancelled
+  // resolution and the caller's cancellation is layered on top of it.
+  // A caller that is already gone must not start work. `resolveCodexToken` is called
+  // without the caller signal below, which bypasses its own pre-abort guard, so a
+  // pre-aborted request would otherwise rotate a credential nobody is waiting for.
+  if (options.signal?.aborted) {
+    settle({ kind: "failed", error: options.signal.reason });
+    throw options.signal.reason;
+  }
+  const completion = resolveCodexToken(
     id,
     { rejectedGeneration: options.rejectedGeneration, rejectedAccessToken: options.rejectedAccessToken },
-    options.signal,
+    // Deliberately no caller signal: the flight is shared and this settlement speaks for
+    // the credential, not for whoever happened to be waiting.
+    undefined,
   );
+  completion.then(
+    resolved => settle({
+      kind: "resolved",
+      provenance: classify(resolved),
+      generation: resolved.generation,
+      rotated: resolved.accessToken !== options.rejectedAccessToken,
+    }),
+    error => settle({ kind: "failed", error }),
+  );
+  const result = await awaitOwnCancellation(completion, options.signal);
+  const provenance = classify(result);
+  const rotated = result.accessToken !== options.rejectedAccessToken;
   return {
     accessToken: result.accessToken,
     chatgptAccountId: result.chatgptAccountId,
     generation: result.generation,
-    rotated: result.accessToken !== options.rejectedAccessToken,
+    rotated,
     // Only a CAS this call performed itself proves the new credential descends from the
     // rejected one; anything else is somebody else's replacement and must not be treated
     // as this request's own lineage.
-    selfRefreshed: result.selfRefreshed === true,
+    selfRefreshed: provenance === "self-refresh",
+    provenance,
   };
 }
 
@@ -633,7 +715,15 @@ async function resolveCodexToken(
   // correct again and refreshing would burn a rotation for nothing.
   const forcedTargetsStoredCredential = forced !== undefined && !forcedFenceSuperseded(record.generation, forced);
   if (cred.expiresAt > Date.now() + REFRESH_SKEW_MS && !forcedTargetsStoredCredential) {
-    return { accessToken: cred.accessToken, chatgptAccountId: cred.chatgptAccountId, generation: record.generation };
+    // The freshness shortcut: nothing was refreshed and nothing was adopted. A forced
+    // caller reaches it only once its fence was superseded, which is a replacement by
+    // definition; an ordinary caller does not read this field.
+    return {
+      accessToken: cred.accessToken,
+      chatgptAccountId: cred.chatgptAccountId,
+      generation: record.generation,
+      provenance: "external-replacement",
+    };
   }
 
   const existing = refreshLocks.get(refreshGrantFingerprint);
@@ -658,6 +748,14 @@ async function resolveCodexToken(
             accessToken: currentCred.accessToken,
             chatgptAccountId: currentCred.chatgptAccountId,
             generation: current.generation,
+            // Adopted the stored result of a flight this caller joined: same grant, same
+            // lineage. Not a replacement — that distinction is the whole point of #3019.
+            //
+            // Only `external-replacement` is inherited. The flight's own success is tagged
+            // `self-refresh` for the caller that performed the CAS, and copying that here
+            // would tell a caller that did no CAS that the credential is its own lineage.
+            // Everything this branch adopts is, by definition, a join.
+            provenance: refreshed.provenance === "external-replacement" ? "external-replacement" : "joined-lineage",
           };
         }
       }
@@ -693,6 +791,9 @@ async function resolveCodexToken(
           accessToken: currentCred.accessToken,
           chatgptAccountId: currentCred.chatgptAccountId,
           generation: current.generation,
+          // `forcedFenceSuperseded` is exactly "somebody else moved this credential past
+          // the generation I was holding" — a new lineage, entitled to its own budget.
+          provenance: "external-replacement",
         };
       }
       if (
@@ -720,6 +821,7 @@ async function resolveCodexToken(
           // This joiner performed its own CAS onto its own record, so the resulting
           // generation is its own lineage even though another caller drove the fetch.
           selfRefreshed: true,
+          provenance: "self-refresh",
           resolvedGrantFingerprint: refreshGrantFingerprint,
         };
       }
@@ -747,7 +849,7 @@ async function resolveCodexToken(
    * eviction) and the 30s ceiling remain, because those bound the flight itself.
    */
   const abort = new AbortController();
-  const signal = AbortSignal.any([abort.signal, AbortSignal.timeout(30_000)]);
+  const signal = AbortSignal.any([abort.signal, AbortSignal.timeout(CODEX_REFRESH_FLIGHT_CEILING_MS)]);
   let flight!: RefreshFlight;
   const fetchPromise = withCodexRefreshFileLock(refreshGrantFingerprint, signal, async (): Promise<CodexRefreshResult> => {
     const current = readCodexAccountRecord(id);
@@ -765,6 +867,9 @@ async function resolveCodexToken(
           credential: lockedCred,
           // This credential belongs to a DIFFERENT grant than the flight was opened
           // for. Tagging it keeps a joiner from adopting it as its own.
+          // It is also somebody else's credential by definition, so a joiner that ends up
+          // adopting it must not charge it to this lineage's budget (#3019).
+          provenance: "external-replacement",
           ...(lockedRefreshGrantFingerprint !== undefined
             ? { resolvedGrantFingerprint: lockedRefreshGrantFingerprint }
             : {}),
@@ -783,6 +888,9 @@ async function resolveCodexToken(
         chatgptAccountId: lockedCred.chatgptAccountId,
         generation: startGeneration,
         credential: lockedCred,
+        // The stored credential is fresh and no forced fence still targets it: whoever
+        // wrote it, it was not this call. A joiner adopting it inherits that provenance.
+        provenance: "external-replacement",
         resolvedGrantFingerprint: refreshGrantFingerprint,
       };
     }
@@ -803,6 +911,7 @@ async function resolveCodexToken(
         credential: sameGrantFreshCredential,
         resolvedGrantFingerprint: refreshGrantFingerprint,
         selfRefreshed: true,
+        provenance: "self-refresh",
       };
     }
     const res = await fetch(CHATGPT_TOKEN_URL, {
@@ -882,6 +991,7 @@ async function resolveCodexToken(
       // token — tagging the new grant would make every legitimate joiner look foreign.
       resolvedGrantFingerprint: refreshGrantFingerprint,
       selfRefreshed: true,
+      provenance: "self-refresh",
     };
   });
   /*
@@ -923,6 +1033,9 @@ async function resolveCodexToken(
     // produced this generation, and a forced caller needs that to know whether the new
     // credential descends from the one it was holding.
     ...(result.selfRefreshed !== undefined ? { selfRefreshed: result.selfRefreshed } : {}),
+    // Provenance rides out with the rest: a joiner that adopts this result needs the
+    // flight's own classification, not a guess made at the adoption site (#3019).
+    ...(result.provenance !== undefined ? { provenance: result.provenance } : {}),
     ...(result.resolvedGrantFingerprint !== undefined
       ? { resolvedGrantFingerprint: result.resolvedGrantFingerprint }
       : {}),

package/src/codex/auth-api.ts

@@ -10,6 +10,7 @@ import {
   getCodexAccountCredential,
   getValidCodexToken,
   isCodexAccountGenerationLive,
+  forceRefreshCodexPoolToken,
   markCodexAccountValidated,
   readCodexAccountRecord,
   saveCodexAccountCredential,
@@ -124,6 +125,14 @@ import { tryAcquireNativeMainProfileClaim } from "./native-main-admission";
 import { withNativeMainSharedClaim } from "./native-main-claim";
 import { resolveNativeProfileContext } from "./native-profile-store";
 import { NativeProfileError } from "./native-profile-types";
+import { WHAM_REQUEST_TIMEOUT_MS } from "./quota-recovery-timing";
+import {
+  claimQuotaRecovery,
+  quotaRecoveryTerminalFor,
+  releaseQuotaRecovery,
+  settleQuotaRecovery,
+  settleQuotaRecoveryTerminal,
+} from "./quota-401-recovery";
 
 function isNativeMainClaimUnavailable(error: unknown): error is NativeProfileError {
   return error instanceof NativeProfileError
@@ -766,7 +775,7 @@ async function fetchMainAccountInfoWhileOwned(
   try {
     const resp = await fetch("https://chatgpt.com/backend-api/wham/usage", {
       headers: { Authorization: `Bearer ${tokens.access_token}`, "ChatGPT-Account-Id": tokens.account_id },
-      signal: AbortSignal.timeout(8000),
+      signal: AbortSignal.timeout(WHAM_REQUEST_TIMEOUT_MS),
     });
     if (!resp.ok) {
       const terminalAuthFailure = await isTerminalMainAuthResponse(resp, isMainAccountTokenVerifiablyLive());
@@ -959,6 +968,180 @@ function reconcileFreshPoolAccountPlans(runtimeConfig: OcxConfig, updates: Fresh
   }
 }
 
+
+
+/**
+ * One refresh-and-replay for a pool account whose WHAM request came back 401 (#3019).
+ *
+ * The account list used to convert any 401 straight into `needsReauth`, and a bare 401 is
+ * exactly what a stale-but-refreshable bearer produces after a plan change — so a healthy
+ * credential was thrown away and the operator was told to log in again.
+ *
+ * Bounded by the recovery store: one attempt per credential lineage. An unbounded retry
+ * against an upstream 401 is a self-inflicted credential-stuffing loop, which is why the
+ * claim is taken BEFORE the refresh and settled by the flight rather than by this caller.
+ */
+async function recoverPoolQuotaFrom401(ctx: {
+  accountId: string;
+  existing: StoredAccountQuota | null;
+  configuredPlan: string | undefined;
+  rejectedAccessToken: string;
+  rejectedGeneration: number;
+  resp: Response;
+  onCredentialGeneration?: (generation: number) => void;
+}): Promise<PoolQuotaResult> {
+  const { accountId, existing, configuredPlan, rejectedAccessToken, rejectedGeneration, resp } = ctx;
+
+  // Structured terminal evidence short-circuits everything: the same allowlist and bounded
+  // parser the main account uses, because it is the same endpoint answering.
+  if (await isTerminalPoolAuthResponse(resp)) {
+    // Durable, not just this response: the account list re-polls, and without a recorded
+    // mark the next bare 401 finds nothing terminal and reports the account healthy.
+    //
+    // Scoped to the generation this evidence is ABOUT. An account-wide mark would outlive
+    // the credential it condemned, so a late terminal response arriving after the operator
+    // re-authenticated would quarantine the replacement.
+    markAccountNeedsReauth(accountId, captureConfigGeneration(), rejectedGeneration);
+    return { quota: existing ?? null, needsReauth: true, credentialGeneration: rejectedGeneration };
+  }
+
+  const claim = claimQuotaRecovery(accountId, rejectedGeneration);
+  if (!claim.granted) {
+    // A lineage fenced by a TERMINAL refresh failure stays terminal. Without this, the
+    // budget being used would make the next bare 401 report a dead credential as healthy.
+    if (quotaRecoveryTerminalFor(accountId, rejectedGeneration)) {
+      return { quota: existing ?? null, needsReauth: true, credentialGeneration: rejectedGeneration };
+    }
+    // Otherwise: this lineage spent its attempt, another caller is mid-refresh, or a
+    // transient failure is backing off. Report transient and let the next poll try —
+    // quarantining here would undo the whole point of the budget.
+    return { quota: existing ?? null, needsReauth: false, credentialGeneration: rejectedGeneration };
+  }
+
+  let refreshed: Awaited<ReturnType<typeof forceRefreshCodexPoolToken>>;
+  try {
+    refreshed = await forceRefreshCodexPoolToken(accountId, {
+      rejectedGeneration,
+      rejectedAccessToken,
+      // Settlement rides the flight, not this await: a cancelled caller would otherwise
+      // leave the claim to expire while the shared refresh commits, and the already
+      // refreshed lineage would get a second attempt.
+      onSettled: outcome => {
+        if (outcome.kind === "resolved") {
+          settleQuotaRecovery(accountId, claim.claimId, outcome);
+        } else if (outcome.error instanceof TokenRefreshError && isTerminalRefreshError(outcome.error)) {
+          // A revoked or expired grant does not become valid on the next poll. Releasing it
+          // into backoff would let the following bare 401 find a non-terminal record and
+          // report a dead credential as healthy.
+          settleQuotaRecoveryTerminal(accountId, claim.claimId);
+        } else {
+          releaseQuotaRecovery(accountId, claim.claimId, QUOTA_RECOVERY_BACKOFF_MS);
+        }
+      },
+    });
+  } catch (e) {
+    // A refresh that failed terminally is the one case where the credential really is gone.
+    // Everything else is unknown, and unknown is not proof.
+    if (e instanceof TokenRefreshError && isTerminalRefreshError(e)) {
+      markAccountNeedsReauth(accountId, captureConfigGeneration(), rejectedGeneration);
+      return { quota: existing ?? null, needsReauth: true, credentialGeneration: rejectedGeneration };
+    }
+    return { quota: existing ?? null, needsReauth: false, credentialGeneration: rejectedGeneration };
+  }
+
+  // A byte-identical access token means replaying earns the same 401. Report transient
+  // rather than burning the replay; the fence already moved to the returned generation.
+  if (!refreshed.rotated) {
+    return { quota: existing ?? null, needsReauth: false, credentialGeneration: refreshed.generation };
+  }
+
+  // The flight may have moved the generation while this request was in the air. Tell the
+  // coalescing layer where the credential actually is, or a late caller joins on a stale
+  // generation and opens a redundant flight.
+  ctx.onCredentialGeneration?.(refreshed.generation);
+
+  const writerGeneration = captureConfigGeneration();
+  const replay = await fetch("https://chatgpt.com/backend-api/wham/usage", {
+    headers: {
+      Authorization: `Bearer ${refreshed.accessToken}`,
+      "ChatGPT-Account-Id": refreshed.chatgptAccountId,
+    },
+    signal: AbortSignal.timeout(WHAM_REQUEST_TIMEOUT_MS),
+  });
+  if (!replay.ok) {
+    if (replay.status === 401 && await isTerminalPoolAuthResponse(replay)) {
+      // The refresh already settled this claim non-terminally, so the record alone would
+      // let the next poll call a dead credential healthy. The evidence is about the
+      // REFRESHED credential, which is what the replay used.
+      markAccountNeedsReauth(accountId, writerGeneration, refreshed.generation);
+      return { quota: existing ?? null, needsReauth: true, credentialGeneration: refreshed.generation };
+    }
+    return { quota: existing ?? null, needsReauth: false, credentialGeneration: refreshed.generation };
+  }
+  return await commitPoolQuotaResponse(replay, {
+    accountId, existing, configuredPlan, generation: refreshed.generation, writerGeneration,
+  });
+}
+
+/** Backoff after a refresh failure that proved nothing about the credential. */
+const QUOTA_RECOVERY_BACKOFF_MS = 60_000;
+
+/** Same allowlist and bounded parser as the main account: it is the same endpoint. */
+async function isTerminalPoolAuthResponse(resp: Response): Promise<boolean> {
+  // Consume the original rather than a clone. `resp.clone()` tees the body, and the
+  // bounded parser's timeout cancels only its own reader — the unread original branch
+  // keeps buffering. Nothing needs this response afterwards, so there is nothing to tee.
+  const code = await readMainAuthErrorCode(resp);
+  return typeof code === "string" && MAIN_TERMINAL_AUTH_CODES.has(code);
+}
+
+/** A revoked or expired grant is terminal; an unknown or transport failure is not. */
+function isTerminalRefreshError(error: TokenRefreshError): boolean {
+  // Read the discriminator, not the message. TokenRefreshError carries `reason`, and
+  // matching on human text would let a durable quarantine decision change the next time
+  // somebody rewords an error string.
+  return error.reason === "revoked" || error.reason === "expired";
+}
+
+/** Parse and store a successful WHAM response. Shared by the first attempt and the replay. */
+async function commitPoolQuotaResponse(
+  resp: Response,
+  ctx: {
+    accountId: string;
+    existing: StoredAccountQuota | null;
+    configuredPlan: string | undefined;
+    generation: number;
+    writerGeneration: number;
+  },
+): Promise<PoolQuotaResult> {
+  const { accountId, existing, configuredPlan, generation, writerGeneration } = ctx;
+  const data = (await resp.json()) as WhamUsageResponse;
+  const freshPlan = nonEmptyPlan(data.plan_type) ?? undefined;
+  const quota = parseUsageQuota({ ...data, plan_type: freshPlan ?? configuredPlan });
+  const freshResetCredits = quota?.resetCredits;
+  if (!quota) {
+    return {
+      quota: isCodexAccountGenerationLive(accountId, generation) ? existing ?? null : getAccountQuota(accountId),
+      needsReauth: false,
+      credentialGeneration: generation,
+      ...(freshPlan !== undefined ? { freshPlan, freshCredentialGeneration: generation } : {}),
+    };
+  }
+  if (!isCodexAccountGenerationLive(accountId, generation)) {
+    return { quota: null, needsReauth: false, credentialGeneration: generation };
+  }
+  setAccountQuotaFromParsed(accountId, quota, writerGeneration);
+  return {
+    quota: getAccountQuota(accountId),
+    needsReauth: false,
+    credentialGeneration: generation,
+    freshQuota: quota,
+    freshCredentialGeneration: generation,
+    ...(freshPlan !== undefined ? { freshPlan } : {}),
+    ...(freshResetCredits !== undefined ? { freshResetCredits } : {}),
+  };
+}
+
 async function fetchFreshPoolAccountQuota(
   accountId: string,
   existing: StoredAccountQuota | null,
@@ -976,39 +1159,25 @@ async function fetchFreshPoolAccountQuota(
       signal: AbortSignal.timeout(8000),
     });
     if (!resp.ok) {
-      return {
-        quota: existing ?? null,
-        needsReauth: resp.status === 401,
-        credentialGeneration: generation,
-      };
-    }
-    const data = (await resp.json()) as WhamUsageResponse;
-    const freshPlan = nonEmptyPlan(data.plan_type) ?? undefined;
-    const quota = parseUsageQuota({ ...data, plan_type: freshPlan ?? configuredPlan });
-    const freshResetCredits = quota?.resetCredits;
-    if (!quota) {
-      return {
-        quota: isCodexAccountGenerationLive(accountId, generation) ? existing ?? null : getAccountQuota(accountId),
-        needsReauth: false,
-        credentialGeneration: generation,
-        ...(freshPlan !== undefined
-          ? { freshPlan, freshCredentialGeneration: generation }
-          : {}),
-      };
-    }
-    if (!isCodexAccountGenerationLive(accountId, generation)) {
-      return { quota: null, needsReauth: false, credentialGeneration: generation };
+      if (resp.status !== 401) {
+        return { quota: existing ?? null, needsReauth: false, credentialGeneration: generation };
+      }
+      // A bare 401 is what a stale-but-refreshable bearer produces after a plan change, so
+      // quarantining on it tells the operator to re-authenticate an account that was fine
+      // (#3019). Refresh once, replay once, and only then decide.
+      return await recoverPoolQuotaFrom401({
+        accountId,
+        existing,
+        configuredPlan,
+        rejectedAccessToken: accessToken,
+        rejectedGeneration: generation,
+        resp,
+        onCredentialGeneration,
+      });
     }
-    setAccountQuotaFromParsed(accountId, quota, writerGeneration);
-    return {
-      quota: getAccountQuota(accountId),
-      needsReauth: false,
-      credentialGeneration: generation,
-      freshQuota: quota,
-      freshCredentialGeneration: generation,
-      ...(freshPlan !== undefined ? { freshPlan } : {}),
-      ...(freshResetCredits !== undefined ? { freshResetCredits } : {}),
-    };
+    return await commitPoolQuotaResponse(resp, {
+      accountId, existing, configuredPlan, generation, writerGeneration,
+    });
   } catch (e) {
     if (e instanceof CodexCredentialGenerationConflictError || e instanceof CodexCredentialRefreshLockTimeoutError
       || e instanceof CodexCredentialRefreshBusyError || e instanceof CodexCredentialRefreshStaleError) {