@bitkyc08/opencodex 2.58.0 → 2.60.0

package/src/codex/model-cache.ts

@@ -71,6 +71,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;
 }
 
@@ -177,6 +179,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 +230,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;
 }
 
@@ -220,6 +252,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 +274,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 +285,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 +297,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-entitlements.ts

@@ -2,7 +2,11 @@ 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,
@@ -17,6 +21,14 @@ import { loadPersistedCodexRuntime } from "./runtime";
 import { codexRuntimeStateEpoch } from "./runtime";
 import upstreamModelsSnapshot from "./data/upstream-models.json";
 import { codexCredentialMutationEpoch } from "./credential-mutation-epoch";
+import {
+  clearObservedCodexModelDenial,
+  forgetObservedCodexModelDenialsForAccount,
+  observedDeniedCodexAccountIdsForModel,
+  recordObservedCodexModelDenial,
+  setObservedDenialGenerationCheck,
+  resetObservedCodexModelDenialsForTests,
+} from "./observed-model-denials";
 
 const CODEX_MODELS_ENDPOINT = "https://chatgpt.com/backend-api/codex/models";
 
@@ -870,6 +882,11 @@ function needsEntitlementRefresh(
   const cached = accountModelsCache.get(cacheKeyFor(accountId, clientVersion));
   if (cached && cached.credentialIdentity !== credentialIdentity) {
     invalidateCodexModelEntitlementsForAccount(accountId);
+    // The credential itself changed, so evidence gathered under the previous one answers for a
+    // different subscription. This is the only call site that knows that: the two gated-model
+    // sites in `core-codex-account.ts` invalidate a STALE roster for an unchanged credential,
+    // and clearing observed refusals there would discard the very evidence #4906 is about.
+    forgetObservedCodexModelDenialsForAccount(accountId);
   } else if (cached && cached.expiresAt > now) {
     return false;
   }
@@ -1280,17 +1297,77 @@ export function cachedDeniedCodexAccountIdsForModel(
     if (state === "granted") granted.add(accountId);
     else if (state === "denied") denied.add(accountId);
   }
+  // The roster is not the only evidence, and on this path it is usually the weaker one. A cached
+  // roster expires in five minutes and nothing on the flagship request path refetches it, so
+  // 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).
+  // 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
   // authoritative regardless of which version asked for it -- the same rule
   // `codexModelEntitlementStateForRoster` applies within a single entry -- so a grant anywhere
   // clears the denial rather than being outvoted by whichever entry the map happened to yield
-  // last.
+  // last. It outranks an observed refusal for the same reason: a confirmed roster that lists the
+  // model is the newer answer, and a rollout that reaches an account must not be held back by a
+  // refusal it has already superseded.
   for (const accountId of granted) denied.delete(accountId);
   return denied.size > 0 ? denied : undefined;
 }
 
