fix(cliproxy): make codex defaults free-plan safe

src/cliproxy/codex-plan-compatibility.ts

@@ -0,0 +1,89 @@
+import { getDefaultAccount } from './account-manager';
+import { fetchCodexQuota } from './quota-fetcher-codex';
+import { getCachedQuota, setCachedQuota } from './quota-response-cache';
+import type { CodexQuotaResult } from './quota-types';
+import { updateSettingsModel } from './services/variant-settings';
+import { info, warn } from '../utils/ui';
+
+export type CodexPlanType = CodexQuotaResult['planType'];
+
+const FREE_SAFE_DEFAULT_MODEL = 'gpt-5-codex';
+const FREE_SAFE_FAST_MODEL = 'gpt-5-codex-mini';
+const CODEX_EFFORT_SUFFIX_REGEX = /-(xhigh|high|medium)$/i;
+const CODEX_PAREN_SUFFIX_REGEX = /\((xhigh|high|medium)\)$/i;
+const EXTENDED_CONTEXT_SUFFIX_REGEX = /\[1m\]$/i;
+
+const FREE_PLAN_FALLBACKS = new Map<string, string>([
+  ['gpt-5.3-codex', FREE_SAFE_DEFAULT_MODEL],
+  ['gpt-5.3-codex-spark', FREE_SAFE_FAST_MODEL],
+  ['gpt-5.4', FREE_SAFE_DEFAULT_MODEL],
+]);
+
+function normalizeCodexModelId(model: string): string {
+  return model
+    .trim()
+    .replace(EXTENDED_CONTEXT_SUFFIX_REGEX, '')
+    .replace(CODEX_PAREN_SUFFIX_REGEX, '')
+    .replace(CODEX_EFFORT_SUFFIX_REGEX, '')
+    .trim()
+    .toLowerCase();
+}
+
+export function getDefaultCodexModel(): string {
+  return FREE_SAFE_DEFAULT_MODEL;
+}
+
+export function getFreePlanFallbackCodexModel(model: string): string | null {
+  return FREE_PLAN_FALLBACKS.get(normalizeCodexModelId(model)) ?? null;
+}
+
+export async function reconcileCodexModelForActivePlan(options: {
+  settingsPath: string;
+  currentModel: string | undefined;
+  verbose: boolean;
+}): Promise<void> {
+  const { settingsPath, currentModel, verbose } = options;
+  if (!currentModel) return;
+
+  const fallbackModel = getFreePlanFallbackCodexModel(currentModel);
+  if (!fallbackModel) return;
+
+  const defaultAccount = getDefaultAccount('codex');
+  if (!defaultAccount) {
+    console.error(
+      warn(
+        `Configured Codex model "${normalizeCodexModelId(currentModel)}" may require a paid Codex plan. ` +
+          `If startup fails, switch to "${fallbackModel}" with "ccs codex --config".`
+      )
+    );
+    return;
+  }
+
+  const cachedQuota = getCachedQuota<CodexQuotaResult>('codex', defaultAccount.id);
+  const quota = cachedQuota ?? (await fetchCodexQuota(defaultAccount.id, verbose));
+  if (!cachedQuota) {
+    setCachedQuota('codex', defaultAccount.id, quota);
+  }
+
+  if (quota.planType === 'free') {
+    updateSettingsModel(settingsPath, fallbackModel, 'codex');
+    console.error(
+      info(
+        `Codex free plan detected. Switched unsupported model "${normalizeCodexModelId(currentModel)}" ` +
+          `to "${fallbackModel}".`
+      )
+    );
+    return;
+  }
+
+  if (quota.planType) {
+    return;
+  }
+
+  console.error(
+    warn(
+      `Could not verify Codex plan for model "${normalizeCodexModelId(currentModel)}". ` +
+        `If startup fails with model_not_supported, switch to "${fallbackModel}" via "ccs codex --config".`
+    )
+  );
+}

src/cliproxy/executor/index.ts

@@ -32,6 +32,7 @@ import { isAuthenticated } from '../auth-handler';
 import { CLIProxyProvider, CLIProxyBackend, PLUS_ONLY_PROVIDERS, ExecutorConfig } from '../types';
 import { DEFAULT_BACKEND } from '../platform-detector';
 import { configureProviderModel, getCurrentModel } from '../model-config';
+import { reconcileCodexModelForActivePlan } from '../codex-plan-compatibility';
 import { resolveProxyConfig, PROXY_CLI_FLAGS } from '../proxy-config-resolver';
 import { supportsModelConfig, isModelBroken, getModelIssueUrl, findModel } from '../model-catalog';
 import { CodexReasoningProxy } from '../codex-reasoning-proxy';
