Surface remote-control MFA enrollment errors in `codex remote-control start`

What version of Codex CLI is running?

codex-cli 0.133.0

What subscription do you have?

ChatGPT auth was used. The exact subscription tier is not available from this environment.

Which model were you using?

N/A. This happens while running codex remote-control start, before a model is used. The local config default model was gpt-5.5.

What platform is your computer?

Linux 6.8.0-78-generic x86_64 x86_64

What terminal emulator and version are you using (if applicable)?

WezTerm 20240203-110809-5046fc22, running through tmux 3.4 over SSH.

Codex doctor report

{
  "schemaVersion": 1,
  "overallStatus": "ok",
  "codexVersion": "0.133.0",
  "checks": {
    "app_server.status": {
      "status": "ok",
      "summary": "background server is running"
    },
    "auth.credentials": {
      "status": "ok",
      "summary": "auth is configured",
      "details": {
        "stored API key": "false",
        "stored ChatGPT tokens": "true",
        "stored auth mode": "chatgpt"
      }
    },
    "config.load": {
      "status": "ok",
      "summary": "config loaded",
      "details": {
        "model": "gpt-5.5",
        "model provider": "openai"
      }
    },
    "installation": {
      "status": "ok",
      "summary": "installation looks consistent",
      "details": {
        "install context": "standalone",
        "platform": "linux-x86_64",
        "version": "0.133.0"
      }
    },
    "network.provider_reachability": {
      "status": "ok",
      "summary": "active provider endpoints are reachable over HTTP",
      "details": {
        "ChatGPT base URL": "https://chatgpt.com/backend-api/ reachable (HTTP 404)",
        "reachability mode": "ChatGPT auth"
      }
    },
    "network.websocket_reachability": {
      "status": "ok",
      "summary": "Responses WebSocket handshake succeeded",
      "details": {
        "auth mode": "chatgpt",
        "handshake result": "HTTP 101 Switching Protocols",
        "supports websockets": "true"
      }
    },
    "runtime.provenance": {
      "status": "ok",
      "summary": "running standalone on linux-x86_64",
      "details": {
        "commit": "unknown",
        "install method": "standalone",
        "platform": "linux-x86_64",
        "version": "0.133.0"
      }
    },
    "terminal.env": {
      "status": "ok",
      "summary": "terminal metadata was detected",
      "details": {
        "terminal": "WezTerm",
        "terminal version": "20240203-110809-5046fc22",
        "multiplexer": "tmux 3.4"
      }
    },
    "updates.status": {
      "status": "ok",
      "summary": "update configuration is locally consistent",
      "details": {
        "latest version": "0.133.0",
        "latest version status": "current version is not older"
      }
    }
  }
}

What issue are you seeing?

When codex remote-control start fails because the remote-control enrollment endpoint requires MFA, the actionable HTTP error can be hidden behind daemon/readiness or generic remote-control connection errors.

The useful error was only visible after inspecting app-server logs/state:

remote control server enrollment failed at https://chatgpt.com/backend-api/wham/remote/control/server/enroll: HTTP 403 Forbidden ... body: {"detail":"Multi-factor authentication required"}

At the CLI level, this led debugging toward local daemon/socket/state issues instead of the real fix: complete ChatGPT device auth / MFA.

The CLI should surface a concise enrollment failure such as:

remote control server enrollment failed at
https://chatgpt.com/backend-api/wham/remote/control/server/enroll
HTTP 403 Forbidden
{"detail":"Multi-factor authentication required"}

What steps can reproduce the bug?

1. Use Codex CLI 0.133.0 with ChatGPT auth.
2. Have a ChatGPT account/session where remote-control server enrollment requires MFA, or where the current auth token has not completed the required MFA/device-auth path.
3. Run:

``sh
codex remote-control start
``

1. Observe that the command does not clearly show the enrollment endpoint HTTP response/body that explains the failure.

What is the expected behavior?

codex remote-control start should include the last remote-control enrollment/connect error when the app-server reports remote-control status errored, especially HTTP enrollment failures from:

https://chatgpt.com/backend-api/wham/remote/control/server/enroll

For the MFA case, the user should immediately see HTTP 403 Forbidden and {"detail":"Multi-factor authentication required"} so they know to complete device-auth/MFA instead of debugging sockets or restarting the daemon.

Additional information

I prepared a reference implementation branch here:

https://github.com/kimdwkimdw/codex/tree/feature/remote-control-enrollment-error

Reference commit:

https://github.com/kimdwkimdw/codex/commit/6e83d1765d8d3a53812b1164c400e400ec7e3dae

The reference change keeps the scope small:

• adds lastError to the remote-control status payload;
• stores the last remote-control connection/enrollment error while status is errored;
• clears it on non-error states;
• makes codex remote-control start print that error directly;
• formats enrollment HTTP failures as a short human-readable block.

This would have made the MFA cause easy to identify.