@bitkyc08/opencodex 2.84.0 → 2.87.0

package/src/codex/inject/restore.ts

@@ -1,3 +1,4 @@
+import { restoreApprovedCodexProviders } from "../provider-routing";
 import { beginCodexWriteSection, cleanExternalProviderJournal, publishCodexArtifact } from "./config-write-section";
 import { assertCodexHomeOwner, codexHomeIsAbsent, codexHomeOwnerBlocksCompensation, CodexHomeOwnerRefusal, type CodexHomeOwnerRefusalReason } from "../codex-home-owner";
 import { loadConfig } from "../../config";
@@ -115,6 +116,7 @@ export interface CodexRestoreConfigResult {
     | "owned-fields-stripped"
     | "routing-restored-provider-retained"
     | "external-provider-preserved"
+    | "approved-provider-restored"
     | "failed";
   message: string;
   retained?: RetainedCodexProviderTable;
@@ -236,6 +238,26 @@ export function failedHistoryRestoreFromOutcome(
   return failedHistoryRestore(undefined, describeHistoryJobFailure(outcome, "restore"));
 }
 
+export function finishApprovedProviderRestore(result: CodexNativeRestoreResult, revalidateDesiredState = false): CodexNativeRestoreResult {
+  if (!result.success || revalidateDesiredState && shouldSyncCodexOnStart(loadConfig())) return result;
+  try {
+    if (!restoreApprovedCodexProviders()) return result;
+  } catch (error) {
+    if (error instanceof CodexHomeOwnerRefusal) throw error;
+    const message = `Approved Codex provider URL restoration failed: ${error instanceof Error ? error.message : String(error)}`;
+    return { ...result, success: false, message: `${result.message} ${message}`, artifacts: {
+      ...result.artifacts, config: { ...result.artifacts.config, state: "failed", action: "failed", message },
+    } };
+  }
+  const message = "Approved Codex provider URLs restored; identity, other settings and history preserved.";
+  return { ...result, message: result.externalProvider ? message : `${result.message} ${message}`, artifacts: {
+    ...result.artifacts,
+    config: { ...result.artifacts.config, state: result.artifacts.config.state === "partial" ? "partial" : "ok", changed: true,
+      action: result.artifacts.config.changed ? result.artifacts.config.action : "approved-provider-restored",
+      message: result.artifacts.config.state === "partial" ? `${result.artifacts.config.message} ${message}` : message },
+  } };
+}
+
 function externalProviderRestoreResult(activeProvider: string): CodexNativeRestoreResult {
   const message = `External Codex provider ${tomlString(activeProvider)} preserved; no native restore was needed.`;
   return {
@@ -553,7 +575,7 @@ export async function restoreNativeCodexAsync(
   if (sibling) return sibling;
   try {
     assertCodexHomeOwner(getCodexHome());
-    return await restoreNativeCodexAsyncImpl(options);
+    return finishApprovedProviderRestore(await restoreNativeCodexAsyncImpl(options), options.revalidateDesiredState);
   } catch (error) {
     if (error instanceof CodexHomeOwnerRefusal) return homeOwnerRestoreRefusal(error);
     if (!(error instanceof CodexRestoreRefusal)) throw error;
@@ -782,7 +804,7 @@ export function restoreNativeCodex(
   if (sibling) return sibling;
   try {
     assertCodexHomeOwner(getCodexHome());
-    return restoreNativeCodexImpl(options);
+    return finishApprovedProviderRestore(restoreNativeCodexImpl(options), options.revalidateDesiredState);
   } catch (error) {
     if (error instanceof CodexHomeOwnerRefusal) return homeOwnerRestoreRefusal(error);
     throw error;

package/src/codex/inject/routing-classify.ts

@@ -1,3 +1,4 @@
+import { isApprovedCodexProviderUrl } from "../provider-routing";
 import { existsSync, readFileSync } from "node:fs";
 import {
   hasInjectedCodexRouting,
@@ -54,7 +55,7 @@ export function classifyRoutingEndpoint(value: string): RoutingEndpointKind {
 }
 
 /** Classify actual routing dependency separately from opencodex ownership. */
-export function classifyCodexRouting(content: string): CodexRoutingKind {
+export function classifyCodexRouting(content: string, approvedProviderUrl?: (id: string, url: string) => boolean): CodexRoutingKind {
   const rootBaseUrl = rootTomlString(content, "openai_base_url");
   if (rootBaseUrl) {
     const endpoint = classifyRoutingEndpoint(rootBaseUrl);
@@ -74,7 +75,7 @@ export function classifyCodexRouting(content: string): CodexRoutingKind {
     if (providerBaseUrl) {
       const endpoint = classifyRoutingEndpoint(providerBaseUrl);
       if (endpoint === "unknown") return "unknown";
-      if (rootProvider === "opencodex") return "opencodex-local";
+      if (rootProvider === "opencodex" || endpoint === "local" && approvedProviderUrl?.(rootProvider, providerBaseUrl)) return "opencodex-local";
       return endpoint === "local" ? "custom-local" : "custom-remote";
     }
     if (
@@ -102,7 +103,7 @@ export function getCodexRoutingKind(): CodexRoutingKind {
   const path = CODEX_CONFIG_PATH;
   if (!existsSync(path)) return "native";
   try {
-    return classifyCodexRouting(readFileSync(path, "utf8"));
+    return classifyCodexRouting(readFileSync(path, "utf8"), isApprovedCodexProviderUrl);
   } catch {
     return "unknown";
   }

package/src/codex/inject.ts

@@ -1,3 +1,4 @@
+import { injectApprovedCodexProvider } from "./provider-routing";
 import { beginCodexWriteSection, cleanExternalProviderJournal, publishCodexArtifact } from "./inject/config-write-section";
 import { closeSync, existsSync, openSync, readFileSync, statSync } from "node:fs";
 import { dirname } from "node:path";
@@ -46,8 +47,8 @@ import {
   writeJournal,
 } from "./journal";
 import { HISTORY_RELABEL_STANDS_DOWN } from "./history-provider";
+import { formatApplyHistoryFailure } from "./inject/history-failure";
 import {
-  describeHistoryJobFailure,
   deriveCodexHistoryOperation,
   resolveCodexHistoryJobTarget,
   runCodexHistoryJob,
@@ -142,6 +143,8 @@ export interface CodexInjectResult {
   message: string;
   /** False when injection intentionally preserves configuration owned by another provider. */
   configApplied?: false;
+  /** True only after a successful configuration transaction changes config.toml bytes. */
+  configChanged?: boolean;
   /**
    * Structured read-only history preflight refusal; never parsed from display text.
    *
@@ -240,6 +243,10 @@ async function injectCodexConfigImpl(
   const rawContent = missingConfig ? "" : readFileSync(CODEX_CONFIG_PATH, "utf-8");
   const activeProvider = externalCodexModelProvider(rawContent);
   if (activeProvider) {
+    const approved = injectApprovedCodexProvider(activeProvider, routingTarget, options.beforeClientWrite ? () => runClientWriteGuard(options.beforeClientWrite) : undefined, options.validateOnly);
+    if (approved) {
+      return { success: true, configChanged: approved.configChanged, ...(options.validateOnly ? { configApplied: false as const } : {}), message: `Approved Codex provider ${tomlString(activeProvider)} routes through OpenCodex; provider identity and transport settings preserved.` };
+    }
     // A launcher may have journaled before the provider manager took ownership. Never let shutdown
     // replay that stale snapshot over externally managed config.
     if (!options.validateOnly) {
@@ -258,7 +265,7 @@ async function injectCodexConfigImpl(
         : {}),
       message:
         `⚠️ Codex routing NOT injected: config.toml selects the external model_provider ${tomlString(activeProvider)}.\n` +
-        `  OpenCodex preserves external provider configuration so existing ${tomlString(activeProvider)} session history stays visible.\n` +
+        `  OpenCodex preserves external provider configuration so existing ${tomlString(activeProvider)} session history stays visible.\n  To authorize URL-only management, run ocx codex-provider allow ${tomlString(activeProvider)} and confirm.\n` +
         `  Configure that provider for Responses passthrough at ${routingTarget.baseUrl}` +
         `${routingTarget.requiresAdmissionToken ? ` with x-opencodex-api-key from ${routingTarget.tokenEnv}` : ""}.\n` +
         `  For direct injection, switch to the built-in openai provider, remove any user-owned root openai_base_url, and rerun 'ocx start'.`,
@@ -717,6 +724,11 @@ async function injectCodexConfigImpl(
     releaseConfigWriteLock(configLock.handle);
     heldConfigWriteLock = undefined;
   }
+  // Both write paths have committed, including the coordinator's post-callback checks.
+  // Compare against the admitted original, not post-v1-reconcile input: the native
+  // feature transition is part of this transaction too. Refusals/rollbacks return
+  // above and must never publish this receipt. No filesystem reread after unlock.
+  const configChanged = Boolean(missingConfig) || effectivePlan.content !== rawContent;
   // Legacy mode still forward-tags history so re-tagged threads stay listable. Design B needs
   // the opposite: a one-time migration of previously re-tagged threads BACK to openai (restore
   // machinery; cheap no-op when there is nothing to migrate). The client-compaction opt-in keeps
@@ -799,6 +811,7 @@ async function injectCodexConfigImpl(
   if (effectivePlan.keptUserBaseUrl && effectivePlan.keepRootOverrideAlongsideTable) {
     return {
       success: true,
+      configChanged,
       ...(effectivePlan.nativeSubagentDefaultsWarning ? { nativeSubagentDefaultsWarning: effectivePlan.nativeSubagentDefaultsWarning } : {}),
       ...(effectivePlan.historyRelabelRefusal ? { historyPreflightFailureReason: effectivePlan.historyRelabelRefusal } : {}),
       message:
@@ -817,6 +830,7 @@ async function injectCodexConfigImpl(
   if (effectivePlan.keptUserBaseUrl) {
     return {
       success: true,
+      configChanged,
       ...(effectivePlan.nativeSubagentDefaultsWarning
         ? { nativeSubagentDefaultsWarning: effectivePlan.nativeSubagentDefaultsWarning }
         : {}),
@@ -839,6 +853,7 @@ async function injectCodexConfigImpl(
       : `Pointed Codex's built-in openai provider at the opencodex proxy (openai_base_url + realtime sideband override).\n`;
   return {
     success: true,
+    configChanged,
     ...(effectivePlan.nativeSubagentDefaultsWarning ? { nativeSubagentDefaultsWarning: effectivePlan.nativeSubagentDefaultsWarning } : {}),
     ...(effectivePlan.historyRelabelRefusal ? { historyPreflightFailureReason: effectivePlan.historyRelabelRefusal } : {}),
     message:
@@ -860,31 +875,7 @@ export function getCodexConfigPath(): string {
   return CODEX_CONFIG_PATH;
 }
 
-/**
- * Frame one failed apply history job honestly.
- *
- * A genuine lock keeps the established deferred/SKIPPED wording; any other
- * reason names itself instead of blaming the Codex app/IDE.
- */
-export function formatApplyHistoryFailure(outcome: CodexHistoryJobOutcome, legacyMode: boolean): string {
-  // A busy database is a deferral no matter which half observed it: the lock
-  // contended (blocked/busy), or the worker acquired the lock and then found
-  // SQLite busy (failed with a busy history reason). Only those keep the
-  // deferred headline; every other failure is a real "NOT changed".
-  const busy =
-    (outcome.kind === "blocked" && outcome.reason === "busy") ||
-    (outcome.kind === "failed" && outcome.historyFailureReason === "busy");
-  const partiallyChanged = outcome.kind === "failed"
-    && ((outcome.rows ?? 0) > 0 || (outcome.files ?? 0) > 0);
-  const headline = partiallyChanged
-    ? "Codex resume history changed but did not converge"
-    : legacyMode
-      ? "Codex resume history sync SKIPPED"
-      : busy
-      ? "Codex resume history metadata restore deferred"
-      : "Codex resume history NOT changed";
-  return `  ⚠️ ${headline}: ${describeHistoryJobFailure(outcome, "apply", legacyMode)}\n`;
-}
+export { formatApplyHistoryFailure };
 
 export {
   providerBaseHost,

package/src/codex/journal.ts

@@ -1,7 +1,7 @@
 import { beginCodexWriteSection, publishCodexArtifact } from "./inject/config-write-section";
 import { createHash } from "node:crypto";
 import type { AtomicWriteHooks } from "../config/atomic-write";
-import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { existsSync, lstatSync, readFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { atomicWriteFile } from "../config";
 import { assertCodexHomeOwner, codexHomeIsAbsent, CODEX_HOME_JOURNAL_FILE, CodexHomeOwnerRefusal, opencodexHomeForInjection, readCodexHomeJournal, type CodexHomeOwnerRefusalReason } from "./codex-home-owner";
@@ -347,6 +347,21 @@ export function restoreJournalState(
     };
   }
 
+  // A matching byte hash does not authorize following a newly substituted profile link.
+  // Refuse the complete pair before restoring config or deleting its recovery journal.
+  let profileIsSymlink = false;
+  if (profileUnchanged && (!comparison.profileAlreadyOriginal || comparison.originalProfile === null)) {
+    try { profileIsSymlink = lstatSync(CODEX_PROFILE_PATH).isSymbolicLink(); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+  }
+  if (profileIsSymlink) {
+    return {
+      configRestored: comparison.configAlreadyOriginal, profileRestored: false,
+      configRewritten: false, profileRewritten: false,
+      configChanged: !configUnchanged, profileChanged: false,
+      complete: false, unverified: false, profileRestoreFailed: true as const,
+    };
+  }
   assertCodexHomeOwner(CODEX_HOME);
   let configRestored = comparison.configAlreadyOriginal;
   let profileRestored = comparison.profileAlreadyOriginal;

package/src/codex/main-account-hard-lock.ts

@@ -1,4 +1,7 @@
 import type { OcxConfig } from "../types";
+import { MAIN_CODEX_ACCOUNT_ID } from "./account-id";
+import { codexAccountUsesRemainingQuota } from "./account-use-remaining";
+import { isDeclaredReasoningEffort } from "../reasoning-effort";
 import { getMainPolicyQuota } from "./quota";
 import { MAIN_ACCOUNT_HARD_LOCK_PERCENT, MAIN_ACCOUNT_HARD_LOCK_SHORT_PERCENT, MAIN_ACCOUNT_HARD_LOCK_MIN_PERCENT } from "./quota-types";
 
@@ -13,9 +16,35 @@ export interface MainAccountHardLockStatus {
   window?: "short" | "long";
 }
 
-type PolicyConfig = Pick<OcxConfig, "codexMainAccountHardLock" | "codexMainAccountHardLockThresholds">;
+type PolicyConfig = Pick<OcxConfig, "codexMainAccountHardLock" | "codexMainAccountHardLockThresholds" | "codexMainAccountHardLockFallback" | "codexUseRemainingQuotaAccountIds">;
+
+/** The reroute destination for requests the lock blocks, when one is configured and readable. */
+export interface MainAccountHardLockFallback {
+  model: string;
+  reasoningEffort?: string;
+}
+
+/**
+ * The configured fallback, or `undefined` when nothing qualifies. The dashboard row keeps
+ * the configured model while its switch is off, so `enabled: false` pauses the reroute
+ * without forgetting the destination. A malformed hand edit — blank or padded model,
+ * undeclared effort — disables the reroute entirely rather than degrading into a
+ * half-applied one: the request path must never guess which part of a broken setting to
+ * keep. This is the same disable-don't-widen reading the compaction override takes, and
+ * the load/write boundaries report the malformation separately.
+ */
+export function resolveMainAccountHardLockFallback(config: PolicyConfig | undefined): MainAccountHardLockFallback | undefined {
+  const raw = config?.codexMainAccountHardLockFallback;
+  if (!raw || raw.enabled === false) return undefined;
+  const model = typeof raw.model === "string" ? raw.model : "";
+  if (model.length === 0 || model !== model.trim() || /\s/.test(model)) return undefined;
+  if (raw.reasoningEffort !== undefined
+    && (typeof raw.reasoningEffort !== "string" || !isDeclaredReasoningEffort(raw.reasoningEffort))) return undefined;
+  return raw.reasoningEffort !== undefined ? { model, reasoningEffort: raw.reasoningEffort } : { model };
+}
 
 export function resolveMainAccountHardLockThresholds(config: PolicyConfig | undefined): { short: number; long: number } {
+  if (codexAccountUsesRemainingQuota(config, MAIN_CODEX_ACCOUNT_ID)) return { short: 100, long: 100 };
   const valid = (value: unknown, fallback: number): number => typeof value === "number"
     && Number.isInteger(value) && value >= MAIN_ACCOUNT_HARD_LOCK_MIN_PERCENT && value <= 100 ? value : fallback;
   const long = valid(config?.codexMainAccountHardLockThresholds?.long, MAIN_ACCOUNT_HARD_LOCK_PERCENT);

package/src/codex/main-account.ts

@@ -31,6 +31,12 @@ import { advanceCodexCredentialMutationEpoch } from "./credential-mutation-epoch
 import { withNativeMainExclusiveClaim } from "./native-main-claim";
 import { resolveNativeProfileContext } from "./native-profile-store";
 import { isNativeMainTrafficBlocked } from "./native-profile-startup";
+import { loadConfig } from "../config";
+import {
+  requestCodexAuthStatus,
+  resolveNativeMainRefreshMode,
+  type CodexAuthStatus,
+} from "./native-main-refresh-mode";
 
 export { MAIN_CODEX_ACCOUNT_ID } from "./account-id";
 
@@ -48,13 +54,11 @@ type MainAuthJsonCredential = {
   path: string;
   rawSha256: string;
   /**
-   * Filesystem identity of the file the hash was taken from (#2999).
-   *
-   * A content hash cannot tell "unchanged" from "replaced with a file that happens to
-   * hash the same", and more importantly it is read at a different instant than the
-   * rename. Carrying dev+ino lets the pre-rename guard ask the sharper question: is this
-   * still the same file, not merely one with the same bytes. `null` when the target could
-   * not be stat'ed, which is treated as "cannot prove identity" rather than "matches".
+   * Filesystem identity of the file the hash was taken from. It catches a writer that
+   * replaces auth.json by rename with identical bytes. It does not see Codex's own writes:
+   * Codex rewrites auth.json in place (truncate + write), which keeps dev and ino, so only
+   * the content hash notices those, and only once the new bytes are visible (#2999).
+   * `null` when the target could not be stat'ed, which fails closed.
    */
   identity: { dev: number; ino: number } | null;
   root: Record<string, unknown>;
@@ -66,6 +70,8 @@ type MainAuthJsonCredential = {
 
 export interface NativeMainRefreshDependencies {
   refreshToken?: (refreshToken: string, options: { signal: AbortSignal }) => Promise<OAuthCredentials>;
+  /** Codex-mode seam: one app-server `getAuthStatus` call. Used only when Codex owns the refresh. */
+  codexAuthStatus?: (options: { refresh: boolean; signal: AbortSignal }) => Promise<CodexAuthStatus>;
   signal?: AbortSignal;
   /** Metadata-only refresh must not retract a concurrent traffic reauth quarantine. */
   preserveReauth?: boolean;
@@ -264,10 +270,9 @@ function assertMainAuthJsonSnapshotUnchanged(expected: MainAuthJsonCredential):
   if (!current || current.path !== expected.path || current.rawSha256 !== expected.rawSha256) {
     throw new MainAuthJsonChangedDuringRefreshError();
   }
-  // Identity, not just content (#2999). A writer can land between this check and the
-  // rename, and rename(2) replaces unconditionally - so the narrower the question asked
-  // here, the smaller the window where a Codex login gets silently overwritten. An
-  // unreadable identity on either side fails closed: unprovable is not the same as equal.
+  // Also refuse a rename-based replacement with identical bytes. An unreadable identity on
+  // either side fails closed. This narrows the window; rename(2) still replaces
+  // unconditionally after this check returns.
   assertMainAuthJsonIdentityUnchanged(expected);
 }
 
@@ -288,9 +293,7 @@ function persistRefreshedMainAuthJson(
   assertNotRealCodexHomeUnderTest(resolveCodexHomeDir());
   const accessToken = refreshed.access;
   const refreshToken = refreshed.refresh || expected.refreshToken!;
-  const chatgptAccountId = refreshed.accountId
-    ?? extractAccountId(undefined, accessToken)
-    ?? expected.chatgptAccountId;
+  const { chatgptAccountId } = inFlightMainAccountToken(expected, refreshed);
   const tokens = {
     ...expected.tokens,
     access_token: accessToken,
@@ -475,6 +478,12 @@ async function resolveMainAccountToken(
   const signal = dependencies.signal
     ? AbortSignal.any([dependencies.signal, refreshTimeout])
     : refreshTimeout;
+  // An injected exchange is the guarded writer by definition. Otherwise Codex refreshes its own
+  // login whenever a supported binary exists, unless the operator chose "opencodex" (#2999).
+  const refreshMode = dependencies.refreshToken
+    ? null
+    : await resolveNativeMainRefreshMode(loadConfig());
+  if (signal.aborted) throw signal.reason;
   const lockKey = refreshGrantFingerprintForToken(initial.refreshToken);
   // Two locks, because they guard two different things that live in two different
   // homes. `withCodexRefreshFileLock` is keyed on the grant fingerprint and lives
@@ -508,6 +517,11 @@ async function resolveMainAccountToken(
           && mainAccessTokenFresh(locked.accessToken, Date.now(), MAIN_TOKEN_REFRESH_SKEW_MS)) {
           return { accessToken: locked.accessToken!, chatgptAccountId: locked.chatgptAccountId };
         }
+        if (refreshMode?.mode === "codex") {
+          const command = refreshMode.command!;
+          return refreshThroughCodex(locked, rejectedAccessToken, dependencies, refreshTimeout,
+            dependencies.codexAuthStatus ?? (options => requestCodexAuthStatus(command, options)));
+        }
         const refresh = dependencies.refreshToken ?? refreshNativeMainGrant;
         let refreshed: OAuthCredentials;
         if (signal.aborted) throw signal.reason;
@@ -539,7 +553,19 @@ async function resolveMainAccountToken(
         // Once the exchange starts, only its own timeout may abort it: a successful
         // rotating grant retires the old refresh token. Save the only live grant before
         // honoring caller cancellation, while retaining the external-writer guards.
-        const result = persistRefreshedMainAuthJson(locked, refreshed);
+        let result: { accessToken: string; chatgptAccountId: string };
+        try {
+          result = persistRefreshedMainAuthJson(locked, refreshed);
+        } catch (cause) {
+          if (!(cause instanceof MainAuthJsonChangedDuringRefreshError)) throw cause;
+          // Another writer owns auth.json now (#2999). The exchange already succeeded, so
+          // failing the request would waste it. Serve the new access token to this request
+          // only: leave the file as the other writer left it, keep nothing as the main
+          // credential, and do not retire the grant.
+          noteNativeMainRefresh("publish-refused-served-in-flight");
+          if (dependencies.signal?.aborted) throw dependencies.signal.reason;
+          return inFlightMainAccountToken(locked, refreshed);
+        }
         // A permitted in-flight success speaks only for its own profile and grant.
         clearMainRefreshGrantRejection(mainRefreshGrantKey(locked)!);
         if (dependencies.preserveReauth !== true) clearAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
@@ -556,6 +582,64 @@ async function resolveMainAccountToken(
   }
 }
 
+/** The refreshed bearer for one request whose save was refused; never stored anywhere. */
+function inFlightMainAccountToken(
+  expected: MainAuthJsonCredential,
+  refreshed: OAuthCredentials,
+): { accessToken: string; chatgptAccountId: string } {
+  return {
+    accessToken: refreshed.access,
+    chatgptAccountId: refreshed.accountId
+      ?? extractAccountId(undefined, refreshed.access)
+      ?? expected.chatgptAccountId,
+  };
+}
+
+/**
+ * Codex mode (#2999): Codex refreshes and stores its own login; OpenCodex only uses the bearer.
+ *
+ * auth.json is not read again after the call. In keyring mode Codex deletes the file once the
+ * keyring save succeeds, so the RPC answer is the only place the new token exists for us.
+ * The call runs on the refresh timeout alone: killing app-server mid-exchange could retire
+ * the grant before Codex saves its successor.
+ */
+async function refreshThroughCodex(
+  locked: MainAuthJsonCredential,
+  rejectedAccessToken: string | undefined,
+  dependencies: NativeMainRefreshDependencies,
+  refreshTimeout: AbortSignal,
+  authStatus: NonNullable<NativeMainRefreshDependencies["codexAuthStatus"]>,
+): Promise<{ accessToken: string; chatgptAccountId: string }> {
+  let status: CodexAuthStatus;
+  try {
+    status = await authStatus({ refresh: true, signal: refreshTimeout });
+  } catch (cause) {
+    noteNativeMainRefresh("codex-unavailable");
+    throw new MainAccountTokenRefreshError("transient", { cause });
+  }
+  if (status.authMethod === "chatgpt" && !status.authToken) {
+    // The only permanent-failure signal the response carries: Codex withholds the token once
+    // its refresh was refused for good. The specific OAuth code is not on the wire.
+    noteNativeMainRefresh("codex-reauth");
+    markMainRefreshGrantRejected(mainRefreshGrantKey(locked)!);
+    throw new MainAccountTokenRefreshError("reauth");
+  }
+  const token = status.authToken;
+  if (status.authMethod !== "chatgpt" || !token) {
+    noteNativeMainRefresh("codex-no-chatgpt-login");
+    throw new MainAccountTokenRefreshError("transient");
+  }
+  // A transient Codex refresh failure still answers with its cached bearer.
+  if (token === rejectedAccessToken || !mainAccessTokenFresh(token, Date.now(), 0)) {
+    noteNativeMainRefresh("codex-transient");
+    throw new MainAccountTokenRefreshError("transient");
+  }
+  noteNativeMainRefresh("codex-ok");
+  if (dependencies.preserveReauth !== true) clearAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
+  if (dependencies.signal?.aborted) throw dependencies.signal.reason;
+  return { accessToken: token, chatgptAccountId: extractAccountId(undefined, token) ?? locked.chatgptAccountId };
+}
+
 /** Refresh the CLI-owned native credential before upstream I/O and publish it atomically. */
 export function getValidMainAccountToken(
   dependencies: NativeMainRefreshDependencies = {},