import { publishCredentialSync } from "../local-credentials/generation";
import { classifyChatgptRefreshFailure, noteChatgptRefreshFailure, type ChatgptRefreshDiagnosticCode } from "./chatgpt-refresh-failure";
import { readBoundedResponseBody } from "../lib/bounded-body";
export { classifyChatgptRefreshFailure } from "./chatgpt-refresh-failure";
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";
import {
  ConfigMutationLockError,
  getConfigDir,
  atomicWriteFile,
  backupInvalidConfig,
  hardenConfigDir,
  hardenExistingSecret,
  loadConfig,
  withConfigMutationLockSync,
} from "../config";
import { notifyCodexStoreLoaded } from "../lib/decision-quota-sink";
import { assertNotRealHomeUnderTest } from "../lib/test-home-guard";
import type { CodexAccount, CodexAccountCredentialRecord, CodexAccountCredentials } from "../types";
import { advanceCodexCredentialMutationEpoch } from "./credential-mutation-epoch";
import { isValidCodexAccountId } from "./account-id";
import { codexAccountLogLabel, fallbackCodexAccountLogLabel } from "./account-label";
import type { PoolQuotaWriter } from "./quota-types";
import { CODEX_REFRESH_FLIGHT_CEILING_MS } from "./quota-recovery-timing";

import {
  CodexPoolRefreshCooldownError,
  clearCodexPoolRefreshFailure,
  codexPoolRefreshFence,
  isCodexPoolRefreshCooling,
  noteCodexPoolRefreshFailure,
} from "./pool-refresh-backoff";

type LegacyCodexAccountStore = Record<string, CodexAccountCredentials>;
type CodexAccountStore = Record<string, CodexAccountCredentialRecord>;
type RawCodexAccountStore = Record<string, CodexAccountCredentials | CodexAccountCredentialRecord>;

const REFRESH_SKEW_MS = 60_000;
const REFRESH_LOCK_STALE_MS = 60_000;
const REFRESH_LOCK_WAIT_MS = REFRESH_LOCK_STALE_MS + 5_000;
const REFRESH_LOCK_POLL_MS = 50;

function codexAccountsPath(): string {
  return join(getConfigDir(), "codex-accounts.json");
}

export function loadCodexAccountStore(): LegacyCodexAccountStore {
  const records = loadCodexAccountRecordStore();
  const credentials: LegacyCodexAccountStore = {};
  for (const [id, record] of Object.entries(records)) {
    if (record.deletedAt == null && record.credential) credentials[id] = record.credential;
  }
  return credentials;
}

function isObject(value: unknown): value is Record<string, unknown> {
  return !!value && typeof value === "object" && !Array.isArray(value);
}

export function inspectLocalCodexCredentialSlots(raw: Record<string, unknown> | null): { count: number; sourcePaths: string[] } {
  if (raw === null) return { count: 0, sourcePaths: [] };
  let count = 0;
  const sourcePaths: string[] = [];
  for (const value of Object.values(raw)) {
    let credential: CodexAccountCredentials | undefined;
    if (isCredentialRecord(value)) {
      credential = value.credential;
      if (!credential && value.deletedAt === undefined) throw new Error("Unrecognized Codex credential record");
    } else if (isCredential(value)) credential = value;
    else throw new Error("Invalid Codex credential record");
    if (credential) {
      count += 1;
      if (credential.sourceAuthPath) sourcePaths.push(credential.sourceAuthPath);
    }
  }
  return { count, sourcePaths };
}

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"
    && value.chatgptAccountId.trim().length > 0
    && (hasNoSource || hasCompleteSource);
}

function isCredentialRecord(value: unknown): value is CodexAccountCredentialRecord {
  return isObject(value)
    && typeof value.generation === "number"
    && (value.credential === undefined || isCredential(value.credential))
    && (value.refreshGrantFingerprint === undefined || typeof value.refreshGrantFingerprint === "string")
    && (value.deletedAt === undefined || typeof value.deletedAt === "number")
    && (value.replacedAt === undefined || typeof value.replacedAt === "number")
    && (value.lastCodexValidatedAt === undefined || typeof value.lastCodexValidatedAt === "number")
    && (value.lastCodexValidationStatus === undefined || value.lastCodexValidationStatus === "ok" || value.lastCodexValidationStatus === "failed")
    && (value.lastCodexValidationError === undefined || typeof value.lastCodexValidationError === "string")
    && (value.codexValidationPending === undefined || typeof value.codexValidationPending === "boolean")
    && (value.lastCodexValidationTerminal === undefined || typeof value.lastCodexValidationTerminal === "boolean");
}

export function refreshGrantFingerprintForToken(refreshToken: string): string {
  return createHash("sha256").update(`codex-refresh-grant:${refreshToken}`).digest("hex");
}

function recordGrantFingerprint(record: CodexAccountCredentialRecord): string | undefined {
  if (record.credential?.sourceAuthPath) return undefined;
  return record.refreshGrantFingerprint ?? (
    record.credential ? refreshGrantFingerprintForToken(record.credential.refreshToken) : undefined
  );
}

function normalizeRecord(value: CodexAccountCredentials | CodexAccountCredentialRecord | undefined): CodexAccountCredentialRecord | undefined {
  if (!value) return undefined;
  if (isCredentialRecord(value)) {
    const refreshGrantFingerprint = recordGrantFingerprint(value);
    return refreshGrantFingerprint ? { ...value, refreshGrantFingerprint } : value;
  }
  if (isCredential(value)) {
    return {
      credential: value,
      generation: 0,
      refreshGrantFingerprint: refreshGrantFingerprintForToken(value.refreshToken),
    };
  }
  return undefined;
}

/**
 * Observe-only read for the JEV quota activation owner: the same normalization as the loader,
 * without hardening, invalid-file backup or slot notification. Absent or invalid stores read as empty.
 */
export function peekCodexAccountRecordStore(): Record<string, CodexAccountCredentialRecord> {
  const path = codexAccountsPath();
  if (!existsSync(path)) return {};
  const normalized: Record<string, CodexAccountCredentialRecord> = {};
  try {
    const raw = JSON.parse(readFileSync(path, "utf-8")) as RawCodexAccountStore;
    for (const [id, value] of Object.entries(raw)) {
      const record = normalizeRecord(value);
      if (record) normalized[id] = record;
    }
  } catch {
    return {};
  }
  return normalized;
}

/** Read the Codex account record store from disk with hardened permissions, and hand it to the opt-in decision-quota slot (a no-op unless JEV quota signals are active). */
function loadCodexAccountRecordStore(): CodexAccountStore {
  const result = loadCodexAccountRecordStoreResult();
  return result.status === "ok" ? result.records : {};
}

type CodexAccountRecordStoreResult = { status: "ok"; records: CodexAccountStore } | { status: "failed" };

