fix(doctor): detect root openai_base_url Codex routing and agent-configured proxy ports (#4490)

## Description

`headroom doctor` gives two false negatives on machines where the proxy
is healthy (reported by a Headroom Desktop user on Windows 11;
reproduced on macOS):

1. **Codex "not routed" when Codex routes through a root
`openai_base_url`.** `check_codex_routing` only reads
`[model_providers.<active>].base_url`. Codex also routes its built-in
`openai` provider (the default when `model_provider` is unset) through a
root `openai_base_url`. Headroom Desktop writes that layout, because the
ChatGPT desktop app hides Dots, dictation and voice for any other
`model_provider` (`openai/codex#55783`). Doctor now reads the root key
for the `openai` provider and for configs with no `model_provider`,
where it wins over a leftover `[model_providers.headroom]` table. Both
keys only count at the TOML root (before the first table header): a
`model_provider` under `[profiles.*]` applies only when that profile is
selected, so it no longer hides the default session's route.
2. **A bare `headroom doctor` can't find a proxy on a port only the
agents know about.** Without `--port`, discovery probes 8787,
`HEADROOM_PORT`, deployment manifests and the wrap marker. Headroom
Desktop (port 6767) and `wrap --port N` leave none of these, so the
proxy row read "not reachable at 8787" with no hint. Discovery now also
probes the loopback ports in Claude Code's `ANTHROPIC_BASE_URL` and
Codex's active base URL, read from the same project and user configs as
the routing rows (`.claude/settings.local.json`,
`.claude/settings.json`, `.codex/config.toml`, then the user files),
through the existing `extra=` hook of `find_live_proxy_elsewhere`. It
still never adopts a port silently: the proxy row names the live port,
as it already does for manifest ports.

`codex_active_base_url` is shared with `init`'s port-alignment warning,
which now sees the same routing.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)

## Changes Made

- `headroom/cli/doctor.py`: `codex_active_base_url` reads
`model_provider` and `openai_base_url` from the TOML root only; with no
root `model_provider` (or `"openai"`), a root `openai_base_url` wins,
else the active provider table, else the legacy
`[model_providers.headroom]` table.
- `headroom/cli/doctor.py`: new `_configured_client_ports(claude_paths,
codex_paths)` feeds the project and user Claude/Codex loopback ports to
`find_live_proxy_elsewhere(extra=...)`.
- `tests/test_cli_doctor.py`: root `openai_base_url` passes (with and
without `model_provider`), beats an inactive
`[model_providers.headroom]` table, is not hidden by a `[profiles.work]
model_provider`; an `openai_base_url` inside a table is not root; a bare
`doctor` names a live proxy on the port a user config, a project
`.codex/config.toml` or a project `.claude/settings.local.json` routes
to.
- `tests/test_cli/test_port_alignment.py`: `init`'s alignment warning
reads the root `openai_base_url` over an inactive
`[model_providers.headroom]` table.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ uv run --frozen --extra dev pytest tests/test_cli_doctor.py tests/test_cli/test_port_alignment.py -q
167 passed in 0.99s
$ uv run --frozen --extra dev pytest tests/test_cli_doctor.py tests/test_cli/test_init_cli.py tests/test_cli/test_port_alignment.py tests/test_cli/test_wrap_stale_marker.py tests/test_corporate_tls.py tests/test_install/test_codex_install.py tests/test_offline_egress_chokepoint.py -q
477 passed, 2 skipped in 81.50s
$ uvx ruff@0.17.0 check headroom/cli/doctor.py tests/test_cli_doctor.py tests/test_cli/test_port_alignment.py
All checks passed!
$ uvx ruff@0.17.0 format --check headroom/cli/doctor.py tests/test_cli_doctor.py tests/test_cli/test_port_alignment.py
3 files already formatted
$ uv run --frozen --extra dev mypy headroom/cli/doctor.py
Success: no issues found in 1 source file
```

## Real Behavior Proof

- Environment: macOS, Headroom Desktop proxy (wheel 0.41.0) live on
127.0.0.1:6767, `~/.codex/config.toml` with root `model_provider =
"openai"` + `openai_base_url = "http://127.0.0.1:6767/v1"`, Claude
`ANTHROPIC_BASE_URL=http://127.0.0.1:6767` in `~/.claude/settings.json`.
- Exact command / steps: `headroom doctor --json` and `headroom doctor
--port 6767 --json`, once with the installed 0.41.0 wheel and once from
this branch (`uv run --frozen headroom doctor`).
- Observed result: The branch reports Codex as routed and names the live
6767 proxy, where 0.41.0 reported Codex as not routed and gave no hint.

