@bitkyc08/opencodex 2.57.0 → 2.59.0

package/src/codex/main-account.ts

@@ -296,7 +296,10 @@ function persistNativeMainReauthTokens(
  *     main account's reauth quarantine for the new credential generation.
  */
 export function beginNativeMainReauth(): {
-  commit: (tokens: NativeMainReauthTokens) => Promise<{ chatgptAccountId: string }>;
+  commit: (
+    tokens: NativeMainReauthTokens,
+    options?: { signal?: AbortSignal },
+  ) => Promise<{ chatgptAccountId: string }>;
 } {
   const expected = readMainAuthJsonCredential();
   if (!expected || !expected.chatgptAccountId) {
@@ -305,7 +308,10 @@ export function beginNativeMainReauth(): {
     );
   }
   return {
-    async commit(tokens: NativeMainReauthTokens): Promise<{ chatgptAccountId: string }> {
+    async commit(
+      tokens: NativeMainReauthTokens,
+      options: { signal?: AbortSignal } = {},
+    ): Promise<{ chatgptAccountId: string }> {
       if (!tokens.accessToken || !tokens.refreshToken || !tokens.idToken) {
         throw new NativeMainReauthUnavailableError("Device grant did not produce a complete token set");
       }
@@ -322,11 +328,12 @@ export function beginNativeMainReauth(): {
             "Native main traffic is blocked by startup or recovery state",
           );
         }
+        if (options.signal?.aborted) throw options.signal.reason;
         assertMainAuthJsonSnapshotUnchanged(expected);
         persistNativeMainReauthTokens(expected, tokens);
         clearAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
         return { chatgptAccountId: tokens.chatgptAccountId };
-      }, { waitMs: 30_000 });
+      }, { waitMs: 30_000, signal: options.signal });
     },
   };
 }

package/src/codex/main-device-reauth.ts

@@ -54,7 +54,9 @@ interface ActiveFlow {
   /** Set once auth.json has been replaced; cancellation can no longer win. */
   published: boolean;
   /** Snapshot-holding commit prepared at start; closure-private identity. */
-  prepared?: { commit: (tokens: NativeMainReauthTokens) => Promise<{ chatgptAccountId: string }> };
+  prepared?: {
+    commit: (tokens: NativeMainReauthTokens, options?: { signal?: AbortSignal }) => Promise<{ chatgptAccountId: string }>;
+  };
 }
 
 /** Bounded terminal retention so status/cancel stay answerable after completion. */
@@ -65,7 +67,9 @@ const terminalFlows = new Map<string, { status: MainDeviceReauthStatus; expiresA
 
 export interface MainDeviceReauthDeps {
   login?: (ctrl: OAuthController) => Promise<NativeDeviceLogin>;
-  beginCommit?: () => { commit: (tokens: NativeMainReauthTokens) => Promise<{ chatgptAccountId: string }> };
+  beginCommit?: () => {
+    commit: (tokens: NativeMainReauthTokens, options?: { signal?: AbortSignal }) => Promise<{ chatgptAccountId: string }>;
+  };
   flowId?: () => string;
   now?: () => number;
 }
@@ -81,10 +85,13 @@ function sweepTerminal(now: number): void {
 }
 
 function finish(flow: ActiveFlow, status: MainDeviceReauthStatus, now: number): void {
-  // Publication beats a racing cancellation: once auth.json was replaced the
-  // honest terminal is succeeded, never cancelled (080). Every other terminal
-  // is first-write-wins so a superseded or cancelled completion cannot
-  // publish a later result.
+  // Terminal results are first-write-wins, with one exception (080): once the
+  // commit actually replaced auth.json, the honest terminal is succeeded. The
+  // signal now fences the claim wait and the pre-write recheck, but it cannot
+  // fence the gap between the synchronous write and this call — the claim
+  // teardown and the promise resolution both yield, so a cancel arriving there
+  // would otherwise report "cancelled" for a credential that was replaced and
+  // a reauth quarantine that was cleared.
   if (isTerminal(flow.status)) {
     if (!(flow.published && status.status === "succeeded")) return;
   }
@@ -165,15 +172,16 @@ export function startMainDeviceReauth(deps: MainDeviceReauthDeps = {}): MainDevi
       if (flow.controller.signal.aborted) return;
       if (!isTerminal(flow.status)) flow.status = { flowId, status: "committing" };
       // Recheck immediately before the write: a cancel that landed while the
-      // grant was resolving must not reach auth.json. Once the commit DOES
-      // publish, the terminal is succeeded even if a cancel raced it (080).
+      // grant was resolving must not reach auth.json. The commit itself is
+      // fenced by the same signal, so a cancel delivered while the claim
+      // waits aborts the publication instead of racing it.
       if (activeFlow !== flow || flow.controller.signal.aborted || isTerminal(flow.status)) return;
       await flow.prepared!.commit({
         accessToken: grant.credential.access,
         refreshToken: grant.credential.refresh,
         idToken: grant.idToken,
         chatgptAccountId: grant.credential.accountId!,
-      });
+      }, { signal: flow.controller.signal });
       flow.published = true;
       finish(flow, { flowId, status: "succeeded", credentialUpdated: true }, clock());
     } catch (error) {

package/src/codex/model-entitlements.ts

@@ -17,6 +17,13 @@ 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,
+  resetObservedCodexModelDenialsForTests,
+} from "./observed-model-denials";
 
 const CODEX_MODELS_ENDPOINT = "https://chatgpt.com/backend-api/codex/models";
 
