docs: clarify encrypted combo recovery fallback outcomes

devlog/_plan/260906_release_244_followups/082_recovery_doc_alignment.md

@@ -0,0 +1,7 @@
+# Recovery wording alignment
+
+C1 documentation follow-up to public PR3754 threads PRRT_kwDOS-0Gi86fqklW and PRRT_kwDOS-0Gi86fqklX. Parent3762 at63282e49c; runtime3754 at8de126998 passedCI34025899357. No runtime behavior changes.
+
+Modify guides/sub-agent-surface.md and fr/zh-cn/zh-tw reference/configuration/agents.md only: native absence/exhaustion may activate explicitly enabled recovery toward an eligible routed target; unreadable ciphertext is not sent if recovery cannot provide a usable task. Clarify pre-dispatch unreadable400 versus preservation of a concrete failed native attempt; cancellation499 remains as implemented. Existing recovery auth, quota and no-persistence boundaries stay intact.
+
+Verifier: source-bound semantic comparison with existing helpers/fixtures, exact-head docsCI submission and outcome; no local test, typecheck or docsbuild under user limits. No external new permission, dependency or release rule changes. Close the public wording finding after published corrected pages; late runtime-status suggestion is rebutted with preserved native-failure contract and passing stored-Pool regression.

docs-site/src/content/docs/fr/reference/configuration/agents.md