/** Retain read/parse failure separately for consumers that must preserve existing evidence. */
function loadCodexAccountRecordStoreResult(): CodexAccountRecordStoreResult {
  const path = codexAccountsPath();
  hardenConfigDir();
  hardenExistingSecret(path);
  const normalized: CodexAccountStore = {};
  try {
    const raw = JSON.parse(readFileSync(path, "utf-8")) as RawCodexAccountStore;
    if (!isObject(raw)) throw new Error("invalid Codex account store shape");
    for (const [id, value] of Object.entries(raw)) {
      const record = normalizeRecord(value);
      if (record) normalized[id] = record;
    }
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
      notifyCodexStoreLoaded({});
      return { status: "ok", records: {} };
    }
    backupInvalidConfig(path);
    notifyCodexStoreLoaded({});
    return { status: "failed" };
  }
  // Outside the parse try: roster publication is advisory and must never route a loaded store into the invalid-config backup path.
  notifyCodexStoreLoaded(normalized);
  return { status: "ok", records: normalized };
}

/** Atomically write the Codex account store, then hand it to the opt-in decision-quota slot so active advisory evidence tracks the persisted credentials. */
function persist(store: CodexAccountStore): void {
  const dir = getConfigDir();
  assertNotRealHomeUnderTest(dir);
  if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
  publishCredentialSync(() => atomicWriteFile(codexAccountsPath(), JSON.stringify(store, null, 2) + "\n"));
  notifyCodexStoreLoaded(store);
}

function persistCredentialMutation(store: CodexAccountStore): void {
  persist(store);
  advanceCodexCredentialMutationEpoch();
}

/**
 * The durable `p<hex6>` label the dashboard and usage log show for this pool account, so a refresh
 * failure line can be matched to the account row (#7592). The id hash is only the label of a
 * legacy row that never received one. A config read failure must not replace the refresh error
 * being reported, so it degrades to that same hash.
 */
function poolAccountLogLabel(id: string): string {
  let account: CodexAccount | undefined;
  try { account = loadConfig().codexAccounts?.find(row => row.id === id); } catch { account = undefined; }
  return account ? codexAccountLogLabel(account) : fallbackCodexAccountLogLabel(id);
}

/**
 * Validation metadata that survives a credential write.
 *
 * `lastCodexValidationTerminal` is deliberately NOT in this list. Every credential write —
 * re-login, the CAS refresh commit, same-grant alias propagation — rebuilds the record from this
 * pick list, so leaving the marker out is what makes a successful refresh or a re-authentication
 * erase a terminal verdict. Both events disprove "the grant was revoked", and a verdict that
 * could only ever be set would brand an account dead forever on one spurious `invalid_grant`.
 */
function preservedValidationMetadata(record: CodexAccountCredentialRecord | undefined): Pick<
  CodexAccountCredentialRecord,
  "lastCodexValidatedAt" | "lastCodexValidationStatus" | "lastCodexValidationError" | "codexValidationPending"
> {
  return {
    ...(record?.codexValidationPending === true ? { codexValidationPending: true } : {}),
    ...(record?.lastCodexValidatedAt !== undefined ? { lastCodexValidatedAt: record.lastCodexValidatedAt } : {}),
    ...(record?.lastCodexValidationStatus !== undefined ? { lastCodexValidationStatus: record.lastCodexValidationStatus } : {}),
    ...(record?.lastCodexValidationError !== undefined ? { lastCodexValidationError: record.lastCodexValidationError } : {}),
  };
}

export function getCodexAccountCredential(id: string): CodexAccountCredentials | null {
  const record = readCodexAccountRecord(id);
  if (!record || record.deletedAt != null) return null;
  return record.credential ?? null;
}

export function saveCodexAccountCredential(
  id: string,
  cred: CodexAccountCredentials,
  options: { validationPending?: boolean } = {},
): number {
  return withCredentialMutationLockSync(() => {
    const store = loadCodexAccountRecordStore();
    const current = store[id];
    const refreshGrantFingerprint = current?.credential?.refreshToken === cred.refreshToken
      ? current.refreshGrantFingerprint ?? refreshGrantFingerprintForToken(cred.refreshToken)
      : refreshGrantFingerprintForToken(cred.refreshToken);
    store[id] = {
      credential: cred,
      generation: (current?.generation ?? 0) + 1,
      refreshGrantFingerprint,
      replacedAt: current ? Date.now() : undefined,
      quotaHistoryIdentity: crypto.randomUUID(),
      ...preservedValidationMetadata(current),
      ...(options.validationPending ? {
        codexValidationPending: true,
        lastCodexValidatedAt: undefined,
        lastCodexValidationStatus: undefined,
        lastCodexValidationError: undefined,
      } : {}),
    };
    persistCredentialMutation(store);
    return store[id].generation;
  });
}

export function markCodexAccountValidated(id: string, atMs: number = Date.now(), generation?: number): void {
  withCredentialMutationLockSync(() => {
    const store = loadCodexAccountRecordStore();
    const current = store[id];
    if (!current || current.deletedAt != null || !current.credential) return;
    if (current.codexValidationPending && generation === undefined) return;
    if (generation !== undefined && current.generation !== generation) return;
    store[id] = {
      ...current,
      lastCodexValidatedAt: atMs,
      lastCodexValidationStatus: "ok",
      lastCodexValidationError: undefined,
      codexValidationPending: undefined,
      // A completed validation is the direct refutation of a terminal verdict, and this
      // spread would otherwise carry the old marker forward.
      lastCodexValidationTerminal: undefined,
    };
    // Becoming routable invalidates credential-derived caches; a timestamp-only
    // update on an already validated account preserves the existing epoch policy.
    if (current.codexValidationPending) persistCredentialMutation(store);
    else persist(store);
  });
}

export interface MarkCodexAccountValidationFailedOptions {
  /**
   * Write only while the stored record is still at this generation.
   *
   * A validation attempt is not atomic with the store: an operator can re-authenticate the
   * account, or another writer can commit a refresh, while a probe is still in flight. Without
   * this fence the late failure lands on whatever credential happens to be there and brands a
   * freshly installed one dead. Declining to write is the safe direction — the failure cannot be
   * attributed to a credential the caller never observed.
   */
  expectedGeneration?: number;
  /** The grant itself is revoked or expired; only a re-login clears it. */
  terminal?: boolean;
}

