Files
headroom/tests/test_cli/test_wrap_kimi.py
trs-80andClaude Opus 5.5 3ffa57ec25 fix(wrap): never reuse a non-Headroom listener on the proxy port (#3799)
## Description

`headroom wrap` decided a proxy was running with `_check_proxy`, which
is a bare TCP connect. Any service listening on the wrap port passed
that check. When something other than Headroom held the port (seen in
practice: a caveman gateway on 8787), wrap would:

- reuse it and route the tool at it
- wait on it as a persistent deployment
- treat it as a live session in the dead-marker self-heal

A listener now counts as Headroom only if its `/health` payload carries
Headroom identity: `service: "headroom-proxy"` (reported by both the
Python and Rust proxies) or a `config` block. Generic JSON such as
`{"status": "ok"}` is foreign. Otherwise wrap uses the existing port
search.

Split out of #3366. These fixes apply to every harness and don't depend
on the wrap-target registry.

Closes #

## Type of Change

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

## Changes Made

- `headroom/cli/wrap.py`:
  - `_is_headroom_health(payload)`: the identity rule above.
- `_foreign_listener(port)`: TCP accepts, but `/health` does not
identify Headroom.
- `_ensure_proxy_unlocked`: a foreign listener is never reused. The port
search takes over, and a persistent manifest on a foreign-held port
falls through to a fresh proxy instead of raising "not healthy".
- `_check_and_clear_dead_wrap_marker`: a foreign listener on a dead
wrapper's port no longer counts as a live session (the marker is kept
while the writer PID is alive).
- `_launch_tool`: on port fallback the launch banner is rewritten too,
so it shows the URL the child actually got (the env already was).
- `wrap claude`: the marker/owner claim records `actual_port` instead of
the requested port.
- `_ensure_claude_wrap_selfheal_hook`: a marker-bearing hook whose
command drifted (hand edit, moved binary) is rewritten in place instead
of skipped.
- `tests/test_cli/test_wrap_claude_vertex_proxy_env.py`: runs in an
isolated cwd so it can't write a selfheal hook into the repo's
`.claude/settings.local.json`. Also gitignored
`.claude/.headroom_wrap_*.json`.

## 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
$ pytest tests/test_cli/
792 passed, 1 skipped
$ ruff check headroom/cli/wrap.py tests/test_cli/ && ruff format --check headroom/cli/wrap.py tests/test_cli/
All checks passed!
$ mypy headroom/cli/wrap.py
Success: no issues found in 1 source file
```

New: `tests/test_cli/test_wrap_foreign_listener.py` (12 tests, including
a generic-JSON `/health` server and the Rust-proxy `/health` shape),
`test_wrap_selfheal_hook_repairs_stale_command`. Updated:
`test_wrap_kimi.py::test_non_kimi_fallback_display_follows_actual_port`
(asserted the old stale banner), plus two `test_wrap_persistent.py`
tests that now identify the listener as Headroom via `/health`.

## Real Behavior Proof

- Environment: macOS (darwin 25.6.0), Python 3.13, this branch vs `main`
at 3aa50128
- Exact command / steps: `python3 -m http.server 8899` as a foreign
listener (its `/health` returns 404); a stub `goose` on PATH that prints
`OPENAI_BASE_URL` and curls `$ANTHROPIC_BASE_URL/health`; then `headroom
wrap goose --port 8899`
- Observed result: main hands the tool the squatter; this branch starts
a real proxy on the next port.
- main: `Proxy already running on port 8899` → child gets
`http://127.0.0.1:8899/v1`, and its `/health` → **404** (the tool is
talking to the squatter)
- this branch: `Port 8899 is in use by a non-Headroom service; selecting
another port...` → proxy starts on 8900, banner and child both show
`http://127.0.0.1:8900/v1`, `/health` → **200**
- Not tested: Windows; a live persistent (`headroom install`) deployment
whose port was taken over (covered by
`test_persistent_manifest_on_foreign_port_falls_through`)

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: n/a
- Stable/default behavior changed: only when a non-Headroom service
holds the wrap port. Wrap used to hand the tool that service; now it
starts a Headroom proxy on the next free port. A real Headroom proxy is
identified by `/health` and reused exactly as before.
- Kill switch / disable path: none needed; pass `--port` to choose a
free port explicitly
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert this PR; no persisted state or format changes

