fix(responses): omit canonical Codex user metadata and hop request-local 400s

devlog/_plan/260914_carry_pr4528/000_plan.md

@@ -0,0 +1,36 @@
+# 260914 — Carry contributor PR #4528
+
+## Why a carry
+
+PR #4528 (branch fix/codex-forward-user-4527, head d1d8d45f22c8, author RHODIZSECURITY)
+fixes issue #4527. It was stuck for reasons unrelated to its code: a contributor draft
+whose four-box readiness checklist resets on every push, and a Cross-platform CI run
+(34774339026) that failed on exactly one test, "release version line > the in-tree
+version is never behind a released one".
+
+That failure is stale base, not a defect. The test compares package.json against the
+highest local release tag. The branch sat at in-tree 2.54.0 while v2.54.0 was already
+tagged, so ordering === 0 and the tag does not point at the branch head. dev has since
+opened 2.55.0 against a highest tag of v2.54.0, so the same test passes on a fresh base.
+
+## Defect being fixed
+
+Claude Code sends metadata.user_id; src/claude/inbound.ts maps it onto the Responses
+top-level user field. src/adapters/openai-responses.ts stripped other unsupported
+native-forward fields but left that one on the canonical ChatGPT Codex wire, which
+rejects it with 400 "Unsupported parameter: user". Because a generic 400 was terminal
+for a combo, a request that had already taken a 429 on an earlier target ended the turn
+rather than trying the next healthy one.
+
+## Scope boundary
+
+Only a clear pre-output, target-local incompatibility may fall through to the next
+target. Widening this to retry all 400s would be a defect, not an improvement.
+Cancellation, policy refusals, context overflow, other invalid requests and anything
+after output commitment must stay terminal.
+
+## Proof policy
+
+Local product suite, typecheck, build and install are NOT RUN. Focused runs are
+debugging only and are never cited. The only proof is hosted Cross-platform CI at the
+exact final head SHA.

devlog/_plan/260914_carry_pr4528/010_phase1.md

@@ -0,0 +1,58 @@
+# Phase 1 — Reimplement on current dev, audit, publish
+
+## Diff level
+
+Branch codex/carry-4528-codex-forward-user off origin/dev 246b5cab43. The upstream diff
+applies cleanly at that base (39 files, 613+/61-), which is itself the evidence that the
+CI red was the version test alone and not a code conflict.
+
+Source changes carried:
+
+- src/adapters/openai-responses.ts — stripCanonicalForwardUser, called only inside the
+  existing isCanonicalOpenAiForwardProvider gate, after the prompt-cache strips.
+- src/combos/failover.ts — isRequestLocalTargetIncompatibility: HTTP 400 only, 16,384
+  char bound, generic outer code required, strict JSON parse, error object required,
+  inner code string-or-null and generic, leaf type invalid_request_error, only the exact
+  "Provider error 400: " wrapper unwrapped with a depth budget of 3. Three accepted
+  shapes. Wired into both comboFailureDecision (hop) and comboFailureCooldownScope.
+- src/vision/plan.ts — requiresVisionPreprocessing replaces the isModelTextOnly call
+  sites. Proven-negative capability preprocesses; unknown custom models stay sighted.
+- src/vision/eligibility.ts — canonical Codex consults the generated openai-codex bundle
+  before generic row metadata; shallow copy plus cloned vision maps so an injected fetch
+  survives enrichment.
+- scripts/generate-model-metadata.ts and src/generated/model-metadata.ts — openai-codex
+  retained as a capability-only bundle.
+- src/providers/registry.ts — OPENCODE_ZEN_IMAGE_MODELS records mimo-v2.5-free and
+  longcat-2.0-free as positive modality evidence instead of blacklist absence.
+- src/server/responses/core.ts, chat-native.ts, chat-completions.ts and
+  src/web-search/index.ts — thread providerName through so one gate applies everywhere.
+
+## Audit plan
+
+Six parallel read-only recon agents: failover classifier bounds, the sanitation
+boundary, vision capability routing and generated-file consistency, structure ownership,
+docs-site locale fidelity, plus one adversarial counter-read of both security boundaries.
+
+## Fold list beyond the upstream diff
+
+Turkish combos.md wording (cikti baslamadan ONCE sonraki uygun hedefe); the stale
+noVisionModels activation row in structure/ops/service-and-sidecars.md; the
+transports/responses.md contract pointer and its whitespace churn; a Zen positive-modality
+note in transports/inventory.md; the English cross-reference; the French before-output
+timing; seven locale failover-table exception rows; and two comment blocks that wrongly
+claimed unknown capability fails closed.
+
+## Known limitation, documented not fixed
+
+On the combo path the classifier never sees more than 500 characters: consumeComboFailure
+passes normalized.safeText, which is redactSecretString(text).slice(0, 500) at
+src/server/responses/core.ts:954. The classifier's own 16,384 bound is the outer belt.
+An envelope fatter than 500 bytes truncates mid-JSON, fails the parse and does not hop.
+That fails closed, and raising it would touch shared redaction and byte-accounting
+contracts outside this carry's scope.
+
+## Exit
+
+Push --no-verify fast-forward only, open against dev with the full template, report the
+PR number, head SHA and the CI run id whose head_sha equals the final head. Do not merge;
+do not close #4528 or #4527.

