@bitkyc08/opencodex 2.84.0 → 2.86.0

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 = {},

package/src/codex/native-main-refresh-mode.ts

@@ -0,0 +1,217 @@
+/**
+ * Who refreshes the native main ChatGPT credential (#2999).
+ *
+ * Codex owns `CODEX_HOME/auth.json`. It rewrites the file in place and serializes its own
+ * refreshes only inside one process, so any second writer can race it, and a lost race
+ * retires the grant. In "codex" mode OpenCodex never writes the file: it asks the Codex
+ * binary to refresh through `app-server` `getAuthStatus` and uses the bearer that call
+ * returns. In "opencodex" mode the guarded writer in `main-account.ts` refreshes as before.
+ *
+ * The default is "codex" only when a version-checked binary is available. Without one, or
+ * when the operator sets `nativeMainRefresh: "opencodex"`, the guarded writer stays.
+ */
+import { codexExecInvocation } from "./exec-invocation";
+import { resolveCodexHomeDir } from "./home";
+import { compareCodexVersions, displayCodexRuntimePath, resolveCodexRuntimeAsync } from "./runtime";
+import type { ResolveCodexRuntimeResult } from "./runtime";
+import { isTestHomeGuardArmed } from "../lib/test-home-guard";
+import type { OcxConfig } from "../types/config";
+
+export type NativeMainRefreshMode = "codex" | "opencodex";
+
+/**
+ * Supported floor for app-server `getAuthStatus` with `includeToken`/`refreshToken` that
+ * withholds the token after a permanent refresh failure, the only reauth signal on the wire.
+ * Releases from about 0.118 already withhold it; 0.130.0 is the first with the handler in
+ * `request_processors/account_processor.rs` and is chosen conservatively.
+ */
+export const CODEX_AUTH_STATUS_MIN_VERSION = "0.130.0";
+
+export type NativeMainRefreshReason =
+  | "codex-compatible"
+  | "configured-opencodex"
+  | "codex-missing"
+  | "codex-too-old"
+  | "test-guard";
+
+export interface NativeMainRefreshResolution {
+  readonly mode: NativeMainRefreshMode;
+  readonly configured: NativeMainRefreshMode | "auto";
+  readonly reason: NativeMainRefreshReason;
+  readonly command?: string;
+  readonly version?: string | null;
+}
+
+export interface CodexAuthStatus {
+  readonly authMethod: string | null;
+  readonly authToken: string | null;
+  readonly requiresOpenaiAuth: boolean | null;
+}
+
+export class CodexAuthStatusError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "CodexAuthStatusError";
+  }
+}
+
+let resolutionForTests: NativeMainRefreshResolution | null = null;
+
+/** Test seam: pin the resolution so no test spawns the developer's real Codex binary. */
+export function setNativeMainRefreshResolutionForTests(value: NativeMainRefreshResolution | null): void {
+  resolutionForTests = value;
+}
+
+function configuredMode(config: Pick<OcxConfig, "nativeMainRefresh"> | null | undefined): NativeMainRefreshMode | "auto" {
+  const value = config?.nativeMainRefresh;
+  return value === "codex" || value === "opencodex" ? value : "auto";
+}
+
+export async function resolveNativeMainRefreshMode(
+  config: Pick<OcxConfig, "nativeMainRefresh"> | null | undefined,
+  deps: { resolveRuntime?: () => Promise<ResolveCodexRuntimeResult> } = {},
+): Promise<NativeMainRefreshResolution> {
+  if (resolutionForTests) return resolutionForTests;
+  const configured = configuredMode(config);
+  if (configured === "opencodex") return { mode: "opencodex", configured, reason: "configured-opencodex" };
+  // Tests run against throwaway CODEX_HOMEs; delegating would spawn the real binary.
+  if (!deps.resolveRuntime && isTestHomeGuardArmed()) return { mode: "opencodex", configured, reason: "test-guard" };
+  const resolved = await (deps.resolveRuntime ?? (() => resolveCodexRuntimeAsync({ discoverAlternatives: false })))();
+  const { command, version, source } = resolved.runtime;
+  if (source === "fallback" && version === null) {
+    return { mode: "opencodex", configured, reason: "codex-missing" };
+  }
+  if (version === null || compareCodexVersions(version, CODEX_AUTH_STATUS_MIN_VERSION) < 0) {
+    return { mode: "opencodex", configured, reason: "codex-too-old", command, version };
+  }
+  return { mode: "codex", configured, reason: "codex-compatible", command, version };
+}
+
+/**
+ * One `getAuthStatus` round trip against a short-lived `codex app-server` on stdio.
+ *
+ * `model_provider="openai"` is forced because an authless Desktop injection sets
+ * `requires_openai_auth = false` on the OpenCodex provider, and then the server reports no
+ * credential at all. The process inherits CODEX_HOME so it reads the same login (file or
+ * keyring) Codex itself uses.
+ */
+export async function requestCodexAuthStatus(
+  command: string,
+  options: { refresh: boolean; signal: AbortSignal; codexHome?: string },
+): Promise<CodexAuthStatus> {
+  if (options.signal.aborted) throw options.signal.reason;
+  const invocation = codexExecInvocation(command, ["-c", 'model_provider="openai"', "app-server"]);
+  let proc: ReturnType<typeof Bun.spawn<"pipe", "pipe", "ignore">>;
+  try {
+    proc = Bun.spawn([invocation.file, ...invocation.args], {
+      env: { ...process.env, CODEX_HOME: options.codexHome ?? resolveCodexHomeDir() },
+      stdin: "pipe",
+      stdout: "pipe",
+      stderr: "ignore",
+      windowsVerbatimArguments: invocation.options.windowsVerbatimArguments,
+      windowsHide: true,
+    });
+  } catch (cause) {
+    throw new CodexAuthStatusError("could not start codex app-server", { cause });
+  }
+  // Abort settles the call by itself. Waiting for stdout to close would hang on a child that
+  // ignores SIGTERM or a launcher descendant that keeps the pipe open.
+  let onAbort = () => {};
+  const aborted = new Promise<never>((_, reject) => {
+    onAbort = () => reject(options.signal.reason);
+    options.signal.addEventListener("abort", onAbort, { once: true });
+  });
+  aborted.catch(() => { /* observed through the race below */ });
+  try {
+    const send = (message: unknown) => proc.stdin.write(JSON.stringify(message) + "\n");
+    send({ id: 1, method: "initialize", params: { clientInfo: { name: "opencodex", title: null, version: "0" } } });
+    send({ method: "initialized" });
+    send({ id: 2, method: "getAuthStatus", params: { includeToken: true, refreshToken: options.refresh } });
+    await Promise.race([proc.stdin.flush(), aborted]);
+    const response = await Promise.race([readResponse(proc.stdout, 2), aborted]);
+    if (options.signal.aborted) throw options.signal.reason;
+    return parseAuthStatus(response);
+  } catch (cause) {
+    if (options.signal.aborted) throw options.signal.reason;
+    if (cause instanceof CodexAuthStatusError) throw cause;
+    throw new CodexAuthStatusError("codex app-server getAuthStatus failed", { cause });
+  } finally {
+    options.signal.removeEventListener("abort", onAbort);
+    stopAppServer(proc);
+  }
+}
+
+const APP_SERVER_KILL_GRACE_MS = 2_000;
+
+/** SIGTERM now, SIGKILL if the child is still alive after a grace period; never awaited. */
+function stopAppServer(proc: { stdin: { end(): unknown }; kill(signal?: number | NodeJS.Signals): void; exited: Promise<number> }): void {
+  try { proc.stdin.end(); } catch { /* already closed */ }
+  let exited = false;
+  void proc.exited.then(() => { exited = true; }, () => { exited = true; });
+  try { proc.kill("SIGTERM"); } catch { /* already gone */ }
+  const timer = setTimeout(() => {
+    if (!exited) try { proc.kill("SIGKILL"); } catch { /* already gone */ }
+  }, APP_SERVER_KILL_GRACE_MS);
+  (timer as { unref?: () => void }).unref?.();
+}
+
+const MAX_APP_SERVER_LINE_BYTES = 1_048_576;
+
+async function readResponse(stream: ReadableStream<Uint8Array>, id: number): Promise<Record<string, unknown>> {
+  const decoder = new TextDecoder();
+  let buffered = "";
+  for await (const chunk of stream) {
+    buffered += decoder.decode(chunk, { stream: true });
+    let newline: number;
+    while ((newline = buffered.indexOf("\n")) >= 0) {
+      const line = buffered.slice(0, newline).trim();
+      buffered = buffered.slice(newline + 1);
+      if (!line) continue;
+      let message: unknown;
+      try { message = JSON.parse(line); } catch { continue; }
+      if (!message || typeof message !== "object") continue;
+      const record = message as Record<string, unknown>;
+      if (record.id !== id) continue;
+      if (record.error !== undefined) throw new CodexAuthStatusError("codex app-server rejected getAuthStatus");
+      if (!record.result || typeof record.result !== "object") {
+        throw new CodexAuthStatusError("codex app-server returned no getAuthStatus result");
+      }
+      return record.result as Record<string, unknown>;
+    }
+    if (buffered.length > MAX_APP_SERVER_LINE_BYTES) throw new CodexAuthStatusError("codex app-server line too long");
+  }
+  throw new CodexAuthStatusError("codex app-server exited before answering getAuthStatus");
+}
+
+function parseAuthStatus(result: Record<string, unknown>): CodexAuthStatus {
+  const authMethod = typeof result.authMethod === "string" ? result.authMethod : null;
+  const authToken = typeof result.authToken === "string" && result.authToken ? result.authToken : null;
+  const requiresOpenaiAuth = typeof result.requiresOpenaiAuth === "boolean" ? result.requiresOpenaiAuth : null;
+  return { authMethod, authToken, requiresOpenaiAuth };
+}
+
+/** `ocx doctor` lines for the active refresh owner. Never includes a credential. */
+export function formatNativeMainRefreshDoctorLines(resolution: NativeMainRefreshResolution): string[] {
+  const configured = resolution.configured === "auto" ? "auto" : `nativeMainRefresh: "${resolution.configured}"`;
+  const binary = resolution.command
+    ? `${displayCodexRuntimePath(resolution.command)} (${resolution.version ?? "unknown"})`
+    : "none";
+  switch (resolution.reason) {
+    case "codex-compatible":
+      return [`  ok  codex: Codex refreshes the main login through app-server (${binary}; ${configured})`];
+    case "configured-opencodex":
+      return [`  --  opencodex: OpenCodex refreshes auth.json with its guarded writer (${configured})`];
+    case "test-guard":
+      return ["  --  opencodex: test guard is armed; Codex delegation is disabled"];
+    case "codex-missing":
+      return [
+        `  !!  opencodex: no Codex binary found, so OpenCodex refreshes auth.json itself (${configured})`,
+        `       Install Codex ${CODEX_AUTH_STATUS_MIN_VERSION} or newer to let Codex own its login.`,
+      ];
+    case "codex-too-old":
+      return [
+        `  !!  opencodex: Codex ${binary} is older than ${CODEX_AUTH_STATUS_MIN_VERSION}, so OpenCodex refreshes auth.json itself (${configured})`,
+        "       Update Codex to let Codex own its login.",
+      ];
+  }
+}

