@bitkyc08/opencodex 2.35.0 → 2.36.0-preview.20260830

package/src/codex/account-store.ts

@@ -218,6 +218,97 @@ export function saveCodexAccountCredentialIfGeneration(
   });
 }
 
+/**
+ * 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) {
+      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,
+      ...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
+    ) {
+      for (const [aliasId, alias] of Object.entries(store)) {
+        if (aliasId === id || alias.deletedAt != null || !alias.credential) 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,
+          ...preservedValidationMetadata(alias),
+        };
+        propagatedAliases.push({ id: aliasId, generation: aliasGeneration });
+      }
+    }
+    persist(store);
+    return { committed: true, propagatedAliases };
+  });
+}
+
 export function tombstoneCodexAccount(id: string): number {
   return withCredentialMutationLockSync(() => {
     const store = loadCodexAccountRecordStore();
@@ -286,7 +377,31 @@ function withCredentialMutationLockSync<T>(fn: () => T): T {
 }
 
 type CodexTokenResult = { accessToken: string; chatgptAccountId: string; generation: number };
-type CodexRefreshResult = CodexTokenResult & { credential?: CodexAccountCredentials };
+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;
+};
 const MAX_CODEX_REFRESH_FLIGHTS = 32;
 const CODEX_REFRESH_FLIGHT_STALE_MS = 120_000;
 interface RefreshFlight {
@@ -331,7 +446,7 @@ function isRefreshLockStale(path: string): boolean {
   }
 }
 
-async function withCodexRefreshFileLock<T>(lockKey: string, signal: AbortSignal, fn: () => Promise<T>): Promise<T> {
+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 });
@@ -375,12 +490,25 @@ async function withCodexRefreshFileLock<T>(lockKey: string, signal: AbortSignal,
 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) 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;
@@ -399,14 +527,106 @@ async function notePlanFromRefreshedAccessToken(
   }
 }
 
+/**
+ * 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 },
+): Promise<CodexTokenResult & { rotated: boolean; selfRefreshed: boolean }> {
+  const result = await resolveCodexToken(
+    id,
+    { rejectedGeneration: options.rejectedGeneration, rejectedAccessToken: options.rejectedAccessToken },
+    options.signal,
+  );
+  return {
+    accessToken: result.accessToken,
+    chatgptAccountId: result.chatgptAccountId,
+    generation: result.generation,
+    rotated: result.accessToken !== options.rejectedAccessToken,
+    // Only a CAS this call performed itself proves the new credential descends from the
+    // rejected one; anything else is somebody else's replacement and must not be treated
+    // as this request's own lineage.
+    selfRefreshed: result.selfRefreshed === true,
+  };
+}
+
 export async function getValidCodexToken(id: string): Promise<CodexTokenResult> {
+  const result = await resolveCodexToken(id);
+  return {
+    accessToken: result.accessToken,
+    chatgptAccountId: result.chatgptAccountId,
+    generation: result.generation,
+  };
+}
+
+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 Error("Codex account credential is unavailable; reauthenticate the account.");
   const refreshGrantFingerprint = recordGrantFingerprint(record);
   if (!refreshGrantFingerprint) throw new Error("Codex account credential is unavailable; reauthenticate the account.");
 
-  if (cred.expiresAt > Date.now() + REFRESH_SKEW_MS) {
+  // 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) {
     return { accessToken: cred.accessToken, chatgptAccountId: cred.chatgptAccountId, generation: record.generation };
   }
 
@@ -416,13 +636,70 @@ export async function getValidCodexToken(id: string): Promise<CodexTokenResult>
       existing.abort.abort(new CodexCredentialRefreshStaleError());
       if (refreshLocks.get(refreshGrantFingerprint) === existing) refreshLocks.delete(refreshGrantFingerprint);
     } else {
-      const refreshed = await existing.promise;
+      const refreshed = await awaitOwnCancellation(existing.promise, callerSignal);
       const current = readCodexAccountRecord(id);
       const currentCred = current?.deletedAt == null ? current?.credential : undefined;
+      // 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,
+          };
+        }
+      }
+      // 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,
+        };
+      }
       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)) {
@@ -434,18 +711,39 @@ export async function getValidCodexToken(id: string): Promise<CodexTokenResult>
           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,
+          resolvedGrantFingerprint: refreshGrantFingerprint,
         };
       }
-      return getValidCodexToken(id);
+      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(30_000)]);
   let flight!: RefreshFlight;
-  const refreshPromise = withCodexRefreshFileLock(refreshGrantFingerprint, signal, async (): Promise<CodexRefreshResult> => {
+  const fetchPromise = withCodexRefreshFileLock(refreshGrantFingerprint, signal, async (): Promise<CodexRefreshResult> => {
     const current = readCodexAccountRecord(id);
     const lockedRecord = readCodexAccountRecord(id);
     const lockedCred = lockedRecord?.deletedAt == null ? lockedRecord?.credential : undefined;
@@ -459,19 +757,35 @@ export async function getValidCodexToken(id: string): Promise<CodexTokenResult>
           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.
+          ...(lockedRefreshGrantFingerprint !== undefined
+            ? { resolvedGrantFingerprint: lockedRefreshGrantFingerprint }
+            : {}),
         };
       }
       throw new CodexCredentialGenerationConflictError();
     }
-    if (lockedCred.expiresAt > Date.now() + REFRESH_SKEW_MS) {
+    // 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,
+        resolvedGrantFingerprint: refreshGrantFingerprint,
       };
     }
-    const sameGrantFreshCredential = findFreshCredentialForGrant(refreshGrantFingerprint, id);
+    const sameGrantFreshCredential = findFreshCredentialForGrant(
+      refreshGrantFingerprint,
+      id,
+      forced?.rejectedAccessToken,
+      lockedCred.chatgptAccountId,
+    );
     if (sameGrantFreshCredential) {
       if (!saveCodexAccountCredentialIfGeneration(id, startGeneration, sameGrantFreshCredential)) {
         throw new CodexCredentialGenerationConflictError();
@@ -481,6 +795,8 @@ export async function getValidCodexToken(id: string): Promise<CodexTokenResult>
         chatgptAccountId: sameGrantFreshCredential.chatgptAccountId,
         generation: startGeneration + 1,
         credential: sameGrantFreshCredential,
+        resolvedGrantFingerprint: refreshGrantFingerprint,
+        selfRefreshed: true,
       };
     }
     const res = await fetch(CHATGPT_TOKEN_URL, {
@@ -496,11 +812,22 @@ export async function getValidCodexToken(id: string): Promise<CodexTokenResult>
     if (!res.ok) {
       const errText = await res.text().catch(() => "");
       let errDesc: string;
+      let errCodeExact: string | undefined;
       try {
         const parsed = JSON.parse(errText) as { error?: string; error_description?: string };
+        errCodeExact = typeof parsed.error === "string" ? parsed.error.trim() : undefined;
         errDesc = [parsed.error, parsed.error_description].filter(Boolean).join(": ") || `HTTP ${res.status}`;
       } catch { errDesc = `HTTP ${res.status}`; }
-      const reason = errDesc.includes("invalidated") || errDesc.includes("revoked") ? "revoked" as const
+      // `invalid_grant` is the standard OAuth code for a refresh token that is no longer
+      // usable, and upstream sends it bare with no description. Without it here the dead
+      // grant is classified "unknown", which callers treat as transient — so the account
+      // is never retired and every request repeats the same doomed refresh (#2887).
+      //
+      // Matched on the exact `error` CODE, not anywhere in the combined text: a transient
+      // `server_error` whose description happens to mention invalid_grant would otherwise
+      // retire a healthy account, which is the failure this whole change exists to remove.
+      const reason = errCodeExact === "invalid_grant"
+          || errDesc.includes("invalidated") || errDesc.includes("revoked") ? "revoked" as const
         : errDesc.includes("expired") ? "expired" as const
         : "unknown" as const;
       throw new TokenRefreshError(reason, `Codex token refresh failed (${reason}); reauthenticate the account.`);
@@ -524,21 +851,74 @@ export async function getValidCodexToken(id: string): Promise<CodexTokenResult>
       expiresAt: safeExpiresAt,
       chatgptAccountId: lockedCred.chatgptAccountId,
     };
-    if (!saveCodexAccountCredentialIfGeneration(id, startGeneration, updated)) {
+    // 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();
     }
-    return { accessToken: updated.accessToken, chatgptAccountId: updated.chatgptAccountId, generation: startGeneration + 1, credential: updated };
+    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,
+    };
+  });
+  /*
+   * 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> => {
+    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);
-  const result = await refreshPromise;
-  await notePlanFromRefreshedAccessToken(id, result.accessToken, result.generation);
+  // 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 } : {}),
+    ...(result.resolvedGrantFingerprint !== undefined
+      ? { resolvedGrantFingerprint: result.resolvedGrantFingerprint }
+      : {}),
   };
 }

package/src/codex/account-usability.ts

@@ -1,6 +1,11 @@
 import { getCodexAccountCredential } from "./account-store";
 import { isAccountNeedsReauth } from "./account-runtime-state";
-import { MAIN_CODEX_ACCOUNT_ID, isMainAccountTokenLive } from "./main-account";
+import {
+  MAIN_CODEX_ACCOUNT_ID,
+  hasMainAccountRefreshGrant,
+  isMainAccountCredentialUsable,
+  isMainAccountTokenLive,
+} from "./main-account";
 import { hasLegacyMainCodexPoolAccount, isSelectableCodexPoolAccount } from "./account-id";
 import type { OcxConfig } from "../types";
 import { isNativeMainTrafficBlocked } from "./native-profile-startup";
@@ -27,13 +32,15 @@ export function isCodexAccountUsable(
     // A legacy pool row with the sentinel makes an active `__main__` ambiguous.
     // Fail closed until the authenticated compatibility-delete path removes it.
     if (hasLegacyMainCodexPoolAccount(config.codexAccounts)) return false;
-    if (isAccountNeedsReauth(accountId)) return false;
+    if (isAccountNeedsReauth(accountId) && !hasMainAccountRefreshGrant()) return false;
     // A selection-only caller owns the recovery/drain fence and will reject main
     // before reservation or token materialization. Treat cached main as a routing
     // candidate without touching the credential file so affinity is not rebound.
     if (options.nativeMainSelectionOnly) return true;
-    // Main account: credential is the read-only ~/.codex/auth.json token (Option A).
-    return (options.isMainAccountTokenLive ?? isMainAccountTokenLive)();
+    // Main account: a refresh grant is enough to route; materialization refreshes before I/O.
+    return options.isMainAccountTokenLive
+      ? options.isMainAccountTokenLive()
+      : isMainAccountCredentialUsable();
   }
   const exists = (config.codexAccounts ?? [])
     .some(account => isSelectableCodexPoolAccount(account) && account.id === accountId);

package/src/codex/app-server-processes.ts

@@ -44,9 +44,14 @@ const CODEX_TARGET_TRIPLE_BODY = "[a-z0-9_]+-[a-z0-9_]+-[a-z0-9_]+(?:-[a-z0-9_]+
  * `"C:\Program Files\...\codex.exe" app-server` still reach GetOwner.
  * Also admits official target-triple basenames such as
  * `codex-x86_64-pc-windows-msvc.exe`.
+ *
+ * The optional `.opencodex-real` sits where `backupPathFor` actually puts it — after
+ * the stem and BEFORE the extension — and deliberately not before the triple. Written
+ * the other way it admits `codex.opencodex-real-x86_64-pc-windows-msvc.exe`, a name
+ * nothing produces, and pays GetOwner for it.
  */
 export const WINDOWS_CODEX_BASENAME_CANDIDATE_RE = new RegExp(
-  `(^|[/\\\\\\s'"=])codex(-${CODEX_TARGET_TRIPLE_BODY})?([.]exe|[.]cmd)?['"]?(\\s|$)`,
+  `(^|[/\\\\\\s'"=])codex(-${CODEX_TARGET_TRIPLE_BODY})?([.]opencodex-real)?([.]exe|[.]cmd|[.]ps1)?['"]?(\\s|$)`,
   "i",
 );
 
@@ -57,6 +62,38 @@ const CODEX_TARGET_TRIPLE_BASENAME_RE = new RegExp(
   `^codex-${CODEX_TARGET_TRIPLE_BODY}(?:\\.exe|\\.cmd)?$`,
 );
 
+/**
+ * Launcher basenames a Codex app-server can be started through, including the
+ * `.opencodex-real` backups the autostart shim creates.
+ *
+ * When the shim installs, `backupPathFor` (`src/codex/shim.ts`) renames the original
+ * launcher by inserting `.opencodex-real` before its extension, so a shimmed host runs
+ * `~/.local/bin/codex.opencodex-real app-server`. Reported by a contributor (#2884) with
+ * `ps` output from an affected host: `--restart-codex` matched nothing and left
+ * app-servers alive holding stale in-memory catalogs.
+ *
+ * An EXACT set, kept separate from the target-triple pattern above rather than folded
+ * into it by stripping the suffix first. That shortcut is unsafe: normalising
+ * `codex-report-generator-worker.opencodex-real` yields a syntactically valid triple
+ * and would make an unrelated process a kill target. A triple binary cannot be a shim
+ * target anyway — Unix discovery accepts only a PATH entry named `codex`, and Windows
+ * refuses a real `codex.exe` outright — so the combination is unreachable, not merely
+ * unlisted.
+ *
+ * `.ps1` and `.cmd` are here because `findWindowsCodexTargets` shims both, and the
+ * extensionless form because Unix discovery and the Git-Bash launcher use it. There is
+ * deliberately no `.opencodex-real.exe`: Windows installation REFUSES to rename a native
+ * `codex.exe`, so that backup cannot exist. Matching it looked like free breadth until a
+ * review round put it plainly — this set decides what receives SIGTERM, and a name no
+ * installation can produce only widens what a coincidence can hit.
+ */
+const CODEX_LAUNCHER_BASENAMES = new Set([
+  "codex", "codex.exe", "codex.cmd",
+  "codex.opencodex-real",
+  "codex.opencodex-real.cmd",
+  "codex.opencodex-real.ps1",
+]);
+
 /** True when a Windows CommandLine is worth paying GetOwner for (current-user scoped later). */
 export function isWindowsCodexCandidateCommandLine(commandLine: string): boolean {
   return WINDOWS_CODEX_BASENAME_CANDIDATE_RE.test(commandLine)
@@ -158,7 +195,7 @@ function tokenBasename(token: string): string {
 
 function isCodexExecutableToken(token: string): boolean {
   const base = tokenBasename(token);
-  return base === "codex" || base === "codex.exe" || base === "codex.cmd"
+  return CODEX_LAUNCHER_BASENAMES.has(base)
     || CODEX_TARGET_TRIPLE_BASENAME_RE.test(base);
 }
 
@@ -282,6 +319,10 @@ export function isCodexAppServerCommandLine(commandLine: string, executable?: st
   let i = 1;
   while (i < tokens.length) {
     const token = tokens[i]!;
+    // `--` ends option parsing, so what follows is a prompt for the interactive TUI, not
+    // a subcommand. `codex -- app-server` starts a session whose first prompt word is
+    // "app-server"; treating it as a match sends SIGTERM to somebody's live session.
+    if (token === "--") return false;
     if (token.startsWith("-")) {
       i = advancePastCodexGlobalOption(tokens, i);
       continue;
@@ -418,9 +459,9 @@ function windowsSnapshotPowerShellCommand(): string {
   // Newlines keep -Command as a real script (space-joined statements need ';').
   // Double-quoted format string so `t expands to a real tab.
   // Codex candidates only: basename token codex / codex.exe / codex.cmd /
-  // official target-triple binaries (optional closing quote after the
-  // basename), or code-mode-host — not incidental substrings like a repo
-  // path with "opencodex".
+  // codex.ps1, their .opencodex-real shim backups, official target-triple
+  // binaries (optional closing quote after the basename), or code-mode-host —
+  // not incidental substrings like a repo path with "opencodex".
   const basenameMatch = powerShellSingleQuotedIgnoreCaseMatch(WINDOWS_CODEX_BASENAME_CANDIDATE_RE.source);
   const codeModeMatch = powerShellSingleQuotedIgnoreCaseMatch(WINDOWS_CODEX_CODE_MODE_HOST_CANDIDATE_RE.source);
   return [