codex-reconnect-repair

name	codex-reconnect-repair
description	Diagnose and safely repair Codex "Reconnecting... 1/5" through "5/5" loops in the CLI, desktop app, or IDE on macOS, Linux, and Windows. Use when a Codex turn stalls on repeated stream reconnects or only succeeds after HTTPS fallback; do not use for generic login, quota, model, or rate-limit errors.

Codex Reconnect Repair

Resolve the affected client's network path with evidence, then make only the smallest reversible change justified by that evidence.

Entrypoint

Set SKILL_DIR to this skill's directory. Use Python 3.9 or newer:

python3 "$SKILL_DIR/scripts/codex_reconnect_repair.py" diagnose --json

On Windows, use py -3 when python3 is unavailable.

The script's default behavior is read-only. repair and rollback also remain dry runs unless --apply is present.

Workflow

1. Identify where the reconnect loop occurs: CLI, ChatGPT/Codex desktop app, IDE extension, SSH host, container, or WSL. Do not assume the codex found on PATH is the binary used by that client. If the context is unclear, read client-contexts.md.

2. Run diagnose --json against the exact binary. Never publish raw codex doctor --json output; the helper emits a reduced report that contains variable names but not proxy values, auth tokens, prompts, or log contents.

3. Follow the returned recommendation.action:

   • compare-client-context: WebSocket works in this process. Compare the affected client's binary and proxy context; do not mutate config.
   • system-proxy: On macOS, Codex detected an unused system proxy and exposes respect_system_proxy. Preview this repair first.
   • http-fallback: HTTP succeeds while WebSocket fails. Preview the managed HTTPS/SSE provider.
   • repair-external-network, repair-authentication, repair-config-manually, custom-provider-manual, update-codex, or collect-more-evidence: stop automatic repair and resolve the reported prerequisite.

4. Preview an actionable repair:

   python3 "$SKILL_DIR/scripts/codex_reconnect_repair.py" repair --strategy auto
   

5. Apply only when the user directly requested a fix or approves the preview:

   python3 "$SKILL_DIR/scripts/codex_reconnect_repair.py" repair --strategy auto --apply
   

6. Restart the affected client so it loads the new configuration, then validate:

   python3 "$SKILL_DIR/scripts/codex_reconnect_repair.py" verify --json
   

   A real request consumes account usage. Run verify --live --json only after the user authorizes that request.

7. If the client regresses after repair, preview and apply the guarded rollback. It refuses to overwrite config edited after the repair:

   python3 "$SKILL_DIR/scripts/codex_reconnect_repair.py" rollback
   python3 "$SKILL_DIR/scripts/codex_reconnect_repair.py" rollback --apply
   

Safety invariants

• Never expose proxy URLs, credentials, auth.json, raw environment values, prompt/session files, or full logs.
• Do not change global proxy apps, DNS, firewall rules, certificates, launchctl, the Windows registry, or shell startup files. Report those as external prerequisites.
• Do not use HTTP fallback when provider HTTP reachability fails, a custom provider is active, or WebSocket succeeds in the affected process.
• Preserve unrelated TOML. The helper creates a timestamped 0600 backup where supported, writes atomically, validates with Codex Doctor, and restores automatically on immediate validation failure.
• The fallback provider intentionally omits base_url, keeps requires_openai_auth = true, uses wire_api = "responses", and uses the exact provider name OpenAI. Do not replace it with older hard-coded ChatGPT URLs or an arbitrary provider name.
• Do not kill an active Codex process. Configuration changes take effect after the relevant client restarts.

For the classification rationale, read decision-tree.md. For upstream behavior and current source links, read evidence.md only when auditing or updating the repair logic.

Completion report

State the affected client and binary, the decisive HTTP/WebSocket evidence, the selected strategy, whether a backup was created, Doctor/live verification results, and any remaining external prerequisite. Do not claim the issue is fixed until a new process completes a real turn without the reconnect loop or the user confirms equivalent behavior.