@bitkyc08/opencodex 2.79.0 → 2.81.0

package/src/clients/config-export.ts

@@ -21,7 +21,7 @@
  */
 import { homedir } from "node:os";
 import { existsSync, lstatSync, readFileSync, realpathSync, statSync } from "node:fs";
-import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve, win32 } from "node:path";
 import { shouldInjectApiAuthHeader, standaloneCodexRoutingTarget } from "../codex/inject";
 import { FORMAT_MEDIA_TYPE, serializeDocument, type ConfigFormat } from "../integrations/serialize";
 import { canonicalizeReasoningEfforts } from "../reasoning-effort";
@@ -69,6 +69,18 @@ import { buildKiloClientConfig, summarizeKilo, buildKiloContribution, kiloConfig
 export { kiloConfigPath, kiloHomeDir, kiloCandidatePath, KILO_CONFIG_CANDIDATES } from "./config-export/kilo";
 export type { KiloGeneratedConfig, KiloProviderBlock, KiloModelEntry } from "./config-export/kilo";
 import { droidConfigPath, buildDroidClientConfig, summarizeDroid, buildDroidContribution } from "./config-export/droid";
+import {
+  buildCommandCodeClientConfig,
+  summarizeCommandCode,
+  buildCommandCodeContribution,
+  commandCodeProviderRoot,
+  type CommandCodeGeneratedConfig,
+  type CommandCodeModelEntry,
+  type CommandCodeProviderBlock,
+} from "./config-export/commandcode";
+
+export type { CommandCodeGeneratedConfig, CommandCodeModelEntry, CommandCodeProviderBlock };
+export { buildCommandCodeClientConfig, summarizeCommandCode, buildCommandCodeContribution, commandCodeProviderRoot };
 
 
 
@@ -474,6 +486,43 @@ export function zcodeConfigPath(env: OpencodeLaunchEnv = process.env, home: stri
   return join(zcodeHomeDir(env, home), "v2", "config.json");
 }
 
+/**
+ * The home directory Command Code itself resolves: `env.HOME ?? env.USERPROFILE`
+ * (`homeDir15` in the published `command-code@1.66.0` bundle).
+ *
+ * On POSIX `os.homedir()` already reads `$HOME`, so the two agree and `home` is
+ * returned as is. On Windows `os.homedir()` reads `%USERPROFILE%` and ignores
+ * `HOME`, which Git for Windows, MSYS2 and Cygwin set, so a user whose `HOME` differs
+ * would get a provider block in a store Command Code never opens. Only the OS-default
+ * home is replaced: a caller that injects a different root (a test, the writer's
+ * `input.home`) keeps it, and a blank or relative value falls back to `home`.
+ */
+export function commandCodeUserHome(env: OpencodeLaunchEnv = process.env, home: string = homedir(), platform: NodeJS.Platform = process.platform): string {
+  if (platform !== "win32" || home !== homedir()) return home;
+  const value = env.HOME ?? env.USERPROFILE;
+  return typeof value === "string" && value.trim() && win32.isAbsolute(value) ? value : home;
+}
+
+/**
+ * Command Code's provider store directory — `.commandcode` under the home the client
+ * resolves (see {@link commandCodeUserHome}), with no override.
+ *
+ * There is deliberately no `COMMANDCODE_HOME` here, unlike the other clients in this
+ * file: `grep -c COMMANDCODE_HOME` over the shipped `dist/cli.mjs` and
+ * `dist/index.mjs` returns 0. An override we honour but the client ignores is worse
+ * than none: `enable` would report success and write a provider block at a path no
+ * Command Code process ever opens, and the user would see an empty model list with no
+ * error anywhere. An apply against a relocated home is instead refused by `detectDir`
+ * not existing.
+ */
+export function commandCodeHomeDir(env: OpencodeLaunchEnv = process.env, home: string = homedir(), platform: NodeJS.Platform = process.platform): string {
+  return join(commandCodeUserHome(env, home, platform), ".commandcode");
+}
+
+export function commandCodeConfigPath(env: OpencodeLaunchEnv = process.env, home: string = homedir(), platform: NodeJS.Platform = process.platform): string {
+  return join(commandCodeHomeDir(env, home, platform), "providers.json");
+}
+
 /**
  * The provider store a current ZCode reads, which is NOT the file above.
  *
@@ -1487,6 +1536,20 @@ export const EXPORT_CLIENTS: Record<ExportClientId, ExportClientSpec> = {
     // remote binds refuse — same reasoning as MCode.
     loopbackOnly: true,
   },
+  commandcode: {
+    id: "commandcode",
+    filename: "providers.json",
+    destination: env => commandCodeConfigPath(env),
+    // No env var exists behind this integration: buildCommandCodeClientConfig
+    // writes `apiKey: false`, the documented keyless form for a loopback endpoint.
+    apiKeyEnv: "",
+    exportHint: "The provider is written with `apiKey: false` — Command Code treats a keyless loopback endpoint as already authenticated. No key is stored or referenced.",
+    build: buildCommandCodeClientConfig,
+    format: "json",
+    summarize: summarizeCommandCode,
+    buildContribution: buildCommandCodeContribution,
+    loopbackOnly: true,
+  },
   prime: {
     id: "prime",
     filename: "prime-models.json",

package/src/codex/auth-api/account-list.ts

@@ -252,6 +252,13 @@ export function reconcileFreshPoolAccountPlans(runtimeConfig: OcxConfig, updates
   }
 }
 
+export interface CodexAuthAccountsListOptions {
+  /** Finish deferred registration; only a dashboard session carries that inference consent. */
+  validatePending?: boolean;
+  /** An operator's explicit refresh command, which may retry a grant already recorded as dead. */
+  explicitRefresh?: boolean;
+}
+
 export interface CodexAuthAccountsSnapshot {
   accounts: CodexAuthAccountDto[];
   mainIdentityGeneration: number;
@@ -260,7 +267,7 @@ export interface CodexAuthAccountsSnapshot {
 export async function listCodexAuthAccountsSnapshot(
   config: OcxConfig,
   forceRefresh = false,
-  options: { validatePending?: boolean } = {},
+  options: CodexAuthAccountsListOptions = {},
 ): Promise<CodexAuthAccountsSnapshot> {
   const runtimeConfig = getRuntimeConfig(config);
   const poolAccounts = (runtimeConfig.codexAccounts ?? []).filter(isSelectableCodexPoolAccount);
@@ -281,7 +288,8 @@ export async function listCodexAuthAccountsSnapshot(
         // identity when the switch is on and nothing has been observed yet.
         const creditsIdentity = runtimeConfig.showCodexCredits === true ? poolQuotaHistoryIdentity(account.id) ?? null : null;
         const creditsUnobserved = creditsIdentity !== null && !hasCodexCreditsObservation(account.id, creditsIdentity);
-        quotaResult = await fetchPoolAccountQuota(account.id, forceRefresh || creditsUnobserved, account.plan, getValidCodexToken, options.validatePending === true);
+        quotaResult = await fetchPoolAccountQuota(account.id, forceRefresh || creditsUnobserved, account.plan, getValidCodexToken,
+          options.validatePending === true, undefined, undefined, options.explicitRefresh === true);
       } catch (error) {
         if (!(error instanceof PoolQuotaProbeBusyError)) throw error;
         quotaResult = {
@@ -447,7 +455,7 @@ export async function refreshCodexQuotaForActivation(config: OcxConfig, accountI
 export async function listCodexAuthAccounts(
   config: OcxConfig,
   forceRefresh = false,
-  options: { validatePending?: boolean } = {},
+  options: CodexAuthAccountsListOptions = {},
 ): Promise<CodexAuthAccountDto[]> {
   return (await listCodexAuthAccountsSnapshot(config, forceRefresh, options)).accounts;
 }

package/src/codex/auth-api/main-account-probe.ts

@@ -146,6 +146,11 @@ export async function fetchMainAccountInfo(forceRefresh = false, config?: OcxCon
   return (await fetchMainAccountInfoSnapshot(forceRefresh, config)).info;
 }
 
+export interface MainAccountInfoProbeOptions {
+  /** Metadata-only renewal never sets or clears the traffic reauth quarantine. */
+  passive?: boolean;
+}
+
 export const EMPTY_MAIN_ACCOUNT_INFO: MainAccountInfo = { email: null, plan: null, quota: null };
 
 export async function retryMainAccountInfoIfIdentityChanged(
@@ -154,12 +159,13 @@ export async function retryMainAccountInfoIfIdentityChanged(
   nativeMainLease: AdmissionLease,
   explicitRefresh: boolean,
   paced: boolean,
+  options: MainAccountInfoProbeOptions = {},
 ): Promise<MainAccountInfoFetchResult | null> {
   const currentAccountId = getMainChatgptAccountId();
   if (currentAccountId === null || currentAccountId === requestAccountId) return null;
   reconcileMainCodexAccountRuntimeState();
   return retriesRemaining > 0
-    ? fetchMainAccountInfoWhileOwned(true, retriesRemaining - 1, nativeMainLease, explicitRefresh, false, paced)
+    ? fetchMainAccountInfoWhileOwned(true, retriesRemaining - 1, nativeMainLease, explicitRefresh, false, paced, options)
     : { info: EMPTY_MAIN_ACCOUNT_INFO, credentialChecked: true, hasCredential: true };
 }
 
@@ -171,6 +177,7 @@ export async function fetchMainAccountInfoAttempt(
   explicitRefresh: boolean = forceRefresh,
   postReset = false,
   config?: OcxConfig,
+  options: MainAccountInfoProbeOptions = {},
 ): Promise<MainAccountInfoFetchResult> {
   const nativeMainLease = existingNativeMainLease ?? tryAcquireNativeMainProfileClaim();
   if (!nativeMainLease) {
@@ -184,7 +191,7 @@ export async function fetchMainAccountInfoAttempt(
   try {
     const paced = sharedMainQuotaPacingEnabled(config ?? loadConfig());
     const operation = async () => ({
-      ...await fetchMainAccountInfoWhileOwned(forceRefresh, retriesRemaining, nativeMainLease, explicitRefresh, postReset, paced),
+      ...await fetchMainAccountInfoWhileOwned(forceRefresh, retriesRemaining, nativeMainLease, explicitRefresh, postReset, paced, options),
       identityGeneration: captureMainAccountIdentityGeneration(),
     });
     if (nativeMainSharedClaimHeld) return await operation();
@@ -225,6 +232,7 @@ export async function fetchMainAccountInfoWhileOwned(
   /** Reset-credit consume needs a fresh post-spend observation, not an earlier read. */
   postReset = false,
   paced = true,
+  options: MainAccountInfoProbeOptions = {},
 ): Promise<MainAccountInfoFetchResult> {
   const writerGeneration = captureConfigGeneration();
   reconcileMainCodexAccountRuntimeState();
@@ -287,7 +295,16 @@ export async function fetchMainAccountInfoWhileOwned(
         const current = credentialIsCurrent() && writerGeneration === captureConfigGeneration();
         if (!current) return { info: getMainAccountInfoCache() ?? EMPTY_MAIN_ACCOUNT_INFO,
           credentialChecked: true, hasCredential: true };
-        if (explicitRefresh && (admission.result.quotaRefresh?.status === "ok"
+        // Single-flight shares evidence, but each caller retains its own auth behavior.
+        if (!options.passive && admission.result.terminalAuthFailure) {
+          const diagnosticStillLive = admission.result.quotaRefreshGeneration !== undefined
+            && isMainAccountIdentityGenerationLive(admission.result.quotaRefreshGeneration);
+          clearMainAccountInfoCache();
+          markAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID, writerGeneration);
+          return { ...admission.result, ...(diagnosticStillLive
+            ? { quotaRefreshGeneration: captureMainAccountIdentityGeneration() } : {}) };
+        }
+        if (!options.passive && explicitRefresh && (admission.result.quotaRefresh?.status === "ok"
           || admission.result.quotaRefresh?.status === "not_reported")) clearAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
         return admission.result;
       }
@@ -297,13 +314,13 @@ export async function fetchMainAccountInfoWhileOwned(
       if (!resp.ok) {
         const authFailure = await classifyMainAuthResponse(resp, isMainAccountTokenVerifiablyLive());
         const terminalAuthFailure = authFailure.terminal;
-        const retried = await retryMainAccountInfoIfIdentityChanged(requestAccountId, retriesRemaining, nativeMainLease, explicitRefresh, paced);
+        const retried = await retryMainAccountInfoIfIdentityChanged(requestAccountId, retriesRemaining, nativeMainLease, explicitRefresh, paced, options);
         if (retried) return retried;
         if (!isQuotaDispatchCurrent(dispatchSequence) || !credentialIsCurrent()) {
           return { info: getMainAccountInfoCache() ?? EMPTY_MAIN_ACCOUNT_INFO,
             credentialChecked: true, hasCredential: true };
         }
-        if (terminalAuthFailure) {
+        if (terminalAuthFailure && !options.passive) {
           // Account for this attempt's own synchronous invalidation, never prior external drift.
           const diagnosticStillLive = isMainAccountIdentityGenerationLive(quotaRefreshGeneration);
           clearMainAccountInfoCache();
@@ -324,7 +341,7 @@ export async function fetchMainAccountInfoWhileOwned(
       quotaPhase = "body";
       const data = (await resp.json()) as WhamUsageResponse;
       quotaPhase = "publish";
-      const retried = await retryMainAccountInfoIfIdentityChanged(requestAccountId, retriesRemaining, nativeMainLease, explicitRefresh, paced);
+      const retried = await retryMainAccountInfoIfIdentityChanged(requestAccountId, retriesRemaining, nativeMainLease, explicitRefresh, paced, options);
       if (retried) return retried;
       quotaPhase = "decode";
       if (data === null || typeof data !== "object" || Array.isArray(data)) {
@@ -376,7 +393,7 @@ export async function fetchMainAccountInfoWhileOwned(
       // never settled and the dashboard kept showing nothing — the symptom #327 reported.
       // An explicit refresh is an operator asking to re-evaluate, normally right after
       // signing in again, so it stays authoritative.
-      if (explicitRefresh) clearAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
+      if (explicitRefresh && !options.passive) clearAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
       // Mirror main quota + plan into the shared stores so the rotation engine can
       // score and auto-switch the main account exactly like a pool account (Option A).
       setMainAccountPlan(result.plan);
@@ -398,7 +415,7 @@ export async function fetchMainAccountInfoWhileOwned(
         ...(freshResetCredits !== undefined ? { freshResetCredits } : {}),
       };
     } catch (error) {
-      const retried = await retryMainAccountInfoIfIdentityChanged(requestAccountId, retriesRemaining, nativeMainLease, explicitRefresh, paced);
+      const retried = await retryMainAccountInfoIfIdentityChanged(requestAccountId, retriesRemaining, nativeMainLease, explicitRefresh, paced, options);
       if (retried) return retried;
       if (!credentialIsCurrent()) {
         return { info: getMainAccountInfoCache() ?? EMPTY_MAIN_ACCOUNT_INFO,

package/src/codex/auth-api/pool-mode-gate.ts

@@ -1,9 +1,11 @@
-import { codexAccountUsesCreditsAfterLimit } from "../account-credit-use";
+import { codexAccountUsesCreditsAfterLimit, codexUsageLimitResetAt } from "../account-credit-use";
 import { nextCodexUsageQueryAt, nextQuotaQueryDelay, pruneRemovedCodexPoolUsageAccounts } from "../quota-query-backoff";
 import { CODEX_PRIORITY_FAILBACK_REFRESH_MS } from "../account-priority";
 import { codexQuotaHasFreshUsage } from "../quota-observation-freshness";
 import { getCodexAccountCredential, getValidCodexToken, readCodexAccountRecord } from "../account-store";
-import { getAccountQuota, isCompleteCodexQuotaRecoverySnapshot } from "../quota";
+import { getAccountQuota, getMainPolicyQuota, isCompleteCodexQuotaRecoverySnapshot } from "../quota";
+import { isCodexAccountPaused } from "../account-pause";
+import { hasSpendableCodexCredits } from "../quota-types";
 import { reconcileMainCodexAccountRuntimeState } from "../account-lifecycle";
 import { claimDueCodexQuotaRecoveryProbes, settleCodexQuotaRecoveryProbe } from "../routing";
 import { readCodexTokens } from "../auth-collision";
@@ -73,17 +75,33 @@ export async function runCodexCooldownRecoveryProbes(config: OcxConfig, now = Da
   return cooldownRecoveryInFlight;
 }
 
+const MAIN_CREDIT_RENEWAL_AGE_MS = 3 * 60_000;
+
 let mainHardLockRecoveryInFlight: Promise<void> | null = null;
 let mainHardLockRecoveryAttempt: { identity: number; credential: number; after: number; delay: number } | undefined;
 
 /** Metadata-only recovery on the existing sweep; failures retain the observed policy block. */
 export async function runMainAccountHardLockRecovery(config: OcxConfig): Promise<void> {
   if (mainHardLockRecoveryInFlight) return mainHardLockRecoveryInFlight;
+  /** Schedule a real credit observation while leaving actual-time admission unchanged. */
+  const creditRecoveryNeeded = (): boolean => {
+    const now = Date.now();
+    const quota = getMainPolicyQuota();
+    const observedAt = quota?.credits?.observedAt;
+    // getMainPolicyQuota binds evidence to the observed physical identity. Only renew
+    // valid formerly spendable funds; admission retains the actual five-minute clock.
+    return codexAccountUsesCreditsAfterLimit(config, MAIN_CODEX_ACCOUNT_ID)
+      && !isCodexAccountPaused(config, MAIN_CODEX_ACCOUNT_ID)
+      && codexUsageLimitResetAt(quota, undefined, now) !== undefined
+      && observedAt !== undefined && observedAt > 0
+      && now - observedAt >= MAIN_CREDIT_RENEWAL_AGE_MS
+      && hasSpendableCodexCredits(quota, observedAt);
+  };
   const status = getMainAccountHardLockStatus(config);
-  if (status.state !== "blocked") { mainHardLockRecoveryAttempt = undefined; return; }
+  if (status.state !== "blocked" && !creditRecoveryNeeded()) { mainHardLockRecoveryAttempt = undefined; return; }
   if (isAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID)) return;
   // A predicted reset is a scheduling hint, never proof that the hard lock can be lifted.
-  if (status.resetAt !== undefined && status.resetAt > Date.now()) return;
+  if (status.state === "blocked" && status.resetAt !== undefined && status.resetAt > Date.now()) return;
   // Reconcile the owned physical credential before skipping work for an older one.
   reconcileMainCodexAccountRuntimeState();
   const physical = readCodexTokens();
@@ -98,9 +116,10 @@ export async function runMainAccountHardLockRecovery(config: OcxConfig): Promise
   if (!lease) return;
   mainHardLockRecoveryInFlight = (async () => {
     reconcileMainCodexAccountRuntimeState();
-    if (getMainAccountHardLockStatus(config).state !== "blocked"
+    if ((getMainAccountHardLockStatus(config).state !== "blocked" && !creditRecoveryNeeded())
       || isAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID)) return;
     const identityGeneration = captureMainAccountIdentityGeneration();
+    const passive = getMainAccountHardLockStatus(config).state !== "blocked";
     try {
       // Refresh can require an exclusive credential claim: never hold WHAM's shared
       // claim while obtaining a valid token. The runtime lease spans both operations.
@@ -111,7 +130,12 @@ export async function runMainAccountHardLockRecovery(config: OcxConfig): Promise
       // Native refresh retains its own grant-scoped refusal; global quarantine would outlive it.
       return;
     }
-    if (isAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID)) return;
+    const currentStatus = getMainAccountHardLockStatus(config);
+    if (isAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID)
+      || !isMainAccountIdentityGenerationLive(identityGeneration)
+      || (passive && !creditRecoveryNeeded())
+      || (currentStatus.state === "blocked" && currentStatus.resetAt !== undefined
+        && currentStatus.resetAt > Date.now())) return;
     const credential = getMainQuotaCredentialGeneration();
     // Reconcile the physical bearer before consulting the previous credential's delay.
     if (previous?.identity === identityGeneration && previous.credential === credential
@@ -123,7 +147,7 @@ export async function runMainAccountHardLockRecovery(config: OcxConfig): Promise
         after: currentQueryAfter };
       return;
     }
-    const result = await fetchMainAccountInfoAttempt(true, 1, lease, false, false, false, config);
+    const result = await fetchMainAccountInfoAttempt(true, 1, lease, false, false, false, config, { passive });
     // Never charge a replacement credential for a late result from its predecessor.
     if (isMainAccountIdentityGenerationLive(identityGeneration)
       && credential === getMainQuotaCredentialGeneration()) {
@@ -134,11 +158,11 @@ export async function runMainAccountHardLockRecovery(config: OcxConfig): Promise
         const authStatus = result.quotaRefresh.status === "http_error"
           ? result.quotaRefresh.httpStatus : undefined;
         const transientAuth = (authStatus === 401 || authStatus === 403)
-          && !isAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
+          && !result.terminalAuthFailure && !isAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
         if (transientAuth) mainHardLockRecoveryAttempt = undefined;
         else {
           const delay = nextQuotaQueryDelay(previousDelay || undefined);
-          mainHardLockRecoveryAttempt = getMainAccountHardLockStatus(config).state === "blocked"
+          mainHardLockRecoveryAttempt = getMainAccountHardLockStatus(config).state === "blocked" || creditRecoveryNeeded()
             ? { identity: identityGeneration, credential, delay, after: Math.max(Date.now() + delay, queryAfter) }
             : undefined;
         }

package/src/codex/auth-api/pool-quota-probe.ts

@@ -495,6 +495,7 @@ export async function fetchPoolAccountQuota(
   validatePending = false,
   afterDispatchSequence?: number,
   recoveryProbeNow?: number,
+  explicitRefresh = false,
 ): Promise<PoolQuotaResult> {
   const existing = getAccountQuota(accountId);
   if (afterDispatchSequence === undefined && !forceRefresh && existing && Date.now() - existing.updatedAt < POOL_CACHE_TTL) {
@@ -504,10 +505,23 @@ export async function fetchPoolAccountQuota(
       credentialGeneration: readCodexAccountRecord(accountId)?.generation,
     };
   }
+  const record = readCodexAccountRecord(accountId);
+  // The token endpoint already called this grant revoked or expired. Only a re-login or a
+  // completed validation rewrites the record and drops the marker, so until then a passive read
+  // (dashboard poll, listing, priming, recovery probe) would only POST the dead refresh token again
+  // and log the same 401. Report the stored verdict the failed refresh would have produced. An
+  // operator's explicit refresh command from any principal, a dashboard validation, and a post-reset
+  // readback keep their probe, and a source-linked credential spends no grant of its own, so none
+  // of them is held here.
+  if (!explicitRefresh && !validatePending && afterDispatchSequence === undefined && record && record.deletedAt == null
+    && record.credential && !record.credential.sourceAuthPath
+    && record.lastCodexValidationTerminal === true && record.lastCodexValidationStatus === "failed") {
+    markAccountNeedsReauth(accountId, captureConfigGeneration(), record.generation);
+    return { quota: existing ?? null, needsReauth: true, reauthReason: "refresh_failed", credentialGeneration: record.generation };
+  }
   // A token refresh may increment the generation (and rotate the refresh token) before WHAM
   // completes. Join a flight whose starting or resolved generation is still current, but let a
   // replacement credential with the same pool id start its own request.
-  const record = readCodexAccountRecord(accountId);
   const flights = poolQuotaRefreshInFlight.get(accountId);
   const current = flights && [...flights].find(flight => {
     const generation = flight.state.resolvedCredentialGeneration

package/src/codex/auth-api/routes.ts

@@ -43,6 +43,7 @@ export async function handleCodexAuthAPI(
     // required by AGENTS_INSTALL.md. Raw-admin/CLI refreshes remain observational.
     return jsonResponse({ accounts: await listCodexAuthAccounts(config, true, {
       validatePending: principal === "gui-session",
+      explicitRefresh: true,
     }) });
   }
 

package/src/codex/autostart-health.ts

@@ -4,7 +4,7 @@ import type { OcxConfig } from "../types";
 import { getCodexRoutingKind, type CodexRoutingKind } from "./inject";
 import { collectRoutingAdoption, type RoutingAdoptionEvidence } from "./routing-adoption";
 import { diagnoseCodexShim, type CodexShimDiagnostic } from "./shim";
-import { diagnoseMacDesktopStartup, type DesktopStartupDiagnostic } from "../service/desktop-startup";
+import { diagnoseDesktopStartup, type DesktopStartupDiagnostic } from "../service/desktop-startup";
 
 export type StartupProtection = "service" | "desktop" | "shim" | "none";
 export type StartupHealthStatus = "native" | "protected" | "at-risk";
@@ -90,7 +90,7 @@ export function deriveStartupHealth(inputs: StartupHealthInputs): StartupHealth
   // We can only credit an opencodex service/shim for routing that opencodex owns.
   // An arbitrary localhost gateway has an independent lifecycle that OCX cannot repair.
   const ownsLocalRouting = inputs.routingKind === "opencodex-local";
-  const desktopEffective = inputs.platform === "darwin" && !inputs.diagnosticStale
+  const desktopEffective = (inputs.platform === "darwin" || inputs.platform === "linux") && !inputs.diagnosticStale
     && inputs.desktop?.owned === true && inputs.desktop.loginEnabled
     && inputs.desktop.running && inputs.desktop.viable;
   const protection: StartupProtection = ownsLocalRouting && inputs.serviceViable
@@ -147,7 +147,7 @@ export function collectStartupHealth(
   const shim = diagnostics.shim ?? diagnoseCodexShim();
   const service = diagnostics.service ?? diagnoseService();
   const routingKind = diagnostics.routingKind ?? getCodexRoutingKind();
-  const desktop = diagnostics.desktop ?? diagnoseMacDesktopStartup();
+  const desktop = diagnostics.desktop ?? diagnoseDesktopStartup();
   const routingAdoption = diagnostics.routingAdoption
     ?? (routingKind === "opencodex-local" ? collectRoutingAdoption({ routingKind }) : undefined);
   return deriveStartupHealth({

package/src/codex/catalog/auto-review.ts

@@ -1,3 +1,4 @@
+import { isCodexControlPlaneModel } from "../control-plane-models";
 import { redactSecretString } from "../../lib/redact";
 import type { OcxConfig } from "../../types";
 import { encodeRoutedModelId } from "../../providers/slug-codec";
@@ -34,6 +35,7 @@ export type AutoReviewModelOverrideResult = "absent" | "applied" | "invalid" | "
 
 /** True when a catalog row was synthesized by opencodex instead of coming from upstream. */
 function isRoutedCatalogEntry(entry: RawEntry): boolean {
+  if (isCodexControlPlaneModel(entry.slug)) return false;
   const slug = typeof entry.slug === "string" ? entry.slug : "";
   return slug.includes("/")
     || (typeof entry.description === "string" && entry.description.startsWith("Routed via opencodex → "));
@@ -57,6 +59,7 @@ function clearAutoReviewOverrideValue(entry: RawEntry): void {
  * Returns the stamped values when the observed rows match that shape.
  */
 function legacyRootStampValues(observedModels: readonly RawEntry[]): ReadonlySet<string> | undefined {
+  observedModels = observedModels.filter(entry => !isCodexControlPlaneModel(entry?.slug));
   if (observedModels.some(entry => entry?.[AUTO_REVIEW_ROOT_MARKER] !== undefined)) return undefined;
   const configuredValues = new Set(observedModels.flatMap(entry => {
     const value = entry?.auto_review_model_override;
@@ -90,7 +93,7 @@ function clearLegacyRootStamps(models: readonly RawEntry[], sourceModels: readon
   const legacyStamp = legacyRootStampValues([...models, ...sourceModels]);
   if (legacyStamp === undefined) return;
   for (const entry of models) {
-    if (!entry || typeof entry !== "object") continue;
+    if (!entry || typeof entry !== "object" || isCodexControlPlaneModel(entry.slug)) continue;
     const current = entry.auto_review_model_override;
     if (entry[AUTO_REVIEW_ROOT_MARKER] === undefined
       && typeof current === "string" && legacyStamp.has(current)) clearAutoReviewOverrideValue(entry);
@@ -107,7 +110,7 @@ function clearAutoReviewModelOverride(
 ): void {
   const legacyStamp = legacyRootStampValues([...models, ...sourceModels]);
   for (const entry of models) {
-    if (!entry || typeof entry !== "object") continue;
+    if (!entry || typeof entry !== "object" || isCodexControlPlaneModel(entry.slug)) continue;
     const current = entry.auto_review_model_override;
     if (isRoutedCatalogEntry(entry)
       || (entry[AUTO_REVIEW_ROOT_MARKER] === true || rootAutoReviewStamp(entry) !== undefined)
@@ -188,6 +191,7 @@ function preserveNativeAutoReviewModelOverrides(
 
 /** Stamp a root-derived override and mark native rows so later root removal is durable. */
 function stampRootAutoReviewOverride(entry: RawEntry, target: string): void {
+  if (isCodexControlPlaneModel(entry.slug)) return;
   if (!isRoutedCatalogEntry(entry)) {
     const previous = rootAutoReviewStamp(entry);
     const current = entry.auto_review_model_override;
@@ -399,7 +403,7 @@ function applyRootSelectorToRemaining(
 ): AutoReviewModelOverrideResult {
   const clearRemaining = (): void => {
     for (const entry of models) {
-      if (!entry || providerStamped.has(entry)) continue;
+      if (!entry || providerStamped.has(entry) || isCodexControlPlaneModel(entry.slug)) continue;
       // Native rows written by releases before the root marker cannot be told apart from upstream
       // values once provider stamps diverge. clearLegacyRootStamps sweeps the ones the legacy
       // uniform signature still recognizes before provider plans land, because provider stamping
@@ -427,7 +431,7 @@ function applyRootSelectorToRemaining(
     return "unresolved";
   }
   for (const entry of models) {
-    if (!entry || providerStamped.has(entry)) continue;
+    if (!entry || providerStamped.has(entry) || isCodexControlPlaneModel(entry.slug)) continue;
     stampRootAutoReviewOverride(entry, trimmed);
   }
   return "applied";
@@ -449,7 +453,7 @@ export function applyConfiguredAutoReviewModelOverride(
   const { plans, failure } = buildProviderReviewPlans(models, config);
   const providerStamped = new Set<RawEntry>();
   for (const entry of models) {
-    if (!entry || typeof entry !== "object") continue;
+    if (!entry || typeof entry !== "object" || isCodexControlPlaneModel(entry.slug)) continue;
     const provider = catalogEntryProviderName(entry);
     if (!provider) continue;
     const plan = plans.get(provider);
@@ -482,7 +486,10 @@ export function finalizeAutoReviewModelOverride(
   sourceModels: readonly RawEntry[] = [],
   config?: Pick<OcxConfig, "providers">,
 ): AutoReviewModelOverrideResult {
-  if (models && sourceModels.length > 0) preserveNativeAutoReviewModelOverrides(models, sourceModels);
+  if (models && sourceModels.length > 0) preserveNativeAutoReviewModelOverrides(
+    models.filter(entry => !isCodexControlPlaneModel(entry.slug)),
+    sourceModels.filter(entry => !isCodexControlPlaneModel(entry.slug)),
+  );
   if (config && configHasProviderAutoReview(config)) {
     return applyConfiguredAutoReviewModelOverride(models, readConfiguredAutoReviewModel(), config, sourceModels);
   }

package/src/codex/catalog/build-entries.ts

@@ -1,3 +1,5 @@
+import { isCodexControlPlaneModel } from "../control-plane-models";
+import { withCodexControlPlaneRows } from "./control-plane";
 import { CODEX_REASONING_LEVELS, type CodexReasoningLevel } from "../../reasoning-effort";
 import { clearModelCache } from "../model-cache";
 import { routedSlug, slugEquivalenceKey } from "../../providers/slug-codec";
@@ -194,7 +196,7 @@ export function buildCatalogEntriesFromObservedState({
   const comboPublicSlugs = new Set(goModels
     .filter(model => model.provider === COMBO_NAMESPACE)
     .map(catalogModelSlug));
-  for (const slug of gptSlugs) {
+  for (const slug of gptSlugs.filter(slug => !isCodexControlPlaneModel(slug))) {
     const native = deriveEntry(template, slug, "OpenAI native model (Codex OAuth passthrough).", 9, undefined, new Set(), openaiContextCap);
     if (rank.has(slug)) native.priority = rank.get(slug)!;
     nativeEntries.push(native);
@@ -224,7 +226,7 @@ export function buildCatalogEntriesFromObservedState({
     const selectorNativeSlugs = accountNativeSlugsBySelector?.get(selector)
       ?? accountNativeSlugs
       ?? gptSlugs;
-    const accountNativeEntries = selectorNativeSlugs.filter(slug => slug !== NATIVE_RESERVE_MODEL).map(slug => (
+    const accountNativeEntries = selectorNativeSlugs.filter(slug => slug !== NATIVE_RESERVE_MODEL && !isCodexControlPlaneModel(slug)).map(slug => (
       nativeEntriesBySlug.get(slug)
         ?? deriveEntry(template, slug, "OpenAI native model (Codex OAuth passthrough).", 9, undefined, new Set(), openaiContextCap)
     ));
@@ -306,7 +308,7 @@ export function buildCatalogEntriesFromObservedState({
       delete entry.prefer_websockets;
     }
   }
-  return applyMultiAgentMode(out, multiAgentMode, multiAgentV2Enabled, {
+  return applyMultiAgentMode(withCodexControlPlaneRows(out, template ? [template] : [], true, wsEnabled), multiAgentMode, multiAgentV2Enabled, {
     keepNativeChatGptOnV1,
     preserveDefaultMultiAgentVersion: isReserveCatalogProjection,
   });
@@ -409,12 +411,12 @@ export function mergeCatalogModelsWithNativeRecovery(
 ): RawEntry[] {
   const merged = [...primaryCatalogModels];
   const recoveredNativeSlugs = new Set(primaryCatalogModels.flatMap(entry => {
-    const slug = recoverableNativeSlug(entry);
+    const slug = isCodexControlPlaneModel(entry.slug) ? String(entry.slug) : recoverableNativeSlug(entry);
     return slug === null ? [] : [slug];
   }));
   for (const source of nativeRecoverySources) {
     for (const entry of source) {
-      const slug = recoverableNativeSlug(entry);
+      const slug = isCodexControlPlaneModel(entry.slug) ? String(entry.slug) : recoverableNativeSlug(entry);
       if (slug === null || recoveredNativeSlugs.has(slug)) continue;
       merged.push(structuredClone(entry) as RawEntry);
       recoveredNativeSlugs.add(slug);
@@ -460,6 +462,7 @@ export function applyFullModelPickerOrder(entries: RawEntry[], order: readonly s
   if (!pickerOrder.some(slug => !slug.includes("/"))) return;
   const rankOf = modelPickerRank(pickerOrder);
   for (const entry of entries) {
+    if (isCodexControlPlaneModel(entry.slug)) continue;
     const natural = entry[SPAWN_PRIORITY_FIELD] ?? entry.priority ?? 9;
     entry[SPAWN_PRIORITY_FIELD] = natural;
     entry.priority = rankOf(String(entry.slug)) ?? pickerOrder.length + Number(natural);
@@ -539,10 +542,12 @@ export function mergeCatalogEntriesFromObservedState({
   // Raw catalog rows contain nested arrays/objects that normalization mutates. Detach every row at
   // the observed-core boundary so callers can safely retain evidence objects or repeat the merge.
   const detachedCatalogModels = catalogModels
+    .filter(entry => !isCodexControlPlaneModel(entry.slug))
     .map(entry => restoreNativeDisplayName(structuredClone(entry) as RawEntry));
   const detachedBaselineCatalogModels = baselineCatalogModels
+    .filter(entry => !isCodexControlPlaneModel(entry.slug))
     .map(entry => restoreNativeDisplayName(structuredClone(entry) as RawEntry));
-  const detachedRoutedEntries = routedEntries.map(entry => structuredClone(entry) as RawEntry);
+  const detachedRoutedEntries = routedEntries.filter(entry => !isCodexControlPlaneModel(entry.slug)).map(entry => structuredClone(entry) as RawEntry);
   // Track this invocation's generated custom rows, not ownership markers read from disk.
   // Their builder already finalized exact native ladders and ordinary routed mock tiers.
   const freshCustomEntries = new Set(detachedRoutedEntries.filter(entry =>
@@ -921,7 +926,10 @@ export function mergeCatalogEntriesFromObservedState({
   // clobber a hide flag back to list. Bare ids disable every account clone; qualified ids disable
   // only their generated account row.
   const versionedEntries = applyMultiAgentMode(
-    applyNativeVisibility(mergedEntries, disabledModels, alignedAccountBoundEntries.length > 0, observedNativeSlugs),
+    withCodexControlPlaneRows(
+      applyNativeVisibility(mergedEntries, disabledModels, alignedAccountBoundEntries.length > 0, observedNativeSlugs),
+      [...catalogModels, ...baselineCatalogModels, ...routedEntries], includeNativeOpenAi, wsEnabled,
+    ),
     multiAgentMode,
     multiAgentV2Enabled,
     { keepNativeChatGptOnV1, preserveDefaultMultiAgentVersion: isReserveCatalogProjection, nativeDefaults: nativeMultiAgentDefaults },

package/src/codex/catalog/control-plane.ts

@@ -0,0 +1,45 @@
+import { CODEX_INTERNAL_OPENAI_MODELS, isCodexControlPlaneModel } from "../control-plane-models";
+import { COMBO_NAMESPACE } from "../../combos";
+import { CODEX_NATIVE_ALIAS_CATALOG_KIND } from "./kinds";
+import { NATIVE_RESERVE_MODEL, SUPPORTED_NATIVE_OPENAI_SLUGS } from "./native-models";
+import { isReserveCatalogProjection } from "./reserve";
+import { pinnedNativeModelRows } from "./pinned-models";
+import type { RawEntry } from "./parsing";
+
+/** Hidden ordinary natives qualify; Reserve, account choices and routed aliases do not. */
+export function hasOrdinaryNativeOpenAiRow(entries: readonly RawEntry[]): boolean {
+  return entries.some(entry => typeof entry.slug === "string"
+    && !entry.slug.includes("/")
+    && SUPPORTED_NATIVE_OPENAI_SLUGS.has(entry.slug)
+    && entry.slug !== NATIVE_RESERVE_MODEL
+    && !isReserveCatalogProjection(entry)
+    && entry.opencodex_catalog_kind !== CODEX_NATIVE_ALIAS_CATALOG_KIND
+    && entry.owned_by !== COMBO_NAMESPACE);
+}
+
+/** Keep internal reviewer metadata separate from native synthesis, picker ordering and account clones. */
+export function withCodexControlPlaneRows(
+  entries: RawEntry[],
+  sourceRows: readonly RawEntry[],
+  includeNativeOpenAi: boolean,
+  wsEnabled: boolean,
+): RawEntry[] {
+  const models = entries.filter(entry => !isCodexControlPlaneModel(entry.slug));
+  if (!includeNativeOpenAi || !hasOrdinaryNativeOpenAiRow(models)) return models;
+  for (const slug of CODEX_INTERNAL_OPENAI_MODELS) {
+    const source = sourceRows.find(entry => entry.slug === slug)
+      ?? pinnedNativeModelRows().find(entry => entry.slug === slug);
+    // A pin without the row degrades to Codex's own task-model fallback rather than failing the
+    // whole catalog write.
+    if (!source) continue;
+    const row: RawEntry = structuredClone(source);
+    row.visibility = "hide";
+    if (wsEnabled) row.supports_websockets = true;
+    else {
+      delete row.supports_websockets;
+      delete row.prefer_websockets;
+    }
+    models.push(row);
+  }
+  return models;
+}