/** Returns whether the verdict was actually persisted (false when the fence declined it). */
export function markCodexAccountValidationFailed(
  id: string,
  reason: string,
  options: MarkCodexAccountValidationFailedOptions = {},
): boolean {
  return withCredentialMutationLockSync(() => {
    const store = loadCodexAccountRecordStore();
    const current = store[id];
    if (!current || current.deletedAt != null || !current.credential) return false;
    // Deferred validation is settled only by a caller that names the generation it observed.
    // An unfenced write must never resolve a pending account, whichever verdict it carries.
    if (current.codexValidationPending && options.expectedGeneration === undefined) return false;
    if (options.expectedGeneration !== undefined && current.generation !== options.expectedGeneration) {
      return false;
    }
    store[id] = {
      ...current,
      lastCodexValidationStatus: "failed",
      lastCodexValidationError: reason,
      // Only ever set here. A transient failure must not clear a terminal marker set earlier,
      // and it must not invent one either, so the flag is written only when the caller proves
      // the grant is dead.
      ...(options.terminal ? { lastCodexValidationTerminal: true } : {}),
    };
    persist(store);
    return true;
  });
}

export function removeCodexAccountCredential(id: string): void {
  tombstoneCodexAccount(id);
}

export function listCodexAccountIds(): string[] {
  return Object.keys(loadCodexAccountStore());
}

export function readCodexAccountRecord(id: string): CodexAccountCredentialRecord | null {
  return loadCodexAccountRecordStore()[id] ?? null;
}

/**
 * One store load, every record, for a caller that resolves MANY ids in a single synchronous pass.
 *
 * `readCodexAccountRecord` reloads, reparses and renormalizes the whole file per id. That is the
 * right shape for one lookup and the wrong shape for a loop: the entitlement denial reader holds
 * up to 64 accounts with four client versions each, so scoring one warm flagship request could
 * perform up to 256 full-store reads on the request path.
 *
 * These are the same normalized records `readCodexAccountRecord` hands out, tombstones included,
 * so the caller keeps its own `deletedAt` and `generation` checks instead of trusting a filtered
 * view. That is the difference from `loadCodexAccountStore`, which drops both and cannot answer a
 * question about credential generation.
 */
export function loadCodexAccountRecordSnapshot(): Readonly<Record<string, CodexAccountCredentialRecord>> {
  return loadCodexAccountRecordStore();
}

const QUOTA_HISTORY_IDENTITY_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;

function validQuotaHistoryIdentity(value: unknown): value is string {
  return typeof value === "string" && QUOTA_HISTORY_IDENTITY_RE.test(value);
}

type DispatchedPoolCredential = Pick<CodexAccountCredentials, "accessToken" | "chatgptAccountId"> & { generation: number };

function matchesDispatchedPoolCredential(record: CodexAccountCredentialRecord | undefined | null, dispatched: DispatchedPoolCredential): record is CodexAccountCredentialRecord & { credential: CodexAccountCredentials } {
  return !!record?.credential && record.deletedAt == null
    && dispatched.accessToken.length > 0 && dispatched.chatgptAccountId.length > 0
    && Number.isSafeInteger(dispatched.generation) && dispatched.generation >= 0
    && record.generation === dispatched.generation
    && record.credential.accessToken === dispatched.accessToken
    && record.credential.chatgptAccountId === dispatched.chatgptAccountId;
}

/** Optional evidence capture; a stale credential or unavailable store never gains a new writer. */
export function capturePoolQuotaWriter(accountId: string, dispatched: DispatchedPoolCredential): PoolQuotaWriter | undefined {
  if (!isValidCodexAccountId(accountId)) return undefined;
  try {
    const current = readCodexAccountRecord(accountId);
    if (!matchesDispatchedPoolCredential(current, dispatched)) return undefined;
    if (validQuotaHistoryIdentity(current.quotaHistoryIdentity)) {
      return { accountId, credentialGeneration: dispatched.generation, historyIdentity: current.quotaHistoryIdentity };
    }
    return withCredentialMutationLockSync(() => {
      const store = loadCodexAccountRecordStore();
      const locked = store[accountId];
      if (!matchesDispatchedPoolCredential(locked, dispatched)) return undefined;
      if (!validQuotaHistoryIdentity(locked.quotaHistoryIdentity)) {
        locked.quotaHistoryIdentity = crypto.randomUUID();
        // Identity metadata is not a new credential; preserve generation and mutation epoch.
        persist(store);
      }
      return { accountId, credentialGeneration: dispatched.generation, historyIdentity: locked.quotaHistoryIdentity };
    });
  } catch {
    // History is optional evidence. Permission, lock and disk errors cannot fail inference.
    return undefined;
  }
}

/** Read-only retention identity; unlike capture this never initializes legacy metadata. */
export function poolQuotaHistoryIdentity(accountId: string): string | undefined {
  if (!isValidCodexAccountId(accountId)) return undefined;
  try {
    return poolQuotaHistoryIdentityOf(readCodexAccountRecord(accountId));
  } catch {
    return undefined;
  }
}

/** {@link poolQuotaHistoryIdentity} for a record the caller already loaded, e.g. from one snapshot. */
export function poolQuotaHistoryIdentityOf(record: CodexAccountCredentialRecord | null | undefined): string | undefined {
  return record?.credential && record.deletedAt == null && validQuotaHistoryIdentity(record.quotaHistoryIdentity)
    ? record.quotaHistoryIdentity : undefined;
}

/** One id out of {@link loadCodexAccountRecordSnapshot}; an invalid id or an inherited key is no record. */
export function codexAccountRecordFromSnapshot(records: Readonly<Record<string, CodexAccountCredentialRecord>>, accountId: string): CodexAccountCredentialRecord | null {
  return isValidCodexAccountId(accountId) && Object.hasOwn(records, accountId) ? records[accountId]! : null;
}

/** Recheck append admission after upstream I/O; refresh may retire a writer without erasing history. */
export function isPoolQuotaWriterLive(writer: PoolQuotaWriter): boolean {
  if (!isValidCodexAccountId(writer.accountId)) return false;
  try {
    const record = readCodexAccountRecord(writer.accountId);
    return !!record?.credential && record.deletedAt == null
      && record.generation === writer.credentialGeneration
      && validQuotaHistoryIdentity(writer.historyIdentity)
      && record.quotaHistoryIdentity === writer.historyIdentity;
  } catch {
    return false;
  }
}

export function isCodexAccountGenerationLive(id: string, generation: number): boolean {
  const record = readCodexAccountRecord(id);
  return !!record?.credential && record.deletedAt == null && record.generation === generation;
}

/** Callable for existing liveness consumers; stateful consumers can distinguish unknown snapshots. */
export type CodexAccountGenerationLiveCheck = ((id: string, generation: number) => boolean)
  & { readonly snapshotStatus: "ok" | "failed" };