@@ -870,6 +877,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 +1292,63 @@ 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).
+  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);
+  }
   // 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.
+ */
+export function recordCodexModelDenialEvidence(
+  accountId: string | null | undefined,
+  modelId: string | undefined,
+  now = Date.now(),
+): void {
+  if (!accountId || !modelId) return;
+  if (!ENTITLEMENT_PREFERRED_NATIVE_OPENAI_MODELS.has(modelId)) return;
+  recordObservedCodexModelDenial(accountId, modelId, now);
+}
+
+/** Drop the refusal evidence for a pair the account has just served successfully. */
+export function clearCodexModelDenialEvidence(
+  accountId: string | null | undefined,
+  modelId: string | undefined,
+): void {
+  if (!accountId || !modelId) return;
+  clearObservedCodexModelDenial(accountId, modelId);
+}
+
 /** Synchronous projection for management/catalog readers after a discovery pass. */
 export function cachedAvailableAccountGatedNativeModels(
   now = Date.now(),
@@ -1351,6 +1409,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/native-profile-startup.ts

@@ -308,6 +308,47 @@ function observeOwner(entry: StartupEntry, owner: NativeMainOwnerSnapshot): void
  * Retain process ownership for one live server. The first reference acquires the
  * canonical-home SQLite lease and owns recovery; later same-process references share it.
  */
+/**
+ * Releases nobody is awaiting.
+ *
+ * A release closes the native-main owner's SQLite lease and its stable lock file, both of which
+ * live under CODEX_HOME. The normal shutdown path awaits it: `server.stop` goes through
+ * `releaseNativeMainStartupLifecycle`, which awaits the flight. The FAILED-start path does not —
+ * `startServer` must stay synchronous, so its rollback can only fire `void lifecycle.release()`
+ * and rethrow. Nothing could then wait for those handles to close, and on Windows an open handle
+ * does not delay an unlink, it refuses it outright with EPERM.
+ *
+ * That is invisible in production, where a failed start is followed by exit rather than by
+ * deleting the home. It is not invisible to a test whose cleanup removes the home it just used:
+ * `tests/server/server-management-auth.test.ts` binds a management ingress on the fixed port
+ * 10101, which nine other test files also use, so a collision on the six-shard Windows leg turns
+ * a passing start into the rollback path. The failure followed that collision across shards 1, 2
+ * and 3 while staying on the same file and line, which is what a shard-independent trigger looks
+ * like.
+ *
+ * Tracking the flight here rather than at the call site keeps `startServer` synchronous and
+ * unchanged, and gives anyone who needs the handles closed something to await.
+ */
+const pendingStartupReleases = new Set<Promise<void>>();
+
+function trackStartupRelease(release: Promise<void>): Promise<void> {
+  const tracked = release.finally(() => { pendingStartupReleases.delete(tracked); });
+  pendingStartupReleases.add(tracked);
+  return tracked;
+}
+
+/**
+ * Settle every native-main startup release still in flight, including ones nobody awaited.
+ *
+ * Loops rather than awaiting a single snapshot: a release can retire an owner whose own teardown
+ * starts another, and draining only the first batch would return with handles still open.
+ */
+export async function flushNativeMainStartupReleases(): Promise<void> {
+  while (pendingStartupReleases.size > 0) {
+    await Promise.allSettled([...pendingStartupReleases]);
+  }
+}
+
 export function startNativeMainStartupLifecycle(
   deps: NativeMainStartupGateDeps = {},
 ): NativeMainStartupLifecycle {
@@ -352,29 +393,32 @@ export function startNativeMainStartupLifecycle(
   }
   entry.refs += 1;
   let released = false;
+  const performRelease = async (): Promise<void> => {
+    if (released) return;
+    released = true;
+    entry!.refs = Math.max(0, entry!.refs - 1);
+    if (entry!.refs !== 0) return;
+    entry!.epoch += 1;
+    entry!.sweepStopping = true;
+    if (entry!.sweepTimer) clearTimeout(entry!.sweepTimer);
+    entry!.sweepTimer = undefined;
+    entry!.unsubscribe();
+    startupEntries.delete(homeId);
+    entry!.resolveAcquisition?.(snapshot);
+    entry!.resolveAcquisition = undefined;
+    // Startup convergence can transition from the exclusive recovery claim
+    // into a stage sweep. Keep the owner registered until that entire chain
+    // settles so no cleanup transaction starts untracked after owner detach.
+    await Promise.allSettled([entry!.settled]);
+    if (entry!.sweepInFlight) await Promise.allSettled([entry!.sweepInFlight]);
+    await entry!.owner.release();
+  };
   return {
     homeId,
     get settled() { return entry!.settled; },
-    async release() {
-      if (released) return;
-      released = true;
-      entry!.refs = Math.max(0, entry!.refs - 1);
-      if (entry!.refs !== 0) return;
-      entry!.epoch += 1;
-      entry!.sweepStopping = true;
-      if (entry!.sweepTimer) clearTimeout(entry!.sweepTimer);
-      entry!.sweepTimer = undefined;
-      entry!.unsubscribe();
-      startupEntries.delete(homeId);
-      entry!.resolveAcquisition?.(snapshot);
-      entry!.resolveAcquisition = undefined;
-      // Startup convergence can transition from the exclusive recovery claim
-      // into a stage sweep. Keep the owner registered until that entire chain
-      // settles so no cleanup transaction starts untracked after owner detach.
-      await Promise.allSettled([entry!.settled]);
-      if (entry!.sweepInFlight) await Promise.allSettled([entry!.sweepInFlight]);
-      await entry!.owner.release();
-    },
+    // Tracked so a caller that cannot await -- the synchronous rollback in `startServer` -- still
+    // leaves the flight drainable through `flushNativeMainStartupReleases`.
+    release: () => trackStartupRelease(performRelease()),
   };
 }
 

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

@@ -0,0 +1,137 @@
+/**
+ * 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;
+
+/** `accountId\u0000modelId` -> expiry. Insertion order is the eviction order. */
+const observedDenials = new Map<string, number>();
+
+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,
+  now = Date.now(),
+): void {
+  const key = denialKey(accountId, modelId);
+  // Delete before set so the refreshed entry moves to the back of the eviction order.
+  observedDenials.delete(key);
+  observedDenials.set(key, now + OBSERVED_DENIAL_TTL_MS);
+  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): void {
+  observedDenials.delete(denialKey(accountId, modelId));
+}
+
+/**
+ * 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(),
+): ReadonlySet<string> | undefined {
+  if (!modelId) return undefined;
+  const denied = new Set<string>();
+  for (const [key, expiresAt] of [...observedDenials]) {
+    if (expiresAt <= now) {
+      observedDenials.delete(key);
+      continue;
+    }
+    if (modelIdOfDenialKey(key) === modelId) denied.add(accountIdOfDenialKey(key));
+  }
+  return denied.size > 0 ? denied : undefined;
+}
+
+export function resetObservedCodexModelDenialsForTests(): void {
+  observedDenials.clear();
+}

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."); }
+}