```text
0.41.0, no --port:   proxy  fail  not reachable at http://127.0.0.1:8787
                     codex  warn  not routed (no active provider base_url in config.toml)
0.41.0, --port 6767: codex  warn  not routed (no active provider base_url in config.toml)
branch, no --port:   proxy  fail  not reachable at http://127.0.0.1:8787; a Headroom proxy IS running on port 6767
                     codex  warn  routed to port 6767, but doctor probed port 8787 (~/.codex/config.toml)
branch, --port 6767: proxy  pass  running at http://127.0.0.1:6767
                     claude pass  routed via ~/.claude/settings.json
                     codex  pass  routed via ~/.codex/config.toml
```

Review follow-up (fd5e6fd5): a real `headroom doctor --json` process
from 85d32990 and from fd5e6fd5, each in a clean `HOME` (`env -i
HOME=<tmp> PATH=/usr/bin:/bin`, so no `ANTHROPIC_BASE_URL` from the
shell), against the same live 6767 proxy:

```text
A  root openai_base_url 6767 + [model_providers.headroom] 8787, no model_provider, --port 6767
   85d32990  codex warn  routed to port 8787, but doctor probed port 6767
   fd5e6fd5  codex pass  routed via <home>/.codex/config.toml
B  root openai_base_url 6767 + [profiles.work] model_provider = "azure", --port 6767
   85d32990  codex warn  not routed (no active provider base_url in config.toml)
   fd5e6fd5  codex pass  routed via <home>/.codex/config.toml
C  only <project>/.codex/config.toml (root openai_base_url 6767), no --port
   85d32990  proxy fail  not reachable at http://127.0.0.1:8787
   fd5e6fd5  proxy fail  not reachable at http://127.0.0.1:8787; a Headroom proxy IS running on port 6767
```

Live, for the built-in provider's credentials: Codex CLI 0.164.0 signed
in with ChatGPT (`auth_mode = chatgpt`, no API key), config root
`model_provider = "openai"` + `openai_base_url =
"http://127.0.0.1:6767/v1"`, `codex exec --skip-git-repo-check -s
read-only "Reply with exactly the word OK and nothing else."` answered
`OK` (16,982 tokens). A routed request without credentials would have
been rejected upstream.

- Not tested: Windows, the reporter's platform (the change is
platform-independent TOML and URL parsing).

## Runtime Rollout Safety

- Rollout-managed feature(s): None.
- Minimum rollout channel: Stable.
- Stable/default behavior changed: Yes, diagnostics only: `doctor`
reports Codex as routed for root `openai_base_url` configs and probes
the agents' configured loopback ports; the proxy is untouched.
- Kill switch / disable path: `HEADROOM_PORT_DISCOVERY=0` disables the
extra probing; the Codex detection has none, as it only changes a
read-only report.
- Unsafe override required: No.
- Qualification impact: None.
- Rollback path: Revert this commit.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

Not applicable (CLI output above).

## Additional Notes

