Merge pull request #154 from ndycode/fix/codex-fallback-chain-153

fix: handle normalized codex fallback

Author: ndycode

config/README.md

@@ -75,17 +75,21 @@ A barebones debug template is available at [`minimal-opencode.json`](./minimal-o
 
 ## Unsupported-model behavior
 
-Current defaults are strict entitlement handling:
-- `unsupportedCodexPolicy: "strict"` returns entitlement errors directly
-- set `unsupportedCodexPolicy: "fallback"` (or `CODEX_AUTH_UNSUPPORTED_MODEL_POLICY=fallback`) to enable automatic fallback retries
+Current defaults are strict entitlement handling except for default public selectors that are commonly entitlement-gated:
+- `gpt-5.5` and canonical `gpt-5-codex` can auto-fallback through `gpt-5.4`, `gpt-5.4-mini`, then `gpt-5.4-nano` when the backend reports the selected model is not supported for the active account/workspace
+- `unsupportedCodexPolicy: "strict"` returns other entitlement errors directly
+- set `unsupportedCodexPolicy: "fallback"` (or `CODEX_AUTH_UNSUPPORTED_MODEL_POLICY=fallback`) to enable the full fallback chain for manual/legacy selectors
 - `fallbackToGpt52OnUnsupportedGpt53: true` keeps the legacy `gpt-5.3-codex -> gpt-5.2-codex` edge inside fallback mode
-- `gpt-5.5 -> gpt-5.4` is included by default for accounts/workspaces that do not yet expose GPT-5.5
 - user-typed `gpt-5.5-pro*` is canonicalized to `gpt-5.5` before fallback because GPT-5.5 Pro is ChatGPT-only, not a Codex-routable model
+- legacy Codex selectors such as `gpt-5.2-codex`, `gpt-5.3-codex`, and `gpt-5.3-codex-spark` normalize to canonical `gpt-5-codex`; if that canonical Codex model is gated, the default auto-fallback can retry through the GPT-5.4 family
+- set `CODEX_AUTH_DISABLE_GPT55_AUTO_FALLBACK=1` to disable GPT-5.5 auto-fallback
+- set `CODEX_AUTH_DISABLE_CODEX_AUTO_FALLBACK=1` to disable canonical Codex/GPT-5.4-family auto-fallback
 - `gpt-5.4-pro -> gpt-5.4` remains available for older manual configs
 - `unsupportedCodexFallbackChain` lets you override fallback order per model
 
-Default fallback chain (when policy is `fallback`):
-- `gpt-5.5 -> gpt-5.4`
+Default fallback chain (auto-fallback for `gpt-5.5`/`gpt-5-codex` through the GPT-5.4 family; full chain when policy is `fallback`):
+- `gpt-5.5 -> gpt-5.4 -> gpt-5.4-mini -> gpt-5.4-nano`
+- `gpt-5-codex -> gpt-5.4 -> gpt-5.4-mini -> gpt-5.4-nano`
 - `gpt-5.4-pro -> gpt-5.4` (if you manually select `gpt-5.4-pro`)
 - `gpt-5.3-codex -> gpt-5-codex -> gpt-5.2-codex`
 - `gpt-5.3-codex-spark -> gpt-5-codex -> gpt-5.3-codex -> gpt-5.2-codex` (only relevant if Spark IDs are added manually)

docs/configuration.md

@@ -172,7 +172,7 @@ The sample above intentionally sets `"retryAllAccountsMaxRetries": 3` as a bound
 | `unsupportedCodexPolicy` | `strict` | unsupported-model behavior: `strict` (return entitlement error) or `fallback` (retry with configured fallback chain) |
 | `fallbackOnUnsupportedCodexModel` | `false` | legacy fallback toggle mapped to `unsupportedCodexPolicy` (prefer using `unsupportedCodexPolicy`) |
 | `fallbackToGpt52OnUnsupportedGpt53` | `true` | legacy compatibility toggle for the `gpt-5.3-codex -> gpt-5.2-codex` edge when generic fallback is enabled |
-| `unsupportedCodexFallbackChain` | `{}` | optional per-model fallback-chain override (map of `model -> [fallback1, fallback2, ...]`; default includes `gpt-5.5 -> gpt-5.4`). `gpt-5.5` auto-fallback is on by default during the rollout; set `CODEX_AUTH_DISABLE_GPT55_AUTO_FALLBACK=1` to opt out. GPT-5.5 Pro is not mapped: it is ChatGPT-only per OpenAI's 2026-04-23 launch. |
+| `unsupportedCodexFallbackChain` | `{}` | optional per-model fallback-chain override (map of `model -> [fallback1, fallback2, ...]`; default includes `gpt-5.5` and `gpt-5-codex` through the GPT-5.4 family). `gpt-5.5` and canonical Codex auto-fallbacks are on by default for common entitlement gates; set `CODEX_AUTH_DISABLE_GPT55_AUTO_FALLBACK=1` or `CODEX_AUTH_DISABLE_CODEX_AUTO_FALLBACK=1` to opt out. GPT-5.5 Pro is not mapped: it is ChatGPT-only per OpenAI's 2026-04-23 launch. |
 | `sessionRecovery` | `true` | auto-recover from common api errors |
 | `autoResume` | `true` | auto-resume after thinking block recovery |
 | `tokenRefreshSkewMs` | `60000` | refresh tokens this many ms before expiry |
@@ -191,12 +191,13 @@ this mode is intended for beginners who prefer quick failures + clearer recovery
 
 ### Unsupported-Model Behavior and Fallback Chain
 
-by default the plugin is strict (`unsupportedCodexPolicy: "strict"`). it returns entitlement errors directly for unsupported models.
+by default the plugin is strict (`unsupportedCodexPolicy: "strict"`) except for common default-selector entitlement gates. it returns other entitlement errors directly for unsupported models.
 
 set `unsupportedCodexPolicy: "fallback"` to enable model fallback after account/workspace attempts are exhausted.
 
 defaults when fallback policy is enabled and `unsupportedCodexFallbackChain` is empty:
-- `gpt-5.5 -> gpt-5.4`
+- `gpt-5.5 -> gpt-5.4 -> gpt-5.4-mini -> gpt-5.4-nano`
+- `gpt-5-codex -> gpt-5.4 -> gpt-5.4-mini -> gpt-5.4-nano`
 - `gpt-5.4-pro -> gpt-5.4` (if `gpt-5.4-pro` is selected manually)
 - `gpt-5.3-codex -> gpt-5-codex -> gpt-5.2-codex`
 - `gpt-5.3-codex-spark -> gpt-5-codex -> gpt-5.3-codex -> gpt-5.2-codex` (applies if you manually select Spark model IDs)
@@ -211,9 +212,10 @@ custom chain example:
   "unsupportedCodexPolicy": "fallback",
   "fallbackOnUnsupportedCodexModel": true,
   "unsupportedCodexFallbackChain": {
-    "gpt-5.5": ["gpt-5.4"],
+    "gpt-5.5": ["gpt-5.4", "gpt-5.4-mini", "gpt-5.4-nano"],
+    "gpt-5.4": ["gpt-5.4-mini", "gpt-5.4-nano"],
     "gpt-5.4-pro": ["gpt-5.4"],
-    "gpt-5-codex": ["gpt-5.2-codex"],
+    "gpt-5-codex": ["gpt-5.4", "gpt-5.4-mini", "gpt-5.4-nano"],
     "gpt-5.3-codex": ["gpt-5-codex", "gpt-5.2-codex"],
     "gpt-5.3-codex-spark": ["gpt-5-codex", "gpt-5.3-codex", "gpt-5.2-codex"]
   }
@@ -255,6 +257,7 @@ override any config with env vars:
 | `CODEX_AUTH_FALLBACK_UNSUPPORTED_MODEL=1` | legacy fallback toggle (prefer policy variable above) |
 | `CODEX_AUTH_FALLBACK_GPT53_TO_GPT52=0` | disable only the legacy `gpt-5.3-codex -> gpt-5.2-codex` edge |
 | `CODEX_AUTH_DISABLE_GPT55_AUTO_FALLBACK=1` | disable automatic `gpt-5.5 -> gpt-5.4` fallback during rollout |
+| `CODEX_AUTH_DISABLE_CODEX_AUTO_FALLBACK=1` | disable automatic canonical Codex/GPT-5.4-family fallback |
 | `CODEX_AUTH_ACCOUNT_ID=acc_xxx` | force specific workspace id |
 | `CODEX_AUTH_FETCH_TIMEOUT_MS=120000` | override fetch timeout |
 | `CODEX_AUTH_STREAM_STALL_TIMEOUT_MS=60000` | override SSE stall timeout |

docs/troubleshooting.md

@@ -362,44 +362,53 @@ resolvedConfig: { reasoningEffort: 'low', ... }  ← Should show your options
    opencode auth login
    ```
 2. Add another entitled account/workspace. The plugin tries remaining accounts/workspaces before model fallback.
-3. Enable fallback policy only if you want automatic model downgrades:
+3. Default public selectors that are commonly entitlement-gated (`gpt-5.5` and canonical `gpt-5-codex`) can auto-fallback through `gpt-5.4`, `gpt-5.4-mini`, then `gpt-5.4-nano`.
+4. Enable fallback policy if you also want automatic downgrades for manual/legacy selectors:
    ```bash
    CODEX_AUTH_UNSUPPORTED_MODEL_POLICY=fallback opencode
    ```
-4. Default fallback chain (when policy is `fallback` and not overridden):
-   - `gpt-5.5 -> gpt-5.4`
+5. Default fallback chain (auto-fallback for `gpt-5.5`/`gpt-5-codex` through the GPT-5.4 family; full chain when policy is `fallback` and not overridden):
+   - `gpt-5.5 -> gpt-5.4 -> gpt-5.4-mini -> gpt-5.4-nano`
+   - `gpt-5-codex -> gpt-5.4 -> gpt-5.4-mini -> gpt-5.4-nano`
    - `gpt-5.4-pro -> gpt-5.4` (if `gpt-5.4-pro` is selected manually)
    - `gpt-5.3-codex -> gpt-5-codex -> gpt-5.2-codex`
    - `gpt-5.3-codex-spark -> gpt-5-codex -> gpt-5.3-codex -> gpt-5.2-codex` (if Spark IDs are selected manually)
    - `gpt-5.2-codex -> gpt-5-codex`
    - `gpt-5.1-codex -> gpt-5-codex`
-5. Configure a custom fallback chain in `~/.opencode/openai-codex-auth-config.json`:
+6. Configure a custom fallback chain in `~/.opencode/openai-codex-auth-config.json`:
    ```json
    {
    "unsupportedCodexPolicy": "fallback",
    "fallbackOnUnsupportedCodexModel": true,
    "unsupportedCodexFallbackChain": {
-      "gpt-5.5": ["gpt-5.4"],
+      "gpt-5.5": ["gpt-5.4", "gpt-5.4-mini", "gpt-5.4-nano"],
+      "gpt-5.4": ["gpt-5.4-mini", "gpt-5.4-nano"],
       "gpt-5.4-pro": ["gpt-5.4"],
-      "gpt-5-codex": ["gpt-5.2-codex"],
+      "gpt-5-codex": ["gpt-5.4", "gpt-5.4-mini", "gpt-5.4-nano"],
       "gpt-5.3-codex": ["gpt-5-codex", "gpt-5.2-codex"],
        "gpt-5.3-codex-spark": ["gpt-5-codex", "gpt-5.3-codex", "gpt-5.2-codex"]
      }
    }
    ```
-6. Use strict mode (no model fallback) for explicit entitlement failures:
+7. Use strict mode for explicit entitlement failures outside the default public selector auto-fallbacks:
    ```bash
    CODEX_AUTH_UNSUPPORTED_MODEL_POLICY=strict opencode
    ```
-7. Legacy compatibility toggle (only controls `gpt-5.3-codex -> gpt-5.2-codex`):
+8. Disable default-selector auto-fallbacks when you need strict entitlement failures for those selectors:
+   ```bash
+   CODEX_AUTH_DISABLE_GPT55_AUTO_FALLBACK=1 opencode
+   CODEX_AUTH_DISABLE_CODEX_AUTO_FALLBACK=1 opencode
+   ```
+   `CODEX_AUTH_DISABLE_CODEX_AUTO_FALLBACK=1` only disables the automatic canonical Codex/GPT-5.4-family fallback path; explicit `unsupportedCodexPolicy: "fallback"` chains still apply.
+9. Legacy compatibility toggle (only controls `gpt-5.3-codex -> gpt-5.2-codex`):
    ```bash
    CODEX_AUTH_FALLBACK_GPT53_TO_GPT52=0 opencode
    ```
-8. Legacy generic fallback toggle compatibility:
+10. Legacy generic fallback toggle compatibility:
    ```bash
    CODEX_AUTH_FALLBACK_UNSUPPORTED_MODEL=1 opencode
    ```
-9. Verify effective upstream model when debugging Spark/fallback behavior:
+11. Verify effective upstream model when debugging Spark/fallback behavior:
    ```bash
    ENABLE_PLUGIN_REQUEST_LOGGING=1 CODEX_PLUGIN_LOG_BODIES=1 opencode run "ping" --model=openai/gpt-5.3-codex-spark
    ```

index.ts

@@ -2631,7 +2631,7 @@ while (attempted.size < Math.max(1, accountCount)) {
 										: waitMs > 0
 											? `All ${count} account(s) are rate-limited. Try again in ${waitLabel} or add another account with \`opencode auth login\`.`
 											: wasEntitlementExhaustion
-												? `All ${count} account(s) returned 'model not supported' for the requested model.${entitlementDetail} If this is a GPT-5.5 request during the rollout period, set \`unsupportedCodexPolicy: "fallback"\` (or \`CODEX_AUTH_UNSUPPORTED_MODEL_POLICY=fallback\`) to auto-fallback to gpt-5.4. See \`codex-health\` for per-account details.`
+												? `All ${count} account(s) returned 'model not supported' for the requested model.${entitlementDetail} Codex model access is account/workspace gated; default gpt-5.5/gpt-5-codex selectors auto-fallback through the GPT-5.4 family when possible. Set \`unsupportedCodexPolicy: "fallback"\` for the full manual fallback chain, or see \`codex-health\` for per-account details.`
 												: `All ${count} account(s) failed (server errors or auth issues). Check account health with \`codex-health\`.`;
 								runtimeMetrics.failedRequests++;
 								runtimeMetrics.lastError = message;

lib/request/fetch-helpers.ts

@@ -54,14 +54,49 @@ const CHATGPT_CODEX_UNSUPPORTED_MODEL_PATTERN =
 const NORMALIZED_UNSUPPORTED_MODEL_PATTERN =
 	/the model ['"]([^'"]+)['"] is not currently available for this chatgpt account/i;
 export const DEFAULT_UNSUPPORTED_CODEX_FALLBACK_CHAIN: Record<string, string[]> = {
-	[GPT_55_MODEL_ID]: ["gpt-5.4"],
+	[GPT_55_MODEL_ID]: ["gpt-5.4", "gpt-5.4-mini", "gpt-5.4-nano"],
+	"gpt-5.4": ["gpt-5.4-mini", "gpt-5.4-nano"],
+	"gpt-5.4-mini": ["gpt-5.4-nano"],
 	"gpt-5.4-pro": ["gpt-5.4"],
+	"gpt-5-codex": ["gpt-5.4", "gpt-5.4-mini", "gpt-5.4-nano"],
+	// Legacy selectors normalize to `gpt-5-codex` before lookup during the
+	// request path. Keep these historical entries for direct helper callers and
+	// custom-chain documentation; the canonical `gpt-5-codex` edge above is the
+	// runtime path for default OpenCode selectors.
 	"gpt-5.3-codex-spark": ["gpt-5-codex", "gpt-5.3-codex", "gpt-5.2-codex"],
 	"gpt-5.3-codex": ["gpt-5-codex", "gpt-5.2-codex"],
 	"gpt-5.2-codex": ["gpt-5-codex"],
 	"gpt-5.1-codex": ["gpt-5-codex"],
 };
 
+const DEFAULT_AUTO_FALLBACK_ENTRY_OPT_OUT_ENV: Record<string, string> = {
+	[GPT_55_MODEL_ID]: "CODEX_AUTH_DISABLE_GPT55_AUTO_FALLBACK",
+	"gpt-5-codex": "CODEX_AUTH_DISABLE_CODEX_AUTO_FALLBACK",
+};
+
+const DEFAULT_AUTO_FALLBACK_CONTINUATION_MODELS = new Set([
+	"gpt-5.4",
+	"gpt-5.4-mini",
+]);
+
+function resolveAutoFallbackEntryModel(
+	currentModel: string,
+	attempted: Set<string>,
+): string | undefined {
+	if (DEFAULT_AUTO_FALLBACK_ENTRY_OPT_OUT_ENV[currentModel] !== undefined) {
+		return currentModel;
+	}
+	if (!DEFAULT_AUTO_FALLBACK_CONTINUATION_MODELS.has(currentModel)) {
+		return undefined;
+	}
+	for (const model of attempted) {
+		if (DEFAULT_AUTO_FALLBACK_ENTRY_OPT_OUT_ENV[model] !== undefined) {
+			return model;
+		}
+	}
+	return undefined;
+}
+
 export interface UnsupportedCodexModelInfo {
 	isUnsupported: boolean;
 	code?: string;
@@ -210,27 +245,34 @@ export function resolveUnsupportedCodexFallbackModel(
 	const currentModel = requestedModel ?? unsupported.unsupportedModel;
 	if (!currentModel) return undefined;
 
-	// During the GPT-5.5 rollout period, the backend gates `gpt-5.5` per-account
-	// even though the plugin maps every GPT-5.5 alias to it. Without a scoped
-	// auto-fallback, every one of the pooled accounts returns
-	// `model_not_supported_with_chatgpt_account` and rotation exhausts the pool
-	// with a misleading "server errors or auth issues" message. Gate this to
-	// gpt-5.5 only so legacy families keep their opt-in behavior.
-	const isGpt55AutoFallbackOptOut =
-		process.env.CODEX_AUTH_DISABLE_GPT55_AUTO_FALLBACK === "1";
-	const shouldAutoFallbackForGpt55 =
-		!isGpt55AutoFallbackOptOut && currentModel === GPT_55_MODEL_ID;
-
-	if (!options.fallbackOnUnsupportedCodexModel && !shouldAutoFallbackForGpt55) {
-		return undefined;
-	}
-
 	const attempted = new Set<string>();
 	for (const model of options.attemptedModels ?? []) {
 		const normalized = canonicalizeModelName(model);
 		if (normalized) attempted.add(normalized);
 	}
 
+	// The backend gates some public selector ids per account/workspace. When the
+	// selected id is a default UI selector, auto-fallback prevents exhausting every
+	// pooled account with the same unsupported-model response. Continuation models
+	// such as `gpt-5.4` only auto-fallback when the attempted set proves the chain
+	// started from a default entry point; direct user selection remains strict.
+	const autoFallbackEntryModel = resolveAutoFallbackEntryModel(
+		currentModel,
+		attempted,
+	);
+	const autoFallbackOptOutEnv = autoFallbackEntryModel
+		? DEFAULT_AUTO_FALLBACK_ENTRY_OPT_OUT_ENV[autoFallbackEntryModel]
+		: undefined;
+	const shouldAutoFallbackForDefaultSelector =
+		!!autoFallbackOptOutEnv && process.env[autoFallbackOptOutEnv] !== "1";
+
+	if (
+		!options.fallbackOnUnsupportedCodexModel &&
+		!shouldAutoFallbackForDefaultSelector
+	) {
+		return undefined;
+	}
+
 	const chain = normalizeFallbackChain(options.customChain);
 	const targets = chain[currentModel] ?? [];
 	if (targets.length === 0) return undefined;