openai-docs can misreport Manual helper DNS failure despite working Docs MCP fallback

What happened

The bundled openai-docs skill can treat a failure of the local Codex Manual helper as if official Codex information were unavailable, even when the configured OpenAI Developer Docs MCP server can fetch the same Manual successfully.

In a Codex task, the skill ran:

node ~/.codex/skills/.system/openai-docs/scripts/fetch-codex-manual.mjs

The helper's HEAD request failed inside the local shell sandbox:

curl: (6) Could not resolve host: developers.openai.com

That failure was then surfaced to the user as an official-manual retrieval failure. However, in the same task:

• openaiDeveloperDocs was configured and enabled.
• mcp__openaiDeveloperDocs__fetch_openai_doc was callable.
• Fetching https://developers.openai.com/codex/codex-manual.md through Docs MCP succeeded (796,211 characters returned).
• No sandbox-external shell execution was required.

The local shell sandbox and MCP/connectors have separate network controls, so a helper DNS failure establishes only that the local helper lane failed.

Environment

• Codex CLI: 0.144.2
• macOS: 26.5.1 (25F80), arm64
• Observed: 2026-07-17
• Docs MCP: openaiDeveloperDocs, configured and enabled

Reproduction

1. Configure the official Docs MCP:

``toml
[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"
enabled = true
``

1. Use a local shell sandbox where outbound DNS is unavailable.
2. Ask a broad Codex self-knowledge question that triggers the bundled openai-docs skill.
3. Let the skill run the Manual helper.
4. Observe the helper fail with ENOTFOUND / curl exit code 6.
5. Call the known MCP tool directly:

``text
mcp__openaiDeveloperDocs__fetch_openai_doc(
url = "https://developers.openai.com/codex/codex-manual.md"
)
``

1. Observe that the official Manual is returned successfully.

Expected behavior

After an actual helper failure, use this deterministic source order:

1. Directly call mcp__openaiDeveloperDocs__fetch_openai_doc with the known Manual URL.
2. If needed, use search_openai_docs and then fetch_openai_doc.
3. If Docs MCP is unavailable or unhelpful, search only official OpenAI domains.
4. Only if all routes fail, report that official information could not be confirmed.

Additional expectations:

• Do not infer that Docs MCP is missing from a fuzzy string search over a generic tool listing. Load or invoke the exact known tool name when it is deferred/callable.
• Do not request sandbox-external shell execution solely to retry the helper while Docs MCP remains available.
• Do not describe one route's failure as an overall official-information failure.
• If a fallback succeeds, normally omit the internal routing detail. When relevant, say: "The local Manual helper was unavailable under the sandbox network policy, so I retrieved the same official information through the configured OpenAI Docs MCP server."

Actual behavior

The first route's DNS failure can be reported as if the official Manual or official information as a whole could not be retrieved, despite a working Docs MCP fallback in the same task.

Root cause and source location

The public bundled source is:

• codex-rs/skills/src/assets/samples/openai-docs/SKILL.md
• codex-rs/skills/src/assets/samples/openai-docs/scripts/fetch-codex-manual.mjs

codex-rs/skills/src/lib.rs embeds these assets and regenerates CODEX_HOME/skills/.system, so editing ~/.codex/skills/.system/openai-docs is not durable.

The current skill already says to continue to Docs MCP and then official web, but it does not make the known-URL direct fetch and user-facing reporting contract explicit. The helper also overwrites transport failures in lastError, so only the final transport cause is retained, and --status-json emits JSON only on success.

Proposed fix

Skill routing

• Add the fixed fallback order above.
• Treat the known Docs MCP names as exact capabilities.
• Explicitly prevent escalation of shell access for a helper-only network denial while MCP fallback remains.
• State that user-facing uncertainty is appropriate only after every official route fails.
• Complete official-web fallback before interrupting a docs answer to install/repair MCP.

Helper diagnostics

Keep MCP orchestration in the skill, not the helper. Improve the helper by:

• Classifying at least dns_unavailable, timeout, http_error, cache_unavailable, and mixed request_failed.
• Retaining structured failure details for both native fetch and curl.
• Emitting parseable { "ok": false, "error": ... } JSON when --status-json is requested, while preserving exit code 1.
• Optionally recording cache metadata and exposing an existing cache as freshness: "unverified" after a network failure. It should not silently count as a fresh success, because that would prevent the skill from continuing to Docs MCP.

A local proof-of-concept adds these diagnostics and a node:test suite; all 8 tests pass. The standalone Node test command is not yet wired into the public repository's normal Cargo/Bazel CI path, so the final upstream change also needs internal CI/eval integration.

Regression matrix

1. Helper succeeds: use the Manual; do not call MCP or web.
2. Helper DNS fails, Docs MCP succeeds: directly fetch the known Manual URL; continue the answer; do not use web or request sandbox-external shell approval; do not say official information is unavailable.
3. Helper and Docs MCP fail, official web succeeds: use official web and continue; do not say official information is unavailable.
4. All routes fail: report bounded uncertainty and distinguish the failed routes without asserting unverified product behavior.

Related issues

• #24239 covers Docs MCP not being configured; this report covers MCP being configured/callable but not reliably used after a helper failure.
• #31984 covers the Manual redirect/checksum failure; this report fails earlier at sandboxed DNS and focuses on fallback orchestration and reporting.
• #31653 covers system-skill/manual-fallback version churn.