@bitkyc08/opencodex 2.76.0 → 2.78.0-preview.20261005

package/src/codex/internal/catalog-writer.ts

@@ -5,12 +5,21 @@ import {
   AtomicWriteResidualTempError,
   AtomicWriteSecretResidualError,
   atomicWriteFile,
-  getConfigDir,
   resolveWriteTarget,
   type AtomicWriteIO,
-} from "../../config";
+} from "../../config/atomic-write";
+import { getConfigDir } from "../../config/paths";
+import { readConfigAdmissionSnapshot } from "../../config/diagnostics";
+import { ConfigMutationLockError, withConfigMutationLockSync } from "../../config/mutation-lock";
+import { codexCatalogAuditPath } from "../catalog/write-audit";
+import type { CatalogAuditConfigSource, CatalogAuditRefusalReason, CatalogWriteAuditDetails } from "../catalog/write-audit-contract";
+import { ocxRoutedRowCount } from "../catalog/routed-removal";
+import { notifyCatalogPublication } from "../catalog/publication-observer";
 import {
   assertCatalogWritePermit,
+  auditCatalogWriteWithPermit,
+  catalogWritePermitContext,
+  CatalogWritePermitRefusal,
   type CatalogWritePermit,
 } from "../catalog-write-serialization";
 import {
@@ -61,14 +70,15 @@ let backupTempSequence = 0;
  * An unreadable or absent file reports "differs", so the caller performs the real
  * write; that also converges a file that does not exist yet.
  */
-export function preparedBytesDifferFromDisk(prepared: PreparedCatalogFileWrite): boolean {
-  let onDisk: Buffer;
-  try {
-    onDisk = readFileSync(prepared.path);
-  } catch {
-    return true;
-  }
-  return !onDisk.equals(Buffer.from(prepared.content, "utf8"));
+function readExistingCatalogBytes(path: string): Buffer | null {
+  try { return readFileSync(path); } catch { return null; }
+}
+
+export function preparedBytesDifferFromDisk(
+  prepared: PreparedCatalogFileWrite,
+  onDisk: Buffer | null = readExistingCatalogBytes(prepared.path),
+): boolean {
+  return onDisk === null || !onDisk.equals(Buffer.from(prepared.content, "utf8"));
 }
 
 function isMissingPathError(error: unknown): boolean {
@@ -199,16 +209,105 @@ function publishCatalogBackup(
   return "written";
 }
 
-/** Replace the active catalog with the caller's already-prepared bytes. */
+export type CatalogFileReplacement =
+  | { readonly kind: "written" }
+  | { readonly kind: "unchanged" }
+  | { readonly kind: "refused"; readonly reason: "unbacked-routed-clear" };
+
+function routedRowsFromJson(content: string): number | null {
+  try { return ocxRoutedRowCount(JSON.parse(content)); } catch { return null; }
+}
+
+function configSourceNow(): CatalogAuditConfigSource {
+  try {
+    const snapshot = readConfigAdmissionSnapshot();
+    return snapshot.kind === "read" ? snapshot.diagnostics.source
+      : snapshot.diagnostics.source === "default" ? "default" : "unreadable";
+  } catch { return "unreadable"; }
+}
+
+function routedRowsOnDisk(path: string): number | null {
+  try { return routedRowsFromJson(readFileSync(path, "utf8")); } catch { return null; }
+}
+
+function auditWrite(
+  permit: CatalogWritePermit,
+  home: string,
+  details: CatalogWriteAuditDetails,
+  register: boolean,
+): void {
+  try {
+    if (auditCatalogWriteWithPermit(permit, home, details) !== "created"
+      || !register || details.configSource !== "file") return;
+    // The manifest rejects external CODEX_HOME paths. Such audit files remain uninstall
+    // residuals; diagnostic creation does not widen config ownership or claim cleanup.
+    if (!recordOwnedConfigPath(getConfigDir(), codexCatalogAuditPath(home))) return;
+  } catch { /* Audit and registration failures cannot change the publication outcome. */ }
+}
+
+/** Audit an actual refusal before the replacement funnel. Caller must avoid a second funnel event. */
+export function auditRefusedCatalogReplacement(
+  permit: CatalogWritePermit,
+  home: string,
+  prepared: PreparedCatalogFileWrite,
+  reason: CatalogAuditRefusalReason,
+): void {
+  assertCatalogWritePermit(permit, home);
+  auditWrite(permit, home, {
+    target: "catalog", outcome: "refused", reason,
+    routedBefore: routedRowsOnDisk(prepared.path), routedAfter: routedRowsFromJson(prepared.content),
+    configSource: configSourceNow(),
+  }, true);
+}
+
+/** One funnel for exact-byte idempotence and intent admission, under a live K permit. */
 export function replaceActiveCodexCatalog(
   permit: CatalogWritePermit,
   owningCodexHome: string,
   prepared: PreparedCatalogFileWrite,
   io?: AtomicWriteIO,
-): void {
+): CatalogFileReplacement {
   assertCatalogWritePermit(permit, owningCodexHome);
+  const { intent } = catalogWritePermitContext(permit);
+  if (intent === "cache") {
+    throw new CatalogWritePermitRefusal("A models-cache permit cannot replace the Codex catalog.");
+  }
+  const onDisk = readExistingCatalogBytes(prepared.path);
+  if (!preparedBytesDifferFromDisk(prepared, onDisk)) {
+    notifyCatalogPublication({ kind: "published", path: prepared.path, intent });
+    return { kind: "unchanged" };
+  }
+  const routedBefore = onDisk === null ? null : routedRowsFromJson(onDisk.toString("utf8"));
+  const routedAfter = routedRowsFromJson(prepared.content);
+  const finish = (result: CatalogFileReplacement): CatalogFileReplacement => {
+    if (result.kind !== "unchanged") auditWrite(permit, owningCodexHome, {
+      target: "catalog", outcome: result.kind,
+      reason: result.kind === "refused" ? result.reason : undefined,
+      routedBefore, routedAfter, configSource: configSourceNow(),
+    }, io === undefined);
+    if (result.kind !== "refused") notifyCatalogPublication({ kind: "published", path: prepared.path, intent });
+    return result;
+  };
+  if (intent === "refresh" && (routedBefore ?? 0) > 0 && routedAfter === 0) {
+    // K -> C, including the replacement: a config save cannot race the authority check.
+    try {
+      return finish(withConfigMutationLockSync(() => {
+        const snapshot = readConfigAdmissionSnapshot();
+        if (snapshot.kind !== "read" || snapshot.diagnostics.source !== "file") {
+          return { kind: "refused", reason: "unbacked-routed-clear" } as const;
+        }
+        atomicWriteFile(prepared.path, prepared.content, io);
+        resetCodexAppServerCatalogStateCache();
+        return { kind: "written" } as const;
+      }));
+    } catch (error) {
+      if (error instanceof ConfigMutationLockError) return finish({ kind: "refused", reason: "unbacked-routed-clear" });
+      throw error;
+    }
+  }
   atomicWriteFile(prepared.path, prepared.content, io);
   resetCodexAppServerCatalogStateCache();
+  return finish({ kind: "written" });
 }
 
 /** Atomically publish the catalog-path-keyed immutable backup without clobbering. */
@@ -242,8 +341,16 @@ export function replaceCodexModelsCache(
   owningCodexHome: string,
   prepared: PreparedCatalogFileWrite,
   io?: AtomicWriteIO,
-): void {
+): Exclude<CatalogFileReplacement, { kind: "refused" }> {
   assertCatalogWritePermit(permit, owningCodexHome);
+  catalogWritePermitContext(permit);
+  if (!preparedBytesDifferFromDisk(prepared)) return { kind: "unchanged" };
+  const routedBefore = routedRowsOnDisk(prepared.path);
   atomicWriteFile(prepared.path, prepared.content, io);
   resetCodexAppServerCatalogStateCache();
+  auditWrite(permit, owningCodexHome, {
+    target: "cache", outcome: "written", routedBefore,
+    routedAfter: routedRowsFromJson(prepared.content), configSource: configSourceNow(),
+  }, io === undefined);
+  return { kind: "written" };
 }

package/src/codex/journal.ts

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { existsSync, readFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { atomicWriteFile } from "../config";
+import { assertCodexHomeOwner, CODEX_HOME_JOURNAL_FILE, CodexHomeOwnerRefusal, opencodexHomeForInjection, readCodexHomeJournal, type CodexHomeOwnerRefusalReason } from "./codex-home-owner";
 import { hasInjectedCodexRouting } from "./injected-marker";
 import { CODEX_HOME, CODEX_CONFIG_PATH, CODEX_PROFILE_PATH } from "./paths";
 
@@ -14,7 +15,7 @@ import { CODEX_HOME, CODEX_CONFIG_PATH, CODEX_PROFILE_PATH } from "./paths";
  * agreed with the producer, and the pair stayed green. One exported constant
  * removes the opportunity.
  */
-export const JOURNAL_PATH = join(CODEX_HOME, "opencodex-journal.json");
+export const JOURNAL_PATH = join(CODEX_HOME, CODEX_HOME_JOURNAL_FILE);
 
 export type JournalOwner =
   | { kind: "process"; pid: number }
@@ -71,12 +72,17 @@ interface Journal {
    * file we actually touched.
    */
   injectedCatalogPath?: string | null;
+  /** Injection binding survives native snapshot replacement and is released by native restore. */
+  opencodexHome?: string;
   pid: number;
   owner?: JournalOwner;
   timestamp: string;
 }
 
 export interface RestoreJournalResult {
+  /** An unchanged generated profile could not be restored; distinct from a preserved user edit. */
+  profileRestoreFailed?: true;
+  ownershipRefusal?: CodexHomeOwnerRefusalReason;
   configRestored: boolean;
   profileRestored: boolean;
   configChanged: boolean;
@@ -146,6 +152,7 @@ export interface WriteJournalOptions {
  * plugins, model choice, and trusted projects.
  */
 export function writeJournal(options: WriteJournalOptions = {}): void {
+  assertCodexHomeOwner(CODEX_HOME);
   if (!existsSync(CODEX_CONFIG_PATH)) return;
   const config = options.configContent ?? readFileSync(CODEX_CONFIG_PATH, "utf-8");
   // Ownership is decided HERE, from the bytes about to be journaled — never taken
@@ -155,7 +162,12 @@ export function writeJournal(options: WriteJournalOptions = {}): void {
   // The caller's verdict only authorizes REPLACEMENT. It is weaker evidence than
   // the check above (it may describe bytes read a moment earlier), so an
   // unclassified call creates a first snapshot but never overwrites one.
-  if (existsSync(JOURNAL_PATH) && readJournal() && options.currentStateIsNative !== true) return;
+  const inspection = readCodexHomeJournal(JOURNAL_PATH);
+  if (inspection.kind === "unknown") {
+    throw new CodexHomeOwnerRefusal("owner-unknown");
+  }
+  const previous = inspection.kind === "read" ? inspection.journal as unknown as Journal : null;
+  if (previous && options.currentStateIsNative !== true) return;
   const profile = existsSync(CODEX_PROFILE_PATH)
     ? readFileSync(CODEX_PROFILE_PATH, "utf-8")
     : null;
@@ -163,6 +175,7 @@ export function writeJournal(options: WriteJournalOptions = {}): void {
     version: 1,
     originalConfig: Buffer.from(config).toString("base64"),
     originalProfile: profile !== null ? Buffer.from(profile).toString("base64") : null,
+    opencodexHome: opencodexHomeForInjection(previous?.opencodexHome),
     pid: process.pid,
     owner: options.owner?.kind === "client"
       ? { kind: "client", apiKeyId: options.owner.apiKeyId }
@@ -187,7 +200,10 @@ export function markJournalInjectedState(
   profile: string | null,
   ownership: InjectedJournalOwnership,
 ): void {
-  const journal = readJournal();
+  assertCodexHomeOwner(CODEX_HOME);
+  const inspection = readCodexHomeJournal(JOURNAL_PATH);
+  if (inspection.kind === "unknown") throw new CodexHomeOwnerRefusal("owner-unknown");
+  const journal = inspection.kind === "read" ? inspection.journal as unknown as Journal : null;
   if (!journal) return;
   // The first exact injected config is the only safe whole-snapshot restore boundary for
   // the first native snapshot. A later reinjection may preserve user edits made while routed;
@@ -204,6 +220,7 @@ export function markJournalInjectedState(
   journal.injectedRootWebSearch = ownership.injectedRootWebSearch ?? null;
   journal.replacedRootWebSearch = ownership.replacedRootWebSearch ?? null;
   journal.injectedCatalogPath = ownership.injectedCatalogPath;
+  journal.opencodexHome = opencodexHomeForInjection(journal.opencodexHome);
   atomicWriteFile(JOURNAL_PATH, JSON.stringify(journal));
 }
 
@@ -240,19 +257,24 @@ export function journaledInjectedCatalogPath(): string | null {
 }
 
 export function removeJournal(): void {
+  assertCodexHomeOwner(CODEX_HOME);
   try { unlinkSync(JOURNAL_PATH); } catch { /* ignore */ }
 }
 
-function readJournal(cleanInvalid = true): Journal | null {
-  if (!existsSync(JOURNAL_PATH)) return null;
-  try {
-    const journal = JSON.parse(readFileSync(JOURNAL_PATH, "utf-8")) as Journal;
-    if (journal.version !== 1) throw new Error("unknown version");
-    return journal;
-  } catch {
-    if (cleanInvalid) removeJournal();
-    return null;
-  }
+/** Successful field-level native restore releases ownership while retaining recovery evidence. */
+export function releaseJournalHomeBinding(): void {
+  assertCodexHomeOwner(CODEX_HOME);
+  const inspection = readCodexHomeJournal(JOURNAL_PATH);
+  if (inspection.kind === "unknown") throw new CodexHomeOwnerRefusal("owner-unknown");
+  if (inspection.kind === "missing" || inspection.journal.opencodexHome === undefined) return;
+  delete inspection.journal.opencodexHome;
+  atomicWriteFile(JOURNAL_PATH, JSON.stringify(inspection.journal));
+}
+
+// Kept compatible with existing read-only callers; invalid evidence is never cleanup authority.
+function readJournal(_cleanInvalid = true): Journal | null {
+  const inspected = readCodexHomeJournal(JOURNAL_PATH);
+  return inspected.kind === "read" ? inspected.journal as unknown as Journal : null;
 }
 
 /**
@@ -274,6 +296,12 @@ export function journalOwner(options: { readOnly?: boolean } = {}): JournalOwner
 }
 
 export function restoreJournalState(): RestoreJournalResult {
+  try { assertCodexHomeOwner(CODEX_HOME); }
+  catch (error) {
+    if (!(error instanceof CodexHomeOwnerRefusal)) throw error;
+    return { configRestored: false, profileRestored: false, configChanged: false, profileChanged: false,
+      complete: false, unverified: true, ownershipRefusal: error.reason };
+  }
   const journal = readJournal();
   if (!journal) {
     return { configRestored: false, profileRestored: false, configChanged: false, profileChanged: false, complete: false, unverified: false };
@@ -295,6 +323,7 @@ export function restoreJournalState(): RestoreJournalResult {
     };
   }
 
+  assertCodexHomeOwner(CODEX_HOME);
   let configRestored = comparison.configAlreadyOriginal;
   let profileRestored = comparison.profileAlreadyOriginal;
   if (configUnchanged && !configRestored) {
@@ -330,6 +359,7 @@ export function restoreJournalState(): RestoreJournalResult {
     profileChanged: !profileUnchanged,
     complete,
     unverified: false,
+    ...(profileUnchanged && !profileRestored ? { profileRestoreFailed: true as const } : {}),
   };
 }
 
@@ -342,6 +372,12 @@ export interface ReconcileJournalOptions {
 }
 
 export function reconcileJournal(options: ReconcileJournalOptions = {}): boolean {
+  try { assertCodexHomeOwner(CODEX_HOME); }
+  catch (error) {
+    if (!(error instanceof CodexHomeOwnerRefusal)) throw error;
+    console.error(error.message);
+    return false;
+  }
   const journal = readJournal();
   if (!journal) return false;
   const owner = journalOwner();

package/src/codex/main-account.ts

@@ -1,11 +1,15 @@
+import { classifyChatgptRefreshFailure, noteChatgptRefreshFailure } from "./chatgpt-refresh-failure";
+import { readBoundedResponseBody } from "../lib/bounded-body";
 import { createHash } from "node:crypto";
 import { readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { readCodexTokens } from "./auth-collision";
 import {
+  CHATGPT_CLIENT_ID,
+  CHATGPT_TOKEN_URL,
+  credsFromToken,
   decodeJwtPayload,
   extractAccountId,
-  refreshChatGPTToken,
 } from "../oauth/chatgpt";
 import type { OAuthCredentials } from "../oauth/types";
 import { extractChatgptPlanType } from "./plan";
@@ -17,7 +21,12 @@ import {
 import { atomicWriteFile, resolveWriteTarget } from "../config/atomic-write";
 import { resolveCodexHomeDir } from "./home";
 import { assertNotRealCodexHomeUnderTest } from "../lib/test-home-guard";
-import { clearAccountNeedsReauth } from "./account-runtime-state";
+import {
+  clearAccountNeedsReauth,
+  isMainRefreshGrantRejected,
+  markMainRefreshGrantRejected,
+  clearMainRefreshGrantRejection,
+} from "./account-runtime-state";
 import { advanceCodexCredentialMutationEpoch } from "./credential-mutation-epoch";
 import { withNativeMainExclusiveClaim } from "./native-main-claim";
 import { resolveNativeProfileContext } from "./native-profile-store";
@@ -78,6 +87,68 @@ export class MainAccountTokenRefreshError extends Error {
   }
 }
 
+/**
+ * The native-main refresh, posted here rather than through `refreshChatGPTToken` so the token
+ * endpoint's structured `error` code survives to {@link classifyChatgptRefreshFailure}.
+ *
+ * `refreshChatGPTToken` collapses the refusal into one display string, and classifying a grant
+ * from that string is what let `refresh_token_reused` pass as transient -- the grant never
+ * retired, every request re-earning its own 401 -- while a 5xx whose description merely read
+ * "session expired" passed as proof and would have retired a live grant.
+ *
+ * Same endpoint, client id and grant type as every other ChatGPT refresh, and the success path
+ * is `credsFromToken` itself, so only the failure branch differs: it classifies by code, exactly
+ * as the stored-pool refresh does.
+ */
+async function refreshNativeMainGrant(
+  refreshToken: string,
+  options: { signal: AbortSignal },
+): Promise<OAuthCredentials> {
+  const resp = await fetch(CHATGPT_TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "refresh_token",
+      client_id: CHATGPT_CLIENT_ID,
+      refresh_token: refreshToken,
+    }).toString(),
+    signal: options.signal,
+  });
+  if (!resp.ok) {
+    const body = await readBoundedResponseBody(resp, { signal: options.signal, maxBytes: 16_384, fatalUtf8: true })
+      .catch(() => undefined);
+    const failure = classifyChatgptRefreshFailure(resp.status, body?.displaySafe ? body.text : "");
+    noteChatgptRefreshFailure("native main", resp.status, failure);
+    throw new MainAccountTokenRefreshError(failure.reason === "unknown" ? "transient" : "reauth");
+  }
+  let credentials: OAuthCredentials;
+  try {
+    credentials = credsFromToken((await resp.json()) as Record<string, unknown>);
+  } catch {
+    if (options.signal.aborted) throw options.signal.reason;
+    noteNativeMainRefresh("transient", resp.status);
+    // Parsing errors may include provider body text; retain only the fixed verdict.
+    throw new MainAccountTokenRefreshError("transient");
+  }
+  noteNativeMainRefresh("ok", resp.status);
+  return credentials;
+}
+
+/**
+ * One line per native-main refresh verdict, so a dead grant is diagnosable from service.log.
+ *
+ * A revoked session is invisible from the outside: the grant is refused, nothing is written, and
+ * the request fails with a status that looks like every other 401. Carries the token endpoint's
+ * HTTP status and its structured `error` code and nothing else -- never a token, never a body.
+ */
+function noteNativeMainRefresh(outcome: string, status?: number, code?: string): void {
+  console.warn(
+    `[codex] native main refresh: ${outcome}`
+      + (status === undefined ? "" : ` status=${status}`)
+      + ` code=${code && /^[A-Za-z0-9._-]{1,64}$/.test(code) ? code : "none"}`,
+  );
+}
+
 function nonEmptyString(value: unknown): string | undefined {
   return typeof value === "string" && value.trim() ? value : undefined;
 }
@@ -147,13 +218,45 @@ function mainAccessTokenFresh(accessToken: string | undefined, now: number, skew
 }
 
 /** A refresh grant makes native main routeable even when the current access token is expired. */
-export function isMainAccountCredentialUsable(now = Date.now()): boolean {
+function mainRefreshGrantKey(current: MainAuthJsonCredential): string | undefined {
+  return current.refreshToken
+    ? `${current.path}:${refreshGrantFingerprintForToken(current.refreshToken)}` : undefined;
+}
+
+function credentialRefreshGrantRejected(current: MainAuthJsonCredential | null): boolean {
+  const key = current && mainRefreshGrantKey(current);
+  return !!key && isMainRefreshGrantRejected(key);
+}
+
+export interface MainAccountCredentialStatus {
+  refreshGrantRejected: boolean;
+  hasRefreshGrant: boolean;
+  usable: boolean;
+}
+
+/** One owned physical observation; no credential material escapes this view. */
+export function getMainAccountCredentialStatus(now = Date.now()): MainAccountCredentialStatus {
   const current = readMainAuthJsonCredential();
-  return !!current?.refreshToken || mainAccessTokenFresh(current?.accessToken, now, 0);
+  const refreshGrantRejected = credentialRefreshGrantRejected(current);
+  const hasRefreshGrant = !!current?.refreshToken && !refreshGrantRejected;
+  return {
+    refreshGrantRejected,
+    hasRefreshGrant,
+    usable: !refreshGrantRejected && (hasRefreshGrant || mainAccessTokenFresh(current?.accessToken, now, 0)),
+  };
+}
+
+/** Current owned profile only; callers must hold the native read/selection permission. */
+export function isMainAccountRefreshGrantRejected(): boolean {
+  return getMainAccountCredentialStatus().refreshGrantRejected;
+}
+
+export function isMainAccountCredentialUsable(now = Date.now()): boolean {
+  return getMainAccountCredentialStatus(now).usable;
 }
 
 export function hasMainAccountRefreshGrant(): boolean {
-  return !!readMainAuthJsonCredential()?.refreshToken;
+  return getMainAccountCredentialStatus().hasRefreshGrant;
 }
 
 function assertMainAuthJsonSnapshotUnchanged(expected: MainAuthJsonCredential): void {
@@ -342,14 +445,26 @@ async function resolveMainAccountToken(
   dependencies: NativeMainRefreshDependencies = {},
   rejectedAccessToken?: string,
 ): Promise<{ accessToken: string; chatgptAccountId: string } | null> {
+  if (dependencies.signal?.aborted) throw dependencies.signal.reason;
   const initial = readMainAuthJsonCredential();
-  if (!initial) return null;
+  // Every skip below ends a forced refresh WITHOUT asking the token endpoint anything, which from
+  // the outside is indistinguishable from a refusal: same failed request, no write, no verdict.
+  // A forced refresh is the only caller that passes `rejectedAccessToken`, so only it reports.
+  if (!initial) {
+    if (rejectedAccessToken !== undefined) noteNativeMainRefresh("skipped-no-credential");
+    return null;
+  }
+  if (credentialRefreshGrantRejected(initial)) throw new MainAccountTokenRefreshError("reauth");
   const now = Date.now();
   if (initial.accessToken !== rejectedAccessToken
     && mainAccessTokenFresh(initial.accessToken, now, MAIN_TOKEN_REFRESH_SKEW_MS)) {
+    // The stored credential is no longer the one upstream rejected: somebody else replaced it
+    // while this request was in flight, so there is nothing here to refresh or to retire.
+    if (rejectedAccessToken !== undefined) noteNativeMainRefresh("skipped-credential-replaced");
     return { accessToken: initial.accessToken!, chatgptAccountId: initial.chatgptAccountId };
   }
   if (!initial.refreshToken) {
+    if (rejectedAccessToken !== undefined) noteNativeMainRefresh("skipped-no-refresh-grant");
     return initial.accessToken !== rejectedAccessToken
       && mainAccessTokenFresh(initial.accessToken, now, 0)
       ? { accessToken: initial.accessToken!, chatgptAccountId: initial.chatgptAccountId }
@@ -380,6 +495,7 @@ async function resolveMainAccountToken(
       () => withCodexRefreshFileLock(lockKey, signal, async () => {
         const locked = readMainAuthJsonCredential();
         if (!locked) throw new MainAuthJsonChangedDuringRefreshError();
+        if (credentialRefreshGrantRejected(locked)) throw new MainAccountTokenRefreshError("reauth");
         if (!locked.refreshToken
           || refreshGrantFingerprintForToken(locked.refreshToken) !== lockKey) {
           if (locked.accessToken !== rejectedAccessToken
@@ -392,16 +508,31 @@ async function resolveMainAccountToken(
           && mainAccessTokenFresh(locked.accessToken, Date.now(), MAIN_TOKEN_REFRESH_SKEW_MS)) {
           return { accessToken: locked.accessToken!, chatgptAccountId: locked.chatgptAccountId };
         }
-        const refresh = dependencies.refreshToken
-          ?? ((refreshToken: string, options: { signal: AbortSignal }) => refreshChatGPTToken(refreshToken, options));
+        const refresh = dependencies.refreshToken ?? refreshNativeMainGrant;
         let refreshed: OAuthCredentials;
         try {
           refreshed = await refresh(locked.refreshToken, { signal });
         } catch (cause) {
+          // A refusal already classified at the endpoint keeps that verdict. An injected refresh
+          // threw an ordinary Error and has only its message, so prose still decides there --
+          // and only there, where there is no structured code to read.
           const message = cause instanceof Error ? cause.message.toLowerCase() : "";
-          const reason = /invalid_grant|invalidated|revoked|expired/.test(message)
-            ? "reauth" as const
-            : "transient" as const;
+          const reason = cause instanceof MainAccountTokenRefreshError
+            ? cause.reason
+            : dependencies.refreshToken && /invalid_grant|invalidated|revoked|expired/.test(message)
+              ? "reauth" as const
+              : "transient" as const;
+          // The shared point every request path reaches a terminal native-main verdict through:
+          // the forced refresh after an upstream 401, the pre-send refresh of an expired bearer,
+          // and the compact twin all land here. Recording the quarantine at the callers instead
+          // left the native main slot alone unrecorded -- `refreshNativeMainForwardAuth` has no
+          // `quarantine` flag for its caller to act on the way the stored-pool twin does -- so a
+          // revoked session stayed `needsReauth: false` and every request re-earned its own 401.
+          if (signal.aborted) throw signal.reason;
+          if (reason === "reauth") {
+            assertMainAuthJsonSnapshotUnchanged(locked);
+            markMainRefreshGrantRejected(mainRefreshGrantKey(locked)!);
+          }
           throw new MainAccountTokenRefreshError(reason, { cause });
         }
         // The refresh may resolve after the caller went away (an implementation that does
@@ -411,6 +542,8 @@ async function resolveMainAccountToken(
         // before its own commit above.
         if (dependencies.signal?.aborted) throw dependencies.signal.reason;
         const result = persistRefreshedMainAuthJson(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);
         return result;
       }),

package/src/codex/management-convergence.ts

@@ -143,6 +143,7 @@ export function projectCatalogOnlyOutcome({
  */
 export function createManagementConvergeCodex(
   config: Readonly<OcxConfig>,
+  options: Readonly<{ beforeCommit?: () => boolean; expectedCatalogPath?: string }> = {},
 ): ConvergeCodex {
   const retainedConfig = config;
   return async request => {
@@ -167,6 +168,8 @@ export function createManagementConvergeCodex(
       const snapshot = captureCatalogAdmissionSnapshot(retainedConfig);
       const result = await convergeCodexCatalog(snapshot, request, {
         onCommitBegin: () => { commitBegan = true; },
+        beforeCommit: options.beforeCommit,
+        expectedCatalogPath: options.expectedCatalogPath,
       });
       return projectCatalogOnlyOutcome(result);
     } catch (error) {

package/src/codex/quota-refresh-outcome.ts

@@ -1,8 +1,22 @@
 /** Diagnostic only: never use this outcome as quota, entitlement, or admission evidence. */
 export type CodexQuotaRefreshOutcome =
-  | { status: "http_error"; httpStatus: number }
+  /** `code` is set only for a provider code that requires a new sign-in (fixed vocabulary). */
+  | { status: "http_error"; httpStatus: number; code?: CodexTerminalAuthCode }
   | { status: "ok" | "not_reported" | "timeout" | "network_error" | "invalid_response" | "internal_error" };
 
+/** Provider auth codes that only a new sign-in can recover. */
+export const CODEX_TERMINAL_AUTH_CODES = [
+  "invalid_workspace_selected",
+  "invalid_refresh_token",
+  // ChatGPT revokes every session of an account whose plan changes (for example Pro to Free),
+  // while the access token's `exp` still lies in the future.
+  "token_invalidated",
+] as const;
+export type CodexTerminalAuthCode = typeof CODEX_TERMINAL_AUTH_CODES[number];
+export function isCodexTerminalAuthCode(code: unknown): code is CodexTerminalAuthCode {
+  return (CODEX_TERMINAL_AUTH_CODES as readonly unknown[]).includes(code);
+}
+
 /** The management response is untrusted at the CLI boundary; copy only the fixed vocabulary. */
 export function projectCodexQuotaRefreshOutcome(value: unknown): CodexQuotaRefreshOutcome | undefined {
   if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
@@ -10,7 +24,8 @@ export function projectCodexQuotaRefreshOutcome(value: unknown): CodexQuotaRefre
   if (row.status === "http_error") {
     return typeof row.httpStatus === "number" && Number.isInteger(row.httpStatus)
       && row.httpStatus >= 100 && row.httpStatus <= 599
-      ? { status: "http_error", httpStatus: row.httpStatus }
+      ? { status: "http_error", httpStatus: row.httpStatus,
+        ...(isCodexTerminalAuthCode(row.code) ? { code: row.code } : {}) }
       : undefined;
   }
   switch (row.status) {

package/src/codex/quota-types.ts

@@ -22,6 +22,32 @@ export const TERMINAL_SHORT_WINDOW_FRESHNESS_MS = 5 * 60_000;
  */
 export const CODEX_EXHAUSTED_USAGE_PERCENT = 100;
 
+/** Credits have a separate clock: ordinary usage headers do not re-observe the balance. */
+export const CODEX_CREDITS_FRESHNESS_MS = 5 * 60_000;
+
+export interface CodexSpendableCredits {
+  hasCredits?: boolean;
+  unlimited?: boolean;
+  balance?: number;
+  overageLimitReached?: boolean;
+  /** Credit spending control, never the included-plan rate_limit.allowed verdict. */
+  allowed?: boolean;
+  observedAt: number;
+}
+
+export function hasSpendableCodexCredits(
+  quota: Pick<StoredAccountQuota, "credits"> | null,
+  now = Date.now(),
+): boolean {
+  const credits = quota?.credits;
+  if (!credits || !Number.isFinite(credits.observedAt)) return false;
+  const age = now - credits.observedAt;
+  if (age < 0 || age > CODEX_CREDITS_FRESHNESS_MS
+    || credits.allowed === false || credits.overageLimitReached === true || credits.hasCredits === false) return false;
+  return credits.unlimited === true || (credits.hasCredits === true
+    && typeof credits.balance === "number" && Number.isFinite(credits.balance) && credits.balance > 0);
+}
+
 /**
  * Above this a value is already milliseconds; at or below it, it is Unix seconds.
  *
@@ -80,6 +106,8 @@ export type StoredAccountQuota = {
   shortWindowSeconds?: number;
   customWindows?: Array<{ label: string; percent: number; resetAt?: number }>;
   resetCredits?: number;
+  /** Spendable usage credits; resetCredits are separate, manually redeemed reset tickets. */
+  credits?: CodexSpendableCredits | null;
   /** Monthly usage came from an explicitly monthly PRIMARY, not supplementary tertiary, window. */
   monthlyIsPrimaryWindow?: boolean;
   updatedAt: number;
@@ -114,7 +142,14 @@ export type WhamUsageResponse = {
     secondary_window?: WhamUsageWindow | null;
     tertiary_window?: WhamUsageWindow | null;
   };
-  credits?: unknown;
+  credits?: {
+    has_credits?: unknown;
+    unlimited?: unknown;
+    balance?: unknown;
+    overage_limit_reached?: unknown;
+  } | null;
+  /** Absent/null imposes no veto; present raw controls require an object with reached:false. */
+  spend_control?: unknown;
   rate_limit_reset_credits?: { available_count: number } | null;
   additional_rate_limits?: WhamAdditionalRateLimit[] | null;
 };