@bitkyc08/opencodex 2.26.0 → 2.28.0

package/src/codex/convergence.ts

@@ -66,6 +66,17 @@ import {
   supportedCodexReasoningEffortsFromObservedCatalog,
 } from "./catalog/effort";
 import { codexRuntimeStatePath, peekCodexRuntimeProcessCache } from "./runtime";
+import { codexAccountNamespaceEntries, isMainCodexAccountTarget } from "./account-namespaces";
+import { MAIN_CODEX_ACCOUNT_ID } from "./main-account";
+import {
+  availableAccountGatedNativeModels,
+  isCodexModelEntitlementSnapshotCurrent,
+  resolveCodexModelEntitlements,
+  type CodexModelEntitlementSnapshot,
+} from "./model-entitlements";
+import { ACCOUNT_GATED_NATIVE_OPENAI_MODELS } from "./catalog/native-models";
+import { providerCodexAccountMode } from "../providers/registry";
+import { OPENAI_CODEX_PROVIDER_ID } from "../providers/openai-tiers";
 import { withCatalogWriteSerialization } from "./catalog-write-serialization";
 import {
   publishHashedCodexCatalogBackup,
@@ -95,7 +106,7 @@ export interface CatalogWriteReceipt {
 
 export type CodexCatalogCommitResult =
   | { readonly kind: "committed"; readonly changed: boolean; readonly writes: CatalogWriteReceipt }
-  | { readonly kind: "stale"; readonly reason: "generation" | "home-selection" | "source-observation" | "process-local" | "target-identity" | "candidate-consumed" }
+  | { readonly kind: "stale"; readonly reason: "generation" | "home-selection" | "source-observation" | "process-local" | "target-identity" | "candidate-consumed" | "account-entitlement" }
   | { readonly kind: "refused"; readonly reason: "source-unreadable" | "source-ambiguous" | "target-unsafe" }
   | { readonly kind: "failed"; readonly surface: "disk"; readonly writes: CatalogWriteReceipt };
 
@@ -122,6 +133,7 @@ interface CandidateState {
   readonly legacyBackup?: PreparedCatalogFileWrite;
   readonly changed: boolean;
   readonly notices: readonly CatalogNotice[];
+  readonly modelEntitlements: CodexModelEntitlementSnapshot;
 }
 
 const candidateStates = new WeakMap<object, CandidateState>();
@@ -217,6 +229,7 @@ function prepareCatalog(
   baseline: ReadonlyMap<string, number>,
   baselineCatalogModels: readonly Readonly<Record<string, unknown>>[],
   degradedProviderNames: ReadonlySet<string>,
+  modelEntitlements: CodexModelEntitlementSnapshot,
   nativeRecoverySources: readonly (readonly RawEntry[])[] = [],
   observedAccountNativeEntries: readonly RawEntry[] = [],
 ): RawCatalog {
@@ -229,19 +242,46 @@ function prepareCatalog(
   const multiAgentMode = config.multiAgentMode === "v1" || config.multiAgentMode === "v2"
     ? config.multiAgentMode : "default";
   const exactComboSlugs = exactComboCatalogSlugs(config);
-  const suppressedBareNativeSlugs = desktopAllowlistSuppressedNativeSlugs(config);
+  const bareEligibleAccountIds = providerCodexAccountMode(
+    OPENAI_CODEX_PROVIDER_ID,
+    config.providers[OPENAI_CODEX_PROVIDER_ID],
+  ) === "direct" ? new Set([MAIN_CODEX_ACCOUNT_ID]) : undefined;
+  const availableBareGatedNativeSlugs = availableAccountGatedNativeModels(
+    modelEntitlements,
+    bareEligibleAccountIds,
+  );
+  const availableAccountGatedNativeSlugs = availableAccountGatedNativeModels(modelEntitlements);
+  const availableBareNativeSlugs = NATIVE_OPENAI_MODELS.filter(slug => (
+    !ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(slug) || availableBareGatedNativeSlugs.has(slug)
+  ));
+  const availableAccountNativeSlugs = NATIVE_OPENAI_MODELS.filter(slug => (
+    !ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(slug) || availableAccountGatedNativeSlugs.has(slug)
+  ));
+  const suppressedBareNativeSlugs = new Set([
+    ...desktopAllowlistSuppressedNativeSlugs(config),
+    ...[...ACCOUNT_GATED_NATIVE_OPENAI_MODELS].filter(slug => !availableBareGatedNativeSlugs.has(slug)),
+  ]);
   const hasPhysicalComboProvider = Object.hasOwn(config.providers, COMBO_NAMESPACE);
   const enabledProviders = Object.entries(config.providers).filter(([, provider]) => provider.disabled !== true);
   const includeNativeOpenAi = shouldIncludeNativeOpenAi(config);
   const accountSelectors = shouldIncludeAccountBoundNativeOpenAi(config)
     ? visibleCodexAccountSelectors(config)
     : [];
-  const accountNativeSlugs = accountSelectors.length > 0
-    ? accountBoundNativeOpenAiSlugs(observedAccountNativeEntries)
-    : [];
+  const accountTargets = new Map(codexAccountNamespaceEntries(config));
   const accountNativeSlugsBySelector = accountSelectors.length > 0
-    ? accountBoundNativeOpenAiSlugsBySelector(config, observedAccountNativeEntries)
+    ? new Map([...accountBoundNativeOpenAiSlugsBySelector(config, observedAccountNativeEntries)].map(([selector, slugs]) => {
+      const target = accountTargets.get(selector);
+      const accountId = target && isMainCodexAccountTarget(target) ? MAIN_CODEX_ACCOUNT_ID : target;
+      const entitled = accountId ? modelEntitlements.modelsByAccount.get(accountId) : undefined;
+      const confirmed = accountId ? modelEntitlements.confirmedAccountIds.has(accountId) : false;
+      return [selector, slugs.filter(slug => (
+        !ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(slug) || (confirmed && entitled?.has(slug) === true)
+      ))] as const;
+    }))
     : new Map<string, readonly string[]>();
+  const accountNativeSlugs = accountSelectors.length > 0
+    ? [...new Set([...accountNativeSlugsBySelector.values()].flatMap(slugs => [...slugs]))]
+    : [];
   // Unknown account-native ids have no safe bare/global identity. They are only projected through
   // selector-qualified rows when a live selector is configured.
   const observedNativeSlugs: string[] = [];
@@ -269,7 +309,7 @@ function prepareCatalog(
     ? []
     : buildCatalogEntriesFromObservedState({
       template: template ? JSON.parse(JSON.stringify(template)) : null,
-      gptSlugs: NATIVE_OPENAI_MODELS,
+      gptSlugs: availableAccountNativeSlugs,
       goModels: [],
       featured,
       wsEnabled: websocketsEnabled(config),
@@ -314,7 +354,7 @@ function prepareCatalog(
     suppressedBareNativeSlugs,
     policy: {
       ...CANONICAL_NATIVE_CATALOG_CONTENT_POLICY,
-      nativeBackfillSlugs: [...NATIVE_OPENAI_MODELS, ...observedNativeSlugs],
+      nativeBackfillSlugs: [...availableBareNativeSlugs, ...observedNativeSlugs],
       warningPolicy: "suppress",
     },
   });
@@ -356,11 +396,14 @@ export async function gatherCodexCatalogCandidate(
     const providerModelOutcomes: CatalogGatherProviderModelOutcome[] = [];
     const discoveryPolicies: CatalogProviderDiscoveryPolicySnapshot[] = [];
     providerGatherStarted = true;
-    const routedModels = await gatherRoutedModelsForCatalogGather(snapshot.config, session, {
-      providerAuthOutcomes: authOutcomes,
-      providerModelOutcomes,
-      discoveryPolicySnapshots: discoveryPolicies,
-    });
+    const [routedModels, modelEntitlements] = await Promise.all([
+      gatherRoutedModelsForCatalogGather(snapshot.config, session, {
+        providerAuthOutcomes: authOutcomes,
+        providerModelOutcomes,
+        discoveryPolicySnapshots: discoveryPolicies,
+      }),
+      resolveCodexModelEntitlements(snapshot.config),
+    ]);
     const processLocal = processEvidence(source);
     const sourceEvidence = sealCatalogGatherEvidenceSession(session);
     if (!same(sourceEvidence.required, snapshot.sourceEvidence.required)) {
@@ -399,6 +442,7 @@ export async function gatherCodexCatalogCandidate(
       new Set(providerModelOutcomes
         .filter(outcome => outcome.state === "degraded")
         .map(outcome => outcome.provider)),
+      modelEntitlements,
       [
         catalogFrom(keyedBackupBytes)?.models ?? [],
         catalogFrom(legacyBackupBytes)?.models ?? [],
@@ -452,6 +496,7 @@ export async function gatherCodexCatalogCandidate(
       changed: Buffer.from(activeBytes ?? []).toString("utf8") !== preparedCatalogBytes
         || Buffer.from(cacheBytes ?? []).toString("utf8") !== preparedCacheBytes,
       notices: Object.freeze([...notices]),
+      modelEntitlements,
     });
     return { kind: "candidate", candidate };
   } catch (error) {
@@ -469,6 +514,9 @@ export async function gatherCodexCatalogCandidate(
 }
 
 function revalidateCandidate(state: CandidateState): CodexCatalogCommitResult | null {
+  if (!isCodexModelEntitlementSnapshotCurrent(state.modelEntitlements)) {
+    return { kind: "stale", reason: "account-entitlement" };
+  }
   let session: CatalogFilesystemEvidenceSession;
   let validatingTargets = false;
   try {

package/src/codex/log-guard/path-safety.ts

@@ -1,5 +1,5 @@
-import { realpathSync } from "node:fs";
-import { resolve, sep } from "node:path";
+import { lstatSync, realpathSync } from "node:fs";
+import { dirname, resolve, sep } from "node:path";
 
 import { samePathIdentity } from "../user-identity";
 
@@ -35,5 +35,54 @@ export function normalizeTrustedDarwinSystemAlias(path: string): string {
  * Arbitrary ancestor symlinks remain refused.
  */
 export function sameLogGuardPathIdentity(realPath: string, requestedPath: string): boolean {
-  return samePathIdentity(realPath, normalizeTrustedDarwinSystemAlias(requestedPath));
+  const requested = normalizeTrustedDarwinSystemAlias(requestedPath);
+  if (samePathIdentity(realPath, requested)) return true;
+  return sameWindowsCanonicalPath(realPath, requested);
+}
+
+/**
+ * On Windows, is the difference between these two spellings the OS canonicalizing the
+ * request rather than a redirection?
+ *
+ * `realpathSync.native` expands 8.3 short components — the `RUNNER~1` form that appears
+ * throughout `%TEMP%` — so the canonical path and the requested path can disagree as
+ * strings while naming the same file. Reading that as an ancestor-symlink redirection made
+ * every Log Guard mutation refuse with `unsafe_path` on Windows, which is what the CI shards
+ * were reporting.
+ *
+ * The first version of this re-canonicalized the requested path and compared the two
+ * canonical forms. That was wrong, and the Windows shard proved it: the caller already
+ * passes `realpathSync.native(requested)` as `realPath`, so re-resolving the request
+ * produced the same value on BOTH sides and a symlinked database compared equal. The
+ * widening let through exactly what the guard exists to refuse.
+ *
+ * The comparison is therefore link-aware. A short-name expansion rewrites the spelling of
+ * components that are all still directories on the same chain, so it is enough to require
+ * that no component of the request is a link: with none present, any remaining difference
+ * is the OS's own canonical spelling. A symlink or junction anywhere in the chain fails
+ * closed as before.
+ */
+function sameWindowsCanonicalPath(realPath: string, requestedPath: string): boolean {
+  if (process.platform !== "win32") return false;
+  try {
+    if (pathChainContainsLink(requestedPath)) return false;
+    return samePathIdentity(realPath, realpathSync.native(requestedPath));
+  } catch {
+    return false;
+  }
+}
+
+/** Is any component of this path a symlink or junction? Fails closed on an unreadable one. */
+function pathChainContainsLink(path: string): boolean {
+  let current = resolve(path);
+  for (;;) {
+    try {
+      if (lstatSync(current).isSymbolicLink()) return true;
+    } catch {
+      return true;
+    }
+    const parent = dirname(current);
+    if (parent === current) return false;
+    current = parent;
+  }
 }

package/src/codex/model-entitlements.ts

@@ -0,0 +1,353 @@
+import { createHash } from "node:crypto";
+import { readBoundedResponseBody } from "../lib/bounded-body";
+import type { OcxConfig } from "../types";
+import { isSelectableCodexPoolAccount } from "./account-id";
+import { getValidCodexToken, readCodexAccountRecord } from "./account-store";
+import { getMainAccountToken, MAIN_CODEX_ACCOUNT_ID } from "./main-account";
+import { ACCOUNT_GATED_NATIVE_OPENAI_MODELS } from "./catalog/native-models";
+
+const CODEX_MODELS_URL = "https://chatgpt.com/backend-api/codex/models?client_version=0.0.0";
+const MODEL_ROSTER_TTL_MS = 5 * 60_000;
+const MODEL_ROSTER_FAILURE_TTL_MS = 15_000;
+const MODEL_ROSTER_TIMEOUT_MS = 8_000;
+const MODEL_ROSTER_MAX_BYTES = 2 * 1024 * 1024;
+const MODEL_ROSTER_CACHE_MAX = 64;
+const DIRECT_CALLER_ACCOUNT_PREFIX = "__direct_codex__:";
+
+export interface CodexModelEntitlementCredentialSnapshot {
+  readonly accountId: string;
+  readonly accessToken: string;
+  readonly chatgptAccountId: string;
+  /** Stable local identity for rejecting a catalog commit after credential replacement. */
+  readonly credentialIdentity: string;
+}
+
+interface CachedAccountModels {
+  readonly credentialIdentity: string;
+  readonly expiresAt: number;
+  readonly models: ReadonlySet<string>;
+  readonly confirmed: boolean;
+}
+
+export interface CodexModelEntitlementSnapshot {
+  readonly modelsByAccount: ReadonlyMap<string, ReadonlySet<string>>;
+  readonly confirmedAccountIds: ReadonlySet<string>;
+  readonly credentialIdentities: ReadonlyMap<string, string>;
+}
+
+export interface CodexModelEntitlementResolveOptions {
+  readonly fetcher?: typeof fetch;
+  readonly now?: number;
+  /** Test-only credential seam; production callers enumerate local main + Pool credentials. */
+  readonly credentials?: readonly CodexModelEntitlementCredentialSnapshot[];
+}
+
+const accountModelsCache = new Map<string, CachedAccountModels>();
+const accountModelsFlights = new Map<string, Promise<CachedAccountModels>>();
+
+/**
+ * Direct-caller entries are evicted separately from main/Pool entries.
+ *
+ * Direct keys are per-credential (`__direct_codex__:<hash>`) and unbounded in practice, while
+ * main/Pool keys are the evidence the CATALOG projects from. Sharing one LRU let 64 distinct
+ * Direct callers evict `__main__` and the Pool accounts, which makes the gated row vanish from
+ * the catalog until rediscovery — fail-closed flapping rather than a leak, but still a visible
+ * model disappearing for a reason the operator cannot see. Two budgets keep one class of caller
+ * from erasing the other's evidence.
+ */
+function boundedCacheSet(accountId: string, value: CachedAccountModels): void {
+  accountModelsCache.delete(accountId);
+  accountModelsCache.set(accountId, value);
+  const isDirect = (key: string): boolean => key.startsWith(DIRECT_CALLER_ACCOUNT_PREFIX);
+  const evictClass = (direct: boolean): void => {
+    let count = 0;
+    for (const key of accountModelsCache.keys()) if (isDirect(key) === direct) count += 1;
+    while (count > MODEL_ROSTER_CACHE_MAX) {
+      let oldest: string | undefined;
+      for (const key of accountModelsCache.keys()) {
+        if (isDirect(key) === direct) { oldest = key; break; }
+      }
+      if (oldest === undefined) break;
+      accountModelsCache.delete(oldest);
+      count -= 1;
+    }
+  };
+  evictClass(isDirect(accountId));
+}
+
+function currentCredentialIdentity(accountId: string): string | undefined {
+  if (accountId.startsWith(DIRECT_CALLER_ACCOUNT_PREFIX)) {
+    return `direct:${accountId.slice(DIRECT_CALLER_ACCOUNT_PREFIX.length)}`;
+  }
+  if (accountId === MAIN_CODEX_ACCOUNT_ID) {
+    const token = getMainAccountToken();
+    return token ? `main:${token.chatgptAccountId}` : undefined;
+  }
+  const record = readCodexAccountRecord(accountId);
+  if (!record?.credential || record.deletedAt != null) return undefined;
+  return `pool:${record.generation}:${record.credential.chatgptAccountId}`;
+}
+
+async function accountCredentialSnapshot(accountId: string): Promise<CodexModelEntitlementCredentialSnapshot | null> {
+  if (accountId === MAIN_CODEX_ACCOUNT_ID) {
+    const token = getMainAccountToken();
+    return token
+      ? {
+        accountId,
+        accessToken: token.accessToken,
+        chatgptAccountId: token.chatgptAccountId,
+        credentialIdentity: `main:${token.chatgptAccountId}`,
+      }
+      : null;
+  }
+  try {
+    const token = await getValidCodexToken(accountId);
+    return {
+      accountId,
+      accessToken: token.accessToken,
+      chatgptAccountId: token.chatgptAccountId,
+      credentialIdentity: `pool:${token.generation}:${token.chatgptAccountId}`,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function parseAccountModels(text: string): ReadonlySet<string> | null {
+  try {
+    const payload = JSON.parse(text) as { models?: unknown };
+    if (!Array.isArray(payload.models)) return null;
+    const models = payload.models.flatMap(entry => {
+      if (!entry || typeof entry !== "object" || Array.isArray(entry)) return [];
+      const row = entry as { slug?: unknown; supported_in_api?: unknown; visibility?: unknown };
+      if (typeof row.slug !== "string" || row.supported_in_api !== true || row.visibility === "hide") return [];
+      return [row.slug];
+    });
+    return new Set(models);
+  } catch {
+    return null;
+  }
+}
+
+async function fetchAccountModels(
+  credential: CodexModelEntitlementCredentialSnapshot,
+  fetcher: typeof fetch,
+  now: number,
+): Promise<CachedAccountModels> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(new DOMException("Codex model discovery timed out", "TimeoutError")), MODEL_ROSTER_TIMEOUT_MS);
+  try {
+    const headers = new Headers({
+      Authorization: `Bearer ${credential.accessToken}`,
+      Accept: "application/json",
+    });
+    if (credential.chatgptAccountId) headers.set("ChatGPT-Account-Id", credential.chatgptAccountId);
+    const response = await fetcher(CODEX_MODELS_URL, {
+      headers,
+      redirect: "error",
+      signal: controller.signal,
+    });
+    const body = await readBoundedResponseBody(response, {
+      signal: controller.signal,
+      maxBytes: MODEL_ROSTER_MAX_BYTES,
+      fatalUtf8: true,
+    });
+    const models = response.ok && body.displaySafe && !body.truncated
+      ? parseAccountModels(body.text)
+      : null;
+    return {
+      credentialIdentity: credential.credentialIdentity,
+      expiresAt: now + (models ? MODEL_ROSTER_TTL_MS : MODEL_ROSTER_FAILURE_TTL_MS),
+      models: models ?? new Set(),
+      confirmed: models !== null,
+    };
+  } catch {
+    return {
+      credentialIdentity: credential.credentialIdentity,
+      expiresAt: now + MODEL_ROSTER_FAILURE_TTL_MS,
+      models: new Set(),
+      confirmed: false,
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function directCallerCredential(headers: Headers): CodexModelEntitlementCredentialSnapshot | null {
+  const match = /^Bearer\s+(\S+)$/i.exec(headers.get("authorization")?.trim() ?? "");
+  if (!match) return null;
+  const accessToken = match[1]!;
+  const chatgptAccountId = headers.get("chatgpt-account-id")?.trim() ?? "";
+  const fingerprint = createHash("sha256")
+    .update(accessToken)
+    .update("\0")
+    .update(chatgptAccountId)
+    .digest("hex");
+  return {
+    accountId: `${DIRECT_CALLER_ACCOUNT_PREFIX}${fingerprint}`,
+    accessToken,
+    chatgptAccountId,
+    credentialIdentity: `direct:${fingerprint}`,
+  };
+}
+
+async function modelsForCredential(
+  credential: CodexModelEntitlementCredentialSnapshot,
+  fetcher: typeof fetch,
+  now: number,
+): Promise<CachedAccountModels> {
+  const cached = accountModelsCache.get(credential.accountId);
+  if (
+    cached
+    && cached.credentialIdentity === credential.credentialIdentity
+    && cached.expiresAt > now
+  ) return cached;
+
+  const flightKey = `${credential.accountId}\u0000${credential.credentialIdentity}`;
+  const existing = accountModelsFlights.get(flightKey);
+  if (existing) return existing;
+  const flight = fetchAccountModels(credential, fetcher, now)
+    .then(result => {
+      if (currentCredentialIdentity(credential.accountId) === credential.credentialIdentity) {
+        boundedCacheSet(credential.accountId, result);
+      }
+      return result;
+    })
+    .finally(() => {
+      if (accountModelsFlights.get(flightKey) === flight) accountModelsFlights.delete(flightKey);
+    });
+  accountModelsFlights.set(flightKey, flight);
+  return flight;
+}
+
+function candidateAccountIds(config: Pick<OcxConfig, "codexAccounts">): string[] {
+  return [
+    MAIN_CODEX_ACCOUNT_ID,
+    ...(config.codexAccounts ?? [])
+      .filter(isSelectableCodexPoolAccount)
+      .map(account => account.id),
+  ];
+}
+
+/**
+ * Fetch the authenticated model roster for every locally usable Codex account.
+ *
+ * [Decision Log]
+ * - 목적과 의도: Account-gated native models must be advertised and selected only for accounts
+ *   whose own authenticated upstream catalog confirms the model.
+ * - 기존 구현 및 제약 조건: The injected Codex catalog is static, while Pool may contain
+ *   accounts with different entitlements. A global allowlist therefore exposed unusable rows.
+ * - 검토한 주요 대안: Infer access from plan labels, learn only after a failed prompt, or rewrite
+ *   Daybreak to its current physical model.
+ * - 선택한 방식: Cache bounded authenticated `/models` rosters per credential generation and
+ *   fail closed for unconfirmed accounts.
+ * - 다른 대안 대신 이 방식을 선택한 이유: Plan names do not prove grants, post-failure
+ *   learning spends a real turn, and model rewriting changes the requested product identity.
+ * - 장점, 단점 및 영향: Catalog and routing share exact account evidence. Cold gated requests
+ *   pay one bounded discovery call per account; discovery failure temporarily hides the gated row.
+ */
+export async function resolveCodexModelEntitlements(
+  config: Pick<OcxConfig, "codexAccounts">,
+  options: CodexModelEntitlementResolveOptions = {},
+): Promise<CodexModelEntitlementSnapshot> {
+  const now = options.now ?? Date.now();
+  const fetcher = options.fetcher ?? fetch;
+  const credentials = options.credentials
+    ? [...options.credentials]
+    : (await Promise.all(candidateAccountIds(config).map(accountCredentialSnapshot)))
+      .filter((value): value is CodexModelEntitlementCredentialSnapshot => value !== null);
+  const results = await Promise.all(credentials.map(async credential => ({
+    credential,
+    result: await modelsForCredential(credential, fetcher, now),
+  })));
+  return {
+    modelsByAccount: new Map(results.map(({ credential, result }) => [credential.accountId, result.models])),
+    confirmedAccountIds: new Set(results.flatMap(({ credential, result }) => result.confirmed ? [credential.accountId] : [])),
+    credentialIdentities: new Map(results.map(({ credential }) => [credential.accountId, credential.credentialIdentity])),
+  };
+}
+
+/** Fail-closed entitlement check for a Direct request's own forwarded ChatGPT credential. */
+export async function isDirectCallerEntitledToCodexModel(
+  headers: Headers,
+  modelId: string,
+  options: Pick<CodexModelEntitlementResolveOptions, "fetcher" | "now"> = {},
+): Promise<boolean> {
+  if (!ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(modelId)) return true;
+  const credential = directCallerCredential(headers);
+  if (!credential) return false;
+  const result = await modelsForCredential(
+    credential,
+    options.fetcher ?? fetch,
+    options.now ?? Date.now(),
+  );
+  return result.confirmed && result.models.has(modelId);
+}
+
+export function entitledCodexAccountIdsForModel(
+  snapshot: CodexModelEntitlementSnapshot,
+  modelId: string | undefined,
+): ReadonlySet<string> | undefined {
+  if (!modelId || !ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(modelId)) return undefined;
+  return new Set([...snapshot.modelsByAccount].flatMap(([accountId, models]) => (
+    snapshot.confirmedAccountIds.has(accountId) && models.has(modelId) ? [accountId] : []
+  )));
+}
+
+export function availableAccountGatedNativeModels(
+  snapshot: CodexModelEntitlementSnapshot,
+  eligibleAccountIds?: ReadonlySet<string>,
+): ReadonlySet<string> {
+  return new Set([...ACCOUNT_GATED_NATIVE_OPENAI_MODELS].filter(modelId => (
+    [...snapshot.modelsByAccount].some(([accountId, models]) => (
+      (!eligibleAccountIds || eligibleAccountIds.has(accountId))
+      && snapshot.confirmedAccountIds.has(accountId)
+      && models.has(modelId)
+    ))
+  )));
+}
+
+/** Synchronous projection for management/catalog readers after a discovery pass. */
+export function cachedAvailableAccountGatedNativeModels(
+  now = Date.now(),
+  eligibleAccountIds?: ReadonlySet<string>,
+): ReadonlySet<string> {
+  return new Set([...ACCOUNT_GATED_NATIVE_OPENAI_MODELS].filter(modelId => (
+    [...accountModelsCache].some(([accountId, entry]) => (
+      (!eligibleAccountIds || eligibleAccountIds.has(accountId))
+      && !accountId.startsWith(DIRECT_CALLER_ACCOUNT_PREFIX)
+      && entry.confirmed
+      && entry.expiresAt > now
+      && entry.models.has(modelId)
+    ))
+  )));
+}
+
+export function isCodexModelEntitlementSnapshotCurrent(snapshot: CodexModelEntitlementSnapshot): boolean {
+  for (const [accountId, identity] of snapshot.credentialIdentities) {
+    if (currentCredentialIdentity(accountId) !== identity) return false;
+  }
+  return true;
+}
+
+export function invalidateCodexModelEntitlementsForAccount(accountId: string | null | undefined): void {
+  if (accountId) accountModelsCache.delete(accountId);
+}
+
+export function resetCodexModelEntitlementCacheForTests(): void {
+  accountModelsCache.clear();
+  accountModelsFlights.clear();
+}
+
+export function seedCodexModelEntitlementsForTests(
+  accountId: string,
+  models: readonly string[],
+  now = Date.now(),
+): void {
+  boundedCacheSet(accountId, {
+    credentialIdentity: `test:${accountId}`,
+    expiresAt: now + MODEL_ROSTER_TTL_MS,
+    models: new Set(models),
+    confirmed: true,
+  });
+}