Files
headroom/tests/test_cli/test_port_alignment.py
02c4e922f7 fix(cli): resolve active proxy port for read commands (#3522)
## Description

`headroom wrap copilot` can intentionally start a dedicated proxy on
port 8788
(or fall forward when 8787 is busy), but read-only CLI commands
previously
defaulted directly to 8787. As a result, `headroom dashboard` could open
a dead
or unrelated dashboard even though the wrapped session reported its
proxy on
8788.

This change extends the shared `headroom/cli/port_discovery.py` resolver
(introduced by #3855) to include live wrap-client markers, preferring
the
newest healthy session while preserving explicit `--port` and
`HEADROOM_PORT`
overrides.

Closes: N/A (no matching open issue found)

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- Extended the shared port discovery module from #3855 with live
wrap-client
marker validation (PID liveness and reuse checks), newest-session
ordering,
  and `/health` verification.
- Updated `dashboard`, `inspect`, and the runtime probe used by `learn`
to
  follow the newest healthy live wrap session after explicit and
  `HEADROOM_PORT` overrides.
- Kept `doctor`'s requested-port behavior; it now reports a healthy
proxy
  discovered from wrap-client markers elsewhere, with a `--port` hint.
- Added a warning when `dashboard` cannot reach the resolved port.
- Exported the actual proxy port as `HEADROOM_PORT` into every wrapped
agent
  environment.
- Reused #3855's port-discovery module rather than introducing a
parallel
  resolver.
- Added regression coverage for stale/recycled markers, multiple
sessions,
  explicit/environment overrides, dashboard output, doctor diagnostics,
  inspect/learn routing, and wrapped child environments.
- Documented automatic discovery and wrong-port troubleshooting.

## 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 pytest tests/test_cli/test_proxy_port_discovery.py \
    tests/test_cli/test_dashboard_port_discovery.py \
    tests/test_cli/test_port_alignment.py \
    tests/test_cli/test_wrap_helpers.py \
    tests/test_cli_doctor.py tests/test_cli_inspect.py tests/test_cli_learn.py -q
267 passed in 5.49s

$ uv run ruff check .
All checks passed!

$ uv run ruff format --check .
1677 files already formatted

$ uv run mypy headroom/cli/port_discovery.py headroom/cli/proxy.py \
    headroom/cli/doctor.py headroom/cli/inspect.py headroom/cli/learn.py
Success: no issues found in 5 source files

$ uv run pre-commit run --all-files
Sync plugin versions.....................................................Passed
Verify Ruff version alignment............................................Passed
check for merge conflicts................................................Passed
ruff (legacy alias)......................................................Passed
ruff format..............................................................Passed
mypy.....................................................................Passed
```

After the first rebase, `make ci-precheck` completed `cargo fmt --check`
and
`cargo clippy --workspace -- -D warnings`, then stalled in the existing
Rust
Magika/detection tests (multiple tests exceeded 60 seconds). The same
stall
recurred during the push hook; it was stopped after confirming the
affected
suite. The final rebase onto #3883 was followed by the Python/CLI
regression
suite and all repository pre-commit gates above, but not another Rust
test run.

## Real Behavior Proof

- Environment: Ubuntu 22.04.5 LTS x86_64; Python 3.10.12; uv 0.12.10;
Headroom proxy 0.40.0-dev, started on isolated port 18788 with an
isolated live-client marker.
- Exact command / steps: Started an isolated process that wrote its live
PID marker and launched `headroom proxy --port 18788` under a temporary
workspace, with `HEADROOM_PORT` unset; then ran `env -u HEADROOM_PORT -u
HEADROOM_PORT_DISCOVERY
HEADROOM_WORKSPACE_DIR=/tmp/headroom-port-discovery-proof-20260930/workspace
./.venv/bin/headroom dashboard --no-open` and curled
`http://127.0.0.1:18788/dashboard`.

```text
$ env -u HEADROOM_PORT -u HEADROOM_PORT_DISCOVERY \
    HEADROOM_WORKSPACE_DIR=/tmp/headroom-port-discovery-proof-20260930/workspace \
    ./.venv/bin/headroom dashboard --no-open
  Detected live proxy on port 18788
  Dashboard: http://127.0.0.1:18788/dashboard

$ curl --max-time 5 -sS -o /dev/null -w '%{http_code}\n' \
    http://127.0.0.1:18788/dashboard
200

# Proxy health before discovery returned:
service=headroom-proxy status=healthy ready=true
```

- Observed result: With `HEADROOM_PORT` unset, the CLI selected the
marker-associated healthy proxy on 18788, printed the matching dashboard
URL, and the endpoint returned HTTP 200. The earlier manual run with a
real wrapped Copilot session also confirmed discovery on 8788 before
this rebase.
- Not tested: Starting a new interactive `wrap copilot` session after
this rebase (avoided launching an agent); Windows/macOS PID-identity
behavior; multiple simultaneous real proxies; browser UI launch. Unit
tests cover marker ordering, PID reuse, and explicit/environment
overrides.

## Runtime Rollout Safety

- Rollout-managed feature(s): None.
- Minimum rollout channel: N/A.
- Stable/default behavior changed: `dashboard`, `inspect`, and `learn`
now follow
the newest healthy live wrap proxy when no port override is set;
`doctor`
remains on the requested/default port and reports a live proxy
elsewhere.
- Kill switch / disable path: Pass `--port`, set `HEADROOM_PORT`, or set
  `HEADROOM_PORT_DISCOVERY=0` to bypass automatic discovery.
- Unsafe override required: No.
- Qualification impact: None.
- Rollback path: Revert this commit; commands return to the fixed 8787
default.

## 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
- [x] 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

## Screenshots (if applicable)

N/A — terminal output above captures the behavior.

## Additional Notes

Port discovery is integrated into #3855's shared `port_discovery.py`;
candidates
are accepted only when `/health` identifies `service: headroom-proxy`,
so an
unrelated local JSON service cannot be mistaken for a Headroom proxy.

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

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/3522"
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 -->

### Maintainer current-main requalification

Exact head `e66a6393f83278aa07e9965f5b87fed820603677`, upstream main
`2d3ee51846435ef5b320eea4806af14e602b0d8c`.

Re-reviewed latest integration head 420c2d636 and current author
response, including isolated workspace/port fixtures and live-marker
ordering/pruning regressions. Clean integration with upstream/main
2d3ee51846. Explicit CLI ports and
HEADROOM_PORT retain precedence; discovery bounds candidate probes,
verifies Headroom health identity, prefers newest live wrap markers, and
preserves configured-agent discovery. No new PR-specific correctness
blocker found in scope.

All 436
dashboard/port/discovery/wrap/doctor/inspect/learn/release/version/MCP
tests pass. All 14 changed Python files pass Ruff check/format;
whitespace passes. Previous cached-read freeze-boundary failure was
independently reproduced on main and is not a contributor-code blocker.
Maintainers handle fresh exact-head qualification and distinguish
inherited failures; no contributor CI execution requested. Existing
native extension supported startup, not a fresh native build. No
contributor discovery logic rewritten; nothing merged.


Exact-head hosted checks are being handled by maintainers. No new
finding in the reviewed scope; formal approval awaits exact-head hosted
qualification; nothing merged.

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-11-05 21:10:06 -06:00

738 lines
31 KiB
Python

"""CODEX_HOME resolution, live-proxy port discovery, and agent/proxy alignment.
Every test isolates HOME/CODEX_HOME/cwd under ``tmp_path`` and injects fake
probes, so no real ``~/.codex``, ``~/.headroom`` or listening proxy is touched.
"""
from __future__ import annotations
import json
from pathlib import Path
from types import SimpleNamespace
from typing import Any
import click
import pytest
from click.testing import CliRunner
import headroom.cli.doctor as doctor_mod
import headroom.cli.init as init_mod
import headroom.cli.port_discovery as pd
import headroom.cli.wrap as wrap_mod
from headroom.cli.main import main
from headroom.install import paths as install_paths
@pytest.fixture
def home(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
"""Fake home + cwd; discovery enabled; HEADROOM_WORKSPACE_DIR sandboxed."""
fake_home = tmp_path / "home"
project = tmp_path / "project"
fake_home.mkdir()
project.mkdir()
monkeypatch.setattr(Path, "home", classmethod(lambda cls: fake_home))
monkeypatch.setenv("HOME", str(fake_home))
monkeypatch.setenv("USERPROFILE", str(fake_home))
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path / "workspace"))
monkeypatch.delenv("CODEX_HOME", raising=False)
monkeypatch.delenv("HEADROOM_PORT", raising=False)
monkeypatch.delenv("HEADROOM_PORT_DISCOVERY", raising=False)
monkeypatch.chdir(project)
return fake_home
def _manifest(profile: str, port: int, targets: list[str] | None = None) -> Any:
return SimpleNamespace(profile=profile, port=port, targets=targets or [])
# ---------------------------------------------------------------------------
# 1. CODEX_HOME
# ---------------------------------------------------------------------------
class TestCodexHome:
def test_defaults_to_dot_codex(self, home: Path) -> None:
assert install_paths.codex_home_dir() == home / ".codex"
assert install_paths.codex_config_path() == home / ".codex" / "config.toml"
assert install_paths.codex_hooks_path() == home / ".codex" / "hooks.json"
def test_honors_codex_home(self, home: Path, tmp_path: Path, monkeypatch) -> None:
custom = tmp_path / "custom-codex"
monkeypatch.setenv("CODEX_HOME", str(custom))
assert install_paths.codex_config_path() == custom / "config.toml"
assert install_paths.codex_hooks_path() == custom / "hooks.json"
# Every consumer resolves through the one helper.
assert wrap_mod._codex_home_dir() == custom
from headroom.mcp_registry.codex import CodexRegistrar
assert CodexRegistrar()._config_file == custom / "config.toml"
def test_blank_codex_home_falls_back(self, home: Path, monkeypatch) -> None:
monkeypatch.setenv("CODEX_HOME", " ")
assert install_paths.codex_home_dir() == home / ".codex"
def test_init_global_codex_paths_follow_codex_home(
self, home: Path, tmp_path: Path, monkeypatch
) -> None:
custom = tmp_path / "custom-codex"
monkeypatch.setenv("CODEX_HOME", str(custom))
assert init_mod._codex_scope_path(True) == custom / "config.toml"
assert init_mod._codex_hooks_path(True) == custom / "hooks.json"
# Project scope stays in the project.
assert init_mod._codex_scope_path(False) == Path.cwd() / ".codex" / "config.toml"
assert init_mod._codex_hooks_path(False) == Path.cwd() / ".codex" / "hooks.json"
def test_doctor_reads_codex_home_config(self, home: Path, tmp_path: Path, monkeypatch) -> None:
custom = tmp_path / "custom-codex"
custom.mkdir()
(custom / "config.toml").write_text(
'model_provider = "headroom"\n[model_providers.headroom]\n'
'base_url = "http://127.0.0.1:8787/v1"\nrequires_openai_auth = true\n',
encoding="utf-8",
)
monkeypatch.setenv("CODEX_HOME", str(custom))
monkeypatch.setattr(doctor_mod, "probe_json", lambda *a, **k: None)
monkeypatch.setattr(doctor_mod, "list_manifests", lambda: [])
monkeypatch.setattr(doctor_mod, "claude_settings_path", lambda: home / "settings.json")
monkeypatch.setattr(doctor_mod, "savings_path", lambda: home / "savings.json")
result = CliRunner().invoke(main, ["doctor", "--json"])
codex = next(c for c in json.loads(result.output)["checks"] if c["name"] == "codex")
assert codex["status"] == "pass", codex
assert str(custom / "config.toml") in codex["summary"]
def test_doctor_prefers_project_codex_config(self, tmp_path: Path) -> None:
user = tmp_path / "user.toml"
user.write_text(
'[model_providers.headroom]\nbase_url = "http://127.0.0.1:9999/v1"\n',
encoding="utf-8",
)
project = tmp_path / "project.toml"
project.write_text(
'[model_providers.headroom]\nbase_url = "http://127.0.0.1:8787/v1"\n',
encoding="utf-8",
)
result = doctor_mod.check_codex_routing(user, 8787, [project])
assert result.status == doctor_mod.PASS
assert str(project) in result.summary
def test_doctor_missing_config_names_actual_path(self, tmp_path: Path) -> None:
result = doctor_mod.check_codex_routing(tmp_path / "nope.toml", 8787, [])
assert result.status == doctor_mod.WARN
assert str(tmp_path / "nope.toml") in result.summary
# ---------------------------------------------------------------------------
# 2. Default port: HEADROOM_PORT + live-proxy discovery
# ---------------------------------------------------------------------------
class TestPortDiscovery:
@pytest.fixture(autouse=True)
def isolate_live_client_discovery(
self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path / "workspace"))
monkeypatch.delenv("HEADROOM_PORT", raising=False)
monkeypatch.delenv("HEADROOM_PORT_DISCOVERY", raising=False)
def test_default_port_reads_env(self) -> None:
assert pd.default_port({}) == 8787
assert pd.default_port({"HEADROOM_PORT": "9100"}) == 9100
assert pd.default_port({"HEADROOM_PORT": "not-a-port"}) == 8787
assert pd.default_port({"HEADROOM_PORT": "70000"}) == 8787
def test_candidates_include_env_manifests_and_wrap_marker(self, tmp_path: Path) -> None:
(tmp_path / ".claude").mkdir()
(tmp_path / ".claude" / ".headroom_wrap_marker.json").write_text(
json.dumps({"port": 9300}), encoding="utf-8"
)
ports = pd.candidate_ports(
8787,
environ={"HEADROOM_PORT": "9100"},
manifests=[_manifest("a", 9200), _manifest("b", 8787)],
cwd=tmp_path,
)
assert ports == [8787, 9100, 9200, 9300]
def test_candidates_order_live_client_markers_by_recency(
self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
clients = tmp_path / "workspace" / "clients"
markers = {
3001: (9000, 100.0),
3002: (9001, 200.0),
3003: (9002, 300.0),
}
for pid, (port, started_at) in markers.items():
marker = clients / str(port) / f"{pid}.json"
marker.parent.mkdir(parents=True, exist_ok=True)
marker.write_text(json.dumps({"pid": pid, "started_at": started_at}), encoding="utf-8")
dead_marker = clients / "9002" / "3003.json"
monkeypatch.setattr(pd, "pid_alive", lambda pid: pid != 3003)
marker_path = tmp_path / ".claude" / ".headroom_wrap_marker.json"
marker_path.parent.mkdir()
marker_path.write_text(json.dumps({"port": 9300}), encoding="utf-8")
ports = pd.candidate_ports(
8787,
environ={"HEADROOM_PORT": "9100"},
manifests=[_manifest("profile", 9200)],
cwd=tmp_path,
extra=[9400],
)
assert ports == [8787, 9100, 9400, 9200, 9300, 9001, 9000]
assert not dead_marker.exists()
def test_candidates_are_bounded(self, tmp_path: Path) -> None:
manifests = [_manifest(str(i), 10000 + i) for i in range(50)]
ports = pd.candidate_ports(8787, environ={}, manifests=manifests, cwd=tmp_path)
assert len(ports) == pd._MAX_CANDIDATES
def test_finds_live_proxy_on_other_port(self, tmp_path: Path) -> None:
live = pd.find_live_proxy_elsewhere(
8787,
environ={},
manifests=[_manifest("p", 9200)],
cwd=tmp_path,
probe=lambda port: port == 9200,
)
assert live == 9200
def test_requested_port_live_means_nothing_to_reconcile(self, tmp_path: Path) -> None:
live = pd.find_live_proxy_elsewhere(
8787,
environ={},
manifests=[_manifest("p", 9200)],
cwd=tmp_path,
probe=lambda port: True,
)
assert live is None
def test_discovery_can_be_disabled(self, tmp_path: Path) -> None:
live = pd.find_live_proxy_elsewhere(
8787,
environ={"HEADROOM_PORT_DISCOVERY": "0"},
manifests=[_manifest("p", 9200)],
cwd=tmp_path,
probe=lambda port: port == 9200,
)
assert live is None
def test_probe_errors_never_raise(self, tmp_path: Path) -> None:
def boom(port: int) -> bool:
raise RuntimeError("nope")
assert (
pd.find_live_proxy_elsewhere(
8787, environ={}, manifests=[_manifest("p", 9200)], cwd=tmp_path, probe=boom
)
is None
)
def test_livez_identity_required(self) -> None:
assert pd.is_headroom_livez({"service": "headroom-proxy", "alive": True})
assert pd.is_headroom_livez({"alive": True, "version": "1.0"}) # legacy shape
assert not pd.is_headroom_livez({"service": "something-else", "alive": True})
assert not pd.is_headroom_livez({"status": "ok"})
assert not pd.is_headroom_livez(None)
def test_non_interactive_keeps_requested_and_warns(self, tmp_path: Path, capsys) -> None:
port = pd.reconcile_default_port(
8787,
interactive=False,
environ={},
manifests=[_manifest("p", 9200)],
cwd=tmp_path,
probe=lambda p: p == 9200,
)
assert port == 8787
err = capsys.readouterr().err
assert "port 9200" in err
assert "--port 9200" in err
@pytest.mark.parametrize(("answer", "expected"), [("c", 9200), ("k", 8787)])
def test_interactive_prompt_connect_or_keep(
self, tmp_path: Path, monkeypatch, answer: str, expected: int
) -> None:
monkeypatch.setattr(pd.click, "prompt", lambda *a, **k: answer)
port = pd.reconcile_default_port(
8787,
interactive=True,
environ={},
manifests=[_manifest("p", 9200)],
cwd=tmp_path,
probe=lambda p: p == 9200,
)
assert port == expected
def test_interactive_prompt_abort(self, tmp_path: Path, monkeypatch) -> None:
monkeypatch.setattr(pd.click, "prompt", lambda *a, **k: "a")
with pytest.raises(click.Abort):
pd.reconcile_default_port(
8787,
interactive=True,
environ={},
manifests=[_manifest("p", 9200)],
cwd=tmp_path,
probe=lambda p: p == 9200,
)
def test_no_live_proxy_is_silent(self, tmp_path: Path, capsys) -> None:
port = pd.reconcile_default_port(
8787, interactive=False, environ={}, manifests=[], cwd=tmp_path, probe=lambda p: False
)
assert port == 8787
assert capsys.readouterr().err == ""
class TestProxyPortOption:
@pytest.fixture
def cmd(self) -> click.Command:
@click.command()
@pd.proxy_port_option()
def _cmd(port: int) -> None:
click.echo(f"port={port}")
return _cmd
@pytest.fixture
def reconcile_calls(self, monkeypatch) -> list[int]:
calls: list[int] = []
def fake(requested: int, **kwargs: Any) -> int:
calls.append(requested)
return 9200
monkeypatch.setattr(pd, "reconcile_default_port", fake)
return calls
def test_default_triggers_reconcile(self, cmd, reconcile_calls) -> None:
result = CliRunner().invoke(cmd, [])
assert result.exit_code == 0, result.output
assert "port=9200" in result.output
assert reconcile_calls == [8787]
def test_explicit_port_is_honored_without_discovery(self, cmd, reconcile_calls) -> None:
result = CliRunner().invoke(cmd, ["--port", "9500"])
assert "port=9500" in result.output
assert reconcile_calls == []
def test_headroom_port_env_is_honored_without_discovery(self, cmd, reconcile_calls) -> None:
result = CliRunner().invoke(cmd, [], env={"HEADROOM_PORT": "9400"})
assert "port=9400" in result.output
assert reconcile_calls == []
def test_wrap_subcommands_use_shared_option(self) -> None:
# Every wrap subcommand with a port option resolves it through the callback.
wrap_group = main.commands["wrap"]
assert isinstance(wrap_group, click.Group)
checked = 0
for name, command in wrap_group.commands.items():
for param in command.params:
if param.name in {"port", "proxy_port"}:
assert param.callback is pd.port_option_callback, name
assert param.envvar == "HEADROOM_PORT", name
checked += 1
assert checked >= 15
class TestCodexProviderPortWarning:
def test_warns_when_repointing(self, tmp_path: Path, capsys) -> None:
config = tmp_path / "config.toml"
config.write_text(
'[model_providers.headroom]\nname = "x"\nbase_url = "http://127.0.0.1:9200/v1"\n',
encoding="utf-8",
)
assert pd.warn_codex_provider_port_change(config, 8787) == 9200
err = capsys.readouterr().err
assert "9200" in err and "8787" in err and "--port 9200" in err
def test_silent_when_same_port_or_absent(self, tmp_path: Path, capsys) -> None:
config = tmp_path / "config.toml"
assert pd.warn_codex_provider_port_change(config, 8787) is None
config.write_text(
'[model_providers.headroom]\nbase_url = "http://127.0.0.1:8787/v1"\n',
encoding="utf-8",
)
assert pd.warn_codex_provider_port_change(config, 8787) is None
assert capsys.readouterr().err == ""
def test_init_provider_write_warns(self, tmp_path: Path, capsys, monkeypatch) -> None:
monkeypatch.setattr(init_mod, "retag_to_headroom", lambda _path: None)
config = tmp_path / "config.toml"
config.write_text(
'[model_providers.headroom]\nbase_url = "http://127.0.0.1:9200/v1"\n',
encoding="utf-8",
)
init_mod._ensure_codex_provider(config, 8787)
assert "port 9200" in capsys.readouterr().err
assert 'base_url = "http://127.0.0.1:8787/v1"' in config.read_text(encoding="utf-8")
def test_init_provider_preserves_user_options_on_repoint(self, tmp_path, monkeypatch):
import tomllib
monkeypatch.setattr(init_mod, "retag_to_headroom", lambda _path: None)
config = tmp_path / "config.toml"
config.write_text(
"[model_providers.headroom]\n"
'base_url = "http://127.0.0.1:9200/v1"\n'
"request_max_retries = 7\n"
'[profiles.work]\nmodel_provider = "custom"\n',
encoding="utf-8",
)
for port in (8787, 9500):
init_mod._ensure_codex_provider(config, port)
parsed = tomllib.loads(config.read_text(encoding="utf-8"))
provider = parsed["model_providers"]["headroom"]
assert provider["base_url"] == f"http://127.0.0.1:{port}/v1"
assert provider["request_max_retries"] == 7
assert parsed["profiles"]["work"]["model_provider"] == "custom"
class TestInitPortResolution:
def _ctx(self, args: list[str]) -> click.Context:
group = main.commands["init"]
return group.make_context("init", list(args), resilient_parsing=False)
def test_explicit_port_wins(self, monkeypatch) -> None:
monkeypatch.setattr(init_mod, "reconcile_default_port", lambda p, **k: 1)
ctx = self._ctx(["--port", "9500"])
assert init_mod._resolve_init_port(ctx, 9500) == 9500
def test_env_port_used_when_no_flag(self, monkeypatch) -> None:
monkeypatch.setattr(init_mod, "reconcile_default_port", lambda p, **k: 1)
monkeypatch.setenv("HEADROOM_PORT", "9400")
ctx = self._ctx([])
assert init_mod._resolve_init_port(ctx, 8787) == 9400
def test_default_reconciles_with_live_proxy(self, monkeypatch) -> None:
monkeypatch.setattr(init_mod, "reconcile_default_port", lambda p, **k: 9200)
ctx = self._ctx([])
assert init_mod._resolve_init_port(ctx, 8787) == 9200
def test_hook_subcommand_skips_discovery(self, monkeypatch) -> None:
def fail(*a: Any, **k: Any) -> int:
raise AssertionError("hook must not run discovery")
monkeypatch.setattr(init_mod, "reconcile_default_port", fail)
ctx = self._ctx([])
ctx.invoked_subcommand = "hook"
assert init_mod._resolve_init_port(ctx, 8787) == 8787
# ---------------------------------------------------------------------------
# 3. init hook ensure alignment warning
# ---------------------------------------------------------------------------
class TestHookAlignment:
@pytest.fixture
def claude_settings(self, home: Path, monkeypatch) -> Path:
path = home / ".claude" / "settings.json"
path.parent.mkdir(parents=True)
monkeypatch.setattr(init_mod, "claude_settings_path", lambda: path)
monkeypatch.setattr(init_mod, "load_manifest", lambda profile: _manifest(profile, 8787))
monkeypatch.setattr(init_mod, "_ensure_profile_running", lambda profile: None)
return path
def _route_claude(self, path: Path, port: int) -> None:
path.write_text(
json.dumps({"env": {"ANTHROPIC_BASE_URL": f"http://127.0.0.1:{port}"}}),
encoding="utf-8",
)
def test_aligned_returns_none(self, claude_settings: Path) -> None:
self._route_claude(claude_settings, 8787)
assert init_mod.alignment_warning("claude", "init-user", probe=lambda p: True) is None
def test_mismatch_to_dead_port_suggests_managed_port(self, claude_settings: Path) -> None:
self._route_claude(claude_settings, 9200)
message = init_mod.alignment_warning("claude", "init-user", probe=lambda p: False)
assert message is not None
assert "9200" in message and "8787" in message
assert "headroom init -g --port 8787 claude" in message
def test_mismatch_to_live_port_suggests_live_port(self, claude_settings: Path) -> None:
self._route_claude(claude_settings, 9200)
message = init_mod.alignment_warning("claude", "init-user", probe=lambda p: p == 9200)
assert message is not None
assert "headroom init -g --port 9200 claude" in message
def test_codex_mismatch_uses_codex_home(self, home: Path, tmp_path: Path, monkeypatch) -> None:
custom = tmp_path / "custom-codex"
custom.mkdir()
(custom / "config.toml").write_text(
'model_provider = "headroom"\n[model_providers.headroom]\n'
'base_url = "http://127.0.0.1:9200/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 "--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(
main,
[
"init",
"hook",
"ensure",
"--profile",
"init-user",
"--marker",
"headroom-init-claude",
],
input=json.dumps({"hook_event_name": "SessionStart"}),
)
assert result.exit_code == 0, result.output
payload = json.loads(result.output.strip().splitlines()[-1])
assert "9200" in payload["systemMessage"]
assert payload["hookSpecificOutput"]["hookEventName"] == "SessionStart"
assert payload["hookSpecificOutput"]["additionalContext"] == payload["systemMessage"]
def test_pre_tool_use_stays_silent(self, claude_settings: Path) -> None:
self._route_claude(claude_settings, 9200)
result = CliRunner().invoke(
main,
[
"init",
"hook",
"ensure",
"--profile",
"init-user",
"--marker",
"headroom-init-claude",
],
input=json.dumps({"hook_event_name": "PreToolUse"}),
)
assert result.exit_code == 0
assert result.output.strip() == ""
def test_never_raises(self, claude_settings: Path, monkeypatch) -> None:
def boom(*a: Any, **k: Any) -> str:
raise RuntimeError("broken")
monkeypatch.setattr(init_mod, "alignment_warning", boom)
result = CliRunner().invoke(
main,
["init", "hook", "ensure", "--profile", "init-user", "--marker", "headroom-init-codex"],
input=json.dumps({"hook_event_name": "SessionStart"}),
)
assert result.exit_code == 0
assert result.output.strip() == ""
# ---------------------------------------------------------------------------
# 4. Doctor: readiness, hooks, live proxy elsewhere
# ---------------------------------------------------------------------------
class TestDoctorAdditions:
def test_readiness(self) -> None:
live = {"service": "headroom-proxy"}
base = "http://127.0.0.1:8787"
assert doctor_mod.check_proxy_readiness(None, None, base).status == doctor_mod.SKIP
assert doctor_mod.check_proxy_readiness(live, None, base).status == doctor_mod.WARN
assert (
doctor_mod.check_proxy_readiness(live, {"ready": True}, base).status == doctor_mod.PASS
)
def _hooks_file(self, path: Path, command: str) -> None:
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(
json.dumps(
{
"hooks": {
"SessionStart": [
{
"matcher": "startup",
"hooks": [{"type": "command", "command": command}],
}
]
}
}
),
encoding="utf-8",
)
def test_hooks_present(self, tmp_path: Path) -> None:
exe = tmp_path / "headroom-bin"
exe.write_text("", encoding="utf-8")
hooks = tmp_path / "hooks.json"
self._hooks_file(hooks, f"{exe.as_posix()} init hook ensure --marker headroom-init-codex")
result = doctor_mod.check_installed_hooks(
[("codex", "user", hooks, "headroom init -g codex")]
)
assert result.status == doctor_mod.PASS, result
def test_hooks_missing(self, tmp_path: Path) -> None:
result = doctor_mod.check_installed_hooks(
[("claude", "user", tmp_path / "settings.json", "headroom init -g claude")]
)
assert result.status == doctor_mod.WARN
assert "headroom init -g claude" in (result.hint or "")
def test_hook_program_missing(self, tmp_path: Path) -> None:
hooks = tmp_path / "settings.json"
gone = (tmp_path / "gone" / "headroom").as_posix()
self._hooks_file(hooks, f"{gone} init hook ensure --marker headroom-init-claude")
result = doctor_mod.check_installed_hooks(
[("claude", "user", hooks, "headroom init -g claude")]
)
assert result.status == doctor_mod.WARN
assert "not found" in result.summary
def test_no_init_means_skip(self) -> None:
assert doctor_mod.check_installed_hooks([]).status == doctor_mod.SKIP
def test_expected_hooks_from_manifests(self, home: Path, tmp_path: Path, monkeypatch) -> None:
custom = tmp_path / "custom-codex"
monkeypatch.setenv("CODEX_HOME", str(custom))
monkeypatch.setattr(doctor_mod, "claude_settings_path", lambda: home / "settings.json")
local = init_mod._local_profile(Path.cwd())
expected = doctor_mod.expected_init_hooks(
[
_manifest("init-user", 9200, ["claude", "codex"]),
_manifest(local, 8787, ["claude"]),
_manifest("someone-else", 8787, ["claude"]),
],
cwd=Path.cwd(),
)
assert ("codex", "user", custom / "hooks.json", "headroom init -g --port 9200 codex") in (
expected
)
assert (
"claude",
"project",
Path.cwd() / ".claude" / "settings.local.json",
"headroom init claude",
) in expected
assert len(expected) == 3
def test_doctor_names_live_proxy_on_other_port(self, home: Path, monkeypatch) -> None:
def fake_probe(url: str, timeout: float = 2.0) -> dict[str, Any] | None:
if url == "http://127.0.0.1:9200/livez":
return {"service": "headroom-proxy", "alive": True, "version": "1"}
return None
monkeypatch.setattr(doctor_mod, "probe_json", fake_probe)
monkeypatch.setattr(doctor_mod, "list_manifests", lambda: [_manifest("prod", 9200)])
monkeypatch.setattr(doctor_mod, "check_deployments", lambda manifests: None)
monkeypatch.setattr(doctor_mod, "claude_settings_path", lambda: home / "settings.json")
monkeypatch.setattr(doctor_mod, "savings_path", lambda: home / "savings.json")
result = CliRunner().invoke(main, ["doctor", "--json", "--port", "8787"])
payload = json.loads(result.output)
assert payload["exit_code"] == 2 # still a failure at the probed port
proxy = next(c for c in payload["checks"] if c["name"] == "proxy")
assert "port 9200" in proxy["summary"]
assert "headroom doctor --port 9200" in proxy["hint"]
def test_doctor_names_live_proxy_from_client_marker(
self, home: Path, tmp_path: Path, monkeypatch
) -> None:
marker = tmp_path / "workspace" / "clients" / "8788" / "4242.json"
marker.parent.mkdir(parents=True)
marker.write_text(json.dumps({"pid": 4242, "started_at": 100.0}), encoding="utf-8")
monkeypatch.setattr(pd, "pid_alive", lambda pid: pid == 4242)
def fake_probe(url: str, timeout: float = 2.0) -> dict[str, Any] | None:
if url == "http://127.0.0.1:8788/livez":
return {"service": "headroom-proxy", "alive": True, "version": "1"}
return None
monkeypatch.setattr(doctor_mod, "probe_json", fake_probe)
monkeypatch.setattr(doctor_mod, "list_manifests", lambda: [])
monkeypatch.setattr(doctor_mod, "check_deployments", lambda manifests: None)
monkeypatch.setattr(doctor_mod, "claude_settings_path", lambda: home / "settings.json")
monkeypatch.setattr(doctor_mod, "savings_path", lambda: home / "savings.json")
result = CliRunner().invoke(main, ["doctor", "--json"])
payload = json.loads(result.output)
assert payload["port"] == 8787
proxy = next(c for c in payload["checks"] if c["name"] == "proxy")
assert "port 8788" in proxy["summary"]
assert "headroom doctor --port 8788" in proxy["hint"]
# ---------------------------------------------------------------------------
# wrap selfheal: warn (never repoint) when a live proxy exists elsewhere
# ---------------------------------------------------------------------------
class TestSelfhealWarning:
def test_warns_with_live_port(self, monkeypatch, capsys) -> None:
monkeypatch.setattr(pd, "find_live_proxy_elsewhere", lambda requested, **k: 9200)
wrap_mod._warn_live_proxy_after_selfheal({"port": 8787})
err = capsys.readouterr().err
assert "headroom wrap claude --port 9200" in err
def test_silent_without_live_proxy(self, monkeypatch, capsys) -> None:
monkeypatch.setattr(pd, "find_live_proxy_elsewhere", lambda requested, **k: None)
wrap_mod._warn_live_proxy_after_selfheal({"port": 8787})
assert capsys.readouterr().err == ""
def test_init_adopted_provider_survives_unwrap(tmp_path, monkeypatch):
import tomllib
monkeypatch.setattr(init_mod, "retag_to_headroom", lambda _path: None)
config = tmp_path / "config.toml"
original = '[model_providers.headroom]\nbase_url = "http://127.0.0.1:9200/v1"\nrequest_max_retries = 7\n'
config.write_text(original, encoding="utf-8")
for port in (8787, 9500):
init_mod._ensure_codex_provider(config, port)
restored = init_mod._strip_codex_init_block(config.read_text(encoding="utf-8"))
assert tomllib.loads(restored) == tomllib.loads(original)
def test_init_replaces_auth_when_credentials_change(tmp_path, monkeypatch):
import json
import tomllib
monkeypatch.setattr(init_mod, "retag_to_headroom", lambda _path: None)
monkeypatch.setattr(init_mod, "codex_home_dir", lambda: tmp_path)
auth = tmp_path / "auth.json"
config = tmp_path / "config.toml"
for payload, oauth in (
(
{
"auth_mode": "chatgpt",
"tokens": {"access_token": "test-oauth", "account_id": "test-account"},
},
True,
),
({"OPENAI_API_KEY": "test-key"}, False),
(
{
"auth_mode": "chatgpt",
"tokens": {"access_token": "test-oauth", "account_id": "test-account"},
},
True,
),
):
auth.write_text(json.dumps(payload), encoding="utf-8")
init_mod._ensure_codex_provider(config, 8787)
provider = tomllib.loads(config.read_text(encoding="utf-8"))["model_providers"]["headroom"]
assert provider.get("requires_openai_auth", False) is oauth
assert ("auth" in provider) is not oauth