/**
 * 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(): CodexAccountGenerationLiveCheck {
  let result: CodexAccountRecordStoreResult;
  try { result = loadCodexAccountRecordStoreResult(); }
  catch { result = { status: "failed" }; }
  const snapshot = result.status === "ok" ? result.records : {};
  return Object.assign((id: string, generation: number) => {
    const record = snapshot[id];
    return !!record?.credential && record.deletedAt == null && record.generation === generation;
  }, { snapshotStatus: result.status });
}

export function saveCodexAccountCredentialIfGeneration(
  id: string,
  generation: number,
  cred: CodexAccountCredentials,
): boolean {
  return withCredentialMutationLockSync(() => {
    const store = loadCodexAccountRecordStore();
    const current = store[id];
    if (!current || current.generation !== generation || current.deletedAt != null || !current.credential) {
      return false;
    }
    const refreshGrantFingerprint = current.credential.refreshToken === cred.refreshToken
      ? current.refreshGrantFingerprint ?? refreshGrantFingerprintForToken(cred.refreshToken)
      : refreshGrantFingerprintForToken(cred.refreshToken);
    store[id] = {
      credential: cred,
      generation: generation + 1,
      refreshGrantFingerprint,
      replacedAt: current.replacedAt,
      quotaHistoryIdentity: current.credential.chatgptAccountId === cred.chatgptAccountId
        ? current.quotaHistoryIdentity : crypto.randomUUID(),
      ...preservedValidationMetadata(current),
    };
    persistCredentialMutation(store);
    return true;
  });
}

/**
 * Commit a refreshed credential to its owner AND to any record that is provably an untouched
 * duplicate of the pre-refresh credential (#2892 gap 3).
 *
 * A refresh normally rotates the refresh token, and the owner CAS above changes only the owner's
 * record. A second non-deleted record holding the same grant that is not participating in the
 * flight therefore keeps a refresh token upstream has just rotated away. Its next refresh sends a
 * dead grant, and `invalid_grant` classifies as `revoked` — retiring a healthy account because we
 * rotated its grant and never told it.
 *
 * Eligibility is deliberately narrow, and each condition earns its place:
 *
 * - Same pre-refresh grant fingerprint, access token, AND expiry. Anything else means the alias was
 *   updated concurrently, and repairing only its grant while keeping its own access token would
 *   advance a generation without advancing the access-token JWT. `plan-from-token` reads a higher
 *   generation as proof of a newer JWT (that is how JWT plan claims supersede a WHAM observation),
 *   so that combination lets a stale JWT overwrite an authoritative plan. It would also hand a live
 *   forced-refresh joiner back its own 401-rejected bearer: flights are keyed by grant and do not
 *   record participants, so a scan cannot tell a dormant alias from a joiner, and the recursion's
 *   freshness shortcut does not re-compare against the rejected token.
 * - Same `chatgptAccountId` as the owner. A fingerprint is `sha256` of the refresh token and
 *   carries no identity claim; no invariant here guarantees one grant cannot span two account ids,
 *   so identity is compared rather than assumed.
 *
 * The rotated access token, refresh token, and expiry move together, keeping a generation bump
 * meaning what every fence already assumes. `replacedAt` and the validation metadata survive
 * because the probe-lease settlement check accepts only an intact `G → G+1` lineage.
 *
 * One lock acquisition and one `persist` for the owner and every alias: `persist` writes the whole
 * store, so a second pass would open a window in which some records hold the dead grant.
 */
export function commitRefreshedCodexCredentialWithAliases(
  id: string,
  generation: number,
  cred: CodexAccountCredentials,
): { committed: boolean; propagatedAliases: { id: string; generation: number }[] } {
  return withCredentialMutationLockSync(() => {
    const store = loadCodexAccountRecordStore();
    const current = store[id];
    if (!current || current.generation !== generation || current.deletedAt != null || !current.credential || current.credential.sourceAuthPath) {
      return { committed: false, propagatedAliases: [] };
    }
    const priorCredential = current.credential;
    const priorFingerprint = recordGrantFingerprint(current);
    const refreshGrantFingerprint = priorCredential.refreshToken === cred.refreshToken
      ? current.refreshGrantFingerprint ?? refreshGrantFingerprintForToken(cred.refreshToken)
      : refreshGrantFingerprintForToken(cred.refreshToken);
    store[id] = {
      credential: cred,
      generation: generation + 1,
      refreshGrantFingerprint,
      replacedAt: current.replacedAt,
      quotaHistoryIdentity: current.credential.chatgptAccountId === cred.chatgptAccountId
        ? current.quotaHistoryIdentity : crypto.randomUUID(),
      ...preservedValidationMetadata(current),
    };

    // Each alias carries its OWN committed generation: aliases need not share one, and the plan
    // reconciliation below is generation-fenced, so an id alone would be reconciled at the wrong fence.
    const propagatedAliases: { id: string; generation: number }[] = [];
    // Nothing to propagate when the grant did not actually rotate: the aliases already hold it.
    // An absent owner identity fails closed: two empty strings compare equal but prove nothing about
    // which upstream account either record was meant to use, and a matching bearer snapshot only
    // shows they copied the same token once. Leave those dormant records alone.
    if (
      priorFingerprint !== undefined
      && priorCredential.refreshToken !== cred.refreshToken
      && !!priorCredential.chatgptAccountId
      && priorCredential.chatgptAccountId === cred.chatgptAccountId
    ) {
      for (const [aliasId, alias] of Object.entries(store)) {
        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;
        if (!alias.credential.chatgptAccountId) continue;
        if (alias.credential.chatgptAccountId !== priorCredential.chatgptAccountId) continue;
        const aliasGeneration = alias.generation + 1;
        store[aliasId] = {
          // The alias keeps its OWN chatgptAccountId value, which the guard above proved equal.
          credential: { ...cred, chatgptAccountId: alias.credential.chatgptAccountId },
          generation: aliasGeneration,
          refreshGrantFingerprint,
          replacedAt: alias.replacedAt,
          quotaHistoryIdentity: alias.quotaHistoryIdentity,
          ...preservedValidationMetadata(alias),
        };
        propagatedAliases.push({ id: aliasId, generation: aliasGeneration });
      }
    }
    persistCredentialMutation(store);
    return { committed: true, propagatedAliases };
  });
}

export function tombstoneCodexAccount(id: string): number {
  return withCredentialMutationLockSync(() => {
    const store = loadCodexAccountRecordStore();
    const current = store[id];
    const generation = (current?.generation ?? 0) + 1;
    store[id] = { generation, deletedAt: Date.now() };
    persistCredentialMutation(store);
    return generation;
  });
}

const CHATGPT_TOKEN_URL = "https://auth.openai.com/oauth/token";
const CHATGPT_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";

export class TokenRefreshError extends Error {
  reason: "expired" | "revoked" | "unknown";
  constructor(reason: "expired" | "revoked" | "unknown", message: string,
    readonly status?: number, readonly code?: ChatgptRefreshDiagnosticCode) {
    super(message);
    this.name = "TokenRefreshError";
    this.reason = reason;
  }
}