Documentation: no doc describes the doctor's Codex detection or
discovery candidates, so nothing to update. Related: #842 (Codex Desktop
doctor support) and #3855 (doctor/live-port alignment).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4490"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
This commit is contained in:
gglucass
2026-10-28 23:38:11 -05:00
committed by GitHub
co-authored by Claude Opus 5.5 JD Davis
parent cd5e2b9e73
commit 222f2d1df3
3 changed files with 150 additions and 5 deletions
+41 -5
View File
@@ -46,7 +46,7 @@ from headroom.providers.claude import (
)
from .main import get_version, main
from .port_discovery import find_live_proxy_elsewhere, is_headroom_livez
from .port_discovery import find_live_proxy_elsewhere, is_headroom_livez, loopback_port
from .wrap import _read_wrap_marker, _wrap_marker_is_stale
PASS = "pass"
@@ -59,6 +59,7 @@ DEFAULT_PROXY_PORT = 8787
_LOOPBACK_URL_RE = re.compile(r"https?://(?:127\.0\.0\.1|localhost):(\d+)")
_CODEX_BASE_URL_RE = re.compile(r'(?m)^[ \t]*base_url\s*=\s*"([^"\r\n]+)"')
_CODEX_MODEL_PROVIDER_RE = re.compile(r'(?m)^[ \t]*model_provider\s*=\s*"([^"\r\n]+)"')
_CODEX_OPENAI_BASE_URL_RE = re.compile(r'(?m)^[ \t]*openai_base_url\s*=\s*"([^"\r\n]+)"')
# Ollama's fixed default port. `ollama launch claude` writes
# ``ANTHROPIC_BASE_URL=http://127.0.0.1:11434`` into the launched Claude Code
@@ -573,7 +574,19 @@ def check_wrap_marker_staleness(settings_path: Path) -> CheckResult:
def codex_active_base_url(text: str) -> tuple[str, str | None]:
"""Return ``(provider_id, base_url)`` for the active Codex provider in ``text``."""
active_match = _CODEX_MODEL_PROVIDER_RE.search(text)
first_table = re.search(r"(?m)^[ \t]*\[", text)
root = text[: first_table.start()] if first_table is not None else text
# Only a root `model_provider` picks the default session's provider; one
# under `[profiles.*]` applies only when that profile is selected.
active_match = _CODEX_MODEL_PROVIDER_RE.search(root)
if active_match is None or active_match.group(1) == "openai":
# A root `openai_base_url` re-points Codex's built-in `openai` provider
# (the default when `model_provider` is unset), so it beats an inactive
# `[model_providers.headroom]` table. Headroom Desktop routes this way
# because the ChatGPT app hides features for any other provider.
root_url = _CODEX_OPENAI_BASE_URL_RE.search(root)
if root_url is not None:
return "openai", root_url.group(1)
provider_id = active_match.group(1) if active_match else "headroom"
return provider_id, _codex_provider_base_url(text, provider_id)
@@ -661,6 +674,24 @@ def _codex_provider_base_url(text: str, provider_id: str) -> str | None:
return base_url_match.group(1) if base_url_match else None
def _configured_client_ports(
claude_paths: Sequence[Path], codex_paths: Sequence[Path]
) -> list[int]:
"""Loopback ports the Claude Code and Codex configs (project and user) send traffic to.
Headroom Desktop (port 6767) and ``wrap --port N`` leave no deployment
manifest, so without these a bare ``doctor`` only ever finds 8787.
"""
urls = [_claude_base_url_in(path)[0] for path in claude_paths]
for path in codex_paths:
try:
text = path.read_text(encoding="utf-8", errors="replace")
except OSError:
continue
urls.append(codex_active_base_url(text)[1] or "")
return [port for port in map(loopback_port, urls) if port is not None]
def _codex_block_missing_openai_auth(
text: str, config_path: Path, provider_id: str = "headroom"
) -> bool:
@@ -1211,20 +1242,25 @@ def doctor(
health = probe_json(f"{base_url}/health", timeout=5.0) if livez else None
stats = probe_json(f"{base_url}/stats", timeout=5.0) if livez else None
installed = get_version()
project_claude_settings = Path.cwd() / ".claude" / "settings.json"
project_local_claude_settings = Path.cwd() / ".claude" / "settings.local.json"
live_elsewhere = None
if livez is None:
# Cheap, bounded: only ports Headroom recorded (HEADROOM_PORT, 8787,
# deployment manifests, the project's wrap marker), probed in parallel.
# deployment manifests, the project's wrap marker) and the ports the
# agents are configured for, probed in parallel.
live_elsewhere = find_live_proxy_elsewhere(
port,
manifests=manifests,
extra=_configured_client_ports(
[project_local_claude_settings, project_claude_settings, claude_settings_path()],
[codex_project_config_path(), codex_config_path()],
),
probe=lambda p: is_headroom_livez(
probe_json(f"http://127.0.0.1:{p}/livez", timeout=0.5)
),
)
project_claude_settings = Path.cwd() / ".claude" / "settings.json"
project_local_claude_settings = Path.cwd() / ".claude" / "settings.local.json"
checks = [
note_live_proxy_elsewhere(check_proxy_liveness(livez, base_url), live_elsewhere),
check_proxy_readiness(livez, readyz, base_url),
+15
View File
@@ -434,6 +434,21 @@ class TestHookAlignment:
message = init_mod.alignment_warning("codex", "init-user", probe=lambda p: False)
assert message is not None and "--port 8787 codex" in message
def test_codex_root_openai_base_url_beats_an_inactive_headroom_table(
self, home: Path, tmp_path: Path, monkeypatch
) -> None:
custom = tmp_path / "custom-codex"
custom.mkdir()
(custom / "config.toml").write_text(
'openai_base_url = "http://127.0.0.1:9200/v1"\n[model_providers.headroom]\n'
'base_url = "http://127.0.0.1:8787/v1"\n',
encoding="utf-8",
)
monkeypatch.setenv("CODEX_HOME", str(custom))
monkeypatch.setattr(init_mod, "load_manifest", lambda profile: _manifest(profile, 8787))
message = init_mod.alignment_warning("codex", "init-user", probe=lambda p: False)
assert message is not None and "127.0.0.1:9200" in message
def test_session_start_emits_hook_json(self, claude_settings: Path) -> None:
self._route_claude(claude_settings, 9200)
result = CliRunner().invoke(
+94
View File
@@ -587,6 +587,57 @@ class TestCodexRouting:
assert result.status == WARN
assert "9999" in result.summary
def test_root_openai_base_url_on_builtin_provider_passes(self, tmp_path):
"""Headroom Desktop's layout: built-in `openai` provider, root base URL."""
path = tmp_path / "config.toml"
path.write_text(
'model_provider = "openai"\n'
'openai_base_url = "http://127.0.0.1:6767/v1"\n'
'[projects."/work/app"]\n'
'trust_level = "trusted"\n',
encoding="utf-8",
)
result = check_codex_routing(path, 6767)
assert result.status == PASS, result.summary
assert check_codex_routing(path, 8787).status == WARN
def test_root_openai_base_url_without_model_provider_passes(self, tmp_path):
path = tmp_path / "config.toml"
path.write_text('openai_base_url = "http://127.0.0.1:8787/v1"\n', encoding="utf-8")
assert check_codex_routing(path, 8787).status == PASS
def test_openai_base_url_inside_a_table_is_not_root(self, tmp_path):
path = tmp_path / "config.toml"
path.write_text(
'model_provider = "openai"\n'
"[profiles.fast]\n"
'openai_base_url = "http://127.0.0.1:8787/v1"\n',
encoding="utf-8",
)
assert check_codex_routing(path, 8787).status == WARN
def test_root_openai_base_url_beats_an_inactive_headroom_table(self, tmp_path):
"""No root `model_provider`: Codex uses its built-in `openai`, not the table."""
path = tmp_path / "config.toml"
path.write_text(
'openai_base_url = "http://127.0.0.1:6767/v1"\n'
"[model_providers.headroom]\n"
'base_url = "http://127.0.0.1:8787/v1"\n',
encoding="utf-8",
)
assert check_codex_routing(path, 6767).status == PASS
assert check_codex_routing(path, 8787).status == WARN
def test_profile_model_provider_does_not_hide_the_default_route(self, tmp_path):
path = tmp_path / "config.toml"
path.write_text(
'openai_base_url = "http://127.0.0.1:6767/v1"\n'
"[profiles.work]\n"
'model_provider = "azure"\n',
encoding="utf-8",
)
assert check_codex_routing(path, 6767).status == PASS
def test_no_marker_warns(self, tmp_path):
path = tmp_path / "config.toml"
path.write_text('model = "gpt-5"\n', encoding="utf-8")
@@ -986,6 +1037,49 @@ class TestDoctorCommand:
assert "http://127.0.0.1:8789/livez" in seen
assert not any("127.0.0.1:8787" in url for url in seen)
def test_names_the_live_port_the_agents_are_configured_for(self, runner, isolated, monkeypatch):
"""Headroom Desktop runs on 6767 and records no deployment manifest."""
monkeypatch.setenv("HEADROOM_PORT_DISCOVERY", "1")
(isolated / "settings.json").write_text(
json.dumps({"env": {"ANTHROPIC_BASE_URL": "http://127.0.0.1:6767"}}),
encoding="utf-8",
)
def desktop_probe(url, timeout=2.0):
return LIVEZ_OK if url == "http://127.0.0.1:6767/livez" else None
monkeypatch.setattr(doctor_mod, "probe_json", desktop_probe)
result = runner.invoke(main, ["doctor", "--json"])
proxy = next(c for c in json.loads(result.output)["checks"] if c["name"] == "proxy")
assert "a Headroom proxy IS running on port 6767" in proxy["summary"]
@pytest.mark.parametrize(
("relative", "content"),
[
("project-codex.toml", 'openai_base_url = "http://127.0.0.1:6767/v1"\n'),
(
".claude/settings.local.json",
json.dumps({"env": {"ANTHROPIC_BASE_URL": "http://127.0.0.1:6767"}}),
),
],
)
def test_names_the_live_port_only_a_project_config_routes_to(
self, runner, isolated, monkeypatch, relative, content
):
monkeypatch.setenv("HEADROOM_PORT_DISCOVERY", "1")
monkeypatch.chdir(isolated)
path = isolated / relative
path.parent.mkdir(exist_ok=True)
path.write_text(content, encoding="utf-8")
def desktop_probe(url, timeout=2.0):
return LIVEZ_OK if url == "http://127.0.0.1:6767/livez" else None
monkeypatch.setattr(doctor_mod, "probe_json", desktop_probe)
result = runner.invoke(main, ["doctor", "--json"])
proxy = next(c for c in json.loads(result.output)["checks"] if c["name"] == "proxy")
assert "a Headroom proxy IS running on port 6767" in proxy["summary"]
class TestCostTrackerBudgetKeys:
def test_stats_exposes_budget_config(self):