@@ -58,7 +58,7 @@ Pour un tour enfant créé, l’ordre de repli est le suivant :
 
 Les chaînes de repli propres à un rôle doivent résider dans la configuration d’opencodex. L’ajout de `model_fallback` dans `$CODEX_HOME/agents/*.toml` amène Codex 0.146+ à rejeter le fichier de rôle entier à cause de ce champ inconnu, puis à ignorer le rôle (#1190). Une ancienne ligne `model_fallback` dans le fichier TOML reste lue par souci de rétrocompatibilité, mais `ocx doctor` la signale.
 
-opencodex ignore les candidats désactivés, non routables, en mauvais état, en période de temporisation ou ayant atteint le seuil de quota. L’instantané de disponibilité est mis en cache pendant `subagentModelFallbackPollMs`. Les tâches enfants chiffrées limitent la chaîne aux cibles ChatGPT natives canoniques et aux routes Responses directes avec authentification par clé explicitement approuvées via `allowEncryptedV2AgentTasks: true` ; si aucune ne peut consommer la charge chiffrée, la requête échoue au lieu d’envoyer un texte chiffré illisible à une autre destination. Un combo essaie d’abord une cible native canonique disponible ; si aucune n’est sélectionnable et que `agentTaskRecovery` est activé, un `NEW_TASK` chiffré est récupéré une fois avant l’envoi routé du combo.
+opencodex ignore les candidats désactivés, non routables, en mauvais état, en période de temporisation ou ayant atteint le seuil de quota. L’instantané de disponibilité est mis en cache pendant `subagentModelFallbackPollMs`. Les tâches enfants chiffrées limitent la chaîne aux cibles ChatGPT natives canoniques et aux routes Responses directes avec authentification par clé explicitement approuvées via `allowEncryptedV2AgentTasks: true` ; si aucune ne peut consommer la charge chiffrée et que la récupération facultative ne permet pas un envoi routé, la requête échoue sans transmettre de texte chiffré illisible. Un combo essaie d’abord une cible native canonique disponible ; si aucune n’est sélectionnable ou si les tentatives natives sont épuisées, et que `agentTaskRecovery` est activé, un `NEW_TASK` chiffré est récupéré une fois avant l’envoi routé du combo.
 
 ```json
 {
@@ -111,7 +111,7 @@ Ce mécanisme ne protège pas contre un autre processus exécuté sous le même
 
 N’activez cette option que si la requête authentifiée supplémentaire, la consommation de quota, la présence de texte en clair dans le processus et la dépendance à un service privé sont acceptables. Dans le cas contraire, privilégiez un enfant ChatGPT natif ou une délégation hétérogène v1.
 
-Ce mécanisme de récupération s’applique aux enfants routés directement et aux `NEW_TASK` chiffrés d’un combo. Au maximum 32 requêtes de récupération peuvent être actives simultanément ; toute absence supplémentaire dans le cache échoue de manière sûre. Un combo disposant d’une cible native canonique disponible continue d’envoyer directement le texte chiffré ; la récupération ne s’exécute que si aucune cible native n’est sélectionnable. Un échec de récupération, l’épuisement des cibles ou leur indisponibilité conserve l’échec fermé sans transmettre le texte chiffré à un fournisseur routé.
+Ce mécanisme de récupération s’applique aux enfants routés directement et aux `NEW_TASK` chiffrés d’un combo. Au maximum 32 requêtes de récupération peuvent être actives simultanément ; toute absence supplémentaire dans le cache échoue de manière sûre. Un combo disposant d’une cible native canonique disponible continue d’envoyer directement le texte chiffré ; la récupération peut s’exécuter si aucune cible native n’est sélectionnable ou si les tentatives natives sont épuisées. Si la récupération est désactivée ou échoue, ou si aucune cible routée n’est disponible, le texte chiffré illisible n’est pas transmis à un fournisseur routé.
 
 ## Plafonds d’effort
 

docs-site/src/content/docs/guides/sub-agent-surface.md

@@ -147,8 +147,9 @@ opencodex fails safely instead of forwarding an empty or unreadable task:
   `error.code = "unreadable_encrypted_agent_task"` and does not echo the ciphertext. An eligible
   direct key-auth Responses provider that explicitly opts in with
   `allowEncryptedV2AgentTasks: true` instead receives the opaque ciphertext and bypasses this error.
-- A combo considers only canonical native ChatGPT targets for that task, including retries. If none
-  is available, it returns the same 400 error.
+- A combo first considers canonical native ChatGPT targets. If none is available or their attempts
+  are exhausted, enabled recovery may make the task readable for an available routed target.
+  Without successful recovery and an eligible target, unreadable ciphertext is never forwarded.
 - A readable plaintext task keeps the normal route and fallback behavior.
 
 Recovery options are to select a native ChatGPT child, explicitly trust a direct key-auth Responses
@@ -165,8 +166,8 @@ authentication, another provider credential, or another Codex account. Only `aut
 `content-type` and `accept` are generated locally, and no other caller headers cross the boundary.
 It consumes quota, adds latency, briefly retains recovered plaintext in a bounded in-memory cache,
 and depends on undocumented ChatGPT backend behavior. Because a model returns the recovered text,
-byte-for-byte fidelity is not guaranteed. It rejects generic/API-key proxy callers and preserves
-`unreadable_encrypted_agent_task` on any failure. See
+byte-for-byte fidelity is not guaranteed. It rejects generic/API-key proxy callers. Failed recovery before any native attempt returns
+`unreadable_encrypted_agent_task`; after native attempts have failed, their last error is retained. See
 [Agent configuration: Encrypted v2 task recovery](/reference/configuration/agents/#encrypted-v2-task-recovery)
 for the full trust boundary and configuration.
 Combo routing prefers a selectable canonical native ChatGPT target for encrypted tasks. If none

docs-site/src/content/docs/zh-cn/reference/configuration/agents.md

@@ -52,7 +52,7 @@ per-role fallback 链必须放在 opencodex 配置里。把 `model_fallback` 写
 `$CODEX_HOME/agents/*.toml` 会让 Codex 0.146+ 把整个角色文件当作未知字段拒绝并跳过该角色
 （#1190）。TOML 中的旧版 `model_fallback` 仍会被读取以保持向后兼容，但 `ocx doctor` 会标记它。
 
-opencodex 会跳过已禁用、不可路由、不健康、处于冷却中，或已达到配额阈值的候选项。可用性快照会在 `subagentModelFallbackPollMs` 期间缓存。对于加密的子任务，候选链只包含规范的原生 ChatGPT 目标，以及通过 `allowEncryptedV2AgentTasks: true` 明确信任的直接密钥认证 Responses 路由。如果没有任何目标能处理加密载荷，请求就会失败，而不是把不可读的密文路由到别处。combo 会先尝试可用的规范原生目标；如果没有可选择的原生目标且已启用 `agentTaskRecovery`，会在路由到 combo 目标前对加密的 `NEW_TASK` 恢复一次。
+opencodex 会跳过已禁用、不可路由、不健康、处于冷却中，或已达到配额阈值的候选项。可用性快照会在 `subagentModelFallbackPollMs` 期间缓存。对于加密的子任务，候选链只包含规范的原生 ChatGPT 目标，以及通过 `allowEncryptedV2AgentTasks: true` 明确信任的直接密钥认证 Responses 路由。如果没有目标能处理加密载荷，且可选恢复无法支持路由发送，请求就会失败，不会转发不可读的密文。combo 会先尝试可用的规范原生目标；如果没有可选择的原生目标或原生尝试已耗尽，且已启用 `agentTaskRecovery`，会在路由到 combo 目标前对加密的 `NEW_TASK` 恢复一次。
 
 ```json
 {

docs-site/src/content/docs/zh-tw/reference/configuration/agents.md

@@ -50,7 +50,7 @@ V1 指引僅在 `max` 或 `ultra` 時為主動文字。V2 僅在存在偏好模
 
 Codex 0.146+ 會將角色檔案中的 `model_fallback` 視為未知欄位並略過整個角色；`ocx doctor` 也會對此發出警告。因此新的角色級 fallback 應設定在 opencodex，而不是角色 TOML 中。
 
-opencodex 會跳過已停用、不可路由、不健康、冷卻中或達到配額閾值的候選項。可用性快取保存 `subagentModelFallbackPollMs`。對於加密的子任務，候選鏈僅包含規範的原生 ChatGPT 目標，以及透過 `allowEncryptedV2AgentTasks: true` 明確信任的直接金鑰驗證 Responses 路由。若無任何目標可處理加密 payload，請求會失敗，而不會將無法讀取的密文路由到別處。組合會先嘗試可用的規範原生目標；若沒有可選擇的原生目標且已啟用 `agentTaskRecovery`，會在路由到組合目標前對加密的 `NEW_TASK` 恢復一次。
+opencodex 會跳過已停用、不可路由、不健康、冷卻中或達到配額閾值的候選項。可用性快取保存 `subagentModelFallbackPollMs`。對於加密的子任務，候選鏈僅包含規範的原生 ChatGPT 目標，以及透過 `allowEncryptedV2AgentTasks: true` 明確信任的直接金鑰驗證 Responses 路由。若無目標可處理加密 payload，且選用的恢復功能無法支援路由傳送，請求會失敗，不會轉送無法讀取的密文。組合會先嘗試可用的規範原生目標；若沒有可選擇的原生目標或原生嘗試已耗盡，且已啟用 `agentTaskRecovery`，會在路由到組合目標前對加密的 `NEW_TASK` 恢復一次。
 
 ```json
 {