docs-site/src/content/docs/fr/guides/combos.md

@@ -200,7 +200,8 @@ Les échecs d’un combo se répartissent entre ceux qui entraînent un **bascul
 | --- | --- |
 | HTTP 401, 403, 404, 408, 429, ou n'importe quel 5xx | Refroidissez la cible et passez à la prochaine cible éligible. |
 | Erreur classée comme erreur d’authentification, d’abonnement, de quota, de limitation de débit, de surcharge ou de serveur en amont | Place la cible en période de refroidissement et bascule, même si le statut seul ne suffit pas. |
-| Annulation client (499), `origin_rejected`, refus de cyber-politique, débordement de contexte ou demande invalide | Arrêtez et renvoyez l'erreur ; une autre cible ne rendrait pas la demande valide. |
+| Annulation client (499), `origin_rejected`, refus de cyber-politique, débordement de contexte ou autre demande invalide | Arrêtez et renvoyez l'erreur ; une autre cible ne rendrait pas la demande valide. |
+| Rejet structuré de `user`, valeur non prise en charge pour `reasoning.effort`/`reasoning_effort`, ou rejet d'entrée d'image propre à un modèle (`param: input`) | Bascule vers la cible admissible suivante avant le début de la sortie, sans délai de refroidissement ; voir Compatibilité des paramètres facultatifs ci-dessous. |
 | Toute autre erreur non classifiée | Arrêtez et renvoyez l'erreur. |
 
 Une cible sautée entre en temps de recharge pendant 60 secondes par défaut. Si la réponse en amont inclut un
@@ -365,3 +366,9 @@ message de validation.
 
 L’erreur était terminale plutôt que spécifique à la cible. Corriger une entrée invalide, réduire un contexte surdimensionné,
 gérer un refus de politique ou corriger l’origine de la demande rejetée. Les combos ne sautent pas dans ces cas-là.
