headroom/tests/test_cli/test_unwrap_claude.py
Parideboy 84509a4b89
fix: detect and clear stale ANTHROPIC_BASE_URL from crashed wrap sessions (#1768) (#1837)
## 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>
2026-07-06 08:35:40 -07:00

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"}