package/src/codex/routing/health-store.ts

@@ -163,7 +163,7 @@ export function deleteScopedHealth(accountId: string, scope: CodexQuotaScope): v
 }
 
 /** Live quota-refusal avoidance for an account, including the lane the request belongs to. */
-function codexQuotaAvoidUntil(
+export function codexQuotaAvoidUntil(
   accountId: string,
   quotaScope: CodexQuotaScope | undefined,
   now: number,

package/src/codex/routing/pool-recovery.ts

@@ -0,0 +1,79 @@
+/**
+ * When another stored pool account can serve again, for a main-account hard-lock refusal (#7046).
+ *
+ * A pool request that fell through to the main login and met the main-account quota guard used
+ * to be told to come back at main's own reset, which can be days away while a sibling pool
+ * account recovers within hours. This module answers one question: the earliest KNOWN instant at
+ * which a stored pool account's every temporary hold ends. It changes no routing state, selects
+ * nothing, and never lifts the main guard. The client retries at that time, and ordinary selection
+ * decides again from fresh state; a reset timestamp is a hint, not proof of fresh quota.
+ *
+ * Conservative by construction (the policy Jun is asked to confirm in #7046):
+ * - An account is a candidate only when it is a selectable stored pool account that is not
+ *   paused, plan-excluded, quarantined for sign-in, otherwise unusable, or denied for the model.
+ *   Those are operator or credential states no clock lifts.
+ * - Its recovery time is the LATEST of every routing hold with a known end: quota-health cooldown,
+ *   quota avoidance, transient soft avoidance, pool-refresh backoff, and the credits-off
+ *   usage-limit reset. An account under a hold whose end is unknown, or under the sliding
+ *   failure-window guard (whose end moves with every failure), is skipped rather than guessed.
+ * - For an account-gated model, only accounts the resolved entitlement roster admits count, and
+ *   with no resolved roster nothing does.
+ * - An account with no recorded hold is skipped: nothing says when it became unavailable, so
+ *   nothing says when it will be available again.
+ * - Main itself is never a candidate; its own reset stays on the refusal.
+ */
+import { isCodexAccountPaused } from "../account-pause";
+import { codexUsageLimitResetAt } from "../account-credit-use";
+import { isSelectableCodexPoolAccount } from "../account-id";
+import { isAccountNeedsReauth } from "../account-runtime-state";
+import { isCodexAccountUsable } from "../account-usability";
+import { getCodexPoolRefreshCooldownUntil } from "../pool-refresh-backoff";
+import { getAccountQuota } from "../quota";
+import type { OcxConfig } from "../../types";
+import { failureWindowSteersNewThreads } from "./failure-window";
+import {
+  codexQuotaAvoidUntil, getCodexAccountSoftAvoidUntil, getCodexQuotaHealthSnapshot, type CodexQuotaScope,
+} from "./health-store";
+import { getPoolAccountPlanForSelection, isCodexAccountHeldAtUsageLimit, isCodexAccountPlanExcluded } from "./selection";
+
+export function nextCodexPoolRecoveryAt(
+  config: OcxConfig,
+  now: number,
+  quotaScope?: CodexQuotaScope,
+  options: {
+    deniedAccountIds?: ReadonlySet<string>;
+    /** When set, only these accounts may serve the model (account-gated models). */
+    eligibleAccountIds?: ReadonlySet<string>;
+  } = {},
+): number | undefined {
+  let earliest: number | undefined;
+  for (const account of config.codexAccounts ?? []) {
+    if (!isSelectableCodexPoolAccount(account)) continue;
+    const id = account.id;
+    if (options.deniedAccountIds?.has(id) || (options.eligibleAccountIds && !options.eligibleAccountIds.has(id))
+      || isCodexAccountPaused(config, id)
+      || isCodexAccountPlanExcluded(config, id) || isAccountNeedsReauth(id)
+      || !isCodexAccountUsable(config, id) || failureWindowSteersNewThreads(config, id, now)) continue;
+    const holds: number[] = [];
+    const health = getCodexQuotaHealthSnapshot(id, quotaScope, now);
+    if (health) {
+      if (typeof health.cooldownUntil !== "number" || !Number.isFinite(health.cooldownUntil)) continue;
+      holds.push(health.cooldownUntil);
+    }
+    const avoidUntil = codexQuotaAvoidUntil(id, quotaScope, now);
+    if (avoidUntil !== null) holds.push(avoidUntil);
+    const softAvoidUntil = getCodexAccountSoftAvoidUntil(id, now);
+    if (softAvoidUntil !== null) holds.push(softAvoidUntil);
+    const refreshCooldownUntil = getCodexPoolRefreshCooldownUntil(id, now);
+    if (refreshCooldownUntil !== null) holds.push(refreshCooldownUntil);
+    if (isCodexAccountHeldAtUsageLimit(config, id, now)) {
+      const resetAt = codexUsageLimitResetAt(getAccountQuota(id), getPoolAccountPlanForSelection(config, id), now);
+      if (resetAt === undefined) continue;
+      holds.push(resetAt);
+    }
+    if (holds.length === 0) continue;
+    const recoveryAt = Math.max(...holds);
+    if (recoveryAt > now && (earliest === undefined || recoveryAt < earliest)) earliest = recoveryAt;
+  }
+  return earliest;
+}

package/src/codex/shim-diagnostics.ts

@@ -29,6 +29,12 @@ export interface CodexShimDiagnostic {
   summary: string;
   runnable?: boolean;
   active?: boolean | null;
+  /**
+   * PATH overlay only: the wrapper and its private state are intact and runnable, but this process
+   * could not see it first on PATH. Reinstalling cannot change that; the shell must source the
+   * environment file. The dashboard's PATH can also differ from the user's shell (#6971).
+   */
+  activationPending?: boolean;
 }
 
 /** Structured, secret-free shim state for CLI/GUI lifecycle diagnostics. */

package/src/codex/shim-overlay.ts

@@ -44,6 +44,10 @@ export function overlayActivationHint(configDir = getConfigDir()): string {
 function sameId(left: OverlayIdentity | null | undefined, right: OverlayIdentity | null | undefined): boolean {
   return !!left && !!right && left.dev === right.dev && left.ino === right.ino;
 }
+/** APFS device numbers can change after reboot; persisted ownership still requires the same inode. */
+function samePersistedInode(current: OverlayIdentity, recorded: OverlayIdentity | undefined): boolean {
+  return !!recorded && current.ino === recorded.ino;
+}
 function lexical(path: string): Stats | null {
   try { return lstatSync(path); }
   catch (error) { if (fileErrorCode(error) === "ENOENT") return null; throw error; }
@@ -128,7 +132,7 @@ function shellEnvironment(): string {
     'unset ocx_shim_dir ocx_shim_rest ocx_shim_path ocx_shim_more ocx_shim_part', ""].join("\n");
 }
 function ownedWrapper(value: Snapshot, state: OverlayState): boolean {
-  return sameId(value.identity, state.wrapperIdentity)
+  return samePersistedInode(value.identity, state.wrapperIdentity)
     && value.content.includes(SHIM_MARKER) && value.content.includes(`exec ${shQuote(state.launcherPath)} "$@"`);
 }
 function requireOverlayIdentities(state: OverlayState): void {
@@ -137,7 +141,7 @@ function requireOverlayIdentities(state: OverlayState): void {
   }
 }
 function ownedEnvironment(value: Snapshot, state: OverlayState): boolean {
-  return sameId(value.identity, state.envIdentity) && value.content === shellEnvironment();
+  return samePersistedInode(value.identity, state.envIdentity) && value.content === shellEnvironment();
 }
 function revalidateOverlay(state: OverlayState, saved: Snapshot | null, wrapper: Snapshot | null, env: Snapshot | null): void {
   if (!unchanged(statePath(), saved) || !unchanged(state.wrapperPath, wrapper) || !unchanged(overlayPaths().env, env)) {
@@ -201,6 +205,7 @@ export function overlayDiagnostic(state: ShimState): CodexShimDiagnostic {
     inspection?.revalidate();
   } catch (error) { active = null; runnable = false; integrityMessage = failure(error).message; }
   return { installed: true, healthy: complete && runnable && active === true, runnable, active,
+    activationPending: complete && runnable && active !== true,
     summary: `Codex PATH shim: ${complete && runnable ? "ready" : "unhealthy"} at ${state.wrapperPath}; launcher ${state.launcherPath}; PATH ${active === null ? "unverified" : active ? "active" : "inactive"}. ${complete && runnable ? overlayActivationHint() : integrityMessage || "Run ocx codex-shim install to repair the shim."}` };
 }
 

package/src/config/diagnostics.ts

@@ -6,6 +6,7 @@ import { lstatSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import * as z from "zod/v4";
 import { compactionRecoveryConfigError } from "./schema/compaction-recovery";
+import { desktopCompatibilityConfigError } from "./schema/desktop-compatibility";
 import { blockedModelRedirectsError } from "./schema/blocked-model-redirects";
 import type { OcxConfig } from "../types";
 import { anthropicAccountPoolConfigError, anthropicOAuthInstanceConfigError, anthropicSidecarConfigError } from "./schema/anthropic-account-pool";
@@ -694,7 +695,7 @@ export function validateConfigCandidate(value: unknown): { ok: true; config: Ocx
   const anthropicError = anthropicOAuthInstanceConfigError(value) ?? anthropicAccountPoolConfigError(value) ?? anthropicSidecarConfigError(value);
   if (anthropicError) return { ok: false, error: anthropicError };
   const boundaryError = blockedModelRedirectsError(value)
-    ?? compactionRecoveryConfigError(value) ?? configReasoningPinsConfigError(value)
+    ?? compactionRecoveryConfigError(value) ?? desktopCompatibilityConfigError(value) ?? configReasoningPinsConfigError(value)
     ?? blankHostnameError(value)
     ?? (rawSubagentModelForce(value) !== undefined && !isSubagentModelEntry(rawSubagentModelForce(value)) ? "schema_invalid: claudeCode.subagentModelForce: expected a safe roster-style model id" : null)
     ?? claudeSubagentEffortError(value)

package/src/config/live-reconcile.ts

@@ -138,6 +138,19 @@ export function adoptPersistedProviderIntoLiveConfig(
   if (persistedConfig) refreshPreservedProviderOwner(config, persistedConfig);
 }
 
+/** Adopt only the committed next-start preference; preserve unrelated pending live edits. */
+export function adoptPersistedDesktopCompatibility(config: OcxConfig, persisted: OcxConfig["desktopCompatibility"]): void {
+  const baseline = liveConfigBaseline.get(config);
+  const merged = reconcileConfigValue(baseline?.desktopCompatibility ?? MISSING_CONFIG_VALUE,
+    config.desktopCompatibility ?? MISSING_CONFIG_VALUE, persisted ?? MISSING_CONFIG_VALUE);
+  if (merged === MISSING_CONFIG_VALUE) delete config.desktopCompatibility;
+  else config.desktopCompatibility = merged as OcxConfig["desktopCompatibility"];
+  if (baseline) {
+    if (persisted === undefined) delete baseline.desktopCompatibility;
+    else baseline.desktopCompatibility = structuredClone(persisted);
+  }
+}
+
 /** Test seam only: is this instance armed? */
 export function claudeCodeBaselineArmed(config: OcxConfig): boolean {
   return claudeCodeBaseline.has(config);

package/src/config/load-degrade.ts

@@ -3,6 +3,7 @@ import { isSubagentModelEntry, rawSubagentModelForce } from "./subagent-models";
 import { chmodSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { compactionRecoveryConfigError } from "./schema/compaction-recovery";
+import { desktopCompatibilityConfigError } from "./schema/desktop-compatibility";
 import { blockedModelRedirectsError } from "./schema/blocked-model-redirects";
 import { anthropicSidecarConfigError } from "./schema/anthropic-account-pool";
 import {
@@ -51,9 +52,12 @@ import { hasWarnedInheritedFastWireConflict, markWarnedInheritedFastWireConflict
 
 export function hardenExistingSecret(path: string): void {
   if (existsSync(path) && !isPassiveRead()) {
-    try { chmodSync(path, 0o600); } catch { /* best-effort */ }
     if (process.platform === "win32") {
+      // Preserve the ACL helper's metadata observation across reads. Windows chmod does
+      // not establish a private DACL and can invalidate that observation before every load.
       hardenSecretPath(path, { required: false });
+    } else {
+      try { chmodSync(path, 0o600); } catch { /* best-effort */ }
     }
   }
 }
@@ -129,6 +133,7 @@ export function warnDegradedCompactionRouting(rawParsed: unknown, validated: Ocx
 export function warnDegradedTopLevelOptIns(rawParsed: unknown, validated: OcxConfig): void {
   setCodexWsReuseAcrossTurns(validated.codexWsReuseAcrossTurns === true);
   if (compactionRecoveryConfigError(rawParsed)) console.warn("⚠️  invalid compactionRecovery disabled; the original compaction failure is preserved");
+  if (desktopCompatibilityConfigError(rawParsed)) console.warn("Invalid desktopCompatibility startup preference ignored; no desktop compatibility service will start automatically.");
   if (blockedModelRedirectsError(rawParsed)) console.warn("⚠️  invalid blockedModelRedirects ignored; provider routing remains available");
   const chatgptDesktop = chatgptDesktopConfigIssue(rawParsed);
   if (chatgptDesktop) console.warn(`⚠️  config.json ${chatgptDesktop} — the whole chatgptDesktop block is ignored, so the ChatGPT desktop integration reads as off`);

package/src/config/paths.ts

@@ -4,6 +4,7 @@ import { join, resolve } from "node:path";
 import { flushWindowsSecretAclReapsBeforeRemoval, hardenSecretDirAsync, windowsSecretAclApplies } from "../lib/windows-secret-acl";
 import { assertNotRealHomeUnderTest } from "../lib/test-home-guard";
 import { isPassiveRead } from "../lib/passive-read";
+import { trackBackgroundWork } from "../lib/background-work";
 
 /**
  * Expand a leading `~` in user-supplied paths without interpreting shell
@@ -37,17 +38,23 @@ export function hardenConfigDir(): void {
   // have changed the protected directory used by the test-home boundary.
   assertNotRealHomeUnderTest(dir);
   if (!existsSync(dir)) return;
-  try { chmodSync(dir, 0o700); } catch { /* best-effort */ }
+  // Windows privacy is enforced by NTFS ACLs. chmod only changes DOS attributes there;
+  // doing it before the ACL lookup can invalidate its ctime-based successful observation.
+  if (!windowsSecretAclApplies()) {
+    try { chmodSync(dir, 0o700); } catch { /* best-effort */ }
+  }
   if (windowsSecretAclApplies() && !configDirHardeningFlights.has(dir)) {
     // This is an optional read-path harden. Waiting synchronously here used to stop the Bun
     // event loop (including /healthz) for the full icacls timeout. Required mutation paths keep
     // their own awaited/fail-closed hardening; ordinary config reads only start one soft flight.
-    const flight = hardenSecretDirAsync(dir, { required: false })
+    // Tracked: icacls holds the directory open, and a config write or removal that lands on
+    // it before the child exits fails with a sharing violation on Windows.
+    const flight = trackBackgroundWork("config-dir-acl-harden", hardenSecretDirAsync(dir, { required: false })
       .then(() => undefined)
       .catch(() => undefined)
       .finally(() => {
         if (configDirHardeningFlights.get(dir) === flight) configDirHardeningFlights.delete(dir);
-      });
+      }));
     configDirHardeningFlights.set(dir, flight);
   }
 }