codex doctor --json: expose an unredacted, secret-free failure class for network.websocket_reachability when a token is present
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 125k
- Forks
- 19.4k
- PR merge metrics
- PR metrics pending
Description
Measured at codex-cli 0.153.4.
With a stored token, a rejected bearer (401), a network outage, and a TLS failure all produce the same codex doctor --json check network.websocket_reachability: status: warning, summary Responses WebSocket failed; HTTPS fallback may still work, auth mode: chatgpt, handshake transport error: <redacted>. The only unredacted 401 is the no-credential case, where there is nothing to redact around.
A scheduler that uses doctor --json as a pre-flight readiness probe therefore cannot tell "reauthenticate" from "network is down" without re-implementing the handshake itself.
Request: keep the message redaction, but add a secret-free typed field to the check — for example handshake_status: 401 and/or failure_class: unauthorized | forbidden | throttled | transport | tls | dns | timeout in the --json document, or a stable auth_ok: true|false. No secret is exposed; only the category.
Why: codex login status never exchanges the stored token, so a rotated or revoked refresh token passes it and only fails on the first real turn. codex doctor --json already performs the authenticated handshake without a model turn — it is the right probe, and one unredacted status class would make it a complete one.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start at the codex doctor --json implementation and the network.websocket_reachability check described in the issue, then trace how authenticated handshake failures are classified and redacted. Define a stable secret-free category or status field for the documented failure cases while preserving the existing message redaction, and verify the JSON output distinguishes authentication failures from transport, TLS, DNS, timeout, and throttling failures.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- authentication, cli, networking
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100