## 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 (a CI guard enforces
this)

## Additional Notes

- Documentation: N/A, no user-facing docs describe port reuse.
- One of three PRs replacing #3366 (see that PR for the split
rationale). Independent of the other two; merges cleanly with them in
either order.

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

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-29 15:30:56 -05:00

323 lines
12 KiB
Python

"""Tests for `headroom wrap kimi` command."""
from __future__ import annotations
import os
import sys
from pathlib import Path
from typing import Any
from unittest.mock import patch
import pytest
from click.testing import CliRunner
from headroom.cli import wrap as wrap_mod
from headroom.cli.main import main
@pytest.fixture
def runner() -> CliRunner:
return CliRunner()
def test_managed_route_reproduction(
runner: CliRunner,
capfd: pytest.CaptureFixture[str],
monkeypatch: pytest.MonkeyPatch,
tmp_path: Path,
) -> None:
"""The production launcher passes the managed endpoint to an exact-contract child."""
direct = "https://api.kimi.com/coding/v1"
monkeypatch.setenv("KIMI_BASE_URL", direct)
monkeypatch.setenv("KIMI_TEST_UNRELATED", "preserved")
monkeypatch.setattr(wrap_mod, "_project_name_from_cwd", lambda: "repo")
captured: dict[str, Any] = {}
def fake_launch_tool(**kwargs: Any) -> None: # noqa: ANN003
captured.update(kwargs)
with patch.object(wrap_mod.shutil, "which", return_value=sys.executable):
with patch.object(wrap_mod, "_launch_tool", side_effect=fake_launch_tool):
result = runner.invoke(main, ["wrap", "kimi", "--port", "8787"])
assert result.exit_code == 0, result.output
env = captured["env"]
display = captured["env_vars_display"]
configure_launch = captured["configure_launch"]
child_result = tmp_path / "kimi-child.txt"
child = (
"import os, sys; from pathlib import Path; Path(r'"
f"{child_result}"
"').write_text('CHILD|' + os.environ['KIMI_CODE_BASE_URL'] + '|' + "
"os.environ['KIMI_BASE_URL'] + '|' + os.environ['KIMI_TEST_UNRELATED'] + '|' + sys.argv[1])"
)
with (
patch.object(wrap_mod, "_make_cleanup", return_value=lambda: None),
patch.object(wrap_mod.signal, "signal"),
patch.object(wrap_mod, "_register_proxy_client"),
patch.object(wrap_mod, "_ensure_proxy", return_value=(None, 9001)),
patch.object(wrap_mod, "_unregister_proxy_client"),
patch.object(wrap_mod, "_push_runtime_env"),
patch.object(wrap_mod, "_configure_quiet_cli_env", return_value=[]),
):
with pytest.raises(SystemExit) as raised:
wrap_mod._launch_tool(
binary=os.fspath(Path(sys.executable)),
args=("-c", child, "child-arg"),
env=env,
port=8787,
no_proxy=False,
tool_label="KIMI",
env_vars_display=display,
configure_launch=configure_launch,
)
assert raised.value.code == 0
output = result.output + capfd.readouterr().out
expected = "http://127.0.0.1:9001/p/repo/v1"
assert f"KIMI_CODE_BASE_URL={expected}" in output
assert f"KIMI_BASE_URL={expected}" in output
assert child_result.read_text() == f"CHILD|{expected}|{expected}|preserved|child-arg"
assert direct not in output
def test_wrap_kimi_launch(
runner: CliRunner,
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""Kimi launches with correct configuration."""
monkeypatch.chdir(tmp_path)
monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
captured: dict[str, Any] = {}
def fake_launch_tool(**kwargs: Any) -> None: # noqa: ANN003
captured.update(kwargs)
with patch.object(wrap_mod.shutil, "which", return_value="kimi"):
with patch.object(wrap_mod, "_launch_tool", side_effect=fake_launch_tool):
with patch.object(wrap_mod, "_project_name_from_cwd", return_value=None):
result = runner.invoke(
main, ["wrap", "kimi", "--port", "9000", "--", "-m", "kimi-for-coding"]
)
assert result.exit_code == 0, result.output
env = captured["env"]
assert isinstance(env, dict)
assert captured["tool_label"] == "KIMI"
assert captured["agent_type"] == "kimi"
assert captured["args"] == ("-m", "kimi-for-coding")
assert captured["openai_api_url"] == "https://api.kimi.com/coding/v1"
assert callable(captured["configure_launch"])
assert env["KIMI_CODE_BASE_URL"] == "http://127.0.0.1:9000/v1"
assert env["KIMI_BASE_URL"] == "http://127.0.0.1:9000/v1"
def test_project_name(
runner: CliRunner,
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""Project name is encoded in both Kimi endpoint variables."""
project_dir = tmp_path / "my-project"
project_dir.mkdir()
monkeypatch.chdir(project_dir)
monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
captured: dict[str, Any] = {}
def fake_launch_tool(**kwargs: Any) -> None: # noqa: ANN003
captured.update(kwargs)
with patch.object(wrap_mod.shutil, "which", return_value="kimi"):
with patch.object(wrap_mod, "_launch_tool", side_effect=fake_launch_tool):
result = runner.invoke(main, ["wrap", "kimi", "--port", "7000"])
assert result.exit_code == 0, result.output
env = captured["env"]
assert env["KIMI_CODE_BASE_URL"] == "http://127.0.0.1:7000/p/my-project/v1"
assert env["KIMI_BASE_URL"] == "http://127.0.0.1:7000/p/my-project/v1"
def test_wrap_kimi_cli_fallback(
runner: CliRunner,
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""Falls back to the `kimi-cli` binary when `kimi` is not on PATH."""
monkeypatch.chdir(tmp_path)
monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
captured: dict[str, Any] = {}
def fake_launch_tool(**kwargs: Any) -> None: # noqa: ANN003
captured.update(kwargs)
def fake_which(name: str) -> str | None:
return "/usr/local/bin/kimi-cli" if name == "kimi-cli" else None
with patch.object(wrap_mod.shutil, "which", side_effect=fake_which):
with patch.object(wrap_mod, "_launch_tool", side_effect=fake_launch_tool):
with patch.object(wrap_mod, "_project_name_from_cwd", return_value=None):
result = runner.invoke(main, ["wrap", "kimi"])
assert result.exit_code == 0, result.output
assert captured["binary"] == "/usr/local/bin/kimi-cli"
def test_wrap_kimi_not_found(
runner: CliRunner,
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""Error message when neither kimi nor kimi-cli is found."""
monkeypatch.chdir(tmp_path)
monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
with patch.object(wrap_mod.shutil, "which", return_value=None):
result = runner.invoke(main, ["wrap", "kimi"])
assert result.exit_code == 1
assert "Error: 'kimi' (or 'kimi-cli') not found in PATH" in result.output
assert "https://github.com/MoonshotAI/kimi-cli" in result.output
def test_port_fallback(
runner: CliRunner,
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""Custom --port is passed to _launch_tool and appears in both URLs."""
monkeypatch.chdir(tmp_path)
monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
captured: dict[str, Any] = {}
def fake_launch_tool(**kwargs: Any) -> None: # noqa: ANN003
captured.update(kwargs)
with patch.object(wrap_mod.shutil, "which", return_value="kimi"):
with patch.object(wrap_mod, "_launch_tool", side_effect=fake_launch_tool):
with patch.object(wrap_mod, "_project_name_from_cwd", return_value=None):
result = runner.invoke(main, ["wrap", "kimi", "--port", "9999"])
assert result.exit_code == 0, result.output
assert captured["port"] == 9999
assert captured["env"]["KIMI_CODE_BASE_URL"] == "http://127.0.0.1:9999/v1"
assert captured["env"]["KIMI_BASE_URL"] == "http://127.0.0.1:9999/v1"
def test_non_kimi_fallback_display_follows_actual_port(
capfd: pytest.CaptureFixture[str], tmp_path: Path
) -> None:
"""A port fallback rewrites the banner too, so it shows the URL the child got."""
env = {**os.environ, "OTHER_BASE_URL": "http://127.0.0.1:8787/v1"}
display = ["OTHER_BASE_URL=http://127.0.0.1:8787/v1"]
child_result = tmp_path / "other-child.txt"
child = (
"import os; from pathlib import Path; Path(r'"
f"{child_result}"
"').write_text('CHILD|' + os.environ['OTHER_BASE_URL'])"
)
with (
patch.object(wrap_mod, "_make_cleanup", return_value=lambda: None),
patch.object(wrap_mod.signal, "signal"),
patch.object(wrap_mod, "_register_proxy_client"),
patch.object(wrap_mod, "_ensure_proxy", return_value=(None, 9001)),
patch.object(wrap_mod, "_unregister_proxy_client"),
patch.object(wrap_mod, "_push_runtime_env"),
patch.object(wrap_mod, "_configure_quiet_cli_env", return_value=[]),
):
with pytest.raises(SystemExit) as raised:
wrap_mod._launch_tool(
binary=os.fspath(Path(sys.executable)),
args=("-c", child),
env=env,
port=8787,
no_proxy=False,
tool_label="OTHER",
env_vars_display=display,
)
assert raised.value.code == 0
output = capfd.readouterr().out
assert "OTHER_BASE_URL=http://127.0.0.1:9001/v1" in output
assert "127.0.0.1:8787" not in output
assert child_result.read_text() == "CHILD|http://127.0.0.1:9001/v1"
def test_wrap_kimi_custom_api_url(
runner: CliRunner,
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""--kimi-api-url overrides the upstream endpoint passed to _launch_tool."""
monkeypatch.chdir(tmp_path)
monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
captured: dict[str, Any] = {}
def fake_launch_tool(**kwargs: Any) -> None: # noqa: ANN003
captured.update(kwargs)
with patch.object(wrap_mod.shutil, "which", return_value="kimi"):
with patch.object(wrap_mod, "_launch_tool", side_effect=fake_launch_tool):
with patch.object(wrap_mod, "_project_name_from_cwd", return_value=None):
result = runner.invoke(
main,
["wrap", "kimi", "--kimi-api-url", "https://api.moonshot.ai/v1"],
)
assert result.exit_code == 0, result.output
assert captured["openai_api_url"] == "https://api.moonshot.ai/v1"
def test_wrap_kimi_no_proxy(
runner: CliRunner,
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""--no-proxy flag prevents proxy startup."""
monkeypatch.chdir(tmp_path)
monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
captured: dict[str, Any] = {}
def fake_launch_tool(**kwargs: Any) -> None: # noqa: ANN003
captured.update(kwargs)
with patch.object(wrap_mod.shutil, "which", return_value="kimi"):
with patch.object(wrap_mod, "_launch_tool", side_effect=fake_launch_tool):
with patch.object(wrap_mod, "_project_name_from_cwd", return_value=None):
result = runner.invoke(main, ["wrap", "kimi", "--no-proxy"])
assert result.exit_code == 0, result.output
assert captured["no_proxy"] is True
def test_wrap_kimi_learn_memory(
runner: CliRunner,
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""--learn and --memory flags are passed to _launch_tool."""
monkeypatch.chdir(tmp_path)
monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
captured: dict[str, Any] = {}
def fake_launch_tool(**kwargs: Any) -> None: # noqa: ANN003
captured.update(kwargs)
with patch.object(wrap_mod.shutil, "which", return_value="kimi"):
with patch.object(wrap_mod, "_launch_tool", side_effect=fake_launch_tool):
with patch.object(wrap_mod, "_project_name_from_cwd", return_value=None):
result = runner.invoke(main, ["wrap", "kimi", "--learn", "--memory"])
assert result.exit_code == 0, result.output
assert captured["learn"] is True
assert captured["memory"] is True