mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-08-27 14:17:10 -04:00
## Description `headroom wrap claude` writes `env.ANTHROPIC_BASE_URL` (or the foundry/vertex variant) into a project's `.claude/settings.local.json` so daemon-spawned Claude Code workers route through the local Headroom proxy. Removal only happened in the wrap process's `finally:` block. An unclean exit — `SIGKILL`, OOM, reboot, or terminal/tmux close (`SIGHUP`, which was not caught; only `SIGINT`/`SIGTERM` were) — skipped that cleanup, so the entry persisted indefinitely. Every subsequent bare `claude` in that project then routed to the dead port and hung indefinitely retrying it. Closes #1768 ## 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) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - `_write_claude_wrap_base_url` now optionally stamps a sidecar marker (`.claude/.headroom_wrap_marker.json`) recording the writer's pid/identity, the port, and the true prior value — kept out of `settings.local.json` itself so Headroom bookkeeping never shows up as a stray key in a file Claude Code's own config loader parses. - A shared `_identity_mismatch` helper (factored out of the existing `_marker_pid_reused` proxy-client-refcounting logic) lets a marker be judged stale: missing/invalid pid, dead pid, or a live pid whose identity doesn't match the recorded one (PID reuse after a crash). - `claude()` now checks for — and self-heals — a stale marker immediately before writing a fresh entry, restoring the recorded prior value instead of trusting a leftover from a dead session. - `claude()` now also registers a `SIGHUP` handler (guarded via `hasattr`, since Windows has none) alongside the existing `SIGTERM` handler, so terminal-close triggers the same cleanup/restore path. - `headroom unwrap claude` now reads the marker's recorded prior value before restoring, instead of unconditionally deleting the key — so a user's own pre-existing `ANTHROPIC_BASE_URL` (set before ever running `wrap`) isn't blindly wiped. - `headroom doctor` gained a new check (`check_wrap_marker_staleness`) that flags a stale project-local marker and points at `headroom unwrap claude` to clean it up — separate from the existing global-settings `check_claude_routing` check. - (Unrelated, pre-existing on `main`) reformatted `headroom/proxy/handlers/openai.py`, `tests/test_openai_codex_ws_lifecycle.py`, `tests/test_output_shaper.py` — whitespace/indentation only, no logic change — since they were already failing `ruff format --check .` on `main` before this branch touched anything, and the repo-wide lint gate blocks on it. Out of scope: `wrap --worktree` — no such flag or multi-worktree `.claude` handling exists anywhere in `wrap.py` today; not adding new surface for an aspirational scenario the issue mentions but that isn't implemented. ## 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/test_wrap_claude_base_url.py tests/test_cli/test_unwrap_claude.py tests/test_cli/test_wrap_stale_marker.py -q 42 passed $ pytest tests/test_cli -q 512 passed, 1 failed (test_wrap_codex_prepare_only_registers_serena_when_uvx_exists — confirmed to fail identically on a clean checkout of main with no changes applied; test-order flake, unrelated to this PR) $ ruff check . All checks passed! $ ruff format --check . 1047 files already formatted $ mypy headroom/cli/wrap.py headroom/cli/doctor.py Success: no issues found in 2 source files ``` ## Real Behavior Proof - Environment: local checkout, Python 3.13, Windows. - Exact command / steps: wrote a base_url entry + marker via `_write_claude_wrap_base_url(..., port=8787)`, then overwrote the marker's recorded pid with a value guaranteed not to be a live process (simulating the crash from the issue's own repro: `headroom wrap claude -- -p ok & ; kill -9 <wrap-pid>`). Ran `headroom.cli.doctor.check_wrap_marker_staleness()` against that path, then called `_check_and_clear_stale_wrap_marker()` (the same check `claude()` now runs before writing a fresh entry). - Observed result: `doctor`'s check correctly reports `WARN` naming the dead pid/port and pointing at `headroom unwrap claude`. The stale-check call then self-heals: in the "nothing existed before wrap" case the leaked entry is removed; in a second run seeded with a real pre-existing `ANTHROPIC_BASE_URL` (set before `wrap` ever ran), that original value is recovered instead of being deleted. In both cases the marker file is cleared afterward. - Not tested: actual OS-level signal delivery (`kill -HUP` against a real running `headroom wrap claude` subprocess) — the SIGHUP registration is exercised via a source-inspection test instead of a live signal, since spawning/killing the real CLI subprocess isn't practical in this environment; verified E2E via CI's `wrap-native` jobs (Ubuntu/macOS) which passed. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [ ] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I have updated the CHANGELOG.md if applicable ## Screenshots (if applicable) N/A — CLI/backend fix, no UI surface. ## Additional Notes - Documentation checklist item left unchecked: no user-facing docs currently describe wrap's settings.local.json write/cleanup behavior in enough detail to need updating; happy to add a troubleshooting note if maintainers want one. - `wrap --worktree` handling is out of scope (see Changes Made) — flagging in case maintainers want it tracked as a separate follow-up issue. --------- Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
359 lines
12 KiB
Python
359 lines
12 KiB
Python
from __future__ import annotations
|
|
|
|
import json
|
|
from pathlib import Path
|
|
from unittest.mock import patch
|
|
|
|
import pytest
|
|
from click.testing import CliRunner
|
|
|
|
from headroom.cli import wrap as wrap_cli
|
|
from headroom.cli.main import main
|
|
|
|
|
|
@pytest.fixture
|
|
def runner() -> CliRunner:
|
|
return CliRunner()
|
|
|
|
|
|
def test_remove_claude_rtk_hooks_preserves_unrelated_hooks(tmp_path: Path) -> None:
|
|
settings = tmp_path / "settings.json"
|
|
settings.write_text(
|
|
json.dumps(
|
|
{
|
|
"model": "opus",
|
|
"hooks": {
|
|
"PreToolUse": [
|
|
{
|
|
"matcher": "Bash",
|
|
"hooks": [
|
|
{
|
|
"type": "command",
|
|
"command": "/Users/test/.claude/hooks/rtk-rewrite.sh",
|
|
},
|
|
{"type": "command", "command": "echo keep"},
|
|
],
|
|
}
|
|
],
|
|
"SessionStart": [
|
|
{"matcher": "startup", "hooks": [{"type": "command", "command": "keep"}]}
|
|
],
|
|
},
|
|
}
|
|
)
|
|
+ "\n",
|
|
encoding="utf-8",
|
|
)
|
|
|
|
assert wrap_cli._remove_claude_rtk_hooks(settings) is True
|
|
|
|
payload = json.loads(settings.read_text(encoding="utf-8"))
|
|
pre_tool_hooks = payload["hooks"]["PreToolUse"][0]["hooks"]
|
|
assert pre_tool_hooks == [{"type": "command", "command": "echo keep"}]
|
|
assert payload["hooks"]["SessionStart"][0]["hooks"][0]["command"] == "keep"
|
|
|
|
|
|
def test_unwrap_claude_removes_mcp_rtk_and_stops_proxy(
|
|
runner: CliRunner,
|
|
tmp_path: Path,
|
|
monkeypatch: pytest.MonkeyPatch,
|
|
) -> None:
|
|
home = str(tmp_path)
|
|
monkeypatch.setenv("HOME", home)
|
|
monkeypatch.setenv("USERPROFILE", home)
|
|
claude_dir = tmp_path / ".claude"
|
|
claude_dir.mkdir()
|
|
settings = claude_dir / "settings.json"
|
|
settings.write_text(
|
|
json.dumps(
|
|
{
|
|
"hooks": {
|
|
"PreToolUse": [
|
|
{
|
|
"matcher": "Bash",
|
|
"hooks": [
|
|
{"type": "command", "command": str(claude_dir / "rtk-rewrite.sh")}
|
|
],
|
|
}
|
|
]
|
|
}
|
|
}
|
|
)
|
|
+ "\n",
|
|
encoding="utf-8",
|
|
)
|
|
stopped: list[int] = []
|
|
unregistered: list[str] = []
|
|
|
|
class Registrar:
|
|
name = "claude"
|
|
|
|
def detect(self) -> bool:
|
|
return True
|
|
|
|
def unregister_server(self, server_name: str) -> bool:
|
|
unregistered.append(server_name)
|
|
return True
|
|
|
|
def get_server(self, server_name: str):
|
|
return None
|
|
|
|
with (
|
|
patch("headroom.mcp_registry.ClaudeRegistrar", return_value=Registrar()),
|
|
patch(
|
|
"headroom.cli.wrap._stop_local_proxy_for_unwrap",
|
|
side_effect=lambda port: stopped.append(port) or "stopped",
|
|
),
|
|
):
|
|
result = runner.invoke(main, ["unwrap", "claude", "--port", "9999"])
|
|
|
|
assert result.exit_code == 0, result.output
|
|
assert unregistered == ["headroom", "codebase-memory-mcp"]
|
|
assert stopped == [9999]
|
|
assert "Stopped local Headroom proxy on port 9999" in result.output
|
|
assert "hooks" not in json.loads(settings.read_text(encoding="utf-8"))
|
|
|
|
|
|
def test_unwrap_claude_preserves_user_managed_serena(
|
|
runner: CliRunner,
|
|
monkeypatch: pytest.MonkeyPatch,
|
|
tmp_path: Path,
|
|
) -> None:
|
|
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path / ".headroom"))
|
|
unregistered: list[str] = []
|
|
|
|
class Registrar:
|
|
name = "claude"
|
|
|
|
def detect(self) -> bool:
|
|
return True
|
|
|
|
def unregister_server(self, server_name: str) -> bool:
|
|
unregistered.append(server_name)
|
|
return True
|
|
|
|
def get_server(self, server_name: str):
|
|
if server_name == "serena":
|
|
from headroom.mcp_registry.base import ServerSpec
|
|
|
|
return ServerSpec(name="serena", command="/usr/local/bin/custom-serena")
|
|
return None
|
|
|
|
with (
|
|
patch("headroom.mcp_registry.ClaudeRegistrar", return_value=Registrar()),
|
|
patch("headroom.cli.wrap._remove_claude_rtk_hooks", return_value=False),
|
|
patch("headroom.cli.wrap._stop_local_proxy_for_unwrap"),
|
|
):
|
|
result = runner.invoke(main, ["unwrap", "claude"])
|
|
|
|
assert result.exit_code == 0, result.output
|
|
assert unregistered == ["headroom", "codebase-memory-mcp"]
|
|
|
|
|
|
def test_unwrap_claude_removes_headroom_installed_serena(
|
|
runner: CliRunner,
|
|
monkeypatch: pytest.MonkeyPatch,
|
|
tmp_path: Path,
|
|
) -> None:
|
|
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path / ".headroom"))
|
|
|
|
from headroom.mcp_registry import build_serena_spec
|
|
from headroom.mcp_registry.ledger import record_install
|
|
|
|
serena_spec = build_serena_spec("claude-code")
|
|
record_install("claude", serena_spec)
|
|
unregistered: list[str] = []
|
|
|
|
class Registrar:
|
|
name = "claude"
|
|
|
|
def detect(self) -> bool:
|
|
return True
|
|
|
|
def unregister_server(self, server_name: str) -> bool:
|
|
unregistered.append(server_name)
|
|
return True
|
|
|
|
def get_server(self, server_name: str):
|
|
if server_name == "serena":
|
|
return serena_spec
|
|
return None
|
|
|
|
with (
|
|
patch("headroom.mcp_registry.ClaudeRegistrar", return_value=Registrar()),
|
|
patch("headroom.cli.wrap._remove_claude_rtk_hooks", return_value=False),
|
|
patch("headroom.cli.wrap._stop_local_proxy_for_unwrap"),
|
|
):
|
|
result = runner.invoke(main, ["unwrap", "claude"])
|
|
|
|
assert result.exit_code == 0, result.output
|
|
assert unregistered == ["headroom", "codebase-memory-mcp", "serena"]
|
|
assert "Removed Headroom-installed Serena MCP server" in result.output
|
|
|
|
|
|
def test_unwrap_claude_keep_flags_skip_cleanup(
|
|
runner: CliRunner,
|
|
) -> None:
|
|
with (
|
|
patch("headroom.mcp_registry.ClaudeRegistrar") as registrar,
|
|
patch("headroom.cli.wrap._remove_claude_rtk_hooks") as remove_rtk,
|
|
patch("headroom.cli.wrap._stop_local_proxy_for_unwrap") as stop_proxy,
|
|
):
|
|
result = runner.invoke(
|
|
main,
|
|
["unwrap", "claude", "--keep-mcp", "--keep-rtk", "--no-stop-proxy"],
|
|
)
|
|
|
|
assert result.exit_code == 0, result.output
|
|
registrar.assert_not_called()
|
|
remove_rtk.assert_not_called()
|
|
stop_proxy.assert_not_called()
|
|
|
|
|
|
def test_unwrap_claude_restores_all_base_url_modes(runner: CliRunner) -> None:
|
|
restore_calls: list[dict[str, object]] = []
|
|
|
|
def restore_base_url(previous: str | None, **kwargs: object) -> None:
|
|
restore_calls.append({"previous": previous, **kwargs})
|
|
|
|
with patch("headroom.cli.wrap._restore_claude_wrap_base_url", side_effect=restore_base_url):
|
|
result = runner.invoke(
|
|
main,
|
|
["unwrap", "claude", "--keep-mcp", "--keep-rtk", "--no-stop-proxy"],
|
|
)
|
|
|
|
assert result.exit_code == 0, result.output
|
|
settings_path = Path.cwd() / ".claude" / "settings.local.json"
|
|
assert restore_calls == [
|
|
{
|
|
"previous": None,
|
|
"foundry_mode": False,
|
|
"vertex_mode": False,
|
|
"settings_path": settings_path,
|
|
},
|
|
{
|
|
"previous": None,
|
|
"foundry_mode": True,
|
|
"vertex_mode": False,
|
|
"settings_path": settings_path,
|
|
},
|
|
{
|
|
"previous": None,
|
|
"foundry_mode": False,
|
|
"vertex_mode": True,
|
|
"settings_path": settings_path,
|
|
},
|
|
]
|
|
|
|
|
|
def test_remove_claude_rtk_hooks_removes_init_hooks_and_env(tmp_path: Path) -> None:
|
|
settings = tmp_path / "settings.json"
|
|
settings.write_text(
|
|
json.dumps(
|
|
{
|
|
"model": "opus",
|
|
"env": {"ANTHROPIC_BASE_URL": "http://127.0.0.1:8787", "FOO": "bar"},
|
|
"hooks": {
|
|
"SessionStart": [
|
|
{
|
|
"matcher": "startup|resume",
|
|
"hooks": [
|
|
{
|
|
"type": "command",
|
|
"command": (
|
|
"/home/u/.local/bin/headroom init hook ensure "
|
|
"--profile init-user --marker headroom-init-claude"
|
|
),
|
|
"timeout": 15,
|
|
}
|
|
],
|
|
}
|
|
],
|
|
"PreToolUse": [
|
|
{
|
|
"matcher": "Bash",
|
|
"hooks": [
|
|
{
|
|
"type": "command",
|
|
"command": "headroom init hook ensure --marker headroom-init-claude",
|
|
},
|
|
{"type": "command", "command": "echo keep-me"},
|
|
],
|
|
}
|
|
],
|
|
},
|
|
}
|
|
)
|
|
+ "\n",
|
|
encoding="utf-8",
|
|
)
|
|
|
|
assert wrap_cli._remove_claude_rtk_hooks(settings) is True
|
|
|
|
payload = json.loads(settings.read_text(encoding="utf-8"))
|
|
# ANTHROPIC_BASE_URL stripped; unrelated env var preserved
|
|
assert payload.get("env") == {"FOO": "bar"}
|
|
# SessionStart removed entirely (its only hook was the init marker)
|
|
assert "SessionStart" not in payload.get("hooks", {})
|
|
# PreToolUse: init-marker hook gone, unrelated hook kept
|
|
assert payload["hooks"]["PreToolUse"][0]["hooks"] == [
|
|
{"type": "command", "command": "echo keep-me"}
|
|
]
|
|
assert payload["model"] == "opus"
|
|
|
|
|
|
def test_remove_claude_rtk_hooks_strips_env_without_hooks(tmp_path: Path) -> None:
|
|
# Regression: unwrap previously returned early when no hooks existed,
|
|
# leaving init's ANTHROPIC_BASE_URL behind in settings.json.
|
|
settings = tmp_path / "settings.json"
|
|
settings.write_text(
|
|
json.dumps({"env": {"ANTHROPIC_BASE_URL": "http://127.0.0.1:8787"}}) + "\n",
|
|
encoding="utf-8",
|
|
)
|
|
|
|
assert wrap_cli._remove_claude_rtk_hooks(settings) is True
|
|
|
|
payload = json.loads(settings.read_text(encoding="utf-8"))
|
|
assert "env" not in payload # emptied env dict is dropped
|
|
|
|
|
|
def test_remove_claude_rtk_hooks_noop_when_nothing_managed(tmp_path: Path) -> None:
|
|
settings = tmp_path / "settings.json"
|
|
original = {
|
|
"model": "opus",
|
|
"env": {"FOO": "bar"},
|
|
"hooks": {
|
|
"PreToolUse": [
|
|
{"matcher": "Bash", "hooks": [{"type": "command", "command": "echo hi"}]}
|
|
]
|
|
},
|
|
}
|
|
settings.write_text(json.dumps(original) + "\n", encoding="utf-8")
|
|
|
|
assert wrap_cli._remove_claude_rtk_hooks(settings) is False
|
|
# nothing managed -> file untouched
|
|
assert json.loads(settings.read_text(encoding="utf-8")) == original
|
|
|
|
|
|
def test_remove_claude_rtk_hooks_strips_enable_tool_search(tmp_path: Path) -> None:
|
|
# unwrap must remove BOTH env vars init writes (ANTHROPIC_BASE_URL +
|
|
# ENABLE_TOOL_SEARCH, GH #746), leaving user-set vars intact.
|
|
settings = tmp_path / "settings.json"
|
|
settings.write_text(
|
|
json.dumps(
|
|
{
|
|
"env": {
|
|
"ANTHROPIC_BASE_URL": "http://127.0.0.1:8787",
|
|
"ENABLE_TOOL_SEARCH": "true",
|
|
"KEEP": "1",
|
|
}
|
|
}
|
|
)
|
|
+ "\n",
|
|
encoding="utf-8",
|
|
)
|
|
|
|
assert wrap_cli._remove_claude_rtk_hooks(settings) is True
|
|
|
|
payload = json.loads(settings.read_text(encoding="utf-8"))
|
|
assert payload["env"] == {"KEEP": "1"}
|