/**
 * The stored record or its refresh-grant fingerprint is gone. Retrying cannot
 * conjure a missing credential, so callers must treat this as terminal.
 */
export class CodexCredentialUnavailableError extends Error {
  constructor(message = "Codex account credential is unavailable; reauthenticate the account.") {
    super(message);
    this.name = "CodexCredentialUnavailableError";
  }
}

export class CodexCredentialGenerationConflictError extends Error {
  constructor(message = "Codex account changed during refresh") {
    super(message);
    this.name = "CodexCredentialGenerationConflictError";
  }
}

export class CodexCredentialRefreshLockTimeoutError extends Error {
  constructor(message = "Timed out waiting for Codex account refresh lock") {
    super(message);
    this.name = "CodexCredentialRefreshLockTimeoutError";
  }
}

export class CodexCredentialRefreshBusyError extends Error {
  readonly code = "CODEX_REFRESH_BUSY";
  readonly retryable = true;

  constructor() {
    super("Codex credential refresh capacity reached");
    this.name = "CodexCredentialRefreshBusyError";
  }
}

export class CodexCredentialRefreshStaleError extends Error {
  readonly code = "CODEX_REFRESH_STALE";
  readonly retryable = true;

  constructor() {
    super("Codex credential refresh owner became stale");
    this.name = "CodexCredentialRefreshStaleError";
  }
}

/**
 * Terminal means the grant itself is dead, or there is no grant to refresh.
 * Token-endpoint 5xx (`unknown`) and a generation CAS loss stay transient
 * because those genuinely may clear (#2887).
 */
export function isTerminalCodexPoolRefreshFailure(error: unknown): boolean {
  return (error instanceof TokenRefreshError && (error.reason === "revoked" || error.reason === "expired"))
    || error instanceof CodexCredentialUnavailableError;
}

function isOperationalCodexPoolRefreshFailure(error: unknown): boolean {
  if (error instanceof CodexPoolRefreshCooldownError) return true;
  if (error instanceof CodexCredentialRefreshBusyError) return true;
  if (error instanceof CodexCredentialRefreshStaleError) return true;
  if (error instanceof CodexCredentialRefreshLockTimeoutError) return true;
  return error instanceof Error && (error.name === "AbortError" || error.name === "TimeoutError");
}

function classifyCodexPoolRefreshFailureReason(error: unknown): string {
  if (error instanceof TokenRefreshError) return error.reason;
  if (error instanceof CodexCredentialGenerationConflictError) return "generation_conflict";
  return "network";
}

/** Credential writers share the config mutation coordinator; contention is transient, not reauth. */
function withCredentialMutationLockSync<T>(fn: () => T): T {
  try {
    return withConfigMutationLockSync(fn);
  } catch (error) {
    if (error instanceof ConfigMutationLockError) throw new CodexCredentialRefreshLockTimeoutError();
    throw error;
  }
}

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;
  /**
   * Records that adopted this refresh's rotated credential through same-grant propagation, each
   * with its own committed generation (#2892 gap 3). Carried on the result so the flight settles
   * every plan in one place rather than the commit doing its own (#2933).
   */
  propagatedAliases?: { id: string; generation: number }[];
  /**
   * Grant the returned credential actually belongs to.
   *
   * Flights are keyed by refresh grant and shared across every account holding that
   * grant, but a flight can resolve to a credential from a DIFFERENT grant: the
   * owner's credential may be externally replaced while it waits for the file lock,
   * and the grant-mismatch branch then hands back that replacement. A joiner that
   * only checks its own current grant would CAS-write another account's access and
   * refresh tokens onto itself. The result therefore carries its own provenance.
   */
  resolvedGrantFingerprint?: string;
  /**
   * True when this call's own CAS write produced `generation` — the credential is a
   * 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;
      /** 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;
interface RefreshFlight {
  promise: Promise<CodexRefreshResult>;
  startedAt: number;
  abort: AbortController;
}
const refreshLocks = new Map<string, RefreshFlight>();

function codexRefreshLockPath(lockKey: string): string {
  const digest = createHash("sha256").update(lockKey).digest("hex").slice(0, 32);
  return join(getConfigDir(), `codex-refresh-${digest}.lock`);
}

function sleep(ms: number, signal?: AbortSignal): Promise<void> {
  if (!signal) return new Promise(resolve => setTimeout(resolve, ms));
  if (signal.aborted) return Promise.reject(signal.reason);
  return new Promise((resolve, reject) => {
    const timer = setTimeout(() => {
      signal.removeEventListener("abort", onAbort);
      resolve();
    }, ms);
    const onAbort = () => {
      clearTimeout(timer);
      reject(signal.reason);
    };
    signal.addEventListener("abort", onAbort, { once: true });
  });
}

function errCode(err: unknown): string | undefined {
  return err && typeof err === "object" && "code" in err ? String((err as { code?: unknown }).code) : undefined;
}

function isRefreshLockStale(path: string): boolean {
  try {
    hardenExistingSecret(path);
    const parsed = JSON.parse(readFileSync(path, "utf-8")) as { acquiredAt?: unknown };
    return typeof parsed.acquiredAt !== "number" || Date.now() - parsed.acquiredAt > REFRESH_LOCK_STALE_MS;
  } catch {
    // The owner creates the file and writes its metadata in two steps, so a live lock is
    // briefly unreadable. Age the file itself instead of calling that window stale, which
    // let a waiter delete a lock whose owner was still inside its critical section.
    try {
      return Date.now() - statSync(path).mtimeMs > REFRESH_LOCK_STALE_MS;
    } catch {
      return false;
    }
  }
}

function releaseCodexRefreshFileLock(path: string, fd: number): void {
  let owned: { dev: bigint; ino: bigint } | null = null;
  try {
    const info = fstatSync(fd, { bigint: true });
    if (info.dev >= 0n && info.ino > 0n) owned = { dev: info.dev, ino: info.ino };
  } catch { /* Unknown descriptor identity never authorizes unlink. */ }
  try {
    withConfigMutationLockSync(() => {
      let current: { dev: bigint; ino: bigint } | null = null;
      try {
        const info = statSync(path, { bigint: true });
        if (info.dev >= 0n && info.ino > 0n) current = { dev: info.dev, ino: info.ino };
      } catch { /* Keep the lock and the callback outcome when the path probe fails. */ }
      if (owned && current && current.dev === owned.dev && current.ino === owned.ino) {
        try { unlinkSync(path); } catch (err) {
          if (errCode(err) !== "ENOENT") throw err;
        }
      }
    });
  } catch (err) {
    // Keep the descriptor alive through comparison/unlink so its inode cannot be recycled.
    // Unavailable coordination leaves the path without masking the completed refresh.
    if (!(err instanceof ConfigMutationLockError)) throw err;
  } finally { closeSync(fd); }
}

