fix(mcp,doctor): serve MCP under a pty; explicit Codex args = ["mcp"]

[yvgude]

Supersedes #1597 by @reysilvaa, whose commit is preserved here with their authorship — I could not push to their fork (403), so the branch lives in this repo instead. Also fixes the root cause their report uncovered.

What @reysilvaa got right

args = ["mcp"] really is the correct default, and their writer changes land unchanged: write_codex_config, upsert_codex_toml and ensure_codex_mcp_server now emit it, matching what the Copilot writer already did.

What I changed in their patch

1. The red test. codex_toml_upserts_existing_section still asserted args = [] and was taking down Test (ubuntu-latest), Test (windows-latest) and Coverage. Fixed, plus a companion test for the behaviour the writer deliberately preserves: args = ["mcp", "--verbose"] survives verbatim instead of being flattened.

2. args = [] is not drift. Their check_codex_toml required the mcp argument, which would have turned every existing Codex installation red. Both args = [] and an absent args start the stdio server (cli/dispatch/server.rs matches None | Some("mcp")), so the doctor would have reported a working config as broken and --fix would have rewritten it into a semantically identical file — the #1596 failure mode, hitting far more users than the change helps. The check now accepts absent / empty / mcp-carrying args and flags only an args array that replaces the entry point (["dashboard"]).

The root cause — and my earlier review was wrong about it

I told @reysilvaa and the reporter of #1595 that bare invocation still serves MCP, and showed a probe to prove it. That probe was wrong: I piped stdin. The reporter's environment gives the process a PTY, and cli/dispatch/mod.rs treats a TTY on stdin as "a human is here", prints the quickstart and exits.

Reproduced against the shipped 3.10.1 binary:

stdin = pipe          →  "lean-ctx v3.10.1 MCP server starting"   ✓
stdin = pty (bare)    →  quickstart text, process exits           ✗
stdin = pty + "mcp"   →  server starts                            ✓

So the report was accurate and args = ["mcp"] was a real workaround, not a cosmetic one. Devin, containerized agent runners, and anything driving the child through script/expect allocate a PTY; every one of them silently failed to connect, with nothing in the logs to explain it.

The fix: a TTY tells us a human may be watching — it never tells us a client is absent. The quickstart now goes to stderr (which MCP clients log rather than parse) and the server starts either way. The human reads what is happening and presses Ctrl-C; the client completes its handshake on stdout. The quickstart text says so instead of claiming the process "is waiting silently".

rust/tests/suite/mcp_pty_startup_1595.rs allocates a real pty with openpty (echo off), spawns the binary with no subcommand, and requires an initialize response. It fails against the previous behaviour.

Verification

• cargo test --lib → 10546 passed, 0 failed
• cargo clippy --lib --all-features -- -D warnings → clean
• cargo fmt --check → clean
• new pty integration test passes; removing the fix makes it fail

Fixes #1595
Closes #1597

Co-authored-by: reysilvaa reynaldsilva123@gmail.com

🤖 Generated with Claude Code

[reysilvaa]

Thanks for review my pull request, and i kindly help to keep contributing in this project