Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
fix(wrap): never reuse a non-Headroom listener on the proxy port (#3799)
trs-803ffa57ec25a6
diff --git a/.gitignore b/.gitignoreindex 646e622e3..fd0e2ce49 100644--- a/.gitignore+++ b/.gitignore@@ -213,6 +213,7 @@ examples/vertex_gemini_benchmark/results.json# Headroom specific.headroom/+.claude/.headroom_wrap_*.jsonheadroom.dbheadroom_*.db*.jsonldiff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.pyindex 0968dafcd..ac9d990e4 100644--- a/headroom/cli/wrap.py+++ b/headroom/cli/wrap.py@@ -579,6 +579,22 @@ def _check_proxy(port: int) -> bool:return False+def _foreign_listener(port: int) -> bool:+ """True when something accepts TCP on ``port`` but is not a Headroom proxy.++ ``_check_proxy`` is a bare TCP connect, so any service squatting the port+ (observed: a caveman gateway on 8787) satisfies it. Only a ``/health``+ payload that ``_is_headroom_health`` recognizes proves Headroom identity —+ generic JSON such as ``{"status": "ok"}`` does not. A listener without it+ must never be reused, restarted, or trusted as a live wrapped session.+ """+ if not _check_proxy(port):+ return False+ if _is_headroom_health(_query_proxy_health(port)):+ return False+ return _query_proxy_config(port) is None++def _port_bind_error(port: int) -> OSError | None:"""Return the bind error for a local proxy port, or None when it is usable."""try:@@ -1633,7 +1649,15 @@ def _check_and_clear_dead_wrap_marker(settings_path: Path, *, key: str) -> str |# is a live session (never cleared); only a port that fails the whole# retry window is dead. One probe here — no correlated double check.if _wrap_proxy_alive(port):- return None+ if not _foreign_listener(port):+ return None+ if not _wrap_marker_is_stale(marker):+ # The port answers but not as Headroom, yet the wrapper that+ # wrote the marker is still alive — leave its claim alone.+ return None+ # A foreign service took the dead proxy's port: TCP-alive+ # is a false liveness signal, and the writer PID is gone. Treat+ # the marker as dead and restore below.elif not _wrap_marker_is_stale(marker):# No recorded port → fall back to PID-based staleness.return None@@ -1726,36 +1750,34 @@ def _ensure_claude_wrap_selfheal_hook(settings_path: Path) -> None:with a SessionStart hook that runs the hidden ``wrap selfheal`` command.SessionStart ONLY (never PreToolUse): the self-heal must not run per Bashcall mid-session, where a transient probe blip could clear a live session.- Idempotent — an existing entry carrying the marker is not duplicated.+ Idempotent — an existing entry carrying the marker is not duplicated; if its+ command drifted (hand edit, moved headroom binary) it is rewritten in place."""payload = _read_settings_for_write(settings_path)hooks = dict(payload.get("hooks") or {}) if isinstance(payload.get("hooks"), dict) else {}entries = (list(hooks.get("SessionStart") or []) if isinstance(hooks.get("SessionStart"), list) else [])- already = any(- isinstance(entry, dict)- and isinstance(entry.get("hooks"), list)- and any(- isinstance(item, dict) and _WRAP_SELFHEAL_HOOK_MARKER in str(item.get("command", ""))- for item in entry["hooks"]- )+ command = _wrap_selfheal_hook_command()+ marked = [+ itemfor entry in entries- )- if already:- return- entries.append(- {- "matcher": "startup|resume",- "hooks": [- {- "type": "command",- "command": _wrap_selfheal_hook_command(),- "timeout": 10,- }- ],- }- )+ if isinstance(entry, dict) and isinstance(entry.get("hooks"), list)+ for item in entry["hooks"]+ if isinstance(item, dict) and _WRAP_SELFHEAL_HOOK_MARKER in str(item.get("command", ""))+ ]+ if marked:+ if all(item.get("command") == command for item in marked):+ return+ for item in marked:+ item["command"] = command+ else:+ entries.append(+ {+ "matcher": "startup|resume",+ "hooks": [{"type": "command", "command": command, "timeout": 10}],+ }+ )hooks["SessionStart"] = entriespayload["hooks"] = hookssettings_path.parent.mkdir(parents=True, exist_ok=True)@@ -3573,6 +3595,18 @@ def _resolve_copilot_provider_type(backend: str | None, provider_type: str) -> sreturn _copilot_resolve_provider_type(backend, provider_type)+def _is_headroom_health(payload: dict[str, Any] | None) -> bool:+ """True when a /health payload identifies a Headroom proxy.++ The Python proxy reports ``service: "headroom-proxy"`` plus a ``config``+ block; the Rust proxy reports only ``{"ok": true, "service": "headroom-proxy"}``.+ Any other JSON (a generic ``{"status": "ok"}``) is a foreign service.+ """+ if payload is None:+ return False+ return payload.get("service") == "headroom-proxy" or _proxy_health_config(payload) is not None++def _query_proxy_config(port: int) -> dict[str, Any] | None:"""Query the running proxy's feature configuration via /health.@@ -4308,6 +4342,19 @@ def _ensure_proxy_unlocked(" Copilot subscription seeds are session-specific; ""starting a dedicated local proxy instance for this wrap session.")+ if (+ not isolated_copilot_subscription_proxy+ and manifest is not None+ and helpers._foreign_listener(port)+ ):+ # The manifest's port is held by a non-Headroom service; recovery+ # can never rebind it. Skip the respawn/wait entirely and start a+ # fresh proxy on another port.+ click.echo(+ f" Persistent deployment '{manifest.profile}' port {port} is held by a "+ "non-Headroom service; starting a fresh proxy on another port."+ )+ manifest = Noneif not isolated_copilot_subscription_proxy and manifest is not None:from headroom.install.health import probe_ready@@ -4434,31 +4481,47 @@ def _ensure_proxy_unlocked(f"Persistent deployment '{manifest.profile}' on port {port} ""could not be restarted with requested features.")- elif helpers._check_proxy(port):+ elif helpers._check_proxy(port) and not helpers._foreign_listener(port):raise click.ClickException(f"Persistent deployment '{manifest.profile}' on port {port} is not healthy.")+ # A foreign (non-Headroom) listener squatting the manifest's+ # port is treated like a stale deployment: fall through and+ # start a fresh proxy on another port.if not persistent_routing_mismatch:click.echo(f" Warning: persistent deployment '{manifest.profile}' on port {port} ""is stale; starting a fresh proxy instead.")- if (+ proxy_listener = (not isolated_copilot_subscription_proxyand not persistent_routing_mismatchand helpers._check_proxy(port)+ )+ health_payload = helpers._query_proxy_health(port) if proxy_listener else None+ running_config = helpers._proxy_health_config(health_payload)+ if proxy_listener and running_config is None:+ running_config = helpers._query_proxy_config(port)+ if (+ proxy_listener+ and running_config is None+ and not helpers._is_headroom_health(health_payload)):+ # TCP accepted, but /health did not identify a Headroom proxy — a+ # foreign service is squatting the port. Fall through to the port+ # search below instead of reusing (or "version-restarting") it.+ click.echo(+ f" Port {port} is in use by a non-Headroom service; selecting another port..."+ )+ proxy_listener = False+ if proxy_listener:# Proxy is running — check if it has the features we needneeds_restart = False# Set False when the running proxy must not serve this session at# all (routing-level mismatch with live clients attached): fall# through to a fresh start on a different port.reuse_running = True- health_payload = helpers._query_proxy_health(port)- running_config = helpers._proxy_health_config(health_payload)- if running_config is None:- running_config = helpers._query_proxy_config(port)routing_mismatches = (Noneif running_config is None@@ -4965,6 +5028,10 @@ def _launch_tool(if actual_port != port:for k, v in dict(env).items():env[k] = v.replace(f"127.0.0.1:{port}", f"127.0.0.1:{actual_port}")+ env_vars_display = [+ line.replace(f"127.0.0.1:{port}", f"127.0.0.1:{actual_port}")+ for line in env_vars_display+ ]if configure_launch is not None:args, env, env_vars_display = configure_launch(actual_port, args, env, env_vars_display)@@ -5644,7 +5711,10 @@ def claude(foundry_mode=_settings_foundry[0],vertex_mode=_settings_vertex[0],settings_path=_wrap_settings_path,- port=port,+ # The URL above is built from actual_port; stamping the requested+ # port here made the marker/owner claim point at the wrong port+ # whenever _ensure_proxy fell back to another one.+ port=actual_port,)# Issue #2221: pair the marker just written with a reader. wrap installs# no hook of its own, so a session that only ran `wrap` (never `init`)diff --git a/tests/test_cli/test_wrap_claude_vertex_proxy_env.py b/tests/test_cli/test_wrap_claude_vertex_proxy_env.pyindex b1be0d7db..16c2f7172 100644--- a/tests/test_cli/test_wrap_claude_vertex_proxy_env.py+++ b/tests/test_cli/test_wrap_claude_vertex_proxy_env.py@@ -104,18 +104,23 @@ def _invoke_wrap_claude(monkeypatch.setattr(wrap_mod, "detect_claude_code_version", lambda *_a, **_k: (2, 1, 196))monkeypatch.setattr(wrap_mod.subprocess, "run", fake_run)- result = runner.invoke(- main,- [- "wrap",- "claude",- "--no-mcp",- "--no-tokensave",- "--no-serena",- *extra_args,- ],- env=env,- )+ # Isolate cwd: the wrap flow writes .claude/settings.local.json (selfheal+ # hook, stale-marker check) relative to cwd, and with shutil.which patched+ # above a run from the repo root would poison the real repo settings with a+ # "/usr/bin/claude wrap selfheal" hook.+ with runner.isolated_filesystem():+ result = runner.invoke(+ main,+ [+ "wrap",+ "claude",+ "--no-mcp",+ "--no-tokensave",+ "--no-serena",+ *extra_args,+ ],+ env=env,+ )assert result.exit_code == 0, result.outputreturn captured, result.outputdiff --git a/tests/test_cli/test_wrap_dead_marker_selfheal.py b/tests/test_cli/test_wrap_dead_marker_selfheal.pyindex 54c2dc1fc..a93c8ca9f 100644--- a/tests/test_cli/test_wrap_dead_marker_selfheal.py+++ b/tests/test_cli/test_wrap_dead_marker_selfheal.py@@ -221,6 +221,30 @@ def test_wrap_selfheal_hook_install_is_idempotent(tmp_path: Path) -> None:assert len(marked) == 1+def test_wrap_selfheal_hook_repairs_stale_command(tmp_path: Path) -> None:+ """A marker-bearing entry whose command drifted (hand edit, moved binary) is rewritten."""+ path = _settings(tmp_path)+ path.parent.mkdir(parents=True)+ stale = f"claude wrap selfheal --marker {_HOOK_MARKER}"+ path.write_text(+ json.dumps(+ {+ "hooks": {+ "SessionStart": [+ {"matcher": "startup|resume", "hooks": [{"command": stale, "timeout": 10}]}+ ]+ }+ }+ ),+ encoding="utf-8",+ )+ wrap_cli._ensure_claude_wrap_selfheal_hook(path)++ payload = json.loads(path.read_text(encoding="utf-8"))+ commands = [h["command"] for e in payload["hooks"]["SessionStart"] for h in e["hooks"]]+ assert commands == [wrap_cli._wrap_selfheal_hook_command()]++def test_wrap_selfheal_hook_preserves_existing_hooks(tmp_path: Path) -> None:path = _settings(tmp_path)path.parent.mkdir(parents=True)diff --git a/tests/test_cli/test_wrap_foreign_listener.py b/tests/test_cli/test_wrap_foreign_listener.pynew file mode 100644index 000000000..0eb0804cf--- /dev/null+++ b/tests/test_cli/test_wrap_foreign_listener.py@@ -0,0 +1,225 @@+"""A non-Headroom service squatting the wrap port must never be reused.++Observed live: a caveman gateway listening on 127.0.0.1:8787 satisfied the bare+TCP connect in ``_check_proxy``, so ``wrap claude`` printed "Proxy already+running" and routed traffic through the foreign gateway; the persistent-manifest+path stalled ~45s in recovery then raised "not healthy"; and the dead-marker+self-heal treated the squatter as a live wrapped session, permanently pinning a+stale ANTHROPIC_BASE_URL. These tests pin the foreign-listener detection at all+three sites.+"""++from __future__ import annotations++import json+import socket+import threading+from collections.abc import Iterator+from contextlib import contextmanager+from http.server import BaseHTTPRequestHandler, HTTPServer+from pathlib import Path++import pytest++from headroom.cli import wrap as wrap_cli+++@contextmanager+def _http_server(handler: type[BaseHTTPRequestHandler]) -> Iterator[int]:+ server = HTTPServer(("127.0.0.1", 0), handler)+ thread = threading.Thread(target=server.serve_forever, daemon=True)+ thread.start()+ try:+ yield server.server_address[1]+ finally:+ server.shutdown()+ thread.join(timeout=5)+ server.server_close()+++def _json_handler(status: int, payload: dict) -> type[BaseHTTPRequestHandler]:+ """Handler answering every GET with ``status`` and ``payload`` as JSON."""++ class _Handler(BaseHTTPRequestHandler):+ def do_GET(self) -> None: # noqa: N802 - BaseHTTPRequestHandler API+ body = json.dumps(payload).encode()+ self.send_response(status)+ self.send_header("Content-Type", "application/json")+ self.send_header("Content-Length", str(len(body)))+ self.end_headers()+ self.wfile.write(body)++ def log_message(self, *args: object) -> None:+ pass++ return _Handler+++# Answers TCP and HTTP, but 404s every route (caveman-gateway shape).+_ForeignHandler = _json_handler(404, {"error": {"code": "cave_route_not_found"}})+# A generic service whose /health returns 200 JSON with no Headroom identity.+# The version field is deliberate: it would otherwise trip the stale-version+# restart path and fail on the missing PID instead of picking another port.+_GenericJsonHandler = _json_handler(200, {"status": "ok", "version": "1.0.0"})+# Minimal Python-proxy /health shape (config block).+_HeadroomHandler = _json_handler(200, {"version": "0.0.0-test", "config": {}})+# Rust proxy /health shape: identity via ``service`` only, no config block.+_RustHeadroomHandler = _json_handler(200, {"ok": True, "service": "headroom-proxy"})+++def _closed_port() -> int:+ s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)+ s.bind(("127.0.0.1", 0))+ port = s.getsockname()[1]+ s.close()+ return port+++# --- _foreign_listener -----------------------------------------------------+++def test_foreign_listener_true_for_non_headroom_http() -> None:+ with _http_server(_ForeignHandler) as port:+ assert wrap_cli._foreign_listener(port) is True+++def test_foreign_listener_false_for_headroom_health() -> None:+ with _http_server(_HeadroomHandler) as port:+ assert wrap_cli._foreign_listener(port) is False+++def test_foreign_listener_true_for_generic_json_health() -> None:+ with _http_server(_GenericJsonHandler) as port:+ assert wrap_cli._foreign_listener(port) is True+++def test_foreign_listener_false_for_rust_proxy_health() -> None:+ with _http_server(_RustHeadroomHandler) as port:+ assert wrap_cli._foreign_listener(port) is False+++def test_foreign_listener_false_when_nothing_listens() -> None:+ assert wrap_cli._foreign_listener(_closed_port()) is False+++# --- _ensure_proxy_unlocked reuse branch -----------------------------------+++def _stub_ensure_proxy_env(monkeypatch: pytest.MonkeyPatch, foreign_port: int) -> dict:+ """Route _ensure_proxy_unlocked around everything but the reuse decision."""+ calls: dict = {"started": None, "recover": 0}+ monkeypatch.setattr(wrap_cli, "_find_persistent_manifest", lambda _p: None)+ monkeypatch.setattr(wrap_cli, "_find_available_port", lambda start, **_kw: foreign_port + 1)++ def _fake_start_proxy(port: int, **_kw: object) -> object:+ calls["started"] = port+ return object()++ monkeypatch.setattr(wrap_cli, "_start_proxy", _fake_start_proxy)+ return calls+++def test_reuse_branch_skips_foreign_listener_and_starts_fresh(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ with _http_server(_ForeignHandler) as port:+ calls = _stub_ensure_proxy_env(monkeypatch, port)+ proc, actual_port = wrap_cli._ensure_proxy_unlocked(port, False)+ assert actual_port == port + 1, "must fall through to the port search"+ assert calls["started"] == port + 1+ assert proc is not None+++def test_reuse_branch_skips_generic_json_listener_and_starts_fresh(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ with _http_server(_GenericJsonHandler) as port:+ calls = _stub_ensure_proxy_env(monkeypatch, port)+ proc, actual_port = wrap_cli._ensure_proxy_unlocked(port, False)+ assert actual_port == port + 1, "generic /health JSON must not count as Headroom"+ assert calls["started"] == port + 1+ assert proc is not None+++def test_reuse_branch_still_reuses_real_headroom_proxy(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ with _http_server(_HeadroomHandler) as port:+ calls = _stub_ensure_proxy_env(monkeypatch, port)+ # Health payload has no pid/version mismatch triggers → plain reuse.+ monkeypatch.setattr(wrap_cli, "_proxy_needs_version_restart", lambda _p: False)+ proc, actual_port = wrap_cli._ensure_proxy_unlocked(port, False)+ assert actual_port == port+ assert proc is None+ assert calls["started"] is None+++def test_persistent_manifest_on_foreign_port_falls_through(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ class _Manifest:+ profile = "test-profile"+ health_url = "http://127.0.0.1:1/readyz"++ with _http_server(_ForeignHandler) as port:+ calls = _stub_ensure_proxy_env(monkeypatch, port)+ monkeypatch.setattr(wrap_cli, "_find_persistent_manifest", lambda _p: _Manifest())++ def _no_recover(_p: int) -> bool:+ calls["recover"] += 1+ return False++ monkeypatch.setattr(wrap_cli, "_recover_persistent_proxy", _no_recover)+ proc, actual_port = wrap_cli._ensure_proxy_unlocked(port, False)+ assert calls["recover"] == 0, "recovery can never rebind a squatted port"+ assert actual_port == port + 1+ assert calls["started"] == port + 1+++# --- dead-marker self-heal --------------------------------------------------+++def _settings(tmp_path: Path) -> Path:+ return tmp_path / ".claude" / "settings.local.json"+++def test_foreign_listener_with_dead_writer_clears_marker(tmp_path: Path) -> None:+ path = _settings(tmp_path)+ with _http_server(_ForeignHandler) as port:+ wrap_cli._write_claude_wrap_base_url(f"http://127.0.0.1:{port}", settings_path=path)+ wrap_cli._write_wrap_marker(+ path, port=port, key="ANTHROPIC_BASE_URL", previous="http://old.proxy:9000"+ )+ # Simulate the writer having died: stamp a dead pid into the marker.+ marker_path = wrap_cli._wrap_marker_path(path)+ marker = json.loads(marker_path.read_text(encoding="utf-8"))+ marker["pid"] = 2**22 + 12345 # beyond macOS/Linux default pid ranges+ marker_path.write_text(json.dumps(marker), encoding="utf-8")++ restored = wrap_cli._check_and_clear_dead_wrap_marker(path, key="ANTHROPIC_BASE_URL")+ assert restored == "http://old.proxy:9000"+ payload = json.loads(path.read_text(encoding="utf-8"))+ assert payload["env"]["ANTHROPIC_BASE_URL"] == "http://old.proxy:9000"+++def test_foreign_listener_with_live_writer_keeps_marker(tmp_path: Path) -> None:+ path = _settings(tmp_path)+ with _http_server(_ForeignHandler) as port:+ wrap_cli._write_claude_wrap_base_url(f"http://127.0.0.1:{port}", settings_path=path)+ # Marker written by this (live) process → conservative: never cleared.+ wrap_cli._write_wrap_marker(path, port=port, key="ANTHROPIC_BASE_URL", previous=None)++ restored = wrap_cli._check_and_clear_dead_wrap_marker(path, key="ANTHROPIC_BASE_URL")+ assert restored is None+ assert wrap_cli._wrap_marker_path(path).exists()+++def test_headroom_listener_is_still_never_cleared(tmp_path: Path) -> None:+ path = _settings(tmp_path)+ with _http_server(_HeadroomHandler) as port:+ wrap_cli._write_claude_wrap_base_url(f"http://127.0.0.1:{port}", settings_path=path)+ wrap_cli._write_wrap_marker(path, port=port, key="ANTHROPIC_BASE_URL", previous=None)++ restored = wrap_cli._check_and_clear_dead_wrap_marker(path, key="ANTHROPIC_BASE_URL")+ assert restored is None+ assert wrap_cli._wrap_marker_path(path).exists()diff --git a/tests/test_cli/test_wrap_kimi.py b/tests/test_cli/test_wrap_kimi.pyindex 05ce3cc61..385f3d724 100644--- a/tests/test_cli/test_wrap_kimi.py+++ b/tests/test_cli/test_wrap_kimi.py@@ -209,9 +209,10 @@ def test_port_fallback(assert captured["env"]["KIMI_BASE_URL"] == "http://127.0.0.1:9999/v1"-def test_non_kimi_fallback_display_is_unchanged(+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"@@ -243,7 +244,8 @@ def test_non_kimi_fallback_display_is_unchanged(assert raised.value.code == 0output = capfd.readouterr().out- assert "OTHER_BASE_URL=http://127.0.0.1:8787/v1" in output+ assert "OTHER_BASE_URL=http://127.0.0.1:9001/v1" in output+ assert "127.0.0.1:8787" not in outputassert child_result.read_text() == "CHILD|http://127.0.0.1:9001/v1"diff --git a/tests/test_cli/test_wrap_persistent.py b/tests/test_cli/test_wrap_persistent.pyindex 2aaeb6c18..67bea3a3a 100644--- a/tests/test_cli/test_wrap_persistent.py+++ b/tests/test_cli/test_wrap_persistent.py@@ -69,6 +69,11 @@ def test_ensure_proxy_recovers_persistent_deployment_when_socket_is_bound(monkeycalls: list[str] = []monkeypatch.setattr(wrap_cli, "_check_proxy", lambda port: True)+ # A bare TCP accept no longer proves the listener is Headroom;+ # identify it via /health so the recovery path still applies.+ monkeypatch.setattr(+ wrap_cli, "_query_proxy_health", lambda port: {"version": "0.0.0-test", "config": {}}+ )monkeypatch.setattr(wrap_cli, "_find_persistent_manifest", lambda port: _Manifest())monkeypatch.setattr("headroom.install.health.probe_ready", lambda url: False)monkeypatch.setattr(@@ -100,6 +105,11 @@ def test_ensure_proxy_recovers_persistent_deployment_when_socket_is_bound(monkeydef test_ensure_proxy_rejects_unhealthy_persistent_deployment(monkeypatch) -> None:monkeypatch.setattr(wrap_cli, "_check_proxy", lambda port: True)+ # Headroom-identified listener: a foreign squatter would fall+ # through to a fresh port instead of raising.+ monkeypatch.setattr(+ wrap_cli, "_query_proxy_health", lambda port: {"version": "0.0.0-test", "config": {}}+ )monkeypatch.setattr(wrap_cli, "_find_persistent_manifest", lambda port: _Manifest())monkeypatch.setattr("headroom.install.health.probe_ready", lambda url: False)monkeypatch.setattr(wrap_cli, "_recover_persistent_proxy", lambda port: False)