@bitkyc08/opencodex 2.58.0 → 2.60.0

package/src/clients/config-export.ts

@@ -41,7 +41,7 @@ export type { RaycastAbility, RaycastAbilityName, RaycastModelEntry, RaycastProv
 export { buildRaycastClientConfig, summarizeRaycast, buildRaycastContribution } from "./config-export/raycast";
 
 import type { OpencodeLaunchEnv, OpencodeCatalogModel, ExportContext, PiModelEntry, ManagedContribution, ManagedFragment, ExportClientId, ExportClientSpec } from "./config-export/contracts";
-import { OPENCODE_API_KEY_ENV_REF, OPENCODE_PROVIDER_BLOCK_DEFAULT_CONFIG, OPENCODE_CONFIG_SCHEMA, OPENCODE_PROVIDER_ID, PI_API_DIALECT, LOOPBACK_API_KEY_PLACEHOLDER, HERMES_API_KEY_ENV_REF, OPENCLAW_API_KEY_ENV_REF, GAJAE_API_KEY_ENV, OPENCODE_API_KEY_ENV, HERMES_API_KEY_ENV, OPENCLAW_API_KEY_ENV } from "./config-export/constants";
+import { OPENCODE_API_KEY_ENV_REF, OPENCODE_PROVIDER_BLOCK_DEFAULT_CONFIG, OPENCODE_CONFIG_SCHEMA, OPENCODE_PROVIDER_ID, PI_API_DIALECT, LOOPBACK_API_KEY_PLACEHOLDER, HERMES_API_KEY_ENV_REF, OPENCLAW_API_KEY_ENV_REF, OPENCODE_API_KEY_ENV, HERMES_API_KEY_ENV, OPENCLAW_API_KEY_ENV } from "./config-export/constants";
 import { exportModelLabel, authoritativeContextWindow, outputBudgetFor, normalizeExportModels, inputModalitiesForClient, opencodeModelCapabilities, proxyAdmissionHeaders, singleFragment } from "./config-export/model-metadata";
 import { buildOmpClientConfig, summarizeOmp, buildOmpContribution } from "./config-export/omp";
 import { buildDshClientConfig, summarizeDsh, buildDshContribution } from "./config-export/dsh";
@@ -867,7 +867,7 @@ export interface GajaeModelEntry {
 /** Gajae validates strictly: an unknown field fails the whole config. */
 export interface GajaeProviderBlock {
   baseUrl: string;
-  apiKeyEnv: string;
+  apiKey: string;
   api: "openai-completions";
   models: GajaeModelEntry[];
 }
@@ -1056,7 +1056,7 @@ function buildGajaeClientConfig(ctx: ExportContext): GajaeGeneratedConfig {
     providers: {
       [OPENCODE_PROVIDER_ID]: {
         baseUrl: ctx.baseUrl,
-        apiKeyEnv: GAJAE_API_KEY_ENV,
+        apiKey: LOOPBACK_API_KEY_PLACEHOLDER,
         api: "openai-completions",
         models,
       },
@@ -1320,8 +1320,8 @@ export const EXPORT_CLIENTS: Record<ExportClientId, ExportClientSpec> = {
     id: "gajae",
     filename: "gajae-models.yaml",
     destination: env => gajaeConfigPath(env),
-    apiKeyEnv: GAJAE_API_KEY_ENV,
-    exportHint: `export ${GAJAE_API_KEY_ENV}=<your key>`,
+    apiKeyEnv: "",
+    exportHint: "No environment variable is needed for the loopback provider.",
     build: buildGajaeClientConfig,
     format: "yaml",
     summarize: summarizeGajae,

package/src/codex/account-store.ts

@@ -1,3 +1,4 @@
+import { readOrcaAuthSource } from "./orca-auth-source";
 import { createHash } from "node:crypto";
 import { closeSync, existsSync, fstatSync, readFileSync, mkdirSync, openSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
@@ -52,11 +53,20 @@ function isObject(value: unknown): value is Record<string, unknown> {
 }
 
 function isCredential(value: unknown): value is CodexAccountCredentials {
+  const hasNoSource = isObject(value)
+    && value.sourceAuthPath === undefined
+    && value.sourceSubject === undefined;
+  const hasCompleteSource = isObject(value)
+    && typeof value.sourceAuthPath === "string"
+    && value.sourceAuthPath.length > 0
+    && typeof value.sourceSubject === "string"
+    && value.sourceSubject.length > 0;
   return isObject(value)
     && typeof value.accessToken === "string"
     && typeof value.refreshToken === "string"
     && typeof value.expiresAt === "number"
-    && typeof value.chatgptAccountId === "string";
+    && typeof value.chatgptAccountId === "string"
+    && (hasNoSource || hasCompleteSource);
 }
 
 function isCredentialRecord(value: unknown): value is CodexAccountCredentialRecord {
@@ -78,6 +88,7 @@ export function refreshGrantFingerprintForToken(refreshToken: string): string {
 }
 
 function recordGrantFingerprint(record: CodexAccountCredentialRecord): string | undefined {
+  if (record.credential?.sourceAuthPath) return undefined;
   return record.refreshGrantFingerprint ?? (
     record.credential ? refreshGrantFingerprintForToken(record.credential.refreshToken) : undefined
   );
@@ -359,6 +370,23 @@ export function isCodexAccountGenerationLive(id: string, generation: number): bo
   return !!record?.credential && record.deletedAt == null && record.generation === generation;
 }
 
+/**
+ * The same verdict as {@link isCodexAccountGenerationLive}, over ONE store load.
+ *
+ * `readCodexAccountRecord` is `loadCodexAccountRecordStore()[id]`, so asking it per row
+ * reloads, reparses and renormalizes the whole file per row — the exact shape
+ * {@link loadCodexAccountRecordSnapshot} was added to avoid. The denial reader resolves
+ * several accounts in one synchronous pass on the request path, so it opens one checker and
+ * closes over the snapshot instead.
+ */
+export function beginCodexAccountGenerationLiveCheck(): (id: string, generation: number) => boolean {
+  const snapshot = loadCodexAccountRecordSnapshot();
+  return (id, generation) => {
+    const record = snapshot[id];
+    return !!record?.credential && record.deletedAt == null && record.generation === generation;
+  };
+}
+
 export function saveCodexAccountCredentialIfGeneration(
   id: string,
   generation: number,
@@ -426,7 +454,7 @@ export function commitRefreshedCodexCredentialWithAliases(
   return withCredentialMutationLockSync(() => {
     const store = loadCodexAccountRecordStore();
     const current = store[id];
-    if (!current || current.generation !== generation || current.deletedAt != null || !current.credential) {
+    if (!current || current.generation !== generation || current.deletedAt != null || !current.credential || current.credential.sourceAuthPath) {
       return { committed: false, propagatedAliases: [] };
     }
     const priorCredential = current.credential;
@@ -458,7 +486,7 @@ export function commitRefreshedCodexCredentialWithAliases(
       && priorCredential.chatgptAccountId === cred.chatgptAccountId
     ) {
       for (const [aliasId, alias] of Object.entries(store)) {
-        if (aliasId === id || alias.deletedAt != null || !alias.credential) continue;
+        if (aliasId === id || alias.deletedAt != null || !alias.credential || alias.credential.sourceAuthPath) continue;
         if (recordGrantFingerprint(alias) !== priorFingerprint) continue;
         if (alias.credential.accessToken !== priorCredential.accessToken) continue;
         if (alias.credential.expiresAt !== priorCredential.expiresAt) continue;
@@ -585,6 +613,41 @@ function withCredentialMutationLockSync<T>(fn: () => T): T {
 }
 
 type CodexTokenResult = { accessToken: string; chatgptAccountId: string; generation: number };
+type CodexRefreshGenerationHandoff = (accountId: string, fromGeneration: number, toGeneration: number) => void;
+// var (hoisted, initialized to undefined) rather than const: a registrar reached
+// through an import cycle can register while this module body is still evaluating,
+// and the lazily created Set must be reachable rather than in the temporal dead zone.
+var refreshGenerationHandoffs: Set<CodexRefreshGenerationHandoff> | undefined;
+function refreshHandoffs(): Set<CodexRefreshGenerationHandoff> {
+  return refreshGenerationHandoffs ??= new Set();
+}
+
+/** Register process-local state that must follow a credential refresh generation. */
+export function registerCodexRefreshGenerationHandoff(handoff: CodexRefreshGenerationHandoff): () => void {
+  const set = refreshHandoffs();
+  set.add(handoff);
+  return () => set.delete(handoff);
+}
+
+/**
+ * Invoke every registered handoff for one committed `fromGeneration` to `toGeneration` move.
+ *
+ * Each listener runs independently and a throw is contained: by the time handoffs run the
+ * rotated credential is already persisted, so a failing listener must not reject the shared
+ * refresh promise (surviving waiters would see a refresh failure that never happened), must
+ * not starve the remaining listeners, and must not block plan reconciliation. The warning
+ * carries no account id or token material — the same scrub refresh error messages get.
+ */
+function dispatchRefreshGenerationHandoffs(accountId: string, fromGeneration: number, toGeneration: number): void {
+  for (const handoff of refreshHandoffs()) {
+    try {
+      handoff(accountId, fromGeneration, toGeneration);
+    } catch (error) {
+      console.warn("[codex-auth] a refresh generation handoff listener failed", error);
+    }
+  }
+}
+
 type CodexRefreshResult = CodexTokenResult & {
   credential?: CodexAccountCredentials;
   /**
@@ -630,7 +693,14 @@ export type CodexRefreshProvenance = "self-refresh" | "joined-lineage" | "extern
 
 /** 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: "resolved";
+      provenance: CodexRefreshProvenance;
+      generation: number;
+      rotated: boolean;
+      /** Same-grant records advanced by this refresh, at their committed generations. */
+      propagatedAliases?: { id: string; generation: number }[];
+    }
   | { kind: "failed"; error: unknown };
 const MAX_CODEX_REFRESH_FLIGHTS = 32;
 const CODEX_REFRESH_FLIGHT_STALE_MS = 120_000;
@@ -776,7 +846,7 @@ function findFreshCredentialForGrant(
   // require both ids to be present and exactly equal rather than inferring identity from the grant.
   if (!expectedChatgptAccountId) return null;
   for (const [candidateId, candidate] of Object.entries(records)) {
-    if (candidateId === excludeId || candidate.deletedAt != null || !candidate.credential) continue;
+    if (candidateId === excludeId || candidate.deletedAt != null || !candidate.credential || candidate.credential.sourceAuthPath) continue;
     if (recordGrantFingerprint(candidate) !== refreshGrantFingerprint) continue;
     if (!candidate.credential.chatgptAccountId) continue;
     if (candidate.credential.chatgptAccountId !== expectedChatgptAccountId) continue;
@@ -926,6 +996,9 @@ export async function forceRefreshCodexPoolToken(
         provenance: classify(resolved),
         generation: resolved.generation,
         rotated: resolved.accessToken !== options.rejectedAccessToken,
+        ...(resolved.propagatedAliases?.length
+          ? { propagatedAliases: resolved.propagatedAliases }
+          : {}),
       });
     },
     error => {
@@ -967,6 +1040,57 @@ export async function getValidCodexToken(
   };
 }
 
+/** Source credentials never join refresh flights or spend a refresh grant, including after 401. */
+function resolveOrcaSourceToken(id: string, forced?: ForcedRefreshFence): CodexRefreshResult {
+  const initial = readCodexAccountRecord(id);
+  const initialCredential = initial?.credential;
+  if (!initial || initial.deletedAt != null || !initialCredential?.sourceAuthPath || !initialCredential.sourceSubject) {
+    throw new CodexCredentialGenerationConflictError();
+  }
+  const sourceCredential = readOrcaAuthSource(initialCredential.sourceAuthPath);
+  if (sourceCredential.chatgptAccountId !== initialCredential.chatgptAccountId
+    || sourceCredential.sourceSubject !== initialCredential.sourceSubject) {
+    throw new Error("Orca credential identity changed; reimport the account explicitly.");
+  }
+  if (sourceCredential.accessToken === initialCredential.accessToken
+    && sourceCredential.expiresAt === initialCredential.expiresAt) {
+    if (forced?.rejectedAccessToken === sourceCredential.accessToken) {
+      throw new Error("Orca bearer was rejected; update the account in Orca and retry.");
+    }
+    return { accessToken: sourceCredential.accessToken, chatgptAccountId: sourceCredential.chatgptAccountId,
+      generation: initial.generation, provenance: "external-replacement" };
+  }
+
+  return withCredentialMutationLockSync(() => {
+    const store = loadCodexAccountRecordStore();
+    const record = store[id];
+    const prior = record?.credential;
+    if (!record || record.deletedAt != null || !prior?.sourceAuthPath || !prior.sourceSubject) {
+      throw new CodexCredentialGenerationConflictError();
+    }
+    if (record.generation !== initial.generation) throw new CodexCredentialGenerationConflictError();
+    const credential = readOrcaAuthSource(prior.sourceAuthPath);
+    if (credential.chatgptAccountId !== prior.chatgptAccountId || credential.sourceSubject !== prior.sourceSubject) {
+      throw new Error("Orca credential identity changed; reimport the account explicitly.");
+    }
+    if (credential.accessToken !== prior.accessToken || credential.expiresAt !== prior.expiresAt) {
+      store[id] = {
+        credential, generation: record.generation + 1, replacedAt: Date.now(),
+        // The source identity was checked above. Retire old-generation writers without
+        // splitting this same account's retained quota history on every source rotation.
+        quotaHistoryIdentity: record.quotaHistoryIdentity,
+        ...preservedValidationMetadata(record),
+      };
+      persistCredentialMutation(store);
+    }
+    if (forced?.rejectedAccessToken === credential.accessToken) {
+      throw new Error("Orca bearer was rejected; update the account in Orca and retry.");
+    }
+    return { accessToken: credential.accessToken, chatgptAccountId: credential.chatgptAccountId,
+      generation: store[id]!.generation, provenance: "external-replacement" };
+  });
+}
+
 async function resolveCodexToken(
   id: string,
   forced?: ForcedRefreshFence,
@@ -976,6 +1100,7 @@ async function resolveCodexToken(
   const record = readCodexAccountRecord(id);
   const cred = record?.deletedAt == null ? record?.credential : undefined;
   if (!record || !cred) throw new CodexCredentialUnavailableError();
+  if (cred.sourceAuthPath) return resolveOrcaSourceToken(id, forced);
   const refreshGrantFingerprint = recordGrantFingerprint(record);
   if (!refreshGrantFingerprint) throw new CodexCredentialUnavailableError();
 
@@ -1005,6 +1130,7 @@ async function resolveCodexToken(
       const refreshed = await awaitOwnCancellation(existing.promise, callerSignal);
       const current = readCodexAccountRecord(id);
       const currentCred = current?.deletedAt == null ? current?.credential : undefined;
+      if (currentCred?.sourceAuthPath) return resolveOrcaSourceToken(id, forced);
       // The flight owner already committed this credential, and it is the one stored
       // for this account: adopt the stored state instead of CAS-writing the identical
       // bytes, which would bump the generation a second time and invalidate the
@@ -1126,6 +1252,7 @@ async function resolveCodexToken(
     const lockedRecord = readCodexAccountRecord(id);
     const lockedCred = lockedRecord?.deletedAt == null ? lockedRecord?.credential : undefined;
     if (!lockedRecord || !lockedCred) throw new CodexCredentialGenerationConflictError();
+    if (lockedCred.sourceAuthPath) return resolveOrcaSourceToken(id, forced);
     const startGeneration = lockedRecord.generation;
     const lockedRefreshGrantFingerprint = recordGrantFingerprint(lockedRecord);
     if (lockedRefreshGrantFingerprint !== refreshGrantFingerprint) {
@@ -1302,6 +1429,19 @@ async function resolveCodexToken(
    * committed result, for every waiter, including none.
    */
   const refreshPromise = fetchPromise.then(async (result): Promise<CodexRefreshResult> => {
+    // Generation-dependent completion belongs to the flight, not to its initiating
+    // request. The owner may stop waiting after a disconnect while this detached work
+    // still commits G+1; advance process-local affinities before any waiter observes
+    // the result (and even when there are no surviving waiters).
+    if (result.selfRefreshed) {
+      dispatchRefreshGenerationHandoffs(id, result.generation - 1, result.generation);
+      // A propagated alias committed at its OWN generation, so its affinities sit at
+      // alias.generation - 1: without this handoff they fail the exact-generation
+      // liveness check on the very next request that reads them.
+      for (const alias of result.propagatedAliases ?? []) {
+        dispatchRefreshGenerationHandoffs(alias.id, alias.generation - 1, alias.generation);
+      }
+    }
     await notePlanFromRefreshedAccessToken(id, result.accessToken, result.generation);
     // One settlement path for the whole flight: the refreshing account, then any dormant alias that
     // adopted the same rotated JWT. An alias holds the identical access token, so a changed
@@ -1331,6 +1471,7 @@ async function resolveCodexToken(
     // 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.propagatedAliases?.length ? { propagatedAliases: result.propagatedAliases } : {}),
     ...(result.resolvedGrantFingerprint !== undefined
       ? { resolvedGrantFingerprint: result.resolvedGrantFingerprint }
       : {}),

package/src/codex/auth-api/account-list.ts

@@ -82,9 +82,9 @@ export function mainQuotaWithCarriedResetCredits(
 /**
  * Why an account needs the operator. `missing_credential`, `refresh_failed`, and
  * `quota_unauthorized` are the three causes this surface tells apart on its own. `unauthorized`
- * and `forbidden` exist because the shared health projection may return them; today
- * `projectCodexAccountHealth` only ever produces `refresh_failed`, so accepting the full union
- * keeps this field correct if that projection widens rather than silently dropping a reason.
+ * and `forbidden` come from the shared health projection: `projectCodexAccountHealth` maps a
+ * stored verification failure's `http_status:401`/`http_status:403` to them, so the union has
+ * to accept every reason the projection can emit rather than silently dropping one.
  */
 export type CodexAccountReauthReason =
   | "missing_credential"
@@ -105,18 +105,26 @@ export function poolAccountDto(
   const plan = codexPlanValue(account.plan);
   const quota = quotaForPlan(quotaResult.quota, plan);
   const runtimeReauth = isAccountNeedsReauth(account.id);
+  const rawReauthReason: CodexAccountReauthReason | undefined = !hasCredential
+    ? "missing_credential"
+    : quotaResult.reauthReason;
   const needsReauth = !hasCredential || quotaResult.needsReauth || runtimeReauth;
-  const health = projectCodexAccountHealth({ accountId: account.id, needsReauth });
+  // An in-memory reauth mark carries no cause of its own, so it must not name one: passing
+  // a caller reason here would outrank the stored verdict's http_status inside the
+  // projection and hide unauthorized/forbidden until the mark is gone. With no caller
+  // reason the projection falls back to the persisted cause, then to refresh_failed.
+  const healthReason = rawReauthReason === "quota_unauthorized" || rawReauthReason === "missing_credential"
+    ? "unauthorized"
+    : rawReauthReason;
+  const health = projectCodexAccountHealth({
+    accountId: account.id,
+    needsReauth,
+    reauthReason: needsReauth ? healthReason : undefined,
+  });
   // `needsReauth` is an OR of three independent causes plus a persisted verdict resolved inside the
   // health projection. Emitting only the boolean is what left #4212's reporter guessing which
   // account took their model away and why, so name the cause they actually have to act on.
-  const reauthReason: CodexAccountReauthReason | undefined = !hasCredential
-    ? "missing_credential"
-    : runtimeReauth
-      ? "refresh_failed"
-      : quotaResult.needsReauth
-        ? "quota_unauthorized"
-        : health.status === "reauth_required" ? health.reason : undefined;
+  const reauthReason: CodexAccountReauthReason | undefined = rawReauthReason ?? (health.status === "reauth_required" ? health.reason : undefined);
   return {
     id: account.id,
     email: projectEmail(account.email, maskEmails) ?? account.email,

package/src/codex/auth-api/pool-quota-probe.ts

@@ -1,4 +1,4 @@
-import { capturePoolQuotaWriter, getValidCodexToken, isCodexAccountGenerationLive, forceRefreshCodexPoolToken, markCodexAccountValidated, markCodexAccountValidationFailed, readCodexAccountRecord, CodexCredentialGenerationConflictError, CodexCredentialRefreshLockTimeoutError, CodexCredentialRefreshBusyError, CodexCredentialRefreshStaleError, TokenRefreshError } from "../account-store";
+import { capturePoolQuotaWriter, getValidCodexToken, isCodexAccountGenerationLive, forceRefreshCodexPoolToken, markCodexAccountValidated, markCodexAccountValidationFailed, readCodexAccountRecord, isTerminalCodexPoolRefreshFailure, CodexCredentialGenerationConflictError, CodexCredentialRefreshLockTimeoutError, CodexCredentialRefreshBusyError, CodexCredentialRefreshStaleError, TokenRefreshError } from "../account-store";
 import type { PoolQuotaWriter } from "../quota-types";
 import { isValidWhamHistoryObservation, getAccountQuota, isCompleteCodexQuotaRecoverySnapshot, parseUsageQuota, setAccountQuotaFromParsed } from "../quota";
 import type { StoredAccountQuota, WhamUsageResponse } from "../quota";
@@ -9,7 +9,7 @@ import { codexWarmupFailureReason, warmCodexAccount } from "../warmup";
 import { readBoundedResponseBody } from "../../lib/bounded-body";
 import { ResourceAdmissionError } from "../../lib/admission";
 import { WHAM_REQUEST_TIMEOUT_MS } from "../quota-recovery-timing";
-import { claimQuotaRecovery, quotaRecoveryTerminalFor, releaseQuotaRecovery, settleQuotaRecovery, settleQuotaRecoveryTerminal } from "../quota-401-recovery";
+import { claimQuotaRecovery, fencePropagatedQuotaRecovery, quotaRecoveryTerminalFor, releaseQuotaRecovery, settleQuotaRecovery, settleQuotaRecoveryTerminal } from "../quota-401-recovery";
 import { seedLoginRowsForTests } from "./login-state";
 import { nonEmptyPlan } from "./runtime-config";
 
@@ -46,6 +46,8 @@ export interface PoolQuotaResult {
   resetRefreshLineage?: ManualResetRefreshLineage;
   quota: StoredAccountQuota | null;
   needsReauth: boolean;
+  /** Failure source observed while obtaining the quota, when reauthentication is required. */
+  reauthReason?: "refresh_failed" | "quota_unauthorized";
   /** Credential generation whose cache or network result this DTO state belongs to. */
   credentialGeneration?: number;
   /** Present only when this call freshly parsed a WHAM usage response. */
@@ -178,7 +180,7 @@ export async function recoverPoolQuotaFrom401(ctx: {
     // 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 };
+    return { quota: existing ?? null, needsReauth: true, reauthReason: "quota_unauthorized", credentialGeneration: rejectedGeneration };
   }
 
   const claim = claimQuotaRecovery(accountId, rejectedGeneration);
@@ -186,7 +188,7 @@ export async function recoverPoolQuotaFrom401(ctx: {
     // 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 };
+      return { quota: existing ?? null, needsReauth: true, reauthReason: "refresh_failed", 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 —
@@ -205,6 +207,12 @@ export async function recoverPoolQuotaFrom401(ctx: {
       onSettled: outcome => {
         if (outcome.kind === "resolved") {
           settleQuotaRecovery(accountId, claim.claimId, outcome);
+          // A propagated alias adopted the rotated grant without spending its own claim. Fence
+          // each committed alias generation so a later 401 on it cannot claim a second refresh
+          // of the same underlying grant.
+          for (const alias of outcome.propagatedAliases ?? []) {
+            fencePropagatedQuotaRecovery(alias.id, alias.generation);
+          }
         } 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
@@ -219,8 +227,15 @@ export async function recoverPoolQuotaFrom401(ctx: {
     // 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)) {
+      // Persist the same verdict the token guardian writes: the in-memory mark dies with
+      // this process, and only the stored terminal failure keeps a cached listing from
+      // calling the dead grant healthy after a restart.
+      markCodexAccountValidationFailed(accountId, `refresh_${e.reason}`, {
+        expectedGeneration: rejectedGeneration,
+        terminal: true,
+      });
       markAccountNeedsReauth(accountId, captureConfigGeneration(), rejectedGeneration);
-      return { quota: existing ?? null, needsReauth: true, credentialGeneration: rejectedGeneration };
+      return { quota: existing ?? null, needsReauth: true, reauthReason: "refresh_failed", credentialGeneration: rejectedGeneration };
     }
     return { quota: existing ?? null, needsReauth: false, credentialGeneration: rejectedGeneration };
   }
@@ -252,7 +267,7 @@ export async function recoverPoolQuotaFrom401(ctx: {
       // 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: true, reauthReason: "quota_unauthorized", credentialGeneration: refreshed.generation };
     }
     return { quota: existing ?? null, needsReauth: false, credentialGeneration: refreshed.generation };
   }
@@ -393,9 +408,23 @@ export async function fetchFreshPoolAccountQuota(
         quotaProbeSkipped: true,
       }, quotaProbeEvidence);
     }
-    if (e instanceof TokenRefreshError) {
+    // Terminal means the grant itself is dead or missing; an `unknown` refresh failure (a
+    // token-endpoint 5xx, a transport blip) may clear, so it reports transient like the
+    // 401-recovery path instead of quarantining a healthy account (#2887). A revoked or
+    // expired grant is also written to the record as a terminal validation failure, the same
+    // verdict the token guardian persists: the in-memory mark dies with this process, and
+    // the stored verdict is what keeps a cached listing from calling the dead grant healthy
+    // after a restart.
+    if (isTerminalCodexPoolRefreshFailure(e)) {
+      if (e instanceof TokenRefreshError && isTerminalRefreshError(e)) {
+        markCodexAccountValidationFailed(accountId, `refresh_${e.reason}`, {
+          expectedGeneration: requestCredentialGeneration,
+          terminal: true,
+        });
+      }
+      markAccountNeedsReauth(accountId, captureConfigGeneration(), requestCredentialGeneration);
       return withQuotaProbeEvidence(
-        { quota: existing ?? null, needsReauth: true, credentialGeneration: requestCredentialGeneration },
+        { quota: existing ?? null, needsReauth: true, reauthReason: "refresh_failed", credentialGeneration: requestCredentialGeneration },
         quotaProbeEvidence,
       );
     }
@@ -476,9 +505,14 @@ export async function fetchPoolAccountQuota(
       && generation !== undefined && record.generation === generation
       && isCompleteCodexQuotaRecoverySnapshot(result.freshQuota ?? null, result.freshPlan ?? configuredPlan)) {
       try {
+        // Quota I/O may outlive the source capture. Never validate a rotated or revoked link
+        // using an older generation's observation. Explicit validation consent still applies.
+        const sourceToken = record.credential.sourceAuthPath ? await getValidToken(accountId) : null;
+        if (sourceToken && (sourceToken.generation !== generation
+          || !isCodexAccountGenerationLive(accountId, generation))) return result;
         await warmCodexAccount({
-          accessToken: record.credential.accessToken,
-          chatgptAccountId: record.credential.chatgptAccountId,
+          accessToken: sourceToken?.accessToken ?? record.credential.accessToken,
+          chatgptAccountId: sourceToken?.chatgptAccountId ?? record.credential.chatgptAccountId,
         });
         markCodexAccountValidated(accountId, Date.now(), generation);
         clearAccountNeedsReauth(accountId, generation);

package/src/codex/auth-api/routes.ts

@@ -7,7 +7,7 @@ import { getAccountQuotaHistory, listAccountQuotas } from "../quota";
 import { deleteCodexAccount } from "../account-lifecycle";
 import { isCodexAccountPaused, setCodexAccountPaused } from "../account-pause";
 import { clearCodexAccountPin, isCodexAccountPriorityKey, pinnedCodexAccountId, setCodexAccountPin, setCodexAccountPriority } from "../account-priority";
-import { codexQuotaScopeForModel, clearCodexAccountCooldown, clearThreadAccountMapForAccount, getEffectiveActiveCodexAccountId, isEffectiveCodexAccountPinned, resetCodexRoutingForManualSelection } from "../routing";
+import { codexAccountPinDrainReason, codexQuotaScopeForModel, clearCodexAccountCooldown, clearThreadAccountMapForAccount, getEffectiveActiveCodexAccountId, isEffectiveCodexAccountPinned, resetCodexRoutingForManualSelection } from "../routing";
 import { DEFAULT_ACCOUNT_PRIORITY, MAX_ACCOUNT_PRIORITY, MIN_ACCOUNT_PRIORITY, normalizeAccountPoolStickyLimit, normalizeCodexAccountPoolStrategy, parseAccountPoolStickyLimit, parseCodexAccountPoolStrategy, parseAccountPriority } from "../pool-rotation";
 import { MAIN_CODEX_ACCOUNT_ID } from "../main-account";
 import { reconcileLiveStateStores } from "../../lib/state-store-registrations";
@@ -235,7 +235,22 @@ export async function handleCodexAuthAPI(
     else setCodexAccountPin(runtimeConfig, targetAccountId);
     resetCodexRoutingForManualSelection(targetAccountId);
     saveRuntimeConfig(config, runtimeConfig);
-    return jsonResponse({ ok: true, activeCodexAccountId: body.accountId, appliesImmediately: true });
+    // A pin this route accepts can still be dropped by the very next resolve, and saying
+    // nothing about that is what made the setting look ignored (#4521). The checks above
+    // refuse an account that cannot be selected at all; this reports the one remaining
+    // outcome they do not cover, from the same predicate routing releases on, so the two
+    // cannot drift. Absent means the pin survives — additive for existing clients.
+    // `appliesImmediately` is unchanged: it answers whether thread affinity was cleared,
+    // not whether the pin is durable.
+    const pinDrainReason = body.accountId == null
+      ? undefined
+      : codexAccountPinDrainReason(runtimeConfig, targetAccountId);
+    return jsonResponse({
+      ok: true,
+      activeCodexAccountId: body.accountId,
+      appliesImmediately: true,
+      ...(pinDrainReason !== undefined ? { pinDrained: true, pinDrainReason } : {}),
+    });
   }
 
   if (url.pathname === "/api/codex-auth/active" && req.method === "GET") {

package/src/codex/auth-context.ts

@@ -135,20 +135,22 @@ export function requestOwnedMainPinState(
 }
 
 /**
- * Every thread keys as ITSELF, never as its parent (#4546, wp8).
+ * One conversation tree keys as ONE cohort (#4780).
  *
- * The old rule preferred `x-codex-parent-thread-id`, so every child of one parent bound under
- * the RAW parent id -- one shared entry, unrelated to the root's own `app:HMAC(session, thread)`
- * binding -- and a grandchild keyed on its own parent landed on a key nobody had ever bound.
- * A child therefore started cold while its parent was being served warm somewhere, and no
- * child could hold a binding of its own.
+ * Upstream keys its prompt cache on something the whole tree shares -- `prompt_cache_key` is the
+ * session id, or `{source}:{parent_thread_id}` for an internal session -- and one `AgentControl`
+ * whose `session_id` is the root thread's id is shared with every sub-agent. While the proxy
+ * keyed per thread, two requests could carry an identical `prompt_cache_key` and be served by
+ * different accounts, so the split member asserted a warm prefix that was deterministically cold
+ * on its account. Nothing failed; the prompt was replayed in full and the tokens burned.
  *
- * Now a request with a `thread-id` keys as HMAC(session ?? parent, thread). A root is
- * unchanged, a child gets an independent key, and a request naming only a parent rides the
- * parent's lane under HMAC(parent, parent) -- the same one-to-one lane it always had, minus
- * the caller-supplied identifier that used to sit in Pool state. Which requests produce no
- * key at all is unchanged. First placement for a child is what consults the family, through
- * `recordCodexThreadLineage` below and the placement hook in ./routing.
+ * THIS IS NOT A REVERT OF #4546 wp8. wp8 fixed a different defect -- a child bound under the RAW
+ * parent id, an identity unrelated to the root's own binding, so siblings shared an entry the
+ * root was not on and a grandchild landed on a key nobody had bound. A cohort key has no such
+ * incoherence, because the root's own binding IS the cohort key. What wp8 additionally gave each
+ * thread, a binding of its own, is what this deliberately gives up.
+ *
+ * Which requests produce no key at all is unchanged, through both units.
  *
  * The derivation itself lives in ./lineage so a lineage record's conversation key and the key
  * the thread actually binds under can never drift apart.
@@ -1419,6 +1421,7 @@ export function materializeCodexUpstreamAuth(
     if (!stored?.accessToken || !isMainAccountTokenLive()) {
       throw new CodexMainSubstitutionUnavailableError();
     }
+    selected.delete("chatgpt-account-id");
     selected.set("authorization", `Bearer ${stored.accessToken}`);
     if (stored.chatgptAccountId) selected.set("chatgpt-account-id", stored.chatgptAccountId);
     observeSelectedMainCredential(stored, writer);
@@ -1496,6 +1499,7 @@ export async function materializeCodexUpstreamAuthAsync(
     ...(options.nativeMainRefreshDependencies ?? {}),
   });
   if (!stored?.accessToken) throw new CodexMainSubstitutionUnavailableError();
+  selected.delete("chatgpt-account-id");
   selected.set("authorization", `Bearer ${stored.accessToken}`);
   if (stored.chatgptAccountId) selected.set("chatgpt-account-id", stored.chatgptAccountId);
   observeSelectedMainCredential(stored, writer);