export async function withCodexRefreshFileLock<T>(lockKey: string, signal: AbortSignal, fn: () => Promise<T>): Promise<T> {
  hardenConfigDir();
  const dir = getConfigDir();
  if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });

  const path = codexRefreshLockPath(lockKey);
  const deadline = Date.now() + REFRESH_LOCK_WAIT_MS;
  let fd: number | null = null;
  while (fd == null) {
    if (signal.aborted) throw signal.reason;
    try {
      // Serialize only metadata operations, never the async refresh callback. Cooperating
      // contenders cannot reclaim a successor between stale observation and path mutation.
      withConfigMutationLockSync(() => {
        try {
          fd = openSync(path, "wx", 0o600);
          writeFileSync(fd, JSON.stringify({ acquiredAt: Date.now(), pid: process.pid }) + "\n");
        } catch (err) {
          if (fd != null) {
            const failedFd = fd;
            fd = null;
            try { releaseCodexRefreshFileLock(path, failedFd); } catch { /* Preserve write failure. */ }
            throw err;
          }
          if (errCode(err) !== "EEXIST") throw err;
          if (isRefreshLockStale(path)) {
            try { unlinkSync(path); } catch (unlinkErr) {
              if (errCode(unlinkErr) !== "ENOENT") throw unlinkErr;
            }
          }
        }
      });
    } catch (err) {
      // A failed SQLite commit can follow successful file creation; it still owns an fd.
      if (fd != null) {
        const failedFd = fd;
        fd = null;
        try { releaseCodexRefreshFileLock(path, failedFd); } catch { /* Preserve admission failure. */ }
      }
      if (!(err instanceof ConfigMutationLockError)) throw err;
    }
    if (fd != null) break;
    if (Date.now() >= deadline) throw new CodexCredentialRefreshLockTimeoutError();
    await sleep(REFRESH_LOCK_POLL_MS, signal);
  }

  try {
    return await fn();
  } finally {
    releaseCodexRefreshFileLock(path, fd);
  }
}

function findFreshCredentialForGrant(
  refreshGrantFingerprint: string,
  excludeId: string,
  rejectedAccessToken?: string,
  expectedChatgptAccountId?: string,
): CodexAccountCredentials | null {
  const now = Date.now();
  const records = loadCodexAccountRecordStore();
  // Adoption copies another record's access AND refresh tokens onto the caller, so the two records
  // must be the same upstream identity. A grant fingerprint is `sha256` of the refresh token and
  // carries no identity claim, and nothing here guarantees one grant cannot span two accounts, so
  // 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 || candidate.credential.sourceAuthPath) continue;
    if (recordGrantFingerprint(candidate) !== refreshGrantFingerprint) continue;
    if (!candidate.credential.chatgptAccountId) continue;
    if (candidate.credential.chatgptAccountId !== expectedChatgptAccountId) continue;
    // A sibling alias can hold a still-unexpired copy of the exact token upstream
    // just rejected. Reusing it would bump the generation and replay the identical
    // bearer — a second 401 dressed up as recovery.
    if (rejectedAccessToken !== undefined && candidate.credential.accessToken === rejectedAccessToken) continue;
    if (candidate.credential.expiresAt > now + REFRESH_SKEW_MS) return candidate.credential;
  }
  return null;
}

async function notePlanFromRefreshedAccessToken(
  id: string,
  accessToken: string,
  generation: number,
): Promise<void> {
  try {
    const { noteCodexAccountAccessToken } = await import("./plan-from-token");
    noteCodexAccountAccessToken(id, accessToken, generation);
  } catch {
    // Derived plan metadata must not fail credential refresh.
  }
}

/**
 * A forced refresh raised by a rejected bearer. Carries the generation the 401 was
 * observed under so a credential someone else already replaced is never refreshed
 * again, and the rejected token so a sibling alias holding that same token cannot
 * satisfy the refresh.
 */
type ForcedRefreshFence = { rejectedGeneration: number; rejectedAccessToken: string };

/** True once the stored credential has moved off the generation the 401 belongs to. */
function forcedFenceSuperseded(recordGeneration: number, forced: ForcedRefreshFence | undefined): boolean {
  return forced !== undefined && recordGeneration !== forced.rejectedGeneration;
}

/**
 * Wait for a SHARED promise while honoring only the calling request's cancellation.
 *
 * The awaited work is not the caller's to cancel — other requests are waiting on the
 * same promise — so an aborted caller stops waiting and the work continues to
 * completion for them (#2892 gap 2). The rejection handler prevents an unhandled
 * rejection from the promise this caller walked away from.
 */
function awaitOwnCancellation<T>(work: Promise<T>, callerSignal?: AbortSignal): Promise<T> {
  if (!callerSignal) return work;
  if (callerSignal.aborted) {
    work.catch(() => {});
    return Promise.reject(callerSignal.reason);
  }
  return new Promise<T>((resolve, reject) => {
    const onAbort = (): void => {
      work.catch(() => {});
      reject(callerSignal.reason);
    };
    callerSignal.addEventListener("abort", onAbort, { once: true });
    work.then(
      value => { callerSignal.removeEventListener("abort", onAbort); resolve(value); },
      err => { callerSignal.removeEventListener("abort", onAbort); reject(err); },
    );
  });
}

/**
 * Refresh a stored pool credential that upstream rejected with a 401, even though its
 * `expiresAt` still looks valid. Ordinary callers must keep using
 * {@link getValidCodexToken}: only a proven rejection justifies spending a refresh.
 *
 * `rotated` is false when the resolved token is byte-identical to the rejected one,
 * which means replaying would earn the same 401 and the caller must not try. That can
 * happen even on a SUCCESSFUL token response: upstream may rotate the refresh grant
 * while returning the same access token. The generation has moved by then, so
 * `generation` reports where the credential actually is — a caller that quarantines
 * on `rotated === false` must fence on the returned value, not on the one it rejected.
 */
