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): serialize shared proxy startup (#2946)
Tejas Choprae540d64febf2
diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.pyindex 14885a9b6..bb85df54d 100644--- a/headroom/cli/wrap.py+++ b/headroom/cli/wrap.py@@ -33,6 +33,8 @@ import sysimport timeimport urllib.parsefrom collections.abc import Callable+from contextlib import contextmanager+from functools import wrapsfrom pathlib import Pathfrom typing import Any, cast@@ -3460,7 +3462,7 @@ def _push_runtime_env(port: int, no_proxy: bool) -> None:click.echo(f" Synced output settings to proxy: {', '.join(sorted(payload))}")-def _ensure_proxy(+def _ensure_proxy_unlocked(port: int,no_proxy: bool,*,@@ -3479,7 +3481,13 @@ def _ensure_proxy(copilot_refresh_oauth_token: str | None = None,copilot_api_token_expires_at: float | None = None,) -> tuple[subprocess.Popen | None, int]:- """Start or verify proxy. Returns (process_handle, actual_port)."""+ """Start or verify proxy. Returns (process_handle, actual_port).++ The public ``_ensure_proxy`` wrapper serializes callers per port before+ entering this function. Keeping the implementation separate makes the+ lock boundary explicit and ensures every health/configuration check runs+ under the same startup critical section.+ """helpers = _live_wrap_module()copilot_subscription_seed_requested = (bool(copilot_api_token)@@ -3846,6 +3854,81 @@ def _ensure_proxy(return None, port+@contextmanager+def _proxy_start_lock(port: int) -> Any:+ """Serialize wrap proxy startup across processes sharing a port.++ A proxy can spend tens of seconds loading optional ML components before it+ binds its socket. Without this lock, two concurrent ``headroom wrap``+ commands both see an unavailable health endpoint, choose the same port,+ and race to spawn a listener. The lock is deliberately held through the+ health/configuration checks and startup, then released once the proxy is+ ready (or startup fails). Lock files are retained so an interrupted+ process cannot create an inode-replacement race for another waiter.+ """+ from headroom import paths as _paths++ lock_path = _paths.proxy_start_lock_path(port)+ try:+ lock_path.parent.mkdir(parents=True, exist_ok=True)+ lock_file = open(lock_path, "a+b") # noqa: SIM115+ except OSError:+ # Locking is a race-prevention enhancement, not a reason to make wrap+ # unusable when a read-only/custom workspace cannot hold state. The+ # existing port bind remains the final safety check in that degraded+ # environment.+ yield+ return+ with lock_file:+ if sys.platform == "win32":+ import msvcrt++ # msvcrt.locking operates on bytes from the current file position.+ lock_file.seek(0)+ if lock_file.read(1) == b"":+ lock_file.seek(0)+ lock_file.write(b"0")+ lock_file.flush()+ lock_file.seek(0)+ # LK_LOCK has implementation-dependent retry limits. A proxy may+ # legitimately take longer than that to load ML components, so+ # use the non-blocking primitive in a loop instead.+ while True:+ try:+ msvcrt.locking(lock_file.fileno(), msvcrt.LK_NBLCK, 1)+ break+ except OSError:+ time.sleep(0.05)+ try:+ yield+ finally:+ lock_file.seek(0)+ msvcrt.locking(lock_file.fileno(), msvcrt.LK_UNLCK, 1)+ else:+ import fcntl++ fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX)+ try:+ yield+ finally:+ fcntl.flock(lock_file.fileno(), fcntl.LOCK_UN)+++@wraps(_ensure_proxy_unlocked)+def _ensure_proxy(+ port: int,+ no_proxy: bool,+ **kwargs: Any,+) -> tuple[subprocess.Popen | None, int]:+ """Start or reuse a proxy without racing another wrap on the same port."""+ if no_proxy:+ return _ensure_proxy_unlocked(port, no_proxy, **kwargs)+ with _proxy_start_lock(port):+ # Re-checking is part of the lock boundary: a concurrent wrapper may+ # have finished startup while this caller was waiting for the lock.+ return _ensure_proxy_unlocked(port, no_proxy, **kwargs)++def _client_marker_path(port: int) -> Path:"""Path to this process's wrap-client marker for ``port``."""from headroom import paths as _pathsdiff --git a/headroom/paths.py b/headroom/paths.pyindex 645d8b6fc..25e9e882a 100644--- a/headroom/paths.py+++ b/headroom/paths.py@@ -342,6 +342,12 @@ def beacon_lock_path(port: int) -> Path:return workspace_dir() / f".beacon_lock_{int(port)}"+def proxy_start_lock_path(port: int) -> Path:+ """Return the per-port lock used to serialize wrap proxy startup."""++ return workspace_dir() / f".proxy_start_{int(port)}.lock"++# ---------------------------------------------------------------------------# Per-resource helpers -- config bucket# ---------------------------------------------------------------------------@@ -432,6 +438,7 @@ __all__ = ["proxy_clients_dir","deploy_root","beacon_lock_path",+ "proxy_start_lock_path","models_config_path","plugin_config_dir","plugin_workspace_dir",diff --git a/tests/test_cli/test_wrap_helpers.py b/tests/test_cli/test_wrap_helpers.pyindex e0bc16928..2fad26a26 100644--- a/tests/test_cli/test_wrap_helpers.py+++ b/tests/test_cli/test_wrap_helpers.py@@ -16,6 +16,7 @@ import errnoimport jsonimport osimport signal+from contextlib import contextmanagerfrom pathlib import Pathfrom typing import Any@@ -817,3 +818,43 @@ class TestFindAvailablePort:)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