+
+## Compatibilité des paramètres facultatifs
+
+Exception aux erreurs 400 terminales : un rejet structuré de `user`, une valeur non prise en charge pour `reasoning.effort`/`reasoning_effort`, ou un rejet d’entrée d’image propre à un modèle (`param: input`) peut faire passer le combo à la cible admissible suivante avant le début de la sortie, sans délai de refroidissement. Le refus de sécurité, l’annulation et une sortie déjà commencée restent non rejouables.
+
+[Canonical compatibility details](/guides/combos/#request-local-target-compatibility).

docs-site/src/content/docs/guides/combos.md

@@ -213,7 +213,8 @@ Combo failures are divided into **hop** failures and **terminal** failures.
 | HTTP 401, 403, 404, 408, 429, or any 5xx | Cool the target and hop to the next eligible target. |
 | HTTP 410 with an explicit model end-of-life, retired, deprecated, sunset, decommissioned, or no-longer-available signal | Cool that target and hop. Unrelated 410 responses remain terminal. |
 | Classified authentication, subscription, quota, rate-limit, overload, or upstream-server error | Cool the target and hop, even when the status alone is not sufficient. |
-| Client cancellation (499), `origin_rejected`, cyber-policy refusal, context overflow, or invalid request | Stop and return the error; another target would not make the request valid. |
+| Client cancellation (499), `origin_rejected`, cyber-policy refusal, context overflow, or other invalid request | Stop and return the error; another target would not make the request valid. |
+| Structured HTTP 400 rejecting optional `user`, an unsupported reasoning effort, or model-scoped image input | Hop before output commitment without cooling; see request-local target compatibility below. |
 | Any other unclassified error | Stop and return the error. |
 
 When `cooldownMs` is unset, a hopped target uses an upstream fallback: 5 seconds for request-rate
@@ -227,8 +228,8 @@ fallback for upstream rate-limit codes `1302`/`1305` → the 60-second default.
 `Retry-After: 0` remains an immediate upstream directive rather than being replaced by a configured
 cooldown.
 
-The current request never retries the same attempted target. Later requests skip it until its
-cooldown expires. A `Retry-After` HTTP-date that is already in the past is also preserved as an
+The current request never retries the same attempted target. Later requests skip a cooled target until its
+cooldown expires; request-local compatibility rejections do not cool the target. A `Retry-After` HTTP-date that is already in the past is also preserved as an
 immediate upstream directive, just like `Retry-After: 0`. Set `waitForCooldownMs` to allow a later
 request to wait for the earliest eligible target cooldown, up to that cap on each selection attempt,
 and then make one fresh selection. A request may therefore wait up to `hops × waitForCooldownMs`
@@ -254,6 +255,12 @@ another provider, which prevents duplicate text and tool execution. If the pre-o
 its safety cap without a terminal or output boundary, OpenCodex also commits the current target
 instead of growing memory without a bound.
 
+## Request-local target compatibility
+
+When routing Claude Code to the canonical ChatGPT Codex backend, OpenCodex removes the unsupported top-level `user` metadata field without changing the session/cache key, input messages, tool schemas, or safety identifiers. Public Responses API and noncanonical forward gateways keep that field.
+
+A combo can also advance after an intact HTTP 400 `invalid_request_error` that specifically rejects `user`, reports `unsupported_value` for `reasoning.effort`/`reasoning_effort`, or reports `param: input` with an exact model-scoped `does not support image inputs` rejection. This is a mismatch for that request, not evidence that the target is unhealthy, so it records no cooldown. This compatibility recovery does not silently change `none` into a different effort or broaden this exception to arbitrary invalid requests. Policy refusals, cancellation and already-committed output remain non-replayable. A single-target request still returns an unresolved upstream rejection.
+
 ## Default reasoning effort
 
 `defaultEffort` fills an absent `reasoning.effort` when the combo has a non-null default and the selected target has a known, nonempty supported ladder. If the target supports the configured value, it is retained; otherwise the highest supported rung at or below it is used, or the lowest supported rung when none is lower. Unknown or empty ladders omit the default.

docs-site/src/content/docs/guides/sidecars.md

@@ -123,11 +123,9 @@ failures after response headers have started are delivered as `response.failed`
 
 ## Vision sidecar
 
-When the routed model is listed in its provider's `noVisionModels` — or declared text-only for
-that model via `modelInputModalities` — and a request carries an image, opencodex describes each
-image **before** the main call and replaces it with text, provided a vision sidecar plan is
-available. Without an available plan the raw image is stripped rather than forwarded to a
-text-only backend. The model catalog advertises image input for every sidecar-covered model.
+Image routing is capability-aware. Before an image-bearing upstream send, opencodex resolves the selected model's effective input modalities from runtime provider evidence, explicit operator declarations, backend/registry metadata, and generated vendor metadata. A target positively known to be text-only goes through the Vision Sidecar first; the image is described **before** the main call and replaced inline with text. A target positively known to support images receives the image directly. Unknown custom models keep the existing compatibility behavior rather than being guessed text-only.
+
+For the canonical ChatGPT Codex route, opencodex uses the `openai-codex` metadata bundle rather than public OpenAI API metadata, so backend-specific modality differences are respected. The native Chat fast path uses the same gate and cannot bypass a known text-only verdict. Without an available sidecar plan, raw images are stripped before a proven text-only backend.
 Combos advertise image input only when every member accepts images, either natively or through a
 sidecar, and the combo's `imageInput` setting is not disabled, so clients such as the Codex app
 allow attachments instead of blocking them before the sidecar runs. When
@@ -164,10 +162,12 @@ sidecar-backed by default; Zen routes are unchanged and were not probed in this
   keys (Anthropic keys omit it, since that field is ignored there); mutable `https:` images are not
   cached.
 
-The management API and Dashboard picker now list models that can actually accept image input.
-When the matching backend is available, `gpt-5.6-luna` (OpenAI) and `claude-haiku-4-5` (Anthropic)
-are always offered as baseline options. `PUT /api/sidecar-settings` rejects a model known to be
-text-only, but still accepts an unknown id so custom or ahead-of-catalog names keep working.
+The management API and Dashboard picker list models that can accept image input. When the matching
+backend is available, `gpt-5.6-luna` (OpenAI) and `claude-haiku-4-5` (Anthropic) are always offered
+as baseline options. `PUT /api/sidecar-settings` may retain an unknown custom/ahead-of-catalog id.
+An explicitly configured routed Vision Sidecar is therefore usable unless capability evidence proves
+that model cannot accept images; this preserves operator-selected custom sidecars without allowing a
+known text-only sidecar to receive image bytes.
 
 ```json
 {

docs-site/src/content/docs/ja/guides/combos.md

@@ -124,7 +124,8 @@ ocx combo set balanced \
 | HTTP 401、403、404、408、429、または任意の 5xx |ターゲットを冷却し、次の適格なターゲットに移動します。 |
 |モデルのサポート終了、retired、deprecated、sunset、decommissioned、または利用不可を明示する HTTP 410 |そのターゲットをクールダウンし、次へ進みます。無関係な 410 はターミナル エラーのままです。 |
 |機密認証、サブスクリプション、クォータ、レート制限、過負荷、またはアップストリーム サーバー エラー |ステータスだけでは物足りない場合でもターゲットを冷やしてホップさせましょう。 |
-|クライアントのキャンセル (499)、`origin_rejected`、サイバー ポリシーの拒否、コンテキスト オーバーフロー、または無効なリクエスト |停止してエラーを返します。別のターゲットではリクエストは有効になりません。 |
+|クライアントのキャンセル (499)、`origin_rejected`、サイバー ポリシーの拒否、コンテキスト オーバーフロー、またはその他の無効なリクエスト |停止してエラーを返します。別のターゲットではリクエストは有効になりません。 |
+|`user` の明示的な拒否、`reasoning.effort`/`reasoning_effort` の非対応値、またはモデル固有の画像入力拒否（`param: input`）を示す構造化 HTTP 400 |出力開始前に次の適格なターゲットへ進み、クールダウンを記録しません。任意パラメーターの互換性を参照してください。 |
 |その他の未分類のエラー |停止してエラーを返します。 |
 
 `cooldownMs` が未設定の場合、ホップされたターゲットはアップストリームのフォールバックを使用します。アップストリームコード `1302` または `1305` を伴うリクエストレート 429 では 5 秒、それ以外では 60 秒です。設定されている場合、使用可能なアップストリームの `Retry-After` または Codex リセットシグナルが存在しないときは、これらのリクエストレート 429 を含め、`cooldownMs` が適用されます。数値の `Retry-After` 秒数と HTTP-date 値が受け入れられ、すべてのクールダウンは 10 分を上限とします。優先順位は強い順に、明示的な `Retry-After` → Codex リセットヘッダー（`x-codex-primary-reset-at`、`x-codex-secondary-reset-at`、または `x-codex-tertiary-reset-at`）→ コンボの `cooldownMs`（設定時）→ アップストリームのレート制限コード `1302`/`1305` に対する 5 秒のリクエストレート フォールバック → 60 秒のデフォルトです。有効な即時指定 `Retry-After: 0` は、設定されたクールダウンで置き換えられず、即時のアップストリーム指示として維持されます。
@@ -260,3 +261,9 @@ ocx combo remove <id> --yes
 ### 最初のエラーの後にフェイルオーバーが停止したのはなぜですか?
 
 このエラーはターゲット固有のものではなく、最終的なものでした。無効な入力を修正し、大きすぎるコンテキストを削減し、ポリシーの拒否を処理し、拒否されたリクエストの送信元を修正します。コンボはそのような場合には機能しません。
+
+## 任意パラメーターの互換性
+
+通常の 400 エラーは終了扱いですが、`user` の明示的な拒否、`reasoning.effort`/`reasoning_effort` の非対応値、またはモデル固有の画像入力拒否（`param: input`）を示す構造化エラーでは、出力開始前に次の適格なターゲットへ進めます。この不一致ではクールダウンを記録しません。安全ポリシーによる拒否、キャンセル、出力開始後の再実行は禁止のままです。
+
+[Canonical compatibility details](/guides/combos/#request-local-target-compatibility).