export async function forceRefreshCodexPoolToken(
  id: string,
  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;
  }
  if (isCodexPoolRefreshCooling(id)) {
    const error = new CodexPoolRefreshCooldownError();
    settle({ kind: "failed", error });
    throw error;
  }
  const completion = resolveCodexToken(
    id,
    { rejectedGeneration: options.rejectedGeneration, rejectedAccessToken: options.rejectedAccessToken },
    // Deliberately no caller signal: the flight is shared and this settlement speaks for
    // the credential, not for whoever happened to be waiting.
    undefined,
  );
  // Captured before the flight settles, spent only if it fails. A reauthentication that lands
  // while this is in the air replaces the grant and clears its failures; this fence is how the
  // late failure knows it is talking about a credential that no longer exists.
  const refreshFence = codexPoolRefreshFence(id);
  completion.then(
    resolved => {
      clearCodexPoolRefreshFailure(id);
      settle({
        kind: "resolved",
        provenance: classify(resolved),
        generation: resolved.generation,
        rotated: resolved.accessToken !== options.rejectedAccessToken,
        ...(resolved.propagatedAliases?.length
          ? { propagatedAliases: resolved.propagatedAliases }
          : {}),
      });
    },
    error => {
      if (isTerminalCodexPoolRefreshFailure(error) || isOperationalCodexPoolRefreshFailure(error)) {
        if (isTerminalCodexPoolRefreshFailure(error)) clearCodexPoolRefreshFailure(id);
      } else {
        noteCodexPoolRefreshFailure(id, classifyCodexPoolRefreshFailureReason(error), undefined, refreshFence, poolAccountLogLabel);
      }
      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,
    // 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: provenance === "self-refresh",
    provenance,
  };
}

export async function getValidCodexToken(
  id: string,
  options: { signal?: AbortSignal } = {},
): Promise<CodexTokenResult> {
  // Cancellation ends THIS caller's wait. A shared refresh already in flight keeps running for
  // whoever else awaits it, which is what `awaitOwnCancellation` inside the resolver preserves.
  const result = await resolveCodexToken(id, undefined, options.signal);
  return {
    accessToken: result.accessToken,
    chatgptAccountId: result.chatgptAccountId,
    generation: result.generation,
  };
}