@@ -731,6 +732,14 @@ export async function execClaudeWithCLIProxy(
   // 6. Ensure user settings file exists
   ensureProviderSettings(provider);
 
+  if (provider === 'codex' && !cfg.isComposite && !skipLocalAuth) {
+    await reconcileCodexModelForActivePlan({
+      settingsPath: cfg.customSettingsPath || getProviderSettingsPath(provider),
+      currentModel: getCurrentModel(provider, cfg.customSettingsPath),
+      verbose,
+    });
+  }
+
   // Local proxy mode: generate config, spawn/join proxy, track session
   let proxy: ChildProcess | null = null;
   let configPath: string | undefined;

src/cliproxy/index.ts

@@ -100,6 +100,11 @@ export {
   configureProviderModel,
   showCurrentConfig,
 } from './model-config';
+export {
+  getDefaultCodexModel,
+  getFreePlanFallbackCodexModel,
+  reconcileCodexModelForActivePlan,
+} from './codex-plan-compatibility';
 
 // Executor
 export { execClaudeWithCLIProxy, isPortAvailable, findAvailablePort } from './cliproxy-executor';

src/cliproxy/model-catalog.ts

@@ -147,15 +147,59 @@ export const MODEL_CATALOG: Partial<Record<CLIProxyProvider, ProviderCatalog>> =
   codex: {
     provider: 'codex',
     displayName: 'Copilot Codex',
-    defaultModel: 'gpt-5.3-codex',
+    defaultModel: 'gpt-5-codex',
     models: [
       {
-        id: 'gpt-5.3-codex',
-        name: 'GPT-5.3 Codex',
-        description: 'Supports up to xhigh effort',
+        id: 'gpt-5-codex',
+        name: 'GPT-5 Codex',
+        description: 'Cross-plan safe Codex default',
         thinking: {
           type: 'levels',
-          levels: ['medium', 'high', 'xhigh'],
+          levels: ['low', 'medium', 'high'],
+          maxLevel: 'high',
+          dynamicAllowed: false,
+        },
+      },
+      {
+        id: 'gpt-5-codex-mini',
+        name: 'GPT-5 Codex Mini',
+        description: 'Faster and cheaper Codex option',
+        thinking: {
+          type: 'levels',
+          levels: ['low', 'medium', 'high'],
+          maxLevel: 'high',
+          dynamicAllowed: false,
+        },
+      },
+      {
+        id: 'gpt-5-mini',
+        name: 'GPT-5 Mini',
+        description: 'Legacy mini model ID kept for backwards compatibility',
+        thinking: {
+          type: 'levels',
+          levels: ['low', 'medium', 'high'],
+          maxLevel: 'high',
+          dynamicAllowed: false,
+        },
+      },
+      {
+        id: 'gpt-5.1-codex-mini',
+        name: 'GPT-5.1 Codex Mini',
+        description: 'Legacy fast Codex mini model',
+        thinking: {
+          type: 'levels',
+          levels: ['low', 'medium', 'high'],
+          maxLevel: 'high',
+          dynamicAllowed: false,
+        },
+      },
+      {
+        id: 'gpt-5.1-codex-max',
+        name: 'GPT-5.1 Codex Max',
+        description: 'Higher-effort Codex model with xhigh support',
+        thinking: {
+          type: 'levels',
+          levels: ['low', 'medium', 'high', 'xhigh'],
           maxLevel: 'xhigh',
           dynamicAllowed: false,
         },
@@ -163,22 +207,47 @@ export const MODEL_CATALOG: Partial<Record<CLIProxyProvider, ProviderCatalog>> =
       {
         id: 'gpt-5.2-codex',
         name: 'GPT-5.2 Codex',
-        description: 'Previous stable Codex model',
+        description: 'Cross-plan Codex model with xhigh support',
         thinking: {
           type: 'levels',
-          levels: ['medium', 'high', 'xhigh'],
+          levels: ['low', 'medium', 'high', 'xhigh'],
           maxLevel: 'xhigh',
           dynamicAllowed: false,
         },
       },
       {
-        id: 'gpt-5-mini',
-        name: 'GPT-5 Mini',
-        description: 'Capped at high effort (no xhigh)',
+        id: 'gpt-5.3-codex',
+        name: 'GPT-5.3 Codex',
+        tier: 'pro',
+        description: 'Paid Codex plans only',
         thinking: {
           type: 'levels',
-          levels: ['medium', 'high'],
-          maxLevel: 'high',
+          levels: ['low', 'medium', 'high', 'xhigh'],
+          maxLevel: 'xhigh',
+          dynamicAllowed: false,
+        },
+      },
+      {
+        id: 'gpt-5.3-codex-spark',
+        name: 'GPT-5.3 Codex Spark',
+        tier: 'pro',
+        description: 'Paid Codex plans only, ultra-fast coding model',
+        thinking: {
+          type: 'levels',
+          levels: ['low', 'medium', 'high', 'xhigh'],
+          maxLevel: 'xhigh',
+          dynamicAllowed: false,
+        },
+      },
+      {
+        id: 'gpt-5.4',
+        name: 'GPT-5.4',
+        tier: 'pro',
+        description: 'Paid Codex plans only, latest GPT-5 family model',
+        thinking: {
+          type: 'levels',
+          levels: ['low', 'medium', 'high', 'xhigh'],
+          maxLevel: 'xhigh',
           dynamicAllowed: false,
         },
       },

src/cliproxy/model-config.ts

@@ -146,9 +146,7 @@ export async function configureProviderModel(
   console.error(header(`Configure ${catalog.displayName} Model`));
   console.error('');
   console.error(dim('    Select which model to use for this provider.'));
-  console.error(
-    dim('    Models marked [Paid Tier] require a paid Google account (not free tier).')
-  );
+  console.error(dim('    Models marked [Pro]/[Ultra] require a paid provider plan.'));
   console.error(dim('    Models marked [DEPRECATED] are not recommended for use.'));
   console.error('');
 
@@ -274,7 +272,7 @@ export async function showCurrentConfig(provider: CLIProxyProvider): Promise<voi
 
   console.error('');
   console.error(bold('Available models:'));
-  console.error(dim('  [Paid Tier] = Requires paid Google account (not free tier)'));
+  console.error(dim('  [Pro]/[Ultra] = Requires a paid provider plan'));
   console.error(dim('  [DEPRECATED] = Not recommended for use'));
   console.error('');
   catalog.models.forEach((m) => {