Files
headroom/tests/test_cli/test_wrap_helpers.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

1276 lines
48 KiB
Python

"""Direct unit tests for the shared wrap-subcommand helpers.
These helpers (`_print_wrap_banner`, `_run_proxy_only_watcher`) were
extracted to remove ~150 LOC of
copy-pasted scaffolding across the wrap subcommands (cursor / cline /
continue / goose / openhands). The wrap-*.py subcommand tests exercise
them indirectly; these tests pin the contract directly so a future
refactor that breaks one of these helpers fails *here* — at the helper
unit boundary — instead of in five different subcommand suites at
once with confusing diffs.
"""
from __future__ import annotations
import errno
import json
import os
import signal
from contextlib import contextmanager
from pathlib import Path
from types import SimpleNamespace
from typing import Any
import click
import pytest
from click.testing import CliRunner
from headroom import paths as paths_mod
from headroom.cli import wrap as wrap_mod
from headroom.cli.main import main
from headroom.memory.storage_router import ProjectResolver, RequestContext
from headroom.proxy.handlers.anthropic import AnthropicHandlerMixin
# ---------------------------------------------------------------------------
# _print_wrap_banner — centering math + box drawing.
# ---------------------------------------------------------------------------
@pytest.fixture
def runner() -> CliRunner:
return CliRunner()
def _run_in_click_context(fn) -> str: # type: ignore[no-untyped-def]
"""Invoke `fn` inside a Click `runner.invoke` so `click.echo` output is captured."""
runner = CliRunner()
@click.command()
def _cmd() -> None:
fn()
result = runner.invoke(_cmd)
assert result.exit_code == 0, result.output
return result.output
@pytest.mark.parametrize(
"agent",
["cline", "cursor", "continue", "goose", "openhands", "x", "a-very-long-agent-name"],
)
def test_print_wrap_banner_box_is_inner_width_chars_wide(agent: str) -> None:
"""The banner's horizontal rule should always be 47 chars between the `║` corners."""
output = _run_in_click_context(lambda: wrap_mod._print_wrap_banner(agent))
lines = [line for line in output.splitlines() if line.strip()]
assert len(lines) == 3, f"banner should be 3 non-empty lines; got {lines!r}"
top, title_line, bottom = lines
# Top and bottom are the `╔════...╗` rules with 47 equals signs between the corners.
assert top.endswith("╗")
assert bottom.endswith("╝")
assert top.count("═") == wrap_mod._WRAP_BANNER_INNER_WIDTH
assert bottom.count("═") == wrap_mod._WRAP_BANNER_INNER_WIDTH
# The middle line has the centered title.
assert title_line.startswith(" ║")
assert title_line.endswith("║")
assert f"HEADROOM WRAP: {agent.upper()}" in title_line
def test_print_wrap_banner_title_is_centered_or_near_centered() -> None:
"""Centering: pad_left and pad_right may differ by at most 1 when total padding is odd."""
output = _run_in_click_context(lambda: wrap_mod._print_wrap_banner("cline"))
lines = [line for line in output.splitlines() if line.strip()]
title_line = lines[1]
# Strip the leading " ║" and trailing "║" so we can measure spaces.
inner = title_line[3:-1]
assert len(inner) == wrap_mod._WRAP_BANNER_INNER_WIDTH
title = "HEADROOM WRAP: CLINE"
pad_left = len(inner) - len(inner.lstrip(" "))
pad_right = len(inner) - len(inner.rstrip(" "))
assert inner.strip() == title
assert abs(pad_left - pad_right) <= 1, (
f"banner not centered: pad_left={pad_left}, pad_right={pad_right}"
)
# ---------------------------------------------------------------------------
# wrap claude argument passthrough.
# ---------------------------------------------------------------------------
def test_wrap_claude_allows_claude_print_short_flag_in_passthrough_args() -> None:
"""Claude owns -p/--print; wrap claude must not parse it as --port."""
result = CliRunner().invoke(
main,
["wrap", "claude", "--prepare-only", "-p", "Say only: hello"],
)
assert result.exit_code == 0, result.output
# ---------------------------------------------------------------------------
# _apply_1m_to_claude_args — add the [1m] suffix to an explicit pass-through
# --model so it survives Claude Code's CLI-over-env precedence (#2915).
# ---------------------------------------------------------------------------
def test_apply_1m_rewrites_model_flag_value() -> None:
args, rewritten = wrap_mod._apply_1m_to_claude_args(("--model", "opusplan"))
assert args == ("--model", "opusplan[1m]")
assert rewritten == "opusplan[1m]"
def test_apply_1m_rewrites_equals_model_flag() -> None:
args, rewritten = wrap_mod._apply_1m_to_claude_args(("--model=opusplan",))
assert args == ("--model=opusplan[1m]",)
assert rewritten == "opusplan[1m]"
def test_apply_1m_is_idempotent_on_already_suffixed_model() -> None:
args, rewritten = wrap_mod._apply_1m_to_claude_args(("--model", "opusplan[1m]"))
assert args == ("--model", "opusplan[1m]")
assert rewritten == "opusplan[1m]"
def test_apply_1m_noop_without_model_flag() -> None:
original = ("--permission-mode", "auto", "--resume")
args, rewritten = wrap_mod._apply_1m_to_claude_args(original)
assert args == original
assert rewritten is None
# ---------------------------------------------------------------------------
# _run_proxy_only_watcher — must print banner, call setup callback, install
# signal handlers, and clean up. Heavily mocked since the real watcher
# blocks on `time.sleep` indefinitely.
# ---------------------------------------------------------------------------
def test_run_proxy_only_watcher_calls_setup_lines_callback(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""The print_setup_lines callback runs after the proxy is ready."""
# Fake proxy: a dummy object whose `.poll()` returns 0 after first iteration
# so the watcher exits cleanly via the "proxy exited unexpectedly" branch.
class _FakeProc:
def __init__(self) -> None:
self._polls = 0
def poll(self) -> int | None:
self._polls += 1
return 0 if self._polls > 1 else None
fake_proc = _FakeProc()
callback_calls: list[None] = []
def fake_setup(_port: int) -> None:
callback_calls.append(None)
monkeypatch.setattr(wrap_mod, "_ensure_proxy", lambda *a, **kw: (fake_proc, 8787))
# Replace time.sleep with a no-op so the loop spins quickly.
monkeypatch.setattr(wrap_mod.time, "sleep", lambda _s: None)
# Replace _make_cleanup to avoid side-effects on real ports/files.
monkeypatch.setattr(wrap_mod, "_make_cleanup", lambda holder, port: lambda *a, **kw: None)
# Avoid touching real signal handlers in the test process.
monkeypatch.setattr(wrap_mod.signal, "signal", lambda *a, **kw: None)
runner = CliRunner()
@click.command()
def _cmd() -> None:
wrap_mod._run_proxy_only_watcher(
agent_label="cline",
port=8787,
no_proxy=False,
learn=False,
memory=False,
agent_type="cline",
print_setup_lines=fake_setup,
)
inv = runner.invoke(_cmd)
# The watcher exits 1 when the proxy dies (our _FakeProc returns 0 on poll #2).
assert inv.exit_code == 1
assert callback_calls == [None]
# Banner is part of the helper's contract.
assert "HEADROOM WRAP: CLINE" in inv.output
# The "proxy exited unexpectedly" message is the documented exit branch.
assert "Proxy process exited unexpectedly." in inv.output
def test_run_proxy_only_watcher_keyboardinterrupt_shuts_down_cleanly(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""Ctrl-C during the watcher loop prints `Shutting down...` and exits 0."""
class _FakeProc:
def poll(self) -> int | None:
return None # Proxy is healthy; loop would run forever.
sleep_calls = {"n": 0}
def raising_sleep(_s: float) -> None:
sleep_calls["n"] += 1
if sleep_calls["n"] >= 1:
raise KeyboardInterrupt
monkeypatch.setattr(wrap_mod, "_ensure_proxy", lambda *a, **kw: (_FakeProc(), 8787))
monkeypatch.setattr(wrap_mod.time, "sleep", raising_sleep)
monkeypatch.setattr(wrap_mod, "_make_cleanup", lambda holder, port: lambda *a, **kw: None)
monkeypatch.setattr(wrap_mod.signal, "signal", lambda *a, **kw: None)
runner = CliRunner()
@click.command()
def _cmd() -> None:
wrap_mod._run_proxy_only_watcher(
agent_label="cursor",
port=8787,
no_proxy=False,
learn=False,
memory=False,
agent_type="cursor",
print_setup_lines=lambda _port: None,
)
inv = runner.invoke(_cmd)
assert inv.exit_code == 0, inv.output
assert "Shutting down..." in inv.output
def test_run_proxy_only_watcher_signal_handler_uses_clean_shutdown(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""Windows console stop handlers must use the clean shutdown path."""
handlers: dict[int, Any] = {}
cleanup_calls = {"n": 0}
class _FakeProc:
def poll(self) -> None:
return None
def capture_handler(sig: int, handler: Any) -> None:
handlers[sig] = handler
def trigger_sigint(_seconds: float) -> None:
handlers[signal.SIGINT](signal.SIGINT, None)
def cleanup(*_args: Any) -> None:
cleanup_calls["n"] += 1
monkeypatch.setattr(wrap_mod, "_ensure_proxy", lambda *a, **kw: (_FakeProc(), 8787))
monkeypatch.setattr(wrap_mod.time, "sleep", trigger_sigint)
monkeypatch.setattr(wrap_mod, "_make_cleanup", lambda holder, port: cleanup)
monkeypatch.setattr(wrap_mod.signal, "signal", capture_handler)
monkeypatch.setattr(wrap_mod.sys, "platform", "win32")
sigbreak = 999
monkeypatch.setattr(wrap_mod.signal, "SIGBREAK", sigbreak, raising=False)
runner = CliRunner()
@click.command()
def _cmd() -> None:
wrap_mod._run_proxy_only_watcher(
agent_label="vscode copilot",
port=8787,
no_proxy=False,
learn=False,
memory=False,
agent_type="copilot",
print_setup_lines=lambda _port: None,
)
inv = runner.invoke(_cmd)
assert inv.exit_code == 0, inv.output
assert "Shutting down..." in inv.output
assert "Proxy process exited unexpectedly" not in inv.output
assert sigbreak in handlers
assert cleanup_calls["n"] >= 2 # signal handler plus finally (idempotent)
def test_run_proxy_only_watcher_unexpected_exception_returns_exit_1(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""Unexpected exceptions in the body are caught and converted to SystemExit(1)."""
def boom(*a: Any, **kw: Any) -> None:
raise RuntimeError("boom")
monkeypatch.setattr(wrap_mod, "_ensure_proxy", boom)
monkeypatch.setattr(wrap_mod, "_make_cleanup", lambda holder, port: lambda *a, **kw: None)
monkeypatch.setattr(wrap_mod.signal, "signal", lambda *a, **kw: None)
runner = CliRunner()
@click.command()
def _cmd() -> None:
wrap_mod._run_proxy_only_watcher(
agent_label="cline",
port=8787,
no_proxy=False,
learn=False,
memory=False,
agent_type="cline",
print_setup_lines=lambda _port: None,
)
inv = runner.invoke(_cmd)
assert inv.exit_code == 1
assert "Error: boom" in inv.output
def test_run_proxy_only_watcher_calls_cleanup_on_finally(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""Cleanup callable is invoked in the `finally` block regardless of exit path."""
cleanup_calls = {"n": 0}
def fake_cleanup(*a: Any, **kw: Any) -> None:
cleanup_calls["n"] += 1
def boom(*a: Any, **kw: Any) -> None:
raise RuntimeError("boom")
monkeypatch.setattr(wrap_mod, "_ensure_proxy", boom)
monkeypatch.setattr(wrap_mod, "_make_cleanup", lambda holder, port: fake_cleanup)
monkeypatch.setattr(wrap_mod.signal, "signal", lambda *a, **kw: None)
runner = CliRunner()
@click.command()
def _cmd() -> None:
wrap_mod._run_proxy_only_watcher(
agent_label="cline",
port=8787,
no_proxy=False,
learn=False,
memory=False,
agent_type="cline",
print_setup_lines=lambda _port: None,
)
inv = runner.invoke(_cmd)
assert inv.exit_code == 1
assert cleanup_calls["n"] >= 1, "cleanup must run via the finally block"
# ---------------------------------------------------------------------------
# _project_name_from_cwd / _apply_project_header_env — per-project savings
# header injection for `headroom wrap claude` (issue: per-project savings).
# ---------------------------------------------------------------------------
class TestApplyProjectHeaderEnv:
"""X-Headroom-Project injection into ANTHROPIC_CUSTOM_HEADERS."""
def test_sets_header_from_cwd_basename(
self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
project_dir = tmp_path / "my-project"
project_dir.mkdir()
monkeypatch.chdir(project_dir)
env: dict[str, str] = {}
wrap_mod._apply_project_header_env(env)
assert env["ANTHROPIC_CUSTOM_HEADERS"].splitlines() == [
"X-Headroom-Project: my-project",
f"X-Headroom-Cwd: {wrap_mod._project_cwd_from_cwd()}",
]
def test_wrap_project_header_resolves_ccr_workspace(
self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
project_dir = tmp_path / "my-project"
project_dir.mkdir()
monkeypatch.chdir(project_dir)
env: dict[str, str] = {}
wrap_mod._apply_project_header_env(env)
headers = {
name.strip().lower(): value.strip()
for name, value in (
line.split(":", 1) for line in env["ANTHROPIC_CUSTOM_HEADERS"].splitlines()
)
}
key, label = AnthropicHandlerMixin()._resolve_ccr_workspace(
SimpleNamespace(headers=headers), {}
)
assert key.startswith("my-project-")
assert label == "my-project"
def test_wrap_same_basename_projects_get_distinct_memory_and_ccr_keys(
self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
"""The wrapped headers keep same-named projects in separate stores."""
first = tmp_path / "one" / "api"
second = tmp_path / "two" / "api"
first.mkdir(parents=True)
second.mkdir(parents=True)
def wrapped_headers(project_dir: Path) -> dict[str, str]:
monkeypatch.chdir(project_dir)
env = {"ANTHROPIC_CUSTOM_HEADERS": "X-Headroom-Project: shared"}
wrap_mod._apply_project_header_env(env)
return {
name.strip().lower(): value.strip()
for name, value in (
line.split(":", 1) for line in env["ANTHROPIC_CUSTOM_HEADERS"].splitlines()
)
}
headers_a = wrapped_headers(first)
headers_b = wrapped_headers(second)
assert headers_a["x-headroom-project"] == headers_b["x-headroom-project"] == "shared"
assert headers_a["x-headroom-cwd"] != headers_b["x-headroom-cwd"]
resolver = ProjectResolver()
memory_a = resolver.resolve(
RequestContext(headers=headers_a, system_prompt="", base_user_id="")
)
memory_b = resolver.resolve(
RequestContext(headers=headers_b, system_prompt="", base_user_id="")
)
assert memory_a is not None and memory_b is not None
assert memory_a[0] != memory_b[0]
ccr_a = AnthropicHandlerMixin()._resolve_ccr_workspace(
SimpleNamespace(headers=headers_a), {}
)
ccr_b = AnthropicHandlerMixin()._resolve_ccr_workspace(
SimpleNamespace(headers=headers_b), {}
)
assert ccr_a[0] == memory_a[0]
assert ccr_b[0] == memory_b[0]
assert ccr_a[0] != ccr_b[0]
def test_appends_to_existing_custom_headers(
self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
project_dir = tmp_path / "proj"
project_dir.mkdir()
monkeypatch.chdir(project_dir)
env = {"ANTHROPIC_CUSTOM_HEADERS": "X-Custom-Trace: abc123"}
wrap_mod._apply_project_header_env(env)
# User header preserved verbatim, ours appended on a new line.
assert env["ANTHROPIC_CUSTOM_HEADERS"].splitlines() == [
"X-Custom-Trace: abc123",
"X-Headroom-Project: proj",
f"X-Headroom-Cwd: {wrap_mod._project_cwd_from_cwd()}",
]
@pytest.mark.parametrize(
"user_value",
[
"X-Headroom-Project: their-name",
"x-headroom-project: their-name",
"X-HEADROOM-PROJECT: their-name",
"X-Other: 1\nx-Headroom-Project: their-name",
],
)
def test_existing_project_header_wins_case_insensitive(
self,
monkeypatch: pytest.MonkeyPatch,
tmp_path: Path,
user_value: str,
) -> None:
project_dir = tmp_path / "proj"
project_dir.mkdir()
monkeypatch.chdir(project_dir)
env = {"ANTHROPIC_CUSTOM_HEADERS": user_value}
wrap_mod._apply_project_header_env(env)
# The user label remains untouched; the missing routing identity is appended.
assert env["ANTHROPIC_CUSTOM_HEADERS"] == (
f"{user_value}\nX-Headroom-Cwd: {wrap_mod._project_cwd_from_cwd()}"
)
@pytest.mark.parametrize(
"user_value",
[
"X-Headroom-Project-Id: other",
"X-Trace: mentions x-headroom-project in the value",
],
)
def test_similar_header_names_do_not_suppress_injection(
self,
monkeypatch: pytest.MonkeyPatch,
tmp_path: Path,
user_value: str,
) -> None:
project_dir = tmp_path / "proj"
project_dir.mkdir()
monkeypatch.chdir(project_dir)
env = {"ANTHROPIC_CUSTOM_HEADERS": user_value}
wrap_mod._apply_project_header_env(env)
# Only an exact header-name match counts as a user override.
assert env["ANTHROPIC_CUSTOM_HEADERS"] == (
f"{user_value}\nX-Headroom-Project: proj\n"
f"X-Headroom-Cwd: {wrap_mod._project_cwd_from_cwd()}"
)
def test_empty_cwd_name_sets_nothing(self, monkeypatch: pytest.MonkeyPatch) -> None:
"""A degenerate cwd (e.g. filesystem root → empty basename) is a no-op."""
monkeypatch.setattr(wrap_mod.Path, "cwd", classmethod(lambda cls: Path("/")))
env: dict[str, str] = {}
wrap_mod._apply_project_header_env(env)
assert "ANTHROPIC_CUSTOM_HEADERS" not in env
def test_whitespace_only_cwd_name_sets_nothing(self, monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.setattr(wrap_mod.Path, "cwd", classmethod(lambda cls: Path("/tmp/ ")))
env: dict[str, str] = {}
wrap_mod._apply_project_header_env(env)
assert "ANTHROPIC_CUSTOM_HEADERS" not in env
def test_project_name_from_cwd_returns_basename(
self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
project_dir = tmp_path / "vibe-headroom"
project_dir.mkdir()
monkeypatch.chdir(project_dir)
assert wrap_mod._project_name_from_cwd() == "vibe-headroom"
def test_non_ascii_cwd_name_is_percent_encoded(
self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
"""Non-ASCII directory names must be percent-encoded for HTTP headers."""
project_dir = tmp_path / "第二大脑共享"
project_dir.mkdir()
monkeypatch.chdir(project_dir)
result = wrap_mod._project_name_from_cwd()
assert result is not None
# Must be pure ASCII so it's safe in an HTTP header value.
result.encode("ascii")
# Must round-trip back to the original name via unquote.
import urllib.parse
assert urllib.parse.unquote(result) == "第二大脑共享"
def test_project_cwd_is_percent_encoded_and_round_trips(
self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
project_dir = tmp_path / "project with space-中文"
project_dir.mkdir()
monkeypatch.chdir(project_dir)
result = wrap_mod._project_cwd_from_cwd()
assert result is not None
result.encode("ascii")
import urllib.parse
assert urllib.parse.unquote(result) == str(project_dir.resolve())
def test_existing_cwd_header_wins_case_insensitive(
self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
project_dir = tmp_path / "proj"
project_dir.mkdir()
monkeypatch.chdir(project_dir)
user_value = "X-Headroom-Project: their-name\nx-headroom-cwd: /already/trusted"
env = {"ANTHROPIC_CUSTOM_HEADERS": user_value}
wrap_mod._apply_project_header_env(env)
assert env["ANTHROPIC_CUSTOM_HEADERS"] == user_value
def test_non_ascii_cwd_header_is_ascii_safe(
self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
"""X-Headroom-Project header value must be ASCII when cwd has non-ASCII chars."""
project_dir = tmp_path / "test-中文-项目"
project_dir.mkdir()
monkeypatch.chdir(project_dir)
env: dict[str, str] = {}
wrap_mod._apply_project_header_env(env)
header_value = env["ANTHROPIC_CUSTOM_HEADERS"]
assert header_value.startswith("X-Headroom-Project: ")
assert "X-Headroom-Cwd: " in header_value
header_value.encode("ascii") # raises UnicodeEncodeError if non-ASCII
# ---------------------------------------------------------------------------
# Proxy-client reference counting
#
# The shared proxy must only be torn down by its owner once *no* other live
# wrap clients remain. Clients carry the proxy URL in ANTHROPIC_BASE_URL /
# OPENAI_BASE_URL (env, not argv), so the old `pgrep -f "127.0.0.1:<port>"`
# guard could neither see real clients nor reject unrelated processes that
# merely had the address in their command line. These tests pin the new
# marker-file contract: a per-PID file under paths.proxy_clients_dir(port).
# ---------------------------------------------------------------------------
class _FakeProxyProc:
"""Minimal stand-in for the proxy ``subprocess.Popen`` handle."""
def __init__(self) -> None:
self.terminated = False
self.killed = False
def poll(self) -> int | None:
return None # alive
def terminate(self) -> None:
self.terminated = True
def wait(self, timeout: float | None = None) -> int:
return 0
def kill(self) -> None:
self.killed = True
def test_start_proxy_strips_ambient_worker_configuration(
monkeypatch: pytest.MonkeyPatch,
tmp_path: Path,
) -> None:
monkeypatch.setenv("HEADROOM_WORKERS", "4")
monkeypatch.setenv("HEADROOM_PROXY_CONFIG_JSON", '{"port": 9999}')
monkeypatch.setenv("CLAUDE_CODE_USE_VERTEX", "1")
captured: dict[str, object] = {}
proc = _FakeProxyProc()
def fake_popen(command: list[str], **kwargs: object) -> _FakeProxyProc:
captured["command"] = command
captured["env"] = kwargs["env"]
return proc
monkeypatch.setattr(wrap_mod.subprocess, "Popen", fake_popen)
monkeypatch.setattr(wrap_mod, "_check_proxy", lambda port: True)
monkeypatch.setattr(wrap_mod, "_get_log_path", lambda port=None: tmp_path / "proxy.log")
monkeypatch.setattr(
wrap_mod,
"_get_proxy_stdio_log_path",
lambda port=None: tmp_path / "proxy-stdio.log",
)
monkeypatch.setattr(wrap_mod.time, "sleep", lambda seconds: None)
assert wrap_mod._start_proxy(8787) is proc
env = captured["env"]
assert isinstance(env, dict)
assert "HEADROOM_WORKERS" not in env
assert "HEADROOM_PROXY_CONFIG_JSON" not in env
assert env["HEADROOM_HTTP2"] == "false"
assert captured["command"][-2:] == ["--workers", "1"]
def test_start_proxy_timeout_kills_failed_new_process(
monkeypatch: pytest.MonkeyPatch,
tmp_path: Path,
) -> None:
proc = _FakeProxyProc()
monkeypatch.setattr(wrap_mod.subprocess, "Popen", lambda *args, **kwargs: proc)
monkeypatch.setattr(wrap_mod, "_check_proxy", lambda port: False)
monkeypatch.setattr(wrap_mod, "_get_log_path", lambda port=None: tmp_path / "proxy.log")
monkeypatch.setattr(
wrap_mod,
"_get_proxy_stdio_log_path",
lambda port=None: tmp_path / "proxy-stdio.log",
)
monkeypatch.setattr(wrap_mod, "_resolve_wrap_proxy_timeout_seconds", lambda: 1)
monkeypatch.setattr(wrap_mod.time, "sleep", lambda seconds: None)
with pytest.raises(RuntimeError, match="failed to start"):
wrap_mod._start_proxy(8787)
assert proc.killed is True
class TestProxyClientRefCounting:
"""Proxy lifecycle is reference-counted via marker files, not pgrep."""
PORT = 8787
@pytest.fixture
def clients_dir(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
"""Redirect ``paths.proxy_clients_dir`` into a throwaway tmp tree."""
base = tmp_path / "clients"
monkeypatch.setattr(paths_mod, "proxy_clients_dir", lambda port: base / str(port))
return base
def _write_marker(
self,
clients_dir: Path,
pid: int,
*,
identity: tuple[str, float] | None = None,
) -> Path:
marker = clients_dir / str(self.PORT) / f"{pid}.json"
marker.parent.mkdir(parents=True, exist_ok=True)
rec: dict[str, Any] = {"pid": pid, "started_at": 0}
if identity is not None:
rec["start_src"], rec["start_time"] = identity
marker.write_text(json.dumps(rec))
return marker
def test_cleanup_unregisters_marker_without_terminating_proxy(self, clients_dir: Path) -> None:
"""Normal exit transfers final shutdown ownership to the watchdog."""
wrap_mod._register_proxy_client(self.PORT)
proc = _FakeProxyProc()
cleanup = wrap_mod._make_cleanup([proc], self.PORT)
cleanup()
assert proc.terminated is False
assert wrap_mod._live_proxy_clients(self.PORT, exclude_self=False) == []
def test_cleanup_leaves_detached_windows_serving_child_to_watchdog(
self, clients_dir: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""Windows cleanup follows the same marker-only ownership transfer."""
wrap_mod._register_proxy_client(self.PORT)
proc = _FakeProxyProc()
proc.poll = lambda: 0 # type: ignore[method-assign]
stopped: list[int] = []
monkeypatch.setattr(wrap_mod.sys, "platform", "win32")
monkeypatch.setattr(wrap_mod, "_check_proxy", lambda port: port == self.PORT)
monkeypatch.setattr(wrap_mod, "_query_proxy_config", lambda port: {"pid": 123})
monkeypatch.setattr(
wrap_mod,
"_stop_local_proxy_for_unwrap",
lambda port: stopped.append(port) or "stopped",
)
wrap_mod._make_cleanup([proc], self.PORT)()
assert not proc.terminated
assert stopped == []
def test_kill_proxy_uses_taskkill_tree_on_windows(
self, monkeypatch: pytest.MonkeyPatch
) -> None:
"""Windows cleanup must terminate the native launcher's whole tree."""
calls: list[tuple[list[str], dict[str, object]]] = []
checks = iter([True, False])
monkeypatch.setattr(wrap_mod.sys, "platform", "win32")
monkeypatch.setattr(wrap_mod.time, "sleep", lambda _seconds: None)
monkeypatch.setattr(wrap_mod, "_check_proxy", lambda _port: next(checks))
monkeypatch.setattr(
wrap_mod.subprocess,
"run",
lambda command, **kwargs: calls.append((command, kwargs)),
)
assert wrap_mod._kill_proxy_by_pid(456, self.PORT)
assert calls == [
(
["taskkill", "/F", "/T", "/PID", "456"],
{"capture_output": True, "timeout": 10, "check": False},
)
]
def test_cleanup_does_not_probe_or_kill_windows_serving_child(
self, clients_dir: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""The watchdog, not wrapper cleanup, owns normal listener shutdown."""
wrap_mod._register_proxy_client(self.PORT)
proc = _FakeProxyProc()
killed: list[tuple[int, int]] = []
monkeypatch.setattr(wrap_mod.sys, "platform", "win32")
monkeypatch.setattr(wrap_mod, "_check_proxy", lambda port: port == self.PORT)
monkeypatch.setattr(wrap_mod, "_query_proxy_config", lambda port: {"pid": 456})
monkeypatch.setattr(wrap_mod, "_stop_local_proxy_for_unwrap", lambda port: "unidentified")
monkeypatch.setattr(
wrap_mod,
"_kill_proxy_by_pid",
lambda pid, port: killed.append((pid, port)) or True,
)
wrap_mod._make_cleanup([proc], self.PORT)()
assert not proc.terminated
assert killed == []
def test_cleanup_leaves_proxy_running_when_other_client_alive(self, clients_dir: Path) -> None:
"""A second live client (here: the test's parent) keeps the proxy up."""
wrap_mod._register_proxy_client(self.PORT)
other_pid = os.getppid() # alive for the duration of the test run
assert other_pid != os.getpid()
self._write_marker(clients_dir, other_pid)
proc = _FakeProxyProc()
cleanup = wrap_mod._make_cleanup([proc], self.PORT)
cleanup()
assert proc.terminated is False
def test_dead_client_marker_is_pruned_and_not_counted(
self, clients_dir: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""A marker for a dead PID is pruned from disk and never counted."""
dead_pid = 358784
marker = self._write_marker(clients_dir, dead_pid)
monkeypatch.setattr(wrap_mod, "_pid_alive", lambda pid: pid != dead_pid)
live = wrap_mod._live_proxy_clients(self.PORT, exclude_self=True)
assert dead_pid not in live
assert not marker.exists()
def test_dead_client_marker_unlink_failure_is_tolerated(
self,
clients_dir: Path,
monkeypatch: pytest.MonkeyPatch,
) -> None:
dead_pid = 358784
marker = self._write_marker(clients_dir, dead_pid)
monkeypatch.setattr(wrap_mod, "_pid_alive", lambda pid: pid != dead_pid)
def fail_unlink(*args: object, **kwargs: object) -> None:
raise OSError("read-only")
monkeypatch.setattr(Path, "unlink", fail_unlink)
assert wrap_mod._live_proxy_clients(self.PORT, exclude_self=True) == []
assert marker.exists()
def test_reused_pid_with_mismatched_identity_is_pruned(
self, clients_dir: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""A *live* PID that the original client no longer owns is pruned.
Models the PID-reuse orphan path: a wrapper crashed, the OS later
recycled its PID for an unrelated long-lived process. `os.kill(pid, 0)`
succeeds, but the recorded start time no longer matches.
"""
live_pid = os.getppid() # alive, but not the process that "registered"
marker = self._write_marker(clients_dir, live_pid, identity=("psutil", 1000.0))
# The process currently holding that PID started much later → reuse.
monkeypatch.setattr(wrap_mod, "_proc_identity", lambda p: ("psutil", 9000.0))
live = wrap_mod._live_proxy_clients(self.PORT, exclude_self=True)
assert live_pid not in live
assert not marker.exists()
def test_matching_identity_within_tolerance_is_kept(
self, clients_dir: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""Same process (start time within tolerance) is a real client — kept."""
live_pid = os.getppid()
marker = self._write_marker(clients_dir, live_pid, identity=("psutil", 1000.0))
monkeypatch.setattr(wrap_mod, "_proc_identity", lambda p: ("psutil", 1000.4))
live = wrap_mod._live_proxy_clients(self.PORT, exclude_self=True)
assert live_pid in live
assert marker.exists()
def test_identity_check_skipped_when_source_unavailable(
self, clients_dir: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""No reuse protection (e.g. macOS w/o psutil) → fall back to existence."""
live_pid = os.getppid()
self._write_marker(clients_dir, live_pid, identity=("psutil", 1000.0))
# Start time unknowable for the live PID → must not prune a real client.
monkeypatch.setattr(wrap_mod, "_proc_identity", lambda p: None)
live = wrap_mod._live_proxy_clients(self.PORT, exclude_self=True)
assert live_pid in live
def test_non_marker_files_are_ignored(self, clients_dir: Path) -> None:
"""Stray non-numeric / non-json files don't crash or count as clients."""
d = clients_dir / str(self.PORT)
d.mkdir(parents=True, exist_ok=True)
(d / "not-a-pid.json").write_text("{}")
(d / "README.txt").write_text("ignore me")
assert wrap_mod._live_proxy_clients(self.PORT, exclude_self=True) == []
def test_non_dict_marker_is_tolerated(self, clients_dir: Path) -> None:
live_pid = os.getppid()
marker = self._write_marker(clients_dir, live_pid)
marker.write_text("[]", encoding="utf-8")
assert wrap_mod._live_proxy_clients(self.PORT, exclude_self=True) == [live_pid]
def test_cleanup_does_not_shell_out_to_pgrep(
self, clients_dir: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""Regression: liveness is never inferred from an argv scan.
An unrelated process whose command line contains ``127.0.0.1:8787``
used to be a false positive (orphaning the proxy). The new path never
calls ``subprocess.run`` at all, so it can't be fooled by argv.
"""
wrap_mod._register_proxy_client(self.PORT)
def _no_subprocess(*args: Any, **kwargs: Any) -> None:
raise AssertionError("cleanup must not invoke subprocess.run (no pgrep)")
monkeypatch.setattr(wrap_mod.subprocess, "run", _no_subprocess)
proc = _FakeProxyProc()
cleanup = wrap_mod._make_cleanup([proc], self.PORT)
cleanup() # must not raise
assert proc.terminated is False
def test_register_then_unregister_is_idempotent(self, clients_dir: Path) -> None:
"""Register adds exactly our marker; unregister removes it; re-call is safe."""
wrap_mod._register_proxy_client(self.PORT)
all_clients = wrap_mod._live_proxy_clients(self.PORT, exclude_self=False)
assert all_clients == [os.getpid()]
wrap_mod._unregister_proxy_client(self.PORT)
assert wrap_mod._live_proxy_clients(self.PORT, exclude_self=False) == []
# Second unregister is a no-op, not an error.
wrap_mod._unregister_proxy_client(self.PORT)
# ---------------------------------------------------------------------------
# _ensure_proxy — dashboard URL is surfaced even when the proxy is already up.
# ---------------------------------------------------------------------------
def test_ensure_proxy_already_running_prints_dashboard_url(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""When a healthy proxy is already running, the dashboard URL is printed.
Regression: the URL was only echoed on the start/restart path, so repeat
wraps (the common case) never told the user where the dashboard lives.
"""
port = 1234
# A compatible running proxy exposes its config; proxies without a config
# block are no longer reused (they cannot be compatibility-checked) and
# are covered by test_ensure_proxy_never_reuses_configless_proxy.
running_config = {"pid": 4321, "backend": "anthropic"}
monkeypatch.setattr(wrap_mod, "_find_persistent_manifest", lambda _p: None)
monkeypatch.setattr(wrap_mod, "_check_proxy", lambda _p: True)
monkeypatch.setattr(wrap_mod, "_query_proxy_health", lambda _p: {})
monkeypatch.setattr(wrap_mod, "_proxy_needs_version_restart", lambda _h: False)
monkeypatch.setattr(wrap_mod, "_proxy_health_config", lambda _h: running_config)
monkeypatch.setattr(wrap_mod, "_live_proxy_clients", lambda *a, **kw: [])
output = _run_in_click_context(lambda: wrap_mod._ensure_proxy(port, no_proxy=False))
assert f"http://127.0.0.1:{port}/dashboard" in output
# ---------------------------------------------------------------------------
# _resolve_1m_model — 1M context window suffix logic (#1158).
# ---------------------------------------------------------------------------
def test_resolve_1m_model_appends_suffix_to_user_model() -> None:
"""A model the user already selected via ANTHROPIC_MODEL is preserved, with
only the [1m] suffix appended so Claude Code requests the 1M window."""
assert wrap_mod._resolve_1m_model("claude-opus-4-1-20250805") == (
"claude-opus-4-1-20250805[1m]"
)
def test_resolve_1m_model_is_idempotent() -> None:
"""A model that already carries [1m] is returned unchanged (no double suffix)."""
assert wrap_mod._resolve_1m_model("claude-opus-4-8[1m]") == "claude-opus-4-8[1m]"
def test_resolve_1m_model_falls_back_to_default_when_unset(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""With no model selected, fall back to the built-in default carrying [1m]."""
monkeypatch.delenv("HEADROOM_1M_MODEL", raising=False)
expected = f"{wrap_mod._DEFAULT_1M_MODEL}[1m]"
assert wrap_mod._resolve_1m_model(None) == expected
assert wrap_mod._resolve_1m_model(" ") == expected
def test_resolve_1m_model_env_overrides_builtin_default(monkeypatch: pytest.MonkeyPatch) -> None:
"""HEADROOM_1M_MODEL overrides the built-in fallback so --1m can track new
Opus releases without a code change or pinning ANTHROPIC_MODEL (#2937)."""
monkeypatch.setenv("HEADROOM_1M_MODEL", "claude-opus-9")
assert wrap_mod._resolve_1m_model(None) == "claude-opus-9[1m]"
def test_resolve_1m_model_current_wins_over_env(monkeypatch: pytest.MonkeyPatch) -> None:
"""An explicit ANTHROPIC_MODEL still wins; HEADROOM_1M_MODEL is only the
fallback default when nothing else is selected."""
monkeypatch.setenv("HEADROOM_1M_MODEL", "claude-opus-9")
assert wrap_mod._resolve_1m_model("claude-sonnet-5") == "claude-sonnet-5[1m]"
def test_resolve_1m_model_env_idempotent_on_suffixed_value(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""A HEADROOM_1M_MODEL that already carries [1m] is not double-suffixed."""
monkeypatch.setenv("HEADROOM_1M_MODEL", "claude-opus-9[1m]")
assert wrap_mod._resolve_1m_model(None) == "claude-opus-9[1m]"
def test_resolve_1m_model_blank_env_falls_back_to_builtin(monkeypatch: pytest.MonkeyPatch) -> None:
"""A blank/whitespace HEADROOM_1M_MODEL falls back to the built-in default."""
monkeypatch.setenv("HEADROOM_1M_MODEL", " ")
assert wrap_mod._resolve_1m_model(None) == f"{wrap_mod._DEFAULT_1M_MODEL}[1m]"
def test_headroom_1m_model_is_documented_and_default_matches_code() -> None:
"""The HEADROOM_1M_MODEL knob must stay documented, and the documented
default must track the code, so the supported configuration surface cannot
silently drift or disappear (#2937).
"""
docs = Path(__file__).resolve().parents[2] / "docs" / "content" / "docs" / "configuration.mdx"
text = docs.read_text(encoding="utf-8")
assert wrap_mod._1M_MODEL_ENV in text, f"{wrap_mod._1M_MODEL_ENV} is not documented"
# The env-var catalog row must advertise the current built-in default.
assert f"`{wrap_mod._DEFAULT_1M_MODEL}`" in text, (
"documented HEADROOM_1M_MODEL default is out of sync with "
f"_DEFAULT_1M_MODEL={wrap_mod._DEFAULT_1M_MODEL!r}"
)
class TestFindAvailablePort:
"""Tests for _find_available_port (Vite-style port fallback)."""
def test_port_free_returns_same(self, monkeypatch: pytest.MonkeyPatch) -> None:
"""When port is free, returns the same port."""
monkeypatch.setattr(wrap_mod, "_port_bind_error", lambda port: None)
assert wrap_mod._find_available_port(8787) == 8787
def test_port_busy_finds_next(self, monkeypatch: pytest.MonkeyPatch) -> None:
"""When port is busy, returns the next free port."""
def mock_bind(port: int) -> OSError | None:
if port == 8787:
return OSError(errno.EADDRINUSE, "Address in use")
return None
monkeypatch.setattr(wrap_mod, "_port_bind_error", mock_bind)
assert wrap_mod._find_available_port(8787) == 8788
def test_multiple_busy_ports(self, monkeypatch: pytest.MonkeyPatch) -> None:
"""When multiple consecutive ports are busy, skips all of them."""
def mock_bind(port: int) -> OSError | None:
if port in (8787, 8788, 8789):
return OSError(errno.EADDRINUSE, "Address in use")
return None
monkeypatch.setattr(wrap_mod, "_port_bind_error", mock_bind)
assert wrap_mod._find_available_port(8787) == 8790
def test_propagates_unexpected_error(self, monkeypatch: pytest.MonkeyPatch) -> None:
"""Errors other than EADDRINUSE/EACCES (e.g. EADDRNOTAVAIL) propagate."""
monkeypatch.setattr(
wrap_mod,
"_port_bind_error",
lambda port: OSError(errno.EADDRNOTAVAIL, "Address not available"),
)
with pytest.raises(OSError, match="Address not available"):
wrap_mod._find_available_port(8787)
def test_propagates_eaddrinuse_with_eacces(self, monkeypatch: pytest.MonkeyPatch) -> None:
"""Both EADDRINUSE and EACCES are skipped (not propagated)."""
def mock_bind(port: int) -> OSError | None:
if port == 8787:
return OSError(errno.EACCES, "Permission denied")
return None
monkeypatch.setattr(wrap_mod, "_port_bind_error", mock_bind)
assert wrap_mod._find_available_port(8787) == 8788
def test_exhausts_range(self, monkeypatch: pytest.MonkeyPatch) -> None:
"""When all ports in range are busy, raises RuntimeError."""
monkeypatch.setattr(
wrap_mod,
"_port_bind_error",
lambda port: OSError(errno.EADDRINUSE, "Address in use"),
)
with pytest.raises(RuntimeError, match="No available port found"):
wrap_mod._find_available_port(8787, max_attempts=3)
def test_ensure_proxy_serializes_startup_per_port(monkeypatch: pytest.MonkeyPatch) -> None:
"""A normal wrap must enter the per-port startup critical section."""
events: list[object] = []
@contextmanager
def fake_lock(port: int):
events.append(("lock-enter", port))
try:
yield
finally:
events.append(("lock-exit", port))
monkeypatch.setattr(wrap_mod, "_proxy_start_lock", fake_lock)
monkeypatch.setattr(
wrap_mod,
"_ensure_proxy_unlocked",
lambda port, no_proxy, **kwargs: events.append(("ensure", port, no_proxy)) or (None, port),
)
assert wrap_mod._ensure_proxy(8787, False) == (None, 8787)
assert events == [("lock-enter", 8787), ("ensure", 8787, False), ("lock-exit", 8787)]
def test_no_proxy_does_not_create_startup_lock(monkeypatch: pytest.MonkeyPatch) -> None:
"""Explicit --no-proxy reuses an existing service without taking the lock."""
entered = False
@contextmanager
def fail_lock(port: int):
nonlocal entered
entered = True
yield
monkeypatch.setattr(wrap_mod, "_proxy_start_lock", fail_lock)
monkeypatch.setattr(wrap_mod, "_ensure_proxy_unlocked", lambda *args, **kwargs: (None, 8787))
assert wrap_mod._ensure_proxy(8787, True) == (None, 8787)
assert entered is False
# ---------------------------------------------------------------------------
# _launch_tool — the wrapped agent inherits the *real* proxy port via
# HEADROOM_PORT, so `headroom dashboard` run inside that session lands on the
# right proxy even when wrap fell back off the requested port.
# ---------------------------------------------------------------------------
def _launch_tool_capturing_env(
monkeypatch: pytest.MonkeyPatch, *, requested_port: int, actual_port: int
) -> dict[str, str]:
"""Drive `_launch_tool` with everything external stubbed, return the child env."""
captured: dict[str, dict[str, str]] = {}
class _Result:
returncode = 0
def fake_run(cmd, env=None, **kwargs): # type: ignore[no-untyped-def]
captured["env"] = dict(env or {})
return _Result()
monkeypatch.setattr(wrap_mod, "_ensure_proxy", lambda *a, **kw: (None, actual_port))
monkeypatch.setattr(wrap_mod, "_register_proxy_client", lambda port: None)
monkeypatch.setattr(wrap_mod, "_unregister_proxy_client", lambda port: None)
monkeypatch.setattr(wrap_mod, "_push_runtime_env", lambda port, no_proxy: None)
monkeypatch.setattr(wrap_mod, "_make_cleanup", lambda holder, port: lambda *a, **kw: None)
monkeypatch.setattr(wrap_mod, "_configure_quiet_cli_env", lambda env: [])
monkeypatch.setattr(wrap_mod, "_print_telemetry_notice", lambda: None)
monkeypatch.setattr(wrap_mod.signal, "signal", lambda *a, **kw: None)
monkeypatch.setattr(wrap_mod.subprocess, "run", fake_run)
runner = CliRunner()
@click.command()
def _cmd() -> None:
wrap_mod._launch_tool(
binary="fake-agent",
args=(),
env={"ANTHROPIC_BASE_URL": f"http://127.0.0.1:{requested_port}"},
port=requested_port,
no_proxy=False,
tool_label="FAKE",
env_vars_display=[],
)
result = runner.invoke(_cmd)
assert result.exit_code == 0, result.output
return captured["env"]
def test_launch_tool_exports_headroom_port_to_child() -> None:
"""The wrapped agent must see HEADROOM_PORT even with no port fallback."""
with pytest.MonkeyPatch.context() as mp:
env = _launch_tool_capturing_env(mp, requested_port=8787, actual_port=8787)
assert env["HEADROOM_PORT"] == "8787"
def test_launch_tool_exports_actual_port_after_fallback() -> None:
"""Regression: wrap bumped to 8788 (e.g. copilot-subscription proxy), so the
child env must advertise 8788 — not the 8787 that was merely requested."""
with pytest.MonkeyPatch.context() as mp:
env = _launch_tool_capturing_env(mp, requested_port=8787, actual_port=8788)
assert env["HEADROOM_PORT"] == "8788"
# The existing URL-rewrite behaviour must keep working alongside it.
assert env["ANTHROPIC_BASE_URL"] == "http://127.0.0.1:8788"
@pytest.mark.parametrize(
("argv", "expected"),
[
(
["wrap", "aider"],
"Error: 'aider' not found in PATH.\nInstall aider: pip install aider-chat",
),
(["wrap", "goose"], "Error: 'goose' not found in PATH."),
(["wrap", "kimi"], "Error: 'kimi' (or 'kimi-cli') not found in PATH."),
],
)
def test_missing_binary_error_goes_to_stderr_only(
monkeypatch: pytest.MonkeyPatch, tmp_path: Path, argv: list[str], expected: str
) -> None:
"""The missing-binary error is a ClickException on stderr; stdout stays empty."""
monkeypatch.chdir(tmp_path)
monkeypatch.setattr(wrap_mod.shutil, "which", lambda name: None)
def no_proxy(*args: Any, **kwargs: Any) -> None:
raise AssertionError("a missing binary must fail before any proxy start")
monkeypatch.setattr(wrap_mod, "_ensure_proxy", no_proxy)
result = CliRunner().invoke(main, argv)
assert result.exit_code == 1
assert result.stdout == ""
assert result.stderr.startswith(expected)
def test_start_proxy_passes_carried_extensions_as_a_flag(
monkeypatch: pytest.MonkeyPatch,
tmp_path: Path,
) -> None:
captured: dict[str, object] = {}
proc = _FakeProxyProc()
def fake_popen(command: list[str], **kwargs: object) -> _FakeProxyProc:
captured["command"] = command
return proc
monkeypatch.setattr(wrap_mod.subprocess, "Popen", fake_popen)
monkeypatch.setattr(wrap_mod, "_check_proxy", lambda port: True)
monkeypatch.setattr(wrap_mod, "_get_log_path", lambda port=None: tmp_path / "proxy.log")
monkeypatch.setattr(
wrap_mod,
"_get_proxy_stdio_log_path",
lambda port=None: tmp_path / "proxy-stdio.log",
)
monkeypatch.setattr(wrap_mod.time, "sleep", lambda seconds: None)
wrap_mod._start_proxy(8788, proxy_extensions=["observability", "routemegood"])
command = captured["command"]
assert isinstance(command, list)
assert command[command.index("--proxy-extension") + 1] == "observability,routemegood"
wrap_mod._start_proxy(8788)
assert "--proxy-extension" not in captured["command"]