/** 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,
  callerSignal?: AbortSignal,
): Promise<CodexRefreshResult> {
  if (callerSignal?.aborted) throw callerSignal.reason;
  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();

  // The freshness shortcut is exactly what makes a 401 on a time-valid token
  // unrecoverable, so a forced caller skips it — but only while the stored credential
  // is still the one that was rejected. Once it has been replaced, the shortcut is
  // 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) {
    // 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);
  if (existing) {
    if (Date.now() - existing.startedAt > CODEX_REFRESH_FLIGHT_STALE_MS) {
      existing.abort.abort(new CodexCredentialRefreshStaleError());
      if (refreshLocks.get(refreshGrantFingerprint) === existing) refreshLocks.delete(refreshGrantFingerprint);
    } else {
      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
      // affinity handoff the owner performed against generation+1.
      if (current && currentCred && refreshed.credential
        && currentCred.accessToken === refreshed.credential.accessToken
        && currentCred.refreshToken === refreshed.credential.refreshToken) {
        // A forced caller must still not accept the bearer upstream rejected.
        if (!(forced !== undefined && currentCred.accessToken === forced.rejectedAccessToken)) {
          return {
            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",
          };
        }
      }
      // Flights are keyed by refresh grant, not by account or generation, so this
      // credential may belong to a flight started for a different generation of the
      // same grant. Writing it onto a replacement would undo that replacement.
      //
      // The rejected-token test comes FIRST: a joined flight that resolved back to the
      // bearer upstream rejected proves nothing, and reporting the replacement as
      // "superseded" would hand the caller a token it must not replay.
      //
      // Freshness is tested here too. Supersession says only that SOMEONE replaced the
      // credential — not that what they wrote is usable. An expired G+1 satisfies the
      // generation test and the rejected-bearer test while being certain to earn
      // another 401, and because the caller treats this return as a successful
      // recovery it spends its one replay on it (#2892 gap 1). A stale winner must
      // fall through to a real refresh instead.
      //
      // Stated honestly: this guard is NOT covered by a red-proven test. Reaching this
      // branch needs a live flight that RESOLVES, a stored credential differing from
      // what the flight produced, and that stored credential expired — three attempted
      // interleavings each landed elsewhere (own flight, first adopt-stored branch, or
      // a CAS conflict that rejects for both callers). The guard is one comparison on a
      // path that otherwise returns a known-dead token, and its only effect is to
      // divert to the refresh the caller would have needed anyway.
      if (
        current && currentCred
        && forcedFenceSuperseded(current.generation, forced)
        && currentCred.expiresAt > Date.now() + REFRESH_SKEW_MS
        && !(forced !== undefined && currentCred.accessToken === forced.rejectedAccessToken)
      ) {
        return {
          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 (
        current &&
        currentCred &&
        refreshed.credential &&
        // Provenance: a flight can resolve to a credential from a DIFFERENT grant when
        // the owner's own credential was replaced while it waited for the lock. Adopting
        // that would copy another account's access and refresh tokens onto this one.
        refreshed.resolvedGrantFingerprint === refreshGrantFingerprint &&
        // A joined flight that resolved to the rejected token proves nothing; fall
        // through and open a real refresh instead of bumping the generation.
        !(forced !== undefined && refreshed.credential.accessToken === forced.rejectedAccessToken) &&
        recordGrantFingerprint(current) === refreshGrantFingerprint
      ) {
        if (!saveCodexAccountCredentialIfGeneration(id, current.generation, refreshed.credential)) {
          throw new CodexCredentialGenerationConflictError();
        }
        const generation = current.generation + 1;
        await notePlanFromRefreshedAccessToken(id, refreshed.credential.accessToken, generation);
        return {
          accessToken: refreshed.credential.accessToken,
          chatgptAccountId: refreshed.credential.chatgptAccountId,
          generation,
          // 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,
        };
      }
      return resolveCodexToken(id, forced, callerSignal);
    }
  }

  if (refreshLocks.size >= MAX_CODEX_REFRESH_FLIGHTS) throw new CodexCredentialRefreshBusyError();

  /*
   * The flight's lifetime belongs to the FLIGHT, not to whichever caller happened to
   * open it (#2892 gap 2).
   *
   * Flights are shared: later callers on the same grant join `existing.promise` rather
   * than starting their own. Folding `callerSignal` into the flight's signal therefore
   * gave one arbitrary waiter the power to abort the token request out from under every
   * other waiter — and the joiners have no way to distinguish that from a genuine
   * upstream failure, so a cancelled Codex tab could retire a healthy account for a
   * request that was still running.
   *
   * The initiating caller still gets cancellation: it is waiting on its own await, and
   * `awaitOwnCancellation` below races its wait against its own signal. What it no
   * longer gets is the ability to cancel work other callers depend on: the flight keeps
   * running for the joiners, and its result is still committed. `abort` (stale-flight
   * eviction) and the 30s ceiling remain, because those bound the flight itself.
   */
  const abort = new AbortController();
  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);
    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) {
      if (lockedCred.expiresAt > Date.now() + REFRESH_SKEW_MS) {
        return {
          accessToken: lockedCred.accessToken,
          chatgptAccountId: lockedCred.chatgptAccountId,
          generation: startGeneration,
          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 }
            : {}),
        };
      }
      throw new CodexCredentialGenerationConflictError();
    }
    // Third fence point: waiting for the lock can take long enough for another
    // writer to replace the credential. Under the lock the stored generation is
    // authoritative, so a superseded forced refresh stops here rather than
    // spending a rotation on a credential nobody rejected.
    const forcedStillTargetsStored = forced !== undefined && !forcedFenceSuperseded(startGeneration, forced);
    if (lockedCred.expiresAt > Date.now() + REFRESH_SKEW_MS && !forcedStillTargetsStored) {
      return {
        accessToken: lockedCred.accessToken,
        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,
      };
    }
    const sameGrantFreshCredential = findFreshCredentialForGrant(
      refreshGrantFingerprint,
      id,
      forced?.rejectedAccessToken,
      lockedCred.chatgptAccountId,
    );
    if (sameGrantFreshCredential) {
      if (!saveCodexAccountCredentialIfGeneration(id, startGeneration, sameGrantFreshCredential)) {
        throw new CodexCredentialGenerationConflictError();
      }
      return {
        accessToken: sameGrantFreshCredential.accessToken,
        chatgptAccountId: sameGrantFreshCredential.chatgptAccountId,
        generation: startGeneration + 1,
        credential: sameGrantFreshCredential,
        resolvedGrantFingerprint: refreshGrantFingerprint,
        selfRefreshed: true,
        provenance: "self-refresh",
      };
    }
    const res = await fetch(CHATGPT_TOKEN_URL, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Accept: "application/json",
      },
      body: JSON.stringify({
        client_id: CHATGPT_CLIENT_ID,
        grant_type: "refresh_token",
        refresh_token: lockedCred.refreshToken,
      }),
      signal,
    });
    if (!res.ok) {
      const body = await readBoundedResponseBody(res, { signal, maxBytes: 16_384, fatalUtf8: true })
        .catch(() => undefined);
      const failure = classifyChatgptRefreshFailure(res.status, body?.displaySafe ? body.text : "");
      const { reason } = failure;
      noteChatgptRefreshFailure("pool", res.status, failure, poolAccountLogLabel(id));
      throw new TokenRefreshError(reason, `Codex token refresh failed (${reason}); reauthenticate the account.`, res.status, failure.code);
    }
    const data = (await res.json()) as { access_token?: unknown; refresh_token?: string; expires_in?: unknown };
    if (!data || typeof data !== "object" || typeof data.access_token !== "string" || !data.access_token.trim()) {
      throw new Error("Codex token refresh response missing access_token");
    }
    // Guard against a missing/non-finite/negative expires_in (malformed upstream
    // response): a NaN expiry would never compare as expired, and a negative
    // duration would stamp an already-past expiry — both block refresh semantics.
    const expiresIn =
      typeof data.expires_in === "number" && Number.isFinite(data.expires_in) && data.expires_in >= 0
        ? data.expires_in
        : 3600;
    // The computed timestamp itself must stay finite: Number.MAX_VALUE passes
    // Number.isFinite but overflows to Infinity once multiplied by 1000.
    const expiresAt = Date.now() + expiresIn * 1000;
    const safeExpiresAt = Number.isFinite(expiresAt) ? expiresAt : Date.now() + 3600 * 1000;

    const updated: CodexAccountCredentials = {
      accessToken: data.access_token,
      refreshToken: data.refresh_token ?? lockedCred.refreshToken,
      expiresAt: safeExpiresAt,
      chatgptAccountId: lockedCred.chatgptAccountId,
    };
    // Commit to the owner and, in the same write, to any record that is still an untouched
    // duplicate of the credential this flight started from (#2892 gap 3). Without this the rotated
    // grant reaches only the owner and live joiners, and a dormant same-grant record is left
    // holding a refresh token upstream has invalidated.
    const commit = commitRefreshedCodexCredentialWithAliases(id, startGeneration, updated);
    if (!commit.committed) {
      throw new CodexCredentialGenerationConflictError();
    }
    if (commit.propagatedAliases.length > 0) {
      console.warn(`[codex-auth] rotated refresh grant propagated to ${commit.propagatedAliases.length} dormant same-grant account record(s)`);
    }
    return {
      accessToken: updated.accessToken,
      chatgptAccountId: updated.chatgptAccountId,
      generation: startGeneration + 1,
      credential: updated,
      // Aliases that adopted this rotated credential travel on the result so the FLIGHT settles
      // their plans in the same single place as the owner's (#2933). Each carries its own committed
      // generation because the plan note is generation-fenced.
      ...(commit.propagatedAliases.length > 0 ? { propagatedAliases: commit.propagatedAliases } : {}),
      // The grant this flight was OPENED for, not the rotated one it produced. Joiners
      // are waiting on that key, and a successful refresh normally rotates the refresh
      // token — tagging the new grant would make every legitimate joiner look foreign.
      resolvedGrantFingerprint: refreshGrantFingerprint,
      selfRefreshed: true,
      provenance: "self-refresh",
    };
  });
  /*
   * Plan reconciliation belongs to the FLIGHT, not to whichever caller opened it.
   *
   * The flight outlives its initiating caller by design (gap 2): an aborted owner stops
   * waiting while the shared work still runs and still commits the rotated credential.
   * Reconciling the plan only after the owner's caller-scoped wait therefore dropped it
   * whenever that owner walked away, and a same-account joiner returning through the
   * adopt-stored branch does not reconcile either — so a changed `chatgpt_plan_type`
   * stayed invisible in `codexAccounts[].plan` for the life of the process and skewed
   * plan-selected quota projection. Attaching it to the flight runs it exactly once per
   * 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
    // `chatgpt_plan_type` applies to it too, and its cached-token fast path would never reconcile it.
    for (const alias of result.propagatedAliases ?? []) {
      await notePlanFromRefreshedAccessToken(alias.id, result.accessToken, alias.generation);
    }
    return result;
  }).finally(() => {
    if (refreshLocks.get(refreshGrantFingerprint) === flight) refreshLocks.delete(refreshGrantFingerprint);
  });

  flight = { promise: refreshPromise, startedAt: Date.now(), abort };
  refreshLocks.set(refreshGrantFingerprint, flight);
  // The owner waits under its own cancellation too: the flight it opened is already
  // registered, so a joiner that arrives after this caller walks away still receives
  // the committed result.
  const result = await awaitOwnCancellation(refreshPromise, callerSignal);
  return {
    accessToken: result.accessToken,
    chatgptAccountId: result.chatgptAccountId,
    generation: result.generation,
    // Carry the flight's provenance out to the caller: the owner is the one whose CAS
    // 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.propagatedAliases?.length ? { propagatedAliases: result.propagatedAliases } : {}),
    ...(result.resolvedGrantFingerprint !== undefined
      ? { resolvedGrantFingerprint: result.resolvedGrantFingerprint }
      : {}),
  };
}