+/**
+ * Record an authenticated upstream refusal as this account's own evidence about `modelId`.
+ *
+ * Scoped to {@link ENTITLEMENT_PREFERRED_NATIVE_OPENAI_MODELS} because that is the set whose
+ * availability varies per account while the row stays visible, and it is the set
+ * {@link cachedDeniedCodexAccountIdsForModel} will read back. A model outside it either has no
+ * per-account variance or is gated by the fail-closed roster path, where an ordering preference
+ * would change nothing.
+ *
+ * The caller must have matched the exact allow-listed refusal body first. A status alone is not
+ * 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;
+  // 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;
+  // 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. */
 export function cachedAvailableAccountGatedNativeModels(
   now = Date.now(),
@@ -1351,6 +1428,7 @@ export function resetCodexModelEntitlementCacheForTests(): void {
   negativeCredentialMemo.clear();
   entitlementEnsureFlights.clear();
   runtimeVersionMemo = null;
+  resetObservedCodexModelDenialsForTests();
 }
 
 /** Test-only snapshot for proving publication fences, which cache lookup intentionally masks. */

package/src/codex/observed-model-denials.ts

@@ -0,0 +1,230 @@
+/**
+ * Per-account model denials observed from an authenticated upstream refusal.
+ *
+ * [Decision Log]
+ * - 목적과 의도: Keep the one piece of account-specific model evidence that is never stale --
+ *   the upstream's own refusal -- instead of discarding it after a single retry.
+ * - 기존 구현 및 제약 조건: `cachedDeniedCodexAccountIdsForModel` reads authenticated `/models`
+ *   rosters, and those entries expire five minutes after they are fetched
+ *   (`MODEL_ROSTER_TTL_MS`). Nothing on the flagship request path refills them, because
+ *   `resolveCodexModelEntitlements` is awaited only for `ACCOUNT_GATED_NATIVE_OPENAI_MODELS`,
+ *   which no longer holds the flagships. So the denial set is usually absent, the #4797
+ *   ordering rules become the identity function, and the pool picks on quota alone (#4906).
+ * - 검토한 주요 대안: Fetch a roster on the flagship request path, lengthen the roster TTL, or
+ *   infer availability from the account's plan name.
+ * - 선택한 방식: Record the exact upstream unsupported-model refusal per (account, model) and
+ *   let selection read it alongside the roster.
+ * - 다른 대안 대신 이 방식을 선택한 이유: A roster fetch on the request path puts an
+ *   authenticated upstream call in front of the most commonly requested models in the product,
+ *   which is what the cache-only contract exists to prevent. A longer TTL keeps a shard's
+ *   stale absence around for longer without adding any evidence. A plan name proves nothing
+ *   about a grant -- `available_in_plans` for `gpt-6-astra` lists `free` while free accounts
+ *   are refused -- and #3022 is what happened the last time availability was inferred rather
+ *   than observed.
+ * - 장점, 단점 및 영향: A refusal is spent once and then remembered, so the pool stops
+ *   re-sending a model to the account that just refused it. The evidence is confirmed rather
+ *   than inferred, it is still only an ordering preference, and it is overridden by any
+ *   positive roster grant for the same pair.
+ *
+ * What this deliberately is NOT: an eligibility filter. Readers treat these ids exactly like
+ * roster denials -- `withoutModelDeniedAccounts` restores them when filtering would empty the
+ * candidate list, and `preferModelEntitledAccount` leaves the active account alone when no
+ * entitled alternative exists. No model is hidden from any catalog and no request is refused
+ * before dispatch, so the 2026-09-04 owner decision that the flagships fail open is untouched.
+ */
+
+/**
+ * Six hours, against a five-minute roster TTL.
+ *
+ * The asymmetry is the point. A roster entry is a snapshot of an answer that may simply not
+ * have arrived yet, so it expires quickly and absence means "unknown". A refusal is an answer:
+ * upstream named this model and this account and said no. It still expires, because a rollout
+ * can reach an account between two requests, and the two faster paths back are a positive
+ * roster grant (which overrides this outright) and a successful response from the same account
+ * for the same model (which clears the entry).
+ */
+const OBSERVED_DENIAL_TTL_MS = 6 * 60 * 60_000;
+
+/** Bounded like the roster cache: pool size times flagship count, with room to spare. */
+const OBSERVED_DENIAL_MAX_ENTRIES = 512;
+
+/**
+ * One entry of refusal evidence.
+ *
+ * `generation` is the credential generation the refusal was observed under (#4952). Evidence
+ * is about a CREDENTIAL, not an account id: reauthenticating the same internal account can
+ * swap the subscription underneath it, so a refusal from the previous credential says nothing
+ * about the replacement. Carrying the generation lets a reader ignore superseded evidence and
+ * lets a late reply from an older generation be refused rather than applied.
+ *
+ * It is OPTIONAL because not every account that can be refused has one. A `main-pool` context
+ * — the stored main login taking part in rotation — carries a real `accountId` and a
+ * `writerGeneration`, but no pool credential generation, because its credential lives in
+ * `auth.json` rather than the pool store. Dropping its evidence would have silently reverted
+ * #4906 for that account: the pool would re-send the same model to the login that just refused
+ * it, on every request, forever. An entry without a generation is account-scoped, and the
+ * generation fences below simply do not apply to it. This is the same rule the quota writer
+ * already uses in `core-codex-account.ts`, where an absent credential generation skips the
+ * liveness check instead of discarding the write.
+ */
+interface ObservedDenial {
+  expiresAt: number;
+  generation?: number;
+}
+
+/** `accountId\u0000modelId` -> entry. Insertion order is the eviction order. */
+const observedDenials = new Map<string, ObservedDenial>();
+
+/** Whether `generation` is still the account's live credential. */
+type GenerationLiveCheck = (accountId: string, generation: number) => boolean;
+
+/**
+ * Opens one liveness check.
+ *
+ * A FACTORY rather than a bare predicate because the production implementation reads the
+ * credential store, and a lookup can ask about several accounts. Loading once per lookup and
+ * closing over that snapshot is the shape `loadCodexAccountRecordSnapshot` exists for; a bare
+ * predicate would reload and reparse the whole store per row, on the request path.
+ *
+ * Injected rather than imported at module scope so this stays a leaf module: `account-store`
+ * reads the credential file, and a unit test of this map should not have to stand one up.
+ */
+type GenerationLiveCheckFactory = () => GenerationLiveCheck;
+
+let beginGenerationLiveCheck: GenerationLiveCheckFactory = () => () => true;
+
+/** Wire the liveness predicate. Called once at startup; tests substitute their own. */
+export function setObservedDenialGenerationCheck(begin: GenerationLiveCheckFactory): void {
+  beginGenerationLiveCheck = begin;
+}
+
+function denialKey(accountId: string, modelId: string): string {
+  return `${accountId}\u0000${modelId}`;
+}
+
+function accountIdOfDenialKey(key: string): string {
+  return key.slice(0, key.indexOf("\u0000"));
+}
+
+function modelIdOfDenialKey(key: string): string {
+  return key.slice(key.indexOf("\u0000") + 1);
+}
+
+/**
+ * Remember that `accountId` was refused `modelId` by its own authenticated upstream.
+ *
+ * Re-recording refreshes the entry rather than extending an older one, so a pair that keeps
+ * being refused stays remembered and one that stops being refused ages out.
+ */
+export function recordObservedCodexModelDenial(
+  accountId: string,
+  modelId: string,
+  generation: number | undefined,
+  now = Date.now(),
+): void {
+  // A refusal dispatched under generation G can arrive after G+1 has been saved. Reject it
+  // BEFORE touching the map at all, not merely when this key already holds newer evidence:
+  // with no entry for this key the stale row would otherwise be inserted, and at the entry
+  // bound it would evict a valid row that nothing can restore (#4952).
+  if (generation !== undefined && !beginGenerationLiveCheck()(accountId, generation)) return;
+  const key = denialKey(accountId, modelId);
+  const existing = observedDenials.get(key);
+  // Second fence, for the window where the replacement credential has been dispatched but the
+  // store read above still answers live. Both sides must name a generation to be comparable;
+  // an account-scoped entry is not older or newer than a credential-scoped one.
+  if (existing !== undefined && existing.generation !== undefined && generation !== undefined
+    && existing.generation > generation) return;
+  // Delete before set so the refreshed entry moves to the back of the eviction order.
+  observedDenials.delete(key);
+  observedDenials.set(key, { expiresAt: now + OBSERVED_DENIAL_TTL_MS, generation });
+  while (observedDenials.size > OBSERVED_DENIAL_MAX_ENTRIES) {
+    const oldest = observedDenials.keys().next();
+    if (oldest.done) break;
+    observedDenials.delete(oldest.value);
+  }
+}
+
+/**
+ * Forget one pair, because the account just served the model.
+ *
+ * A success is newer and stronger evidence than the refusal that preceded it: whatever the
+ * entitlement was when upstream refused, it is not that now.
+ */
+export function clearObservedCodexModelDenial(
+  accountId: string,
+  modelId: string,
+  generation: number | undefined,
+): void {
+  const key = denialKey(accountId, modelId);
+  const existing = observedDenials.get(key);
+  if (!existing) return;
+  // The mirror of the write fence: a success dispatched under G arriving after G+1 was
+  // refused must not clear the replacement's evidence (#4952). Equal generations clear,
+  // because that is the ordinary "this account just served this model" case.
+  if (existing.generation !== undefined && generation !== undefined
+    && existing.generation > generation) return;
+  observedDenials.delete(key);
+}
+
+/**
+ * Forget every pair for one account, because its credential changed.
+ *
+ * A reauthenticated account can be a different subscription entirely, so evidence gathered
+ * under the previous credential says nothing about this one -- the same reasoning
+ * `invalidateCodexModelEntitlementsForAccount` applies to cached rosters.
+ */
+export function forgetObservedCodexModelDenialsForAccount(accountId: string | null | undefined): void {
+  if (!accountId) return;
+  for (const key of [...observedDenials.keys()]) {
+    if (accountIdOfDenialKey(key) === accountId) observedDenials.delete(key);
+  }
+}
+
+/**
+ * Accounts refused `modelId` within the retention window.
+ *
+ * Returns `undefined` rather than an empty set when nothing is recorded, matching
+ * `cachedDeniedCodexAccountIdsForModel`: a caller must not be able to read "no evidence" as
+ * "nobody is denied".
+ */
+export function observedDeniedCodexAccountIdsForModel(
+  modelId: string | undefined,
+  now = Date.now(),
+  options: { excludeAccountIds?: ReadonlySet<string> } = {},
+): ReadonlySet<string> | undefined {
+  if (!modelId) return undefined;
+  const denied = new Set<string>();
+  // Opened lazily and at most once: a lookup that matches no credential-scoped row must not
+  // read the credential store at all.
+  let isLive: GenerationLiveCheck | undefined;
+  for (const [key, entry] of [...observedDenials]) {
+    if (entry.expiresAt <= now) {
+      observedDenials.delete(key);
+      continue;
+    }
+    // Model and the caller's exclusion fence FIRST. The issue asks for identity validation
+    // after the exclusion read, and an excluded account — a draining profile switch, or a
+    // request-owned credential — must produce no credential-store read on its behalf.
+    if (modelIdOfDenialKey(key) !== modelId) continue;
+    const accountId = accountIdOfDenialKey(key);
+    if (options.excludeAccountIds?.has(accountId)) continue;
+    if (entry.generation !== undefined) {
+      isLive ??= beginGenerationLiveCheck();
+      // Superseded evidence stops denying the replacement. It is SKIPPED, not deleted: the
+      // predicate cannot tell "this account reauthenticated" from "the credential store could
+      // not be read", and deleting on the second would throw away valid evidence that a
+      // transient read failure was never entitled to touch. Skipping already delivers the
+      // routing outcome the issue asks for, on every read, without depending on the
+      // conditional account-wide forget that cannot run when no roster was ever cached.
+      // Superseded rows still leave by TTL, by eviction, and by the account-wide forget.
+      if (!isLive(accountId, entry.generation)) continue;
+    }
+    denied.add(accountId);
+  }
+  return denied.size > 0 ? denied : undefined;
+}
+
+export function resetObservedCodexModelDenialsForTests(): void {
+  observedDenials.clear();
+  beginGenerationLiveCheck = () => () => true;
+}

package/src/codex/orca-auth-source.ts

@@ -0,0 +1,94 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, join, parse, relative, resolve } from "node:path";
+
+const MAX_AUTH_BYTES = 256 * 1024;
+export const ORCA_ACCOUNT_DIRECTORY = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export function sameLocalPath(left: string, right: string): boolean {
+  return process.platform === "win32" ? left.toLowerCase() === right.toLowerCase() : left === right;
+}
+
+/** Reject links at every component; never follow an external credential reference. */
+export function assertPlainLocalPath(path: string): string {
+  if (/^(?:\\\\|\/\/)/.test(path)) throw new Error("Network and device credential paths are unsupported.");
+  const absolute = resolve(path);
+  let current = parse(absolute).root;
+  for (const component of relative(current, absolute).split(/[\\/]/).filter(Boolean)) {
+    current = join(current, component);
+    if (lstatSync(current).isSymbolicLink()) throw new Error("Unsafe local credential path.");
+  }
+  if (!sameLocalPath(realpathSync(absolute), absolute)) throw new Error("Unsafe local credential path.");
+  return absolute;
+}
+
+export function readBoundedLocalFile(path: string, limit = MAX_AUTH_BYTES): string {
+  assertPlainLocalPath(path);
+  const before = lstatSync(path);
+  if (!before.isFile() || before.size > limit) throw new Error("Invalid local credential file.");
+  const fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+  try {
+    const opened = fstatSync(fd);
+    if (!opened.isFile() || opened.size > limit || before.dev !== opened.dev || before.ino !== opened.ino) {
+      throw new Error("Local credential file changed.");
+    }
+    // The cap bounds the read, not the allocation: tiny registry files should not
+    // allocate 32 MiB on each preview/recheck. One extra byte detects concurrent growth.
+    const bytes = Buffer.alloc(opened.size + 1);
+    let length = 0;
+    while (length < bytes.length) {
+      const count = readSync(fd, bytes, length, bytes.length - length, null);
+      if (!count) break;
+      length += count;
+    }
+    if (length !== opened.size) throw new Error("Local credential file changed.");
+    assertPlainLocalPath(path);
+    const after = lstatSync(path);
+    if (after.dev !== opened.dev || after.ino !== opened.ino || after.size !== opened.size || after.mtimeMs !== opened.mtimeMs) {
+      throw new Error("Local credential file changed.");
+    }
+    return bytes.subarray(0, length).toString("utf8");
+  } finally { closeSync(fd); }
+}
+
+function object(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Invalid local OAuth credential.");
+  return value as Record<string, unknown>;
+}
+
+export function parseOrcaAuth(raw: string, requireFresh = true) {
+  const auth = object(JSON.parse(raw));
+  if ((auth.auth_mode !== undefined && auth.auth_mode !== "chatgpt")
+    || (auth.OPENAI_API_KEY !== undefined && auth.OPENAI_API_KEY !== null && auth.OPENAI_API_KEY !== "")) {
+    throw new Error("Expected a ChatGPT OAuth credential.");
+  }
+  const tokens = object(auth.tokens);
+  if (typeof tokens.access_token !== "string" || typeof tokens.account_id !== "string" || !tokens.account_id) {
+    throw new Error("Local OAuth credential lacks account identity.");
+  }
+  const parts = tokens.access_token.split(".");
+  if (parts.length !== 3) throw new Error("Invalid local OAuth bearer.");
+  const claims = object(JSON.parse(Buffer.from(parts[1]!, "base64url").toString("utf8")));
+  const identity = object(claims["https://api.openai.com/auth"]);
+  if (identity.chatgpt_account_id !== tokens.account_id || typeof claims.sub !== "string" || !claims.sub
+    || typeof claims.exp !== "number" || !Number.isSafeInteger(claims.exp) || !Number.isSafeInteger(claims.exp * 1000)
+    || (requireFresh && claims.exp * 1000 <= Date.now() + 60_000)) {
+    throw new Error("Local OAuth identity or expiry is invalid.");
+  }
+  return { accessToken: tokens.access_token, refreshToken: "", expiresAt: claims.exp * 1000,
+    chatgptAccountId: tokens.account_id, sourceSubject: claims.sub };
+}
+
+export function readOrcaAuthSource(path: string) {
+  if (!isAbsolute(path) || !ORCA_ACCOUNT_DIRECTORY.test(dirname(dirname(path)).split(/[\\/]/).pop() ?? "")
+    || dirname(path).split(/[\\/]/).pop() !== "home"
+    || dirname(dirname(dirname(path))).split(/[\\/]/).pop() !== "codex-accounts"
+    || path.split(/[\\/]/).pop() !== "auth.json") throw new Error("Invalid Orca credential location.");
+  try {
+    const accountDirectory = dirname(dirname(path)).split(/[\\/]/).pop()!;
+    if (readBoundedLocalFile(join(dirname(path), ".orca-managed-home"), 128).trim() !== accountDirectory) {
+      throw new Error("Orca home ownership marker does not match.");
+    }
+    return { ...parseOrcaAuth(readBoundedLocalFile(path)), sourceAuthPath: path };
+  }
+  catch { throw new Error("Orca credential unavailable; update the account in Orca and retry."); }
+}