@bitkyc08/opencodex 2.59.0 → 2.61.0-preview.20260922

package/src/codex/model-cache.ts

@@ -10,6 +10,7 @@
 import type { CatalogModel } from "./catalog";
 import type { GenerationContext } from "../lib/state-store-sweeper";
 import { enforceAppOwnedMemoryBudget, type RetainedStoreSnapshot } from "../lib/app-owned-memory";
+import { clearLiveCursorRosterState } from "../adapters/cursor/catalog";
 
 /** Default freshness window. Matches Codex's own 5-min models cache so the two stay in step. */
 export const DEFAULT_MODEL_CACHE_TTL_MS = 5 * 60 * 1000;
@@ -71,6 +72,8 @@ function deleteCachedProvider(provider: string): number {
   cache.delete(provider);
   cacheBytes = Math.max(0, cacheBytes - entry.sizeBytes);
   if (oldestCachedProvider === provider) recomputeOldestCachedProvider();
+  // A removal changes this provider's content as surely as a publication does.
+  bumpProviderCacheRevision(provider);
   return entry.sizeBytes;
 }
 
@@ -78,7 +81,17 @@ function deleteCachedProvider(provider: string): number {
  * the full fetch timeout on every catalog poll (issue #54: UI stalls behind corporate proxies). */
 export const MODELS_FETCH_FAILURE_COOLDOWN_MS = 30_000;
 
-const failureAt = new Map<string, number>();
+interface DiscoveryFailure {
+  at: number;
+  /**
+   * Credential the failure was observed under, for entitlement-specific rosters. Absent means
+   * the failure is credential-agnostic (a plain `/models` endpoint) and suppresses every
+   * caller, which is the original #54 behaviour.
+   */
+  authorityIdentity?: string;
+}
+
+const failureAt = new Map<string, DiscoveryFailure>();
 const discoveryStatus = new Map<string, ProviderModelDiscoveryStatus>();
 /**
  * How many models the last successful discovery actually returned, before any configured-alias
@@ -89,8 +102,12 @@ const discoveryStatus = new Map<string, ProviderModelDiscoveryStatus>();
 const liveModelCounts = new Map<string, number>();
 let lastReconciledGeneration = 0;
 
-export function markModelsFetchFailure(provider: string, now = Date.now()): void {
-  failureAt.set(provider, now);
+export function markModelsFetchFailure(
+  provider: string,
+  now = Date.now(),
+  authorityIdentity?: string,
+): void {
+  failureAt.set(provider, { at: now, ...(authorityIdentity ? { authorityIdentity } : {}) });
 }
 
 /** `liveModelCount` is required so a caller that forgets to pass it fails typecheck instead of
@@ -145,9 +162,25 @@ export function getProviderLiveModelCount(provider: string): number | undefined
   return liveModelCounts.get(provider);
 }
 
-export function isModelsFetchCoolingDown(provider: string, cooldownMs = MODELS_FETCH_FAILURE_COOLDOWN_MS, now = Date.now()): boolean {
-  const at = failureAt.get(provider);
-  return at !== undefined && now - at < cooldownMs;
+/**
+ * Whether a failed discovery still suppresses the next one.
+ *
+ * `authorityIdentity` scopes the suppression to the credential that actually observed the
+ * failure. A roster that upstream filters per account is evidence about that account, and
+ * one account's 401 or 404 must not decide that a different account has no catalog. A
+ * failure recorded without an identity stays credential-agnostic and suppresses everyone,
+ * so the plain-endpoint providers keep the timeout protection #54 added.
+ */
+export function isModelsFetchCoolingDown(
+  provider: string,
+  cooldownMs = MODELS_FETCH_FAILURE_COOLDOWN_MS,
+  now = Date.now(),
+  authorityIdentity?: string,
+): boolean {
+  const failure = failureAt.get(provider);
+  if (failure === undefined || now - failure.at >= cooldownMs) return false;
+  if (failure.authorityIdentity === undefined || authorityIdentity === undefined) return true;
+  return failure.authorityIdentity === authorityIdentity;
 }
 
 /** Fresh cached models for a provider, or null when absent/stale (caller should re-fetch). */
@@ -166,6 +199,20 @@ export function getStaleCached(provider: string, authorityIdentity?: string): Ca
   return entry.models;
 }
 
+/** Selector decoding may use unscoped rows, but scoped rows need current authority. */
+export function getRoutingCached(
+  provider: string, resolveAuthority: () => string | undefined,
+): CatalogModel[] | null {
+  const entry = cache.get(provider);
+  if (!entry) return null;
+  if (entry.authorityIdentity !== undefined) {
+    try {
+      if (resolveAuthority() !== entry.authorityIdentity) return null;
+    } catch { return null; }
+  }
+  return entry.models;
+}
+
 /** Capture the cache generation before an asynchronous provider discovery starts. */
 export function captureModelCacheGeneration(provider: string): string {
   if (!providerCacheGenerations.has(provider)) providerCacheGenerations.set(provider, 0);
@@ -177,6 +224,34 @@ export function isModelCacheGenerationCurrent(provider: string, generation: stri
   return generation === captureModelCacheGeneration(provider);
 }
 
+/**
+ * How many times this provider's cached content has actually changed.
+ *
+ * Deliberately separate from the generation. A generation revokes an in-flight discovery's right
+ * to publish, so it advances on an authority clear and must not be repurposed: moving it on a
+ * successful publication would cancel writes that are still legitimate. This counts accepted
+ * publications and removals instead, which is what a reader holding a derived roster needs to
+ * know, and it advances on exactly the event a generation does not: a discovery that succeeded
+ * and changed the rows.
+ *
+ * Reading is passive. An unseen provider reads as `0` rather than seeding an entry, so observing
+ * one cannot alter what a later capture or publication sees.
+ */
+const providerCacheRevisions = new Map<string, number>();
+let globalContentRevision = 0;
+
+function bumpProviderCacheRevision(provider: string): void {
+  providerCacheRevisions.set(provider, (providerCacheRevisions.get(provider) ?? 0) + 1);
+}
+
+export function observeModelCacheRevision(provider: string): string {
+  // The global term covers a clear that empties the map wholesale, which per-provider counters
+  // cannot express: without it, wiping every entry and republishing identical-looking rows would
+  // read as unchanged. It also survives pruning, so a retired provider cannot come back with a
+  // counter that matches a roster built before it left.
+  return `${globalContentRevision}:${providerCacheRevisions.get(provider) ?? 0}`;
+}
+
 /**
  * Store a live result unless the cache was cleared while that asynchronous discovery was running.
  * The optional generation keeps existing direct cache writers unchanged while discovery callers can
@@ -200,6 +275,8 @@ export function setCached(
     oldestCachedAt = now;
   }
   enforceAppOwnedMemoryBudget();
+  // Published and accepted, so anything derived from this provider's rows is now out of date.
+  bumpProviderCacheRevision(provider);
   return true;
 }
 
@@ -208,6 +285,7 @@ export function clearModelCache(
   provider?: string,
   reason: ModelCacheClearReason = "authority",
 ): void {
+  clearLiveCursorRosterState(provider);
   const revokesInFlightDiscovery = reason === "authority";
   if (provider) {
     if (revokesInFlightDiscovery) {
@@ -220,6 +298,11 @@ export function clearModelCache(
   } else {
     if (revokesInFlightDiscovery) globalCacheGeneration += 1;
     cache.clear();
+    // A wholesale clear changes every provider's content at once, and clearing the map means no
+    // per-provider counter can record it. Advancing the global term retires every derived roster
+    // and lets the per-provider entries be dropped without an ABA on the way back.
+    globalContentRevision += 1;
+    providerCacheRevisions.clear();
     cacheBytes = 0;
     oldestCachedProvider = undefined;
     oldestCachedAt = null;
@@ -237,6 +320,7 @@ export function reconcileModelCacheProviders(
   const removedProviders = new Set<string>();
   const trackedProviders = new Set([
     ...providerCacheGenerations.keys(),
+    ...providerCacheRevisions.keys(),
     ...failureAt.keys(),
     ...discoveryStatus.keys(),
     ...liveModelCounts.keys(),
@@ -247,6 +331,10 @@ export function reconcileModelCacheProviders(
     if (validProviders.has(provider)) continue;
     if (!revokedRemovedProviderAuthority) {
       globalCacheGeneration += 1;
+      // Advanced BEFORE any revision entry is dropped, so a provider that comes back cannot
+      // present the counter a roster was built against. Without this the delete below is an ABA:
+      // the entry returns at zero and an old stamp matches again.
+      globalContentRevision += 1;
       revokedRemovedProviderAuthority = true;
     }
     providerCacheGenerations.set(provider, (providerCacheGenerations.get(provider) ?? 0) + 1);
@@ -255,6 +343,11 @@ export function reconcileModelCacheProviders(
     failureAt.delete(provider);
     discoveryStatus.delete(provider);
     liveModelCounts.delete(provider);
+    // AFTER the cache deletion, which bumps this provider's revision and would otherwise recreate
+    // the entry we just removed. Dropped rather than left behind: a provider the configuration no
+    // longer has must not keep an entry alive for the life of the process merely because nothing
+    // cleared the whole cache. The global epoch advanced above, so the removal is not an ABA.
+    providerCacheRevisions.delete(provider);
     removedProviders.add(provider);
   }
   lastReconciledGeneration = generation;

package/src/codex/model-entitlement-admission.ts

@@ -0,0 +1,59 @@
+import type { OcxConfig } from "../types";
+import { MAIN_CODEX_ACCOUNT_ID } from "./main-account";
+import {
+  resolveCodexModelEntitlements,
+  type CodexModelEntitlementResolveOptions,
+  type CodexModelEntitlementSnapshot,
+} from "./model-entitlements";
+import {
+  type NativeMainCredentialAdmissionDeps,
+  withNativeMainCredentialAdmission,
+} from "./native-main-admission";
+
+interface ModelEntitlementAdmissionDeps extends NativeMainCredentialAdmissionDeps {
+  readonly resolve?: typeof resolveCodexModelEntitlements;
+}
+
+function excludeNativeMain(
+  options: CodexModelEntitlementResolveOptions,
+): CodexModelEntitlementResolveOptions {
+  return {
+    ...options,
+    excludeAccountIds: new Set([
+      ...(options.excludeAccountIds ?? []),
+      MAIN_CODEX_ACCOUNT_ID,
+    ]),
+  };
+}
+
+/**
+ * Resolve background/data-plane entitlements inside the native-main fences.
+ *
+ * Pool discovery remains available when startup recovery or a profile drain
+ * owns the physical credential. When main is admitted, the process-local lease
+ * covers only the credential snapshot: getValidMainAccountToken holds the
+ * cross-process exclusive claim just for the auth.json refresh write, and the
+ * lease is released before the upstream entitlement request so a profile drain
+ * never waits on a network fetch.
+ */
+export async function resolveAdmittedCodexModelEntitlements(
+  config: Pick<OcxConfig, "codexAccounts">,
+  options: CodexModelEntitlementResolveOptions = {},
+  deps: ModelEntitlementAdmissionDeps = {},
+): Promise<CodexModelEntitlementSnapshot> {
+  const resolve = deps.resolve ?? resolveCodexModelEntitlements;
+  // A caller-supplied roster or an already-excluded main never reads auth.json,
+  // so there is no native credential to fence.
+  if (options.credentials || options.excludeAccountIds?.has(MAIN_CODEX_ACCOUNT_ID)) {
+    return resolve(config, options);
+  }
+  return withNativeMainCredentialAdmission(
+    (excludedAccountIds, releaseMainLease) => resolve(
+      config,
+      excludedAccountIds.size === 0
+        ? { ...options, releaseNativeMainCredentialLease: releaseMainLease }
+        : excludeNativeMain(options),
+    ),
+    { acquireNativeMain: deps.acquireNativeMain },
+  );
+}

package/src/codex/model-entitlements.ts

@@ -2,13 +2,18 @@ import { createHash } from "node:crypto";
 import { readBoundedResponseBody } from "../lib/bounded-body";
 import type { CodexAccountCredentialRecord, OcxConfig } from "../types";
 import { isSelectableCodexPoolAccount } from "./account-id";
-import { getValidCodexToken, loadCodexAccountRecordSnapshot } from "./account-store";
+import {
+  beginCodexAccountGenerationLiveCheck,
+  getValidCodexToken,
+  loadCodexAccountRecordSnapshot,
+} from "./account-store";
 import {
   getMainAccountToken,
   getValidMainAccountToken,
   MAIN_CODEX_ACCOUNT_ID,
   type NativeMainRefreshDependencies,
 } from "./main-account";
+import { withNativeMainCredentialAdmission } from "./native-main-admission";
 import {
   ACCOUNT_GATED_NATIVE_OPENAI_MODELS,
   NATIVE_GPT6_ASTRA_MODEL,
@@ -22,6 +27,7 @@ import {
   forgetObservedCodexModelDenialsForAccount,
   observedDeniedCodexAccountIdsForModel,
   recordObservedCodexModelDenial,
+  setObservedDenialGenerationCheck,
   resetObservedCodexModelDenialsForTests,
 } from "./observed-model-denials";
 
@@ -434,6 +440,12 @@ export interface CodexModelEntitlementResolveOptions {
   readonly excludeAccountIds?: ReadonlySet<string>;
   /** Ensure-only fence; ordinary request resolvers retain their established flight identity. */
   readonly credentialMutationEpoch?: number;
+  /**
+   * Internal plumbing from `withNativeMainCredentialAdmission`: releases the
+   * native-main lifecycle lease once the credential phase settles, before any
+   * upstream roster fetch, so a profile drain never waits on network work.
+   */
+  readonly releaseNativeMainCredentialLease?: () => void;
 }
 
 export interface CodexEntitlementFreshnessOptions extends Pick<
@@ -447,6 +459,8 @@ export interface CodexEntitlementFreshnessOptions extends Pick<
   | "signal"
 > {
   readonly waitMs?: number;
+  /** Test seam for the native-main admission fence around the refresh workset. */
+  readonly nativeMainCredentialAdmission?: typeof withNativeMainCredentialAdmission;
 }
 
 const accountModelsCache = new Map<string, CachedAccountModels>();
@@ -576,21 +590,31 @@ function currentCredentialIdentity(accountId: string): string | undefined {
 
 async function accountCredentialSnapshot(
   accountId: string,
-  options: Pick<CodexModelEntitlementResolveOptions, "nativeMainRefreshDependencies" | "signal"> = {},
+  options: Pick<
+    CodexModelEntitlementResolveOptions,
+    "nativeMainRefreshDependencies" | "releaseNativeMainCredentialLease" | "signal"
+  > = {},
 ): Promise<CodexModelEntitlementCredentialSnapshot | null> {
   if (accountId === MAIN_CODEX_ACCOUNT_ID) {
-    const token = await getValidMainAccountToken({
-      signal: options.signal,
-      ...(options.nativeMainRefreshDependencies ?? {}),
-    });
-    return token
-      ? {
-        accountId,
-        accessToken: token.accessToken,
-        chatgptAccountId: token.chatgptAccountId,
-        credentialIdentity: `main:${token.chatgptAccountId}`,
-      }
-      : null;
+    try {
+      const token = await getValidMainAccountToken({
+        signal: options.signal,
+        ...(options.nativeMainRefreshDependencies ?? {}),
+      });
+      return token
+        ? {
+          accountId,
+          accessToken: token.accessToken,
+          chatgptAccountId: token.chatgptAccountId,
+          credentialIdentity: `main:${token.chatgptAccountId}`,
+        }
+        : null;
+    } finally {
+      // The lifecycle lease fences only this credential read; releasing here —
+      // on success and on a credential-ownership failure alike — keeps a
+      // profile drain from waiting on the roster fetches that follow.
+      options.releaseNativeMainCredentialLease?.();
+    }
   }
   try {
     const token = await getValidCodexToken(accountId);
@@ -906,38 +930,58 @@ async function refreshCodexEntitlementWorkset(
   mutationEpoch: number,
   options: CodexEntitlementFreshnessOptions,
 ): Promise<void> {
-  const credentialSnapshot = options.credentialSnapshot ?? accountCredentialSnapshot;
-  const observations = await Promise.all(workset.map(async accountId => {
-    const credential = await credentialSnapshot(accountId, options);
-    return {
-      accountId,
-      credential,
-      absenceObservedAt: options.now ?? Date.now(),
-    };
-  }));
-  const credentials = observations.flatMap(observation => observation.credential
-    ? [observation.credential]
-    : []);
-  if (credentials.length > 0) {
-    await resolveCodexModelEntitlements(config, {
-      ...options,
-      clientVersion,
-      credentialMutationEpoch: mutationEpoch,
-      credentials,
-    });
-  }
+  const run = async (
+    excludedAccountIds: ReadonlySet<string>,
+    releaseMainLease?: () => void,
+  ): Promise<void> => {
+    // An excluded main is filtered before the snapshot phase, not just before the
+    // roster fetch: it never produces an absence observation, so a denied
+    // admission cannot memoize a credential read that never happened.
+    const admittedWorkset = excludedAccountIds.size === 0
+      ? workset
+      : workset.filter(accountId => !excludedAccountIds.has(accountId));
+    const credentialSnapshot = options.credentialSnapshot ?? accountCredentialSnapshot;
+    const observations = await Promise.all(admittedWorkset.map(async accountId => {
+      const credential = await credentialSnapshot(accountId, {
+        ...options,
+        releaseNativeMainCredentialLease: releaseMainLease,
+      });
+      return {
+        accountId,
+        credential,
+        absenceObservedAt: options.now ?? Date.now(),
+      };
+    }));
+    // The lease fences only the credential phase; release before roster fetches
+    // so a profile drain never waits on upstream network work.
+    releaseMainLease?.();
+    const credentials = observations.flatMap(observation => observation.credential
+      ? [observation.credential]
+      : []);
+    if (credentials.length > 0) {
+      await resolveCodexModelEntitlements(config, {
+        ...options,
+        clientVersion,
+        credentialMutationEpoch: mutationEpoch,
+        credentials,
+      });
+    }
 
-  for (const observation of observations) {
-    if (observation.credential) continue;
-    const capturedIdentity = identityVector.get(observation.accountId) ?? null;
-    if (codexCredentialMutationEpoch() !== mutationEpoch) continue;
-    if ((currentCredentialIdentity(observation.accountId) ?? null) !== capturedIdentity) continue;
-    boundedNegativeCredentialMemoSet(observation.accountId, {
-      credentialIdentity: capturedIdentity,
-      mutationEpoch,
-      expiresAt: observation.absenceObservedAt + MODEL_ROSTER_NEGATIVE_CREDENTIAL_TTL_MS,
-    });
-  }
+    for (const observation of observations) {
+      if (observation.credential) continue;
+      const capturedIdentity = identityVector.get(observation.accountId) ?? null;
+      if (codexCredentialMutationEpoch() !== mutationEpoch) continue;
+      if ((currentCredentialIdentity(observation.accountId) ?? null) !== capturedIdentity) continue;
+      boundedNegativeCredentialMemoSet(observation.accountId, {
+        credentialIdentity: capturedIdentity,
+        mutationEpoch,
+        expiresAt: observation.absenceObservedAt + MODEL_ROSTER_NEGATIVE_CREDENTIAL_TTL_MS,
+      });
+    }
+  };
+  if (!workset.includes(MAIN_CODEX_ACCOUNT_ID)) return run(new Set<string>());
+  const admission = options.nativeMainCredentialAdmission ?? withNativeMainCredentialAdmission;
+  return admission(run);
 }
 
 function waitForEntitlementEnsureFlight(
@@ -1105,6 +1149,10 @@ export async function resolveCodexModelEntitlements(
     ? [...options.credentials].filter(credential => !options.excludeAccountIds?.has(credential.accountId))
     : (await Promise.all(allowedAccountIds.map(accountId => credentialSnapshot(accountId, options))))
       .filter((value): value is CodexModelEntitlementCredentialSnapshot => value !== null);
+  // The credential phase is the only part the native-main lease fences. The
+  // real snapshot releases it as soon as the main token settles; this boundary
+  // release keeps the guarantee when a seam snapshot never invokes it.
+  options.releaseNativeMainCredentialLease?.();
   const results = await Promise.all(credentials.map(async credential => ({
     credential,
     result: await modelsForCredential(
@@ -1297,13 +1345,14 @@ export function cachedDeniedCodexAccountIdsForModel(
   // absent an ongoing catalog sync the loop above contributes nothing at all. An upstream
   // refusal does not expire on that schedule and is not a snapshot of a pending answer: it is
   // the account's own Codex surface naming this model and declining it (#4906).
-  for (const accountId of observedDeniedCodexAccountIdsForModel(modelId, now) ?? []) {
-    // Under the caller's read fence, like the roster loop above. Nothing here reads account
-    // storage, but an excluded account must stay UNKNOWN rather than denied so a profile switch
-    // or a request-owned credential produces the same selection it does today.
-    if (options.excludeAccountIds?.has(accountId)) continue;
-    denied.add(accountId);
-  }
+  // The caller's read fence is passed IN rather than applied to the result, so an excluded
+  // account is skipped before the credential-generation validation reads account storage
+  // (#4952). An excluded account must stay UNKNOWN rather than denied, so a profile switch or
+  // a request-owned credential produces the same selection it does today.
+  const observedDenied = observedDeniedCodexAccountIdsForModel(modelId, now, {
+    ...(options.excludeAccountIds ? { excludeAccountIds: options.excludeAccountIds } : {}),
+  });
+  for (const accountId of observedDenied ?? []) denied.add(accountId);
   // One account holds one entry per client version, and upstream filters the roster by that
   // version. So the same account can legitimately carry a granted entry under a current client
   // and a denied one under an older client that predates the model. Positive evidence is
@@ -1330,23 +1379,36 @@ export function cachedDeniedCodexAccountIdsForModel(
  * admissible here: 400 covers every malformed request too, and remembering one of those as an
  * entitlement fact would steer routing away from a perfectly capable account.
  */
+// Denial evidence is credential-scoped (#4952). The store stays a leaf module, so the
+// liveness predicate is injected here, where the account store is already a dependency.
+setObservedDenialGenerationCheck(beginCodexAccountGenerationLiveCheck);
+
 export function recordCodexModelDenialEvidence(
   accountId: string | null | undefined,
   modelId: string | undefined,
+  generation: number | null | undefined,
   now = Date.now(),
 ): void {
   if (!accountId || !modelId) return;
   if (!ENTITLEMENT_PREFERRED_NATIVE_OPENAI_MODELS.has(modelId)) return;
-  recordObservedCodexModelDenial(accountId, modelId, now);
+  // A caller that cannot name a credential generation records ACCOUNT-scoped evidence rather
+  // than none. The one production context in that position is `main-pool`, whose credential
+  // lives in `auth.json` and has no pool generation; discarding its refusals would revert
+  // #4906 for the stored main login (#4952). Request-owned `main` never reaches here — its
+  // `accountId` is null and the guard above returns.
+  recordObservedCodexModelDenial(accountId, modelId, typeof generation === "number" ? generation : undefined, now);
 }
 
 /** Drop the refusal evidence for a pair the account has just served successfully. */
 export function clearCodexModelDenialEvidence(
   accountId: string | null | undefined,
   modelId: string | undefined,
+  generation: number | null | undefined,
 ): void {
   if (!accountId || !modelId) return;
-  clearObservedCodexModelDenial(accountId, modelId);
+  // Mirror of the write: an account-scoped success clears account-scoped evidence. It cannot
+  // clear a credential-scoped entry that names a newer generation, and vice versa (#4952).
+  clearObservedCodexModelDenial(accountId, modelId, typeof generation === "number" ? generation : undefined);
 }
 
 /** Synchronous projection for management/catalog readers after a discovery pass. */

package/src/codex/native-main-admission.ts

@@ -3,7 +3,13 @@ import {
   tryAcquireNativeMainProfileClaim as tryAcquireLifecycleNativeMainProfileClaim,
   tryClaimNativeMainProfileForTurn as tryClaimLifecycleNativeMainProfileForTurn,
 } from "../server/lifecycle";
+import {
+  MAIN_CODEX_ACCOUNT_ID,
+  MainAccountTokenRefreshError,
+  MainAuthJsonChangedDuringRefreshError,
+} from "./main-account";
 import { isNativeMainTrafficBlocked } from "./native-profile-startup";
+import { NativeProfileError } from "./native-profile-types";
 
 export interface NativeMainTurnClaimDeps {
   /** Test seams for the synchronous precheck/claim/postcheck transition. */
@@ -45,3 +51,80 @@ export function tryAcquireNativeMainProfileClaim(): AdmissionLease | null {
   claim.release();
   return null;
 }
+
+export interface NativeMainCredentialAdmissionDeps {
+  /** Test seam for the synchronous admission precheck. */
+  readonly acquireNativeMain?: () => AdmissionLease | null;
+}
+
+const NO_EXCLUDED_ACCOUNT_IDS: ReadonlySet<string> = new Set();
+const NATIVE_MAIN_EXCLUDED_ACCOUNT_IDS: ReadonlySet<string> = new Set([MAIN_CODEX_ACCOUNT_ID]);
+const RELEASE_NOTHING = () => {};
+
+/**
+ * Run credential-backed work inside the native-main lifecycle fence.
+ *
+ * The lease keeps startup recovery and profile drains from owning the physical
+ * credential while the operation reads it. Cross-process ownership of the file
+ * itself is already coordinated inside the refresh path's exclusive claim, so
+ * this fence deliberately does not take the shared claim: holding it across an
+ * operation that may refresh would ask for exclusive ownership against our own
+ * shared lock, and holding it across the upstream work that follows would
+ * stall an unrelated credential commit behind a network fetch.
+ *
+ * The fence covers only the credential read. The operation must invoke
+ * `releaseMainLease` as soon as the native-main credential settles — on both
+ * the success and the credential-error path — and before any upstream model
+ * listing, so a profile drain never waits on a network fetch while this turn
+ * is still counted. The wrapper releases on settle regardless, so an
+ * operation without a fenced credential phase may ignore the callback.
+ *
+ * When the gate refuses, or the credential cannot be read because another
+ * lifecycle owns it, the operation reruns with main excluded so independent
+ * Pool work is never suppressed by main's unavailability.
+ */
+export async function withNativeMainCredentialAdmission<T>(
+  operation: (
+    excludeAccountIds: ReadonlySet<string>,
+    releaseMainLease?: () => void,
+  ) => Promise<T>,
+  deps: NativeMainCredentialAdmissionDeps = {},
+): Promise<T> {
+  const lease = (deps.acquireNativeMain ?? tryAcquireNativeMainProfileClaim)();
+  if (!lease) return operation(NATIVE_MAIN_EXCLUDED_ACCOUNT_IDS, RELEASE_NOTHING);
+  let released = false;
+  const releaseMainLease = () => {
+    if (released) return;
+    released = true;
+    lease.release();
+  };
+  try {
+    return await operation(NO_EXCLUDED_ACCOUNT_IDS, releaseMainLease);
+  } catch (error) {
+    // The Pool-only retry never reads the native-main credential; release first
+    // so a profile drain is not kept waiting behind Pool network work.
+    releaseMainLease();
+    if (!isNativeMainCredentialUnavailableError(error)) throw error;
+    return await operation(NATIVE_MAIN_EXCLUDED_ACCOUNT_IDS, RELEASE_NOTHING);
+  } finally {
+    releaseMainLease();
+  }
+}
+
+/**
+ * The credential-ownership failures that make main unavailable for one
+ * operation: a foreign exclusive holder or an unsupported claim filesystem
+ * (NATIVE_MAIN_CLAIM_BUSY / NATIVE_MAIN_CLAIM_UNAVAILABLE), a writer that moved
+ * auth.json mid-refresh, or a grant that no longer refreshes. Like a Pool
+ * credential failure, none of them may suppress independent Pool discovery.
+ * Any other NativeProfileError — MAIN_REQUESTS_ACTIVE, VAULT_INVALID,
+ * INTERNAL_ERROR — is not a credential-ownership failure and propagates.
+ */
+function isNativeMainCredentialUnavailableError(error: unknown): boolean {
+  if (error instanceof NativeProfileError) {
+    return error.code === "NATIVE_MAIN_CLAIM_BUSY"
+      || error.code === "NATIVE_MAIN_CLAIM_UNAVAILABLE";
+  }
+  return error instanceof MainAuthJsonChangedDuringRefreshError
+    || error instanceof MainAccountTokenRefreshError;
+}