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(cli): honor CODEX_HOME and align wrap/init/doctor with the live proxy port (#3855)
JD Davis5bf661232667
diff --git a/headroom/cli/doctor.py b/headroom/cli/doctor.pyindex 62cdf1e3a..e30628661 100644--- a/headroom/cli/doctor.py+++ b/headroom/cli/doctor.py@@ -25,7 +25,11 @@ import clickfrom headroom._version import format_version_label, normalize_release_versionfrom headroom.install.health import probe_json-from headroom.install.paths import claude_settings_path, codex_config_path+from headroom.install.paths import (+ claude_settings_path,+ codex_config_path,+ codex_project_config_path,+)from headroom.install.state import list_manifestsfrom headroom.paths import savings_pathfrom headroom.providers.claude import (@@ -41,6 +45,7 @@ from headroom.providers.claude import ()from .main import get_version, main+from .port_discovery import find_live_proxy_elsewhere, is_headroom_livezfrom .wrap import _read_wrap_marker, _wrap_marker_is_stalePASS = "pass"@@ -117,6 +122,166 @@ def check_proxy_liveness(livez: dict[str, Any] | None, base_url: str) -> CheckRe)+def note_live_proxy_elsewhere(check: CheckResult, live_port: int | None) -> CheckResult:+ """Point an unreachable-proxy row at a live Headroom proxy on another port."""+ if live_port is None or check.status == PASS:+ return check+ check.summary += f"; a Headroom proxy IS running on port {live_port}"+ check.hint = (+ f"re-run with: headroom doctor --port {live_port} "+ f"(or export HEADROOM_PORT={live_port}); to use port {live_port} from agents, "+ f"re-run `headroom wrap <agent> --port {live_port}` / `headroom init --port {live_port} "+ "<agent>`"+ )+ return check+++def check_proxy_readiness(+ livez: dict[str, Any] | None, readyz: dict[str, Any] | None, base_url: str+) -> CheckResult:+ """Is the live proxy also *ready* (``/readyz``: upstream reachable, warmed up)?++ ``/livez`` only proves the event loop answers. ``/readyz`` answers 503 --+ which the probe reports as ``None`` -- while the upstream check fails or+ startup work is pending, so a live-but-unready proxy is a WARN, not a FAIL.+ """+ name = "readiness"+ if livez is None:+ return CheckResult(name=name, status=SKIP, summary="proxy not reachable")+ if readyz is not None and (readyz.get("ready") or readyz.get("status") == "healthy"):+ return CheckResult(name=name, status=PASS, summary="/readyz reports ready")+ return CheckResult(+ name=name,+ status=WARN,+ summary="proxy is live but /readyz is not ready (upstream unreachable or still starting)",+ hint=f"inspect component state: curl {base_url}/health",+ )+++_HOOK_MARKERS = {"claude": "headroom-init-claude", "codex": "headroom-init-codex"}+++def _hook_commands(payload: Any) -> list[str]:+ """Every ``command`` string under a Claude/Codex-style ``hooks`` mapping."""+ commands: list[str] = []+ hooks = payload.get("hooks") if isinstance(payload, dict) else None+ if not isinstance(hooks, dict):+ return commands+ for entries in hooks.values():+ if not isinstance(entries, list):+ continue+ for entry in entries:+ items = entry.get("hooks") if isinstance(entry, dict) else None+ if isinstance(items, list):+ for item in items:+ if isinstance(item, dict) and item.get("command"):+ commands.append(str(item["command"]))+ elif isinstance(entry, dict) and entry.get("command"):+ commands.append(str(entry["command"]))+ return commands+++def _missing_hook_executable(command: str) -> str | None:+ """The hook command's program when it no longer resolves, else None."""+ import shlex+ import shutil++ try:+ tokens = shlex.split(command, posix=os.name != "nt")+ except ValueError:+ return None+ if not tokens:+ return None+ program = tokens[0].strip('"')+ if Path(program).exists() or shutil.which(program):+ return None+ return program+++def check_installed_hooks(expected: Sequence[tuple[str, str, Path, str]]) -> CheckResult:+ """Are the hooks ``headroom init`` installed still present and runnable?++ ``expected`` holds ``(agent, scope_label, hooks_file, init_command)`` for+ each agent an init deployment manifest says was configured. A missing+ hook means the proxy is never auto-started for new sessions; a hook whose+ program vanished (uninstalled venv, moved checkout) fails silently.+ """+ name = "hooks"+ if not expected:+ return CheckResult(name=name, status=SKIP, summary="no `headroom init` hooks expected")+ problems: list[str] = []+ fixes: list[str] = []+ installed: list[str] = []+ for agent, scope, path, fix in expected:+ marker = _HOOK_MARKERS.get(agent, f"headroom-init-{agent}")+ try:+ payload = json.loads(path.read_text(encoding="utf-8")) if path.exists() else {}+ except (OSError, ValueError):+ problems.append(f"{agent} ({scope}): could not parse {path}")+ fixes.append(fix)+ continue+ commands = [cmd for cmd in _hook_commands(payload) if marker in cmd]+ if not commands:+ problems.append(f"{agent} ({scope}): no Headroom hook in {path}")+ fixes.append(fix)+ continue+ missing = {prog for cmd in commands if (prog := _missing_hook_executable(cmd))}+ if missing:+ problems.append(+ f"{agent} ({scope}): hook program not found: {', '.join(sorted(missing))}"+ )+ fixes.append(fix)+ continue+ installed.append(f"{agent} ({scope})")+ if problems:+ return CheckResult(+ name=name,+ status=WARN,+ summary="; ".join(problems),+ hint="re-install with: " + " && ".join(dict.fromkeys(fixes)),+ )+ return CheckResult(name=name, status=PASS, summary="installed for " + ", ".join(installed))+++def expected_init_hooks(+ manifests: Sequence[Any], cwd: Path | None = None+) -> list[tuple[str, str, Path, str]]:+ """Hook files ``headroom init`` should have written, from its deployment manifests."""+ from headroom.install.paths import codex_hooks_path++ from .init import _GLOBAL_PROFILE, _local_profile++ root = cwd or Path.cwd()+ try:+ local_profile = _local_profile(root)+ except Exception: # noqa: BLE001 - odd cwd names must not crash doctor+ local_profile = None+ expected: list[tuple[str, str, Path, str]] = []+ for manifest in manifests:+ profile = getattr(manifest, "profile", "")+ if profile == _GLOBAL_PROFILE:+ scope, flag = "user", " -g"+ elif local_profile is not None and profile == local_profile:+ scope, flag = "project", ""+ else:+ continue+ port = getattr(manifest, "port", 8787)+ port_flag = f" --port {port}" if port != 8787 else ""+ for agent in getattr(manifest, "targets", []) or []:+ if agent == "claude":+ path = (+ claude_settings_path()+ if scope == "user"+ else root / ".claude" / "settings.local.json"+ )+ elif agent == "codex":+ path = codex_hooks_path() if scope == "user" else root / ".codex" / "hooks.json"+ else:+ continue+ expected.append((agent, scope, path, f"headroom init{flag}{port_flag} {agent}"))+ return expected++def check_version_drift(livez: dict[str, Any] | None, installed: str) -> CheckResult:"""Does the running proxy match the installed package version?"""if livez is None:@@ -400,36 +565,65 @@ def check_wrap_marker_staleness(settings_path: Path) -> CheckResult:)-def check_codex_routing(config_path: Path, port: int) -> CheckResult:+def codex_active_base_url(text: str) -> tuple[str, str | None]:+ """Return ``(provider_id, base_url)`` for the active Codex provider in ``text``."""+ active_match = _CODEX_MODEL_PROVIDER_RE.search(text)+ provider_id = active_match.group(1) if active_match else "headroom"+ return provider_id, _codex_provider_base_url(text, provider_id)+++def check_codex_routing(+ config_path: Path,+ port: int,+ project_config_paths: Sequence[Path] | None = None,+) -> CheckResult:"""Is Codex configured to route through the proxy?Detection prefers the active ``model_provider`` section's loopback``base_url``, while retaining the ``[model_providers.headroom]`` fallbackemitted by persistent and wrap installs. Best-effort matching keepsmalformed TOML a WARN instead of a crash.++ ``config_path`` is the user config (``$CODEX_HOME/config.toml``, so a+ relocated Codex home is inspected rather than ``~/.codex``). Codex layers a+ trusted project's ``.codex/config.toml`` over it, and ``headroom init+ codex`` without ``-g`` writes there, so project candidates are consulted+ first and the summary names the file that supplied the routing."""name = "codex"- if not config_path.exists():+ candidates = [*(project_config_paths or []), config_path]+ existing = [path for path in candidates if path.exists()]+ if not existing:return CheckResult(name=name,status=WARN,- summary="not routed (no ~/.codex/config.toml)",+ summary=f"not routed (no {config_path})",hint="wrap it: headroom wrap codex",)- try:- text = config_path.read_text(encoding="utf-8", errors="replace")- except OSError as exc:- return CheckResult(name=name, status=WARN, summary=f"could not read {config_path}: {exc}")- active_match = _CODEX_MODEL_PROVIDER_RE.search(text)- provider_id = active_match.group(1) if active_match else "headroom"- base_url = _codex_provider_base_url(text, provider_id)- if base_url is None:+ first_error: CheckResult | None = None+ found: tuple[Path, str, str, str] | None = None+ for candidate in existing:+ try:+ text = candidate.read_text(encoding="utf-8", errors="replace")+ except OSError as exc:+ first_error = first_error or CheckResult(+ name=name, status=WARN, summary=f"could not read {candidate}: {exc}"+ )+ continue+ provider_id, base_url = codex_active_base_url(text)+ if base_url is not None:+ found = (candidate, text, provider_id, base_url)+ break+ if found is None:+ if first_error is not None:+ return first_errorreturn CheckResult(name=name,status=WARN,summary="not routed (no active provider base_url in config.toml)",hint="wrap it: headroom wrap codex",)+ config_path, text, provider_id, base_url = foundrouting = _classify_routing_url(name, base_url, port, source=str(config_path))if routing.status != PASS:return routing@@ -939,14 +1133,28 @@ def doctor(port: int, emit_json: bool, network: bool, network_urls: tuple[str, ."""base_url = f"http://127.0.0.1:{port}"livez = probe_json(f"{base_url}/livez")+ readyz = probe_json(f"{base_url}/readyz", timeout=3.0) if livez else Nonehealth = probe_json(f"{base_url}/health", timeout=5.0) if livez else Nonestats = probe_json(f"{base_url}/stats", timeout=5.0) if livez else Noneinstalled = get_version()+ manifests = list_manifests()+ live_elsewhere = None+ if livez is None:+ # Cheap, bounded: only ports Headroom recorded (HEADROOM_PORT, 8787,+ # deployment manifests, the project's wrap marker), probed in parallel.+ live_elsewhere = find_live_proxy_elsewhere(+ port,+ manifests=manifests,+ probe=lambda p: is_headroom_livez(+ probe_json(f"http://127.0.0.1:{p}/livez", timeout=0.5)+ ),+ )project_claude_settings = Path.cwd() / ".claude" / "settings.json"project_local_claude_settings = Path.cwd() / ".claude" / "settings.local.json"checks = [- check_proxy_liveness(livez, base_url),+ note_live_proxy_elsewhere(check_proxy_liveness(livez, base_url), live_elsewhere),+ check_proxy_readiness(livez, readyz, base_url),check_version_drift(livez, installed),check_claude_routing(claude_settings_path(),@@ -954,7 +1162,8 @@ def doctor(port: int, emit_json: bool, network: bool, network_urls: tuple[str, .[project_local_claude_settings, project_claude_settings],),check_wrap_marker_staleness(project_local_claude_settings),- check_codex_routing(codex_config_path(), port),+ check_codex_routing(codex_config_path(), port, [codex_project_config_path()]),+ check_installed_hooks(expected_init_hooks(manifests)),check_shell_env(os.environ, port),check_kompress_health(health),check_savings(stats, savings_path()),@@ -994,7 +1203,7 @@ def doctor(port: int, emit_json: bool, network: bool, network_urls: tuple[str, .desktop_check = check_claude_desktop(claude_desktop_config_dir())if desktop_check is not None:checks.append(desktop_check)- deployments = check_deployments(list_manifests())+ deployments = check_deployments(manifests)if deployments is not None:checks.append(deployments)diff --git a/headroom/cli/init.py b/headroom/cli/init.pyindex 1f0e25caa..d623014ff 100644--- a/headroom/cli/init.py+++ b/headroom/cli/init.py@@ -24,9 +24,22 @@ except ModuleNotFoundError: # Python < 3.11import tomli as tomllib # type: ignore[no-redef]import click+from click.core import ParameterSource+from headroom.cli.port_discovery import (+ DEFAULT_PROXY_PORT,+ env_port,+ reconcile_default_port,+ warn_codex_provider_port_change,+)from headroom.install.models import ConfigScope, InstallPreset, RuntimeKind, SupervisorKind-from headroom.install.paths import claude_settings_path, codex_config_path, validate_profile_name+from headroom.install.paths import (+ claude_settings_path,+ codex_config_path,+ codex_hooks_path,+ codex_project_config_path,+ validate_profile_name,+)from headroom.install.planner import build_manifestfrom headroom.install.providers import _apply_unix_env_scope, _apply_windows_env_scopefrom headroom.install.runtime import (@@ -136,7 +149,11 @@ def _copilot_config_path() -> Path:def _codex_hooks_path(global_scope: bool) -> Path:- return (Path.home() if global_scope else Path.cwd()) / ".codex" / "hooks.json"+ # User scope follows Codex's own home resolution (CODEX_HOME, else ~/.codex)+ # so `init -g codex` writes the hooks file Codex will actually load.+ if global_scope:+ return codex_hooks_path()+ return Path.cwd() / ".codex" / "hooks.json"def _claude_scope_path(global_scope: bool) -> Path:@@ -148,7 +165,7 @@ def _claude_scope_path(global_scope: bool) -> Path:def _codex_scope_path(global_scope: bool) -> Path:if global_scope:return codex_config_path()- return Path.cwd() / ".codex" / "config.toml"+ return codex_project_config_path()def _json_file(path: Path) -> dict[str, Any]:@@ -332,6 +349,7 @@ def _ensure_codex_provider(path: Path, port: int) -> None:import relogger.debug("ensure codex provider block: %s (port=%s)", path, port)+ warn_codex_provider_port_change(path, port)# Emit requires_openai_auth only for ChatGPT-OAuth users (restores the# account menu); omitting it for API-key users avoids forcing an OAuth# login (#406).@@ -970,14 +988,33 @@ def _install_headroom_mcp_for_targets(*, targets: list[str], port: int) -> None:click.echo(line)+def _resolve_init_port(ctx: click.Context, port: int) -> int:+ """Honor ``--port``; otherwise ``HEADROOM_PORT``; otherwise reconcile with a live proxy.++ Skipped for the internal ``init hook`` group: hooks run non-interactively+ on every session start and must stay silent and fast.+ """+ if ctx.invoked_subcommand == "hook":+ return port+ if ctx.get_parameter_source("port") is not ParameterSource.DEFAULT:+ return port+ configured = env_port()+ if configured is not None:+ return configured+ return reconcile_default_port(port)++@main.group(invoke_without_command=True)@click.option("-g", "--global", "global_scope", is_flag=True, help="Install for the current user.")@click.option("--port",- default=8787,+ default=DEFAULT_PROXY_PORT,type=click.IntRange(1, 65535),show_default=True,- help="Headroom proxy port.",+ help=(+ "Headroom proxy port. When omitted, HEADROOM_PORT is used if set; otherwise a "+ "live Headroom proxy on another port is detected and offered."+ ),)@click.option("--backend", default="anthropic", show_default=True, help="Proxy backend.")@click.option("--anyllm-provider", default=None, help="Provider for any-llm backends.")@@ -1004,6 +1041,7 @@ def init("""Install durable Headroom integrations for supported agents."""if verbose:_enable_verbose_logging()+ port = _resolve_init_port(ctx, port)logger.debug("init: global_scope=%s port=%s backend=%s anyllm_provider=%s region=%s memory=%s ""invoked_subcommand=%s",@@ -1122,7 +1160,6 @@ def init_hook() -> None:@click.option("--marker", default=None, hidden=True)def init_hook_ensure(profile: str | None, marker: str | None) -> None:"""Best-effort ensure used by installed agent hooks."""- del markerdef _has_manifest(name: str) -> bool:# Best-effort: a corrupt manifest must not crash the session-start hook.@@ -1142,3 +1179,158 @@ def init_hook_ensure(profile: str | None, marker: str | None) -> None:profiles.append(_GLOBAL_PROFILE)for name in profiles:_ensure_profile_running(name)+ _emit_alignment_warning(marker, profiles)+++_HOOK_AGENT_BY_MARKER = {_CLAUDE_HOOK_MARKER: "claude", _CODEX_HOOK_MARKER: "codex"}+_HOOK_STDIN_WAIT_SECONDS = 0.5+++def _read_hook_event_name() -> str | None:+ """``hook_event_name`` from the hook's stdin JSON, read with a hard time bound.++ Claude Code and Codex pipe a JSON object into command hooks. A reader+ thread keeps a host that never closes stdin from stalling the hook.+ """+ import threading++ try:+ stream = sys.stdin+ if stream is None or stream.isatty():+ return None+ except (AttributeError, ValueError, OSError):+ return None+ box: dict[str, str] = {}++ def _read() -> None:+ try:+ box["raw"] = stream.read(1 << 20)+ except Exception: # noqa: BLE001 - best effort+ pass++ reader = threading.Thread(target=_read, daemon=True)+ reader.start()+ reader.join(_HOOK_STDIN_WAIT_SECONDS)+ raw = box.get("raw")+ if not raw:+ return None+ try:+ payload = json.loads(raw)+ except ValueError:+ return None+ event = payload.get("hook_event_name") if isinstance(payload, dict) else None+ return event if isinstance(event, str) else None+++def _claude_configured_base_url(cwd: Path) -> str | None:+ """Effective ``ANTHROPIC_BASE_URL`` from Claude settings (local > project > user)."""+ for path in (+ cwd / ".claude" / "settings.local.json",+ cwd / ".claude" / "settings.json",+ claude_settings_path(),+ ):+ try:+ payload = json.loads(path.read_text(encoding="utf-8")) if path.exists() else None+ except (OSError, ValueError):+ continue+ env_block = payload.get("env") if isinstance(payload, dict) else None+ if isinstance(env_block, dict) and env_block.get("ANTHROPIC_BASE_URL"):+ return str(env_block["ANTHROPIC_BASE_URL"])+ return os.environ.get("ANTHROPIC_BASE_URL") or None+++def _codex_configured_base_url(cwd: Path) -> str | None:+ """Active Codex provider ``base_url`` (project ``.codex`` first, then ``$CODEX_HOME``)."""+ from .doctor import codex_active_base_url++ for path in (codex_project_config_path(cwd), codex_config_path()):+ try:+ text = path.read_text(encoding="utf-8", errors="replace") if path.exists() else ""+ except OSError:+ continue+ if not text:+ continue+ _provider, base_url = codex_active_base_url(text)+ if base_url:+ return base_url+ return None+++def alignment_warning(+ agent: str,+ profile: str,+ *,+ cwd: Path | None = None,+ probe: Any = None,+) -> str | None:+ """Message when ``agent``'s configured proxy port differs from ``profile``'s.++ Returns None when aligned, unconfigured, or anything cannot be read.+ """+ from .port_discovery import loopback_port, probe_headroom_proxy++ try:+ manifest = load_manifest(profile)+ except ManifestError:+ return None+ if manifest is None:+ return None+ root = cwd or Path.cwd()+ if agent == "claude":+ base_url = _claude_configured_base_url(root)+ elif agent == "codex":+ base_url = _codex_configured_base_url(root)+ else:+ return None+ configured = loopback_port(base_url or "")+ expected = int(manifest.port)+ if configured is None or configured == expected:+ return None+ check = probe or probe_headroom_proxy+ configured_live = bool(check(configured))+ scope_flag = " -g" if profile == _GLOBAL_PROFILE else ""+ label = "Claude Code" if agent == "claude" else "Codex"+ if configured_live:+ state = f"a Headroom proxy is running on {configured}, not the managed one"+ fix_port = configured+ else:+ state = f"nothing Headroom answers on {configured}, so requests may fail"+ fix_port = expected+ return (+ f"Headroom: {label} is configured for http://127.0.0.1:{configured} but the Headroom "+ f"proxy managed by `headroom init` ({profile}) uses port {expected}; {state}. "+ f"Fix: headroom init{scope_flag} --port {fix_port} {agent}"+ )+++def _emit_alignment_warning(marker: str | None, profiles: list[str]) -> None:+ """Surface a base_url/proxy port mismatch through the SessionStart hook channel.++ Emitted only for Claude/Codex SessionStart hooks, as hook JSON+ (``systemMessage`` for the user, ``additionalContext`` for the agent).+ Must never raise or block: any failure silently emits nothing.+ """+ try:+ agent = _HOOK_AGENT_BY_MARKER.get(marker or "")+ if agent is None or not profiles:+ return+ if _read_hook_event_name() != "SessionStart":+ return+ message = alignment_warning(agent, profiles[0])+ if not message:+ return+ sys.stdout.write(+ json.dumps(+ {+ "systemMessage": message,+ "hookSpecificOutput": {+ "hookEventName": "SessionStart",+ "additionalContext": message,+ },+ }+ )+ + "\n"+ )+ sys.stdout.flush()+ except Exception: # noqa: BLE001 - a hook must never break the session+ returndiff --git a/headroom/cli/port_discovery.py b/headroom/cli/port_discovery.pynew file mode 100644index 000000000..3b1b7f98a--- /dev/null+++ b/headroom/cli/port_discovery.py@@ -0,0 +1,319 @@+"""Resolve which local port the Headroom proxy is (or should be) on.++``wrap``, ``init`` and ``doctor`` all default to port 8787. When a proxy is+already running elsewhere (``HEADROOM_PORT``, a persistent deployment on a+custom port, a live wrap session), silently defaulting to 8787 either starts a+second proxy or points an agent at a dead port. These helpers make the default+port follow ``HEADROOM_PORT`` and cheaply discover a live Headroom proxy on the+other ports Headroom itself recorded, so the CLI can warn -- or, on a TTY, ask+-- instead of guessing.++Discovery is deliberately bounded: loopback only, a handful of candidate ports+(the requested/default port, ``HEADROOM_PORT``, 8787, deployment-manifest ports+and the project's wrap marker), probed concurrently with a sub-second timeout.+It never scans port ranges. ``HEADROOM_PORT_DISCOVERY=0`` disables it.+"""++from __future__ import annotations++import json+import os+import re+import sys+from collections.abc import Callable, Iterable, Mapping, Sequence+from pathlib import Path+from typing import Any++import click++DEFAULT_PROXY_PORT = 8787+PORT_ENV = "HEADROOM_PORT"+DISCOVERY_ENV = "HEADROOM_PORT_DISCOVERY"+_PROBE_TIMEOUT_SECONDS = 0.5+_MAX_CANDIDATES = 8+_HEADROOM_SERVICE = "headroom-proxy"+_LOOPBACK_PORT_RE = re.compile(r"^https?://(?:127\.0\.0\.1|localhost|\[::1\]):(\d+)")++Probe = Callable[[int], bool]+++def _valid_port(value: Any) -> int | None:+ try:+ port = int(value)+ except (TypeError, ValueError):+ return None+ return port if 1 <= port <= 65535 else None+++def env_port(environ: Mapping[str, str] | None = None) -> int | None:+ """Return ``HEADROOM_PORT`` as a port number, or None when unset/invalid."""+ env = os.environ if environ is None else environ+ raw = (env.get(PORT_ENV) or "").strip()+ return _valid_port(raw) if raw else None+++def default_port(environ: Mapping[str, str] | None = None) -> int:+ """The port a command should use absent ``--port``: ``HEADROOM_PORT`` or 8787."""+ return env_port(environ) or DEFAULT_PROXY_PORT+++def discovery_enabled(environ: Mapping[str, str] | None = None) -> bool:+ """Whether live-proxy discovery may run (``HEADROOM_PORT_DISCOVERY=0`` disables)."""+ env = os.environ if environ is None else environ+ return (env.get(DISCOVERY_ENV) or "").strip().lower() not in {"0", "false", "no", "off"}+++def loopback_port(url: str) -> int | None:+ """Port of a loopback ``http(s)://127.0.0.1|localhost:<port>`` URL, else None."""+ match = _LOOPBACK_PORT_RE.match((url or "").strip())+ return _valid_port(match.group(1)) if match else None+++def _manifest_ports(manifests: Iterable[Any] | None) -> list[int]:+ if manifests is None:+ try:+ from headroom.install.state import list_manifests++ manifests = list_manifests()+ except Exception: # noqa: BLE001 - discovery is best-effort+ return []+ ports: list[int] = []+ for manifest in manifests:+ port = _valid_port(getattr(manifest, "port", None))+ if port is not None:+ ports.append(port)+ return ports+++def _wrap_marker_ports(cwd: Path | None) -> list[int]:+ """Ports recorded by ``wrap claude``'s project marker (read-only, no import of wrap)."""+ marker = (cwd or Path.cwd()) / ".claude" / ".headroom_wrap_marker.json"+ try:+ payload = json.loads(marker.read_text(encoding="utf-8"))+ except (OSError, ValueError):+ return []+ port = _valid_port(payload.get("port")) if isinstance(payload, dict) else None+ return [port] if port is not None else []+++def candidate_ports(+ requested: int,+ *,+ environ: Mapping[str, str] | None = None,+ manifests: Iterable[Any] | None = None,+ cwd: Path | None = None,+ extra: Sequence[int] = (),+) -> list[int]:+ """Ordered, de-duplicated, bounded list of ports worth probing."""+ ordered: list[int] = [requested]+ env_value = env_port(environ)+ if env_value is not None:+ ordered.append(env_value)+ ordered.append(DEFAULT_PROXY_PORT)+ ordered.extend(extra)+ ordered.extend(_manifest_ports(manifests))+ ordered.extend(_wrap_marker_ports(cwd))+ seen: list[int] = []+ for port in ordered:+ if port not in seen:+ seen.append(port)+ return seen[:_MAX_CANDIDATES]+++def probe_headroom_proxy(port: int, timeout: float = _PROBE_TIMEOUT_SECONDS) -> bool:+ """True when a Headroom proxy answers ``/livez`` on loopback ``port``.++ Requires the ``service: headroom-proxy`` identity (or the legacy+ ``alive``+``version`` shape) so an unrelated local server on the port is+ never mistaken for Headroom.+ """+ from headroom.install.health import probe_json++ return is_headroom_livez(probe_json(f"http://127.0.0.1:{port}/livez", timeout=timeout))+++def is_headroom_livez(payload: Mapping[str, Any] | None) -> bool:+ """Whether a ``/livez`` payload identifies a Headroom proxy."""+ if not payload:+ return False+ if payload.get("service") == _HEADROOM_SERVICE:+ return True+ return "alive" in payload and "version" in payload and "service" not in payload+++def live_ports(ports: Sequence[int], probe: Probe | None = None) -> list[int]:+ """Return the subset of ``ports`` with a live Headroom proxy, preserving order."""+ if not ports:+ return []+ check = probe or probe_headroom_proxy+ if len(ports) == 1:+ return [ports[0]] if check(ports[0]) else []+ from concurrent.futures import ThreadPoolExecutor++ with ThreadPoolExecutor(max_workers=len(ports)) as pool:+ results = list(pool.map(check, ports))+ return [port for port, alive in zip(ports, results, strict=True) if alive]+++def find_live_proxy_elsewhere(+ requested: int,+ *,+ environ: Mapping[str, str] | None = None,+ manifests: Iterable[Any] | None = None,+ cwd: Path | None = None,+ probe: Probe | None = None,+ extra: Sequence[int] = (),+) -> int | None:+ """Port of a live Headroom proxy when ``requested`` has none, else None.++ Returns None when discovery is disabled, when ``requested`` itself is live+ (nothing to reconcile), or when no candidate answers. Never raises.+ """+ if not discovery_enabled(environ):+ return None+ try:+ candidates = candidate_ports(+ requested, environ=environ, manifests=manifests, cwd=cwd, extra=extra+ )+ alive = live_ports(candidates, probe=probe)+ except Exception: # noqa: BLE001 - discovery must never break a command+ return None+ if requested in alive:+ return None+ return next((port for port in alive if port != requested), None)+++def _is_interactive() -> bool:+ try:+ return sys.stdin.isatty() and sys.stdout.isatty()+ except (AttributeError, ValueError):+ return False+++def reconcile_default_port(+ requested: int,+ *,+ option_name: str = "--port",+ interactive: bool | None = None,+ environ: Mapping[str, str] | None = None,+ manifests: Iterable[Any] | None = None,+ cwd: Path | None = None,+ probe: Probe | None = None,+) -> int:+ """Return the port to use when the user did not choose one explicitly.++ * No live proxy elsewhere (or ``requested`` is live): ``requested``.+ * A live Headroom proxy on another port and a TTY: ask whether to connect+ to it, keep ``requested``, or abort (``click.Abort``).+ * Non-interactive: keep ``requested`` -- never adopt a port silently -- and+ warn on stderr naming the live port and the flag that selects it.+ """+ live = find_live_proxy_elsewhere(+ requested, environ=environ, manifests=manifests, cwd=cwd, probe=probe+ )+ if live is None:+ return requested+ click.echo(+ f"headroom: no Headroom proxy on port {requested}, but one is running on port {live}.",+ err=True,+ )+ if interactive is None:+ interactive = _is_interactive()+ if not interactive:+ click.echo(+ f"headroom: continuing with port {requested}. To use the running proxy, pass "+ f"{option_name} {live} (or set {PORT_ENV}={live}).",+ err=True,+ )+ return requested+ choice = click.prompt(+ f"Connect to the running proxy on {live} [c], keep port {requested} [k], or abort [a]?",+ type=click.Choice(["c", "k", "a"], case_sensitive=False),+ default="c",+ err=True,+ )+ choice = choice.lower()+ if choice == "a":+ raise click.Abort()+ return live if choice == "c" else requested+++def port_option_callback(ctx: click.Context, param: click.Parameter, value: Any) -> Any:+ """Click callback: reconcile a defaulted ``--port`` with any live proxy.++ An explicit ``--port`` (command line) or ``HEADROOM_PORT`` (the option's+ envvar) is always honored as-is. Only a pure default triggers discovery.+ """+ from click.core import ParameterSource++ if value is None or param.name is None:+ return value+ if ctx.resilient_parsing:+ return value+ if ctx.get_parameter_source(param.name) is not ParameterSource.DEFAULT:+ return value+ option_name = next((opt for opt in param.opts if opt.startswith("--")), "--port")+ return reconcile_default_port(int(value), option_name=option_name)+++def proxy_port_option(*param_decls: str, help_text: str | None = None) -> Callable[[Any], Any]:+ """``--port`` option shared by ``wrap`` subcommands.++ Defaults to ``HEADROOM_PORT`` (else 8787) and, when left at the default,+ detects a live Headroom proxy on another recorded port (see module docs).+ """+ decls = param_decls or ("--port", "-p")+ option: Callable[[Any], Any] = click.option(+ *decls,+ default=DEFAULT_PROXY_PORT,+ envvar=PORT_ENV,+ show_envvar=False,+ type=click.IntRange(1, 65535),+ callback=port_option_callback,+ help=help_text+ or (+ f"Proxy port (default: ${PORT_ENV}, else {DEFAULT_PROXY_PORT}; a live "+ "Headroom proxy on another port is detected and offered)"+ ),+ )+ return option+++_CODEX_HEADROOM_TABLE_RE = re.compile(+ r"(?ms)^[ \t]*\[model_providers\.headroom\][^\n]*\n(?P<body>.*?)(?=^[ \t]*\[|\Z)"+)+_CODEX_BASE_URL_LINE_RE = re.compile(r'(?m)^[ \t]*base_url[ \t]*=[ \t]*"(?P<url>[^"\n]*)"')+++def codex_headroom_provider_port(content: str) -> int | None:+ """Port in an existing ``[model_providers.headroom]`` loopback ``base_url``."""+ table = _CODEX_HEADROOM_TABLE_RE.search(content or "")+ if table is None:+ return None+ base = _CODEX_BASE_URL_LINE_RE.search(table.group("body"))+ return loopback_port(base.group("url")) if base else None+++def warn_codex_provider_port_change(config_path: Path, new_port: int) -> int | None:+ """Warn (stderr) before a Codex headroom provider is repointed to a new port.++ Returns the previous port when it differs from ``new_port``; None otherwise.+ Never raises.+ """+ try:+ if not config_path.exists():+ return None+ previous = codex_headroom_provider_port(+ config_path.read_text(encoding="utf-8", errors="replace")+ )+ except OSError:+ return None+ if previous is None or previous == new_port:+ return None+ click.echo(+ f"headroom: warning: {config_path} routes Codex's [model_providers.headroom] to "+ f"port {previous}; repointing it to port {new_port}. Pass --port {previous} to keep "+ "the existing route.",+ err=True,+ )+ return previousdiff --git a/headroom/cli/recover.py b/headroom/cli/recover.pyindex 8c5cf1e3c..7d2c66a71 100644--- a/headroom/cli/recover.py+++ b/headroom/cli/recover.py@@ -2,12 +2,12 @@from __future__ import annotations-import osfrom pathlib import Pathimport clickfrom headroom.cli.main import main+from headroom.install.paths import codex_home_dirfrom headroom.providers.codex.recovery import (audit_codex_history,discover_dangling_homes,@@ -38,7 +38,7 @@ def recover() -> None:@click.option("--yes", is_flag=True, help="Apply the recovery without prompting.")def recover_codex(sources: tuple[Path, ...], target: Path | None, yes: bool) -> None:"""Merge sessions and configuration from dangling Codex homes."""- target = target or Path(os.environ.get("CODEX_HOME", Path.home() / ".codex"))+ target = target or codex_home_dir()selected_sources = list(sources) or [*discover_dangling_homes(),*discover_retained_sources(target),diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.pyindex 0388c79f3..0968dafcd 100644--- a/headroom/cli/wrap.py+++ b/headroom/cli/wrap.py@@ -61,6 +61,7 @@ from headroom._version import normalize_release_version as _normalize_release_vefrom headroom.agent_savings import (apply_agent_savings_env_defaults,)+from headroom.cli.port_discovery import proxy_port_option, warn_codex_provider_port_changefrom headroom.cli.proxy import ensure_proxy_dependenciesfrom headroom.copilot_auth import (_API_TOKEN_ENV_VARS,@@ -1670,16 +1671,42 @@ def _selfheal_dead_wrap_base_url() -> None:"""try:settings_path = Path.cwd() / ".claude" / "settings.local.json"+ marker_before = _read_wrap_marker(settings_path)for key in (_claude_wrap_base_url_env_key(),_claude_wrap_base_url_env_key(foundry_mode=True),_claude_wrap_base_url_env_key(vertex_mode=True),):_check_and_clear_dead_wrap_marker(settings_path, key=key)+ # The prior value a clear restores may itself be None, so detect the+ # clear by the marker changing rather than by the return value.+ if marker_before is not None and _read_wrap_marker(settings_path) != marker_before:+ _warn_live_proxy_after_selfheal(marker_before)except Exception: # noqa: BLE001 - hook must never break session startuppass+def _warn_live_proxy_after_selfheal(dead_marker: dict[str, Any] | None) -> None:+ """After clearing a dead wrap route, point at a live proxy if one exists.++ Deliberately warn-only: repointing settings at another session's proxy+ would silently adopt a proxy this project never chose (different backend,+ mode, or owner). The message names the exact command instead.+ """+ from headroom.cli.port_discovery import find_live_proxy_elsewhere++ dead_port = dead_marker.get("port") if isinstance(dead_marker, dict) else None+ requested = dead_port if isinstance(dead_port, int) else 8787+ live = find_live_proxy_elsewhere(requested)+ if live is None:+ return+ click.echo(+ f"headroom: a Headroom proxy is running on port {live}; route this project "+ f"through it with: headroom wrap claude --port {live}",+ err=True,+ )++def _wrap_selfheal_hook_command() -> str:"""Command string for the SessionStart self-heal hook (mirrors init hooks)."""from headroom.cli.init import _command_string@@ -2636,10 +2663,9 @@ _CODEX_CONFIG_BACKUP_SUFFIX = ".headroom-backup"def _codex_home_dir() -> Path:"""Return Codex's config directory, respecting ``CODEX_HOME`` when set."""- codex_home = os.environ.get("CODEX_HOME")- if codex_home:- return Path(codex_home).expanduser()- return Path.home() / ".codex"+ from headroom.install.paths import codex_home_dir++ return codex_home_dir()def _codex_profile_from_args(codex_args: tuple[str, ...]) -> str | None:@@ -3147,6 +3173,9 @@ def _inject_codex_provider_config(port: int) -> str | None:"""config_file, backup_file = _codex_config_paths()config_dir = config_file.parent+ # Never repoint an existing headroom provider to another port silently: a+ # different live proxy (or a persistent install) may own the old route.+ warn_codex_provider_port_change(config_file, port)# Detect an existing custom OpenAI-compatible provider BEFORE building the# injected block below, so it can be preserved as the upstream the proxy@@ -5266,13 +5295,8 @@ def wrap_selfheal(marker: str | None) -> None:@wrap.command(context_settings={"ignore_unknown_options": True})@_retired_context_tool_option@_serena_instructions_option- # no "-p" short alias here: claude's own -p/--print must fall through to CLAUDE_ARGS- "--port",- default=8787,- type=click.IntRange(1, 65535),- help="Proxy port (default: 8787)",-)+# no "-p" short alias here: claude's own -p/--print must fall through to CLAUDE_ARGS+@proxy_port_option("--port")@click.option("--no-mcp",is_flag=True,@@ -5849,9 +5873,7 @@ def _require_copilot_subscription_resolution() -> CopilotSubscriptionTokenResolu@wrap.command(context_settings={"ignore_unknown_options": True})@_retired_context_tool_option- "--port", "-p", default=8787, type=click.IntRange(1, 65535), help="Proxy port (default: 8787)"-)+@proxy_port_option()@click.option("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")@click.option("--backend",@@ -6189,7 +6211,7 @@ def copilot(@wrap.command("vscode")[email protected]("--port", "-p", default=8787, type=click.IntRange(1, 65535), help="Proxy port")+@proxy_port_option()@click.option("--memory", is_flag=True, help="Enable persistent cross-session memory")@click.option("--settings-file",@@ -6272,7 +6294,7 @@ def unwrap_vscode_copilot(settings_file: Path | None) -> None:@wrap.command("vscode-claude")[email protected]("--port", "-p", default=8787, type=click.IntRange(1, 65535), help="Proxy port")+@proxy_port_option()@click.option("--memory", is_flag=True, help="Enable persistent cross-session memory")@click.option("--settings-file",@@ -6594,9 +6616,7 @@ def _run_codex_wrap(@wrap.command(context_settings={"ignore_unknown_options": True})@_retired_context_tool_option@_serena_instructions_option- "--port", "-p", default=8787, type=click.IntRange(1, 65535), help="Proxy port (default: 8787)"-)+@proxy_port_option()@click.option("--no-mcp",is_flag=True,@@ -6706,9 +6726,7 @@ def codex(@wrap.command(context_settings={"ignore_unknown_options": True})@_retired_context_tool_option- "--port", "-p", default=8787, type=click.IntRange(1, 65535), help="Proxy port (default: 8787)"-)+@proxy_port_option()@click.option("--code-graph",is_flag=True,@@ -6788,9 +6806,7 @@ def aider(@wrap.command(context_settings={"ignore_unknown_options": True})@_retired_context_tool_option- "--port", "-p", default=8787, type=click.IntRange(1, 65535), help="Proxy port (default: 8787)"-)+@proxy_port_option()@click.option("--code-graph",is_flag=True,@@ -6859,9 +6875,7 @@ def vibe(@wrap.command(context_settings={"ignore_unknown_options": True})@_retired_context_tool_option- "--port", "-p", default=8787, type=click.IntRange(1, 65535), help="Proxy port (default: 8787)"-)+@proxy_port_option()@click.option("--code-graph",is_flag=True,@@ -6953,9 +6967,7 @@ def kimi(@wrap.command(context_settings={"ignore_unknown_options": True})@_retired_context_tool_option@_serena_instructions_option- "--port", "-p", default=8787, type=click.IntRange(1, 65535), help="Proxy port (default: 8787)"-)+@proxy_port_option()@click.option("--no-mcp", is_flag=True, help="Skip headroom MCP server registration")@_code_memory_option@click.option(@@ -7084,9 +7096,7 @@ def grok(@wrap.command(context_settings={"ignore_unknown_options": True})@_retired_context_tool_option- "--port", "-p", default=8787, type=click.IntRange(1, 65535), help="Proxy port (default: 8787)"-)+@proxy_port_option()@click.option("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")@click.option("--learn", is_flag=True, help="Enable live traffic learning (patterns saved to .cursor/rules/)"@@ -7143,9 +7153,7 @@ def cursor(@wrap.command("grok-build", context_settings={"ignore_unknown_options": True})@_retired_context_tool_option- "--port", "-p", default=8787, type=click.IntRange(1, 65535), help="Proxy port (default: 8787)"-)+@proxy_port_option()@click.option("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")@click.option("--learn", is_flag=True, help="Enable live traffic learning")@click.option("--memory", is_flag=True, help="Enable persistent cross-session memory")@@ -7213,9 +7221,7 @@ def grok_build(@wrap.command(context_settings={"ignore_unknown_options": True})@_retired_context_tool_option- "--port", "-p", default=8787, type=click.IntRange(1, 65535), help="Proxy port (default: 8787)"-)+@proxy_port_option()@click.option("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")@click.option("--learn", is_flag=True, help="Enable live traffic learning")@click.option("--memory", is_flag=True, help="Enable persistent cross-session memory")@@ -7278,9 +7284,7 @@ def cline(@wrap.command(context_settings={"ignore_unknown_options": True})@_retired_context_tool_option- "--port", "-p", default=8787, type=click.IntRange(1, 65535), help="Proxy port (default: 8787)"-)+@proxy_port_option()@click.option("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")@click.option("--learn", is_flag=True, help="Enable live traffic learning")@click.option("--memory", is_flag=True, help="Enable persistent cross-session memory")@@ -7344,9 +7348,7 @@ def zcode(@wrap.command("continue", context_settings={"ignore_unknown_options": True})@_retired_context_tool_option- "--port", "-p", default=8787, type=click.IntRange(1, 65535), help="Proxy port (default: 8787)"-)+@proxy_port_option()@click.option("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")@click.option("--learn", is_flag=True, help="Enable live traffic learning")@click.option("--memory", is_flag=True, help="Enable persistent cross-session memory")@@ -7444,8 +7446,8 @@ def continue_dev(is_flag=True,help="Install by copying plugin path instead of using --link",)- "--proxy-port", default=8787, type=click.IntRange(1, 65535), help="Headroom proxy port"+@proxy_port_option(+ "--proxy-port", help_text="Headroom proxy port (default: $HEADROOM_PORT, else 8787)")@click.option("--startup-timeout-ms", default=20000, type=int, help="Proxy startup timeout")@click.option(@@ -7686,9 +7688,7 @@ def openclaw(@wrap.command(context_settings={"ignore_unknown_options": True})@_retired_context_tool_option@_serena_instructions_option- "--port", "-p", default=8787, type=click.IntRange(1, 65535), help="Proxy port (default: 8787)"-)+@proxy_port_option()@click.option("--no-mcp", is_flag=True, help="Skip headroom MCP server registration")@click.option("--no-serena", is_flag=True, help="Skip Serena MCP server registration")@click.option(@@ -8220,9 +8220,7 @@ def unwrap_codex(port: int, no_stop_proxy: bool) -> None:@wrap.command(context_settings={"ignore_unknown_options": True})@_retired_context_tool_option- "--port", "-p", default=8787, type=click.IntRange(1, 65535), help="Proxy port (default: 8787)"-)+@proxy_port_option()@click.option("--code-graph",is_flag=True,@@ -8494,13 +8492,7 @@ def _make_registry_command(target: WrapTarget) -> click.Command:is_flag=True,help="Enable code graph indexing via codebase-memory-mcp (optional)",),- click.option(- "--port",- "-p",- default=8787,- type=click.IntRange(1, 65535),- help="Proxy port (default: 8787)",- ),+ proxy_port_option(),_retired_context_tool_option,):command = decorator(command)diff --git a/headroom/install/paths.py b/headroom/install/paths.pyindex bcca00b0e..6a4e7b8de 100644--- a/headroom/install/paths.py+++ b/headroom/install/paths.py@@ -109,10 +109,41 @@ def claude_settings_path() -> Path:return Path.home() / ".claude" / "settings.json"+def codex_home_dir() -> Path:+ """Return Codex's user config directory, honoring ``CODEX_HOME``.++ Codex itself resolves its home from ``CODEX_HOME`` (falling back to+ ``~/.codex``); every Headroom reader and writer of Codex state must agree+ with it, or ``doctor`` inspects one file while ``wrap``/``init`` write+ another.+ """++ configured = os.environ.get("CODEX_HOME", "").strip()+ if configured:+ return Path(configured).expanduser()+ return Path.home() / ".codex"++def codex_config_path() -> Path:- """Return the Codex config path."""+ """Return the user-level Codex config path (``$CODEX_HOME/config.toml``)."""++ return codex_home_dir() / "config.toml"+++def codex_hooks_path() -> Path:+ """Return the user-level Codex hooks file (``$CODEX_HOME/hooks.json``)."""++ return codex_home_dir() / "hooks.json"+++def codex_project_config_path(cwd: Path | None = None) -> Path:+ """Return the project-scoped Codex config (``<cwd>/.codex/config.toml``).++ Codex layers a trusted project's ``.codex/config.toml`` over the user+ config, and ``headroom init codex`` (without ``-g``) writes there.+ """- return Path.home() / ".codex" / "config.toml"+ return (cwd or Path.cwd()) / ".codex" / "config.toml"def openclaw_config_path() -> Path:diff --git a/headroom/mcp_registry/codex.py b/headroom/mcp_registry/codex.pyindex 8e7c4b25c..2c4bdd591 100644--- a/headroom/mcp_registry/codex.py+++ b/headroom/mcp_registry/codex.py@@ -12,7 +12,6 @@ anything else the user has configured.from __future__ import annotationsimport logging-import osimport sysfrom pathlib import Pathfrom typing import Any@@ -53,10 +52,10 @@ class CodexRegistrar(MCPRegistrar):def __init__(self, *, home_dir: Path | None = None) -> None:if home_dir is not None:self._codex_dir = home_dir / ".codex"- elif os.environ.get("CODEX_HOME"):- self._codex_dir = Path(os.environ["CODEX_HOME"]).expanduser()else:- self._codex_dir = Path.home() / ".codex"+ from headroom.install.paths import codex_home_dir++ self._codex_dir = codex_home_dir()self._config_file = self._codex_dir / "config.toml"# ------------------------------------------------------------------diff --git a/tests/conftest.py b/tests/conftest.pyindex b4f96293a..52c8a50e5 100644--- a/tests/conftest.py+++ b/tests/conftest.py@@ -90,6 +90,17 @@ def _disable_telemetry_beacon(monkeypatch, _scrub_developer_headroom_env):monkeypatch.setenv("HEADROOM_BEACON", "off")+# `wrap`/`init`/`doctor` probe loopback ports (and read deployment manifests)+# to find a live Headroom proxy when --port is left at its default. A+# developer's running proxy would make CLI tests non-deterministic, so+# discovery is off unless a test turns it back on. A developer's CODEX_HOME+# would likewise redirect every Codex path helper away from the test's tmp home.[email protected](autouse=True)+def _disable_live_proxy_discovery(monkeypatch, _scrub_developer_headroom_env):+ monkeypatch.setenv("HEADROOM_PORT_DISCOVERY", "0")+ monkeypatch.delenv("CODEX_HOME", raising=False)++# The MCP install ledger defaults to ``~/.headroom/mcp_installs.json``, so any# test that registers a server (directly or through `wrap`) writes into the# developer's REAL ledger — observed adding a live `claude/serena` entry during adiff --git a/tests/test_cli/test_port_alignment.py b/tests/test_cli/test_port_alignment.pynew file mode 100644index 000000000..78f8f3b23--- /dev/null+++ b/tests/test_cli/test_port_alignment.py@@ -0,0 +1,591 @@+"""CODEX_HOME resolution, live-proxy port discovery, and agent/proxy alignment.++Every test isolates HOME/CODEX_HOME/cwd under ``tmp_path`` and injects fake+probes, so no real ``~/.codex``, ``~/.headroom`` or listening proxy is touched.+"""++from __future__ import annotations++import json+from pathlib import Path+from types import SimpleNamespace+from typing import Any++import click+import pytest+from click.testing import CliRunner++import headroom.cli.doctor as doctor_mod+import headroom.cli.init as init_mod+import headroom.cli.port_discovery as pd+import headroom.cli.wrap as wrap_mod+from headroom.cli.main import main+from headroom.install import paths as install_paths+++def home(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:+ """Fake home + cwd; discovery enabled; HEADROOM_WORKSPACE_DIR sandboxed."""+ fake_home = tmp_path / "home"+ project = tmp_path / "project"+ fake_home.mkdir()+ project.mkdir()+ monkeypatch.setattr(Path, "home", classmethod(lambda cls: fake_home))+ monkeypatch.setenv("HOME", str(fake_home))+ monkeypatch.setenv("USERPROFILE", str(fake_home))+ monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path / "workspace"))+ monkeypatch.delenv("CODEX_HOME", raising=False)+ monkeypatch.delenv("HEADROOM_PORT", raising=False)+ monkeypatch.delenv("HEADROOM_PORT_DISCOVERY", raising=False)+ monkeypatch.chdir(project)+ return fake_home+++def _manifest(profile: str, port: int, targets: list[str] | None = None) -> Any:+ return SimpleNamespace(profile=profile, port=port, targets=targets or [])+++# ---------------------------------------------------------------------------+# 1. CODEX_HOME+# ---------------------------------------------------------------------------+++class TestCodexHome:+ def test_defaults_to_dot_codex(self, home: Path) -> None:+ assert install_paths.codex_home_dir() == home / ".codex"+ assert install_paths.codex_config_path() == home / ".codex" / "config.toml"+ assert install_paths.codex_hooks_path() == home / ".codex" / "hooks.json"++ def test_honors_codex_home(self, home: Path, tmp_path: Path, monkeypatch) -> None:+ custom = tmp_path / "custom-codex"+ monkeypatch.setenv("CODEX_HOME", str(custom))+ assert install_paths.codex_config_path() == custom / "config.toml"+ assert install_paths.codex_hooks_path() == custom / "hooks.json"+ # Every consumer resolves through the one helper.+ assert wrap_mod._codex_home_dir() == custom+ from headroom.mcp_registry.codex import CodexRegistrar++ assert CodexRegistrar()._config_file == custom / "config.toml"++ def test_blank_codex_home_falls_back(self, home: Path, monkeypatch) -> None:+ monkeypatch.setenv("CODEX_HOME", " ")+ assert install_paths.codex_home_dir() == home / ".codex"++ def test_init_global_codex_paths_follow_codex_home(+ self, home: Path, tmp_path: Path, monkeypatch+ ) -> None:+ custom = tmp_path / "custom-codex"+ monkeypatch.setenv("CODEX_HOME", str(custom))+ assert init_mod._codex_scope_path(True) == custom / "config.toml"+ assert init_mod._codex_hooks_path(True) == custom / "hooks.json"+ # Project scope stays in the project.+ assert init_mod._codex_scope_path(False) == Path.cwd() / ".codex" / "config.toml"+ assert init_mod._codex_hooks_path(False) == Path.cwd() / ".codex" / "hooks.json"++ def test_doctor_reads_codex_home_config(self, home: Path, tmp_path: Path, monkeypatch) -> None:+ custom = tmp_path / "custom-codex"+ custom.mkdir()+ (custom / "config.toml").write_text(+ 'model_provider = "headroom"\n[model_providers.headroom]\n'+ 'base_url = "http://127.0.0.1:8787/v1"\nrequires_openai_auth = true\n',+ encoding="utf-8",+ )+ monkeypatch.setenv("CODEX_HOME", str(custom))+ monkeypatch.setattr(doctor_mod, "probe_json", lambda *a, **k: None)+ monkeypatch.setattr(doctor_mod, "list_manifests", lambda: [])+ monkeypatch.setattr(doctor_mod, "claude_settings_path", lambda: home / "settings.json")+ monkeypatch.setattr(doctor_mod, "savings_path", lambda: home / "savings.json")+ result = CliRunner().invoke(main, ["doctor", "--json"])+ codex = next(c for c in json.loads(result.output)["checks"] if c["name"] == "codex")+ assert codex["status"] == "pass", codex+ assert str(custom / "config.toml") in codex["summary"]++ def test_doctor_prefers_project_codex_config(self, tmp_path: Path) -> None:+ user = tmp_path / "user.toml"+ user.write_text(+ '[model_providers.headroom]\nbase_url = "http://127.0.0.1:9999/v1"\n',+ encoding="utf-8",+ )+ project = tmp_path / "project.toml"+ project.write_text(+ '[model_providers.headroom]\nbase_url = "http://127.0.0.1:8787/v1"\n',+ encoding="utf-8",+ )+ result = doctor_mod.check_codex_routing(user, 8787, [project])+ assert result.status == doctor_mod.PASS+ assert str(project) in result.summary++ def test_doctor_missing_config_names_actual_path(self, tmp_path: Path) -> None:+ result = doctor_mod.check_codex_routing(tmp_path / "nope.toml", 8787, [])+ assert result.status == doctor_mod.WARN+ assert str(tmp_path / "nope.toml") in result.summary+++# ---------------------------------------------------------------------------+# 2. Default port: HEADROOM_PORT + live-proxy discovery+# ---------------------------------------------------------------------------+++class TestPortDiscovery:+ def test_default_port_reads_env(self) -> None:+ assert pd.default_port({}) == 8787+ assert pd.default_port({"HEADROOM_PORT": "9100"}) == 9100+ assert pd.default_port({"HEADROOM_PORT": "not-a-port"}) == 8787+ assert pd.default_port({"HEADROOM_PORT": "70000"}) == 8787++ def test_candidates_include_env_manifests_and_wrap_marker(self, tmp_path: Path) -> None:+ (tmp_path / ".claude").mkdir()+ (tmp_path / ".claude" / ".headroom_wrap_marker.json").write_text(+ json.dumps({"port": 9300}), encoding="utf-8"+ )+ ports = pd.candidate_ports(+ 8787,+ environ={"HEADROOM_PORT": "9100"},+ manifests=[_manifest("a", 9200), _manifest("b", 8787)],+ cwd=tmp_path,+ )+ assert ports == [8787, 9100, 9200, 9300]++ def test_candidates_are_bounded(self, tmp_path: Path) -> None:+ manifests = [_manifest(str(i), 10000 + i) for i in range(50)]+ ports = pd.candidate_ports(8787, environ={}, manifests=manifests, cwd=tmp_path)+ assert len(ports) == pd._MAX_CANDIDATES++ def test_finds_live_proxy_on_other_port(self, tmp_path: Path) -> None:+ live = pd.find_live_proxy_elsewhere(+ 8787,+ environ={},+ manifests=[_manifest("p", 9200)],+ cwd=tmp_path,+ probe=lambda port: port == 9200,+ )+ assert live == 9200++ def test_requested_port_live_means_nothing_to_reconcile(self, tmp_path: Path) -> None:+ live = pd.find_live_proxy_elsewhere(+ 8787,+ environ={},+ manifests=[_manifest("p", 9200)],+ cwd=tmp_path,+ probe=lambda port: True,+ )+ assert live is None++ def test_discovery_can_be_disabled(self, tmp_path: Path) -> None:+ live = pd.find_live_proxy_elsewhere(+ 8787,+ environ={"HEADROOM_PORT_DISCOVERY": "0"},+ manifests=[_manifest("p", 9200)],+ cwd=tmp_path,+ probe=lambda port: port == 9200,+ )+ assert live is None++ def test_probe_errors_never_raise(self, tmp_path: Path) -> None:+ def boom(port: int) -> bool:+ raise RuntimeError("nope")++ assert (+ pd.find_live_proxy_elsewhere(+ 8787, environ={}, manifests=[_manifest("p", 9200)], cwd=tmp_path, probe=boom+ )+ is None+ )++ def test_livez_identity_required(self) -> None:+ assert pd.is_headroom_livez({"service": "headroom-proxy", "alive": True})+ assert pd.is_headroom_livez({"alive": True, "version": "1.0"}) # legacy shape+ assert not pd.is_headroom_livez({"service": "something-else", "alive": True})+ assert not pd.is_headroom_livez({"status": "ok"})+ assert not pd.is_headroom_livez(None)++ def test_non_interactive_keeps_requested_and_warns(self, tmp_path: Path, capsys) -> None:+ port = pd.reconcile_default_port(+ 8787,+ interactive=False,+ environ={},+ manifests=[_manifest("p", 9200)],+ cwd=tmp_path,+ probe=lambda p: p == 9200,+ )+ assert port == 8787+ err = capsys.readouterr().err+ assert "port 9200" in err+ assert "--port 9200" in err++ @pytest.mark.parametrize(("answer", "expected"), [("c", 9200), ("k", 8787)])+ def test_interactive_prompt_connect_or_keep(+ self, tmp_path: Path, monkeypatch, answer: str, expected: int+ ) -> None:+ monkeypatch.setattr(pd.click, "prompt", lambda *a, **k: answer)+ port = pd.reconcile_default_port(+ 8787,+ interactive=True,+ environ={},+ manifests=[_manifest("p", 9200)],+ cwd=tmp_path,+ probe=lambda p: p == 9200,+ )+ assert port == expected++ def test_interactive_prompt_abort(self, tmp_path: Path, monkeypatch) -> None:+ monkeypatch.setattr(pd.click, "prompt", lambda *a, **k: "a")+ with pytest.raises(click.Abort):+ pd.reconcile_default_port(+ 8787,+ interactive=True,+ environ={},+ manifests=[_manifest("p", 9200)],+ cwd=tmp_path,+ probe=lambda p: p == 9200,+ )++ def test_no_live_proxy_is_silent(self, tmp_path: Path, capsys) -> None:+ port = pd.reconcile_default_port(+ 8787, interactive=False, environ={}, manifests=[], cwd=tmp_path, probe=lambda p: False+ )+ assert port == 8787+ assert capsys.readouterr().err == ""+++class TestProxyPortOption:+ @pytest.fixture+ def cmd(self) -> click.Command:+ @click.command()+ @pd.proxy_port_option()+ def _cmd(port: int) -> None:+ click.echo(f"port={port}")++ return _cmd++ @pytest.fixture+ def reconcile_calls(self, monkeypatch) -> list[int]:+ calls: list[int] = []++ def fake(requested: int, **kwargs: Any) -> int:+ calls.append(requested)+ return 9200++ monkeypatch.setattr(pd, "reconcile_default_port", fake)+ return calls++ def test_default_triggers_reconcile(self, cmd, reconcile_calls) -> None:+ result = CliRunner().invoke(cmd, [])+ assert result.exit_code == 0, result.output+ assert "port=9200" in result.output+ assert reconcile_calls == [8787]++ def test_explicit_port_is_honored_without_discovery(self, cmd, reconcile_calls) -> None:+ result = CliRunner().invoke(cmd, ["--port", "9500"])+ assert "port=9500" in result.output+ assert reconcile_calls == []++ def test_headroom_port_env_is_honored_without_discovery(self, cmd, reconcile_calls) -> None:+ result = CliRunner().invoke(cmd, [], env={"HEADROOM_PORT": "9400"})+ assert "port=9400" in result.output+ assert reconcile_calls == []++ def test_wrap_subcommands_use_shared_option(self) -> None:+ # Every wrap subcommand with a port option resolves it through the callback.+ wrap_group = main.commands["wrap"]+ assert isinstance(wrap_group, click.Group)+ checked = 0+ for name, command in wrap_group.commands.items():+ for param in command.params:+ if param.name in {"port", "proxy_port"}:+ assert param.callback is pd.port_option_callback, name+ assert param.envvar == "HEADROOM_PORT", name+ checked += 1+ assert checked >= 15+++class TestCodexProviderPortWarning:+ def test_warns_when_repointing(self, tmp_path: Path, capsys) -> None:+ config = tmp_path / "config.toml"+ config.write_text(+ '[model_providers.headroom]\nname = "x"\nbase_url = "http://127.0.0.1:9200/v1"\n',+ encoding="utf-8",+ )+ assert pd.warn_codex_provider_port_change(config, 8787) == 9200+ err = capsys.readouterr().err+ assert "9200" in err and "8787" in err and "--port 9200" in err++ def test_silent_when_same_port_or_absent(self, tmp_path: Path, capsys) -> None:+ config = tmp_path / "config.toml"+ assert pd.warn_codex_provider_port_change(config, 8787) is None+ config.write_text(+ '[model_providers.headroom]\nbase_url = "http://127.0.0.1:8787/v1"\n',+ encoding="utf-8",+ )+ assert pd.warn_codex_provider_port_change(config, 8787) is None+ assert capsys.readouterr().err == ""++ def test_init_provider_write_warns(self, tmp_path: Path, capsys, monkeypatch) -> None:+ monkeypatch.setattr(init_mod, "retag_to_headroom", lambda _path: None)+ config = tmp_path / "config.toml"+ config.write_text(+ '[model_providers.headroom]\nbase_url = "http://127.0.0.1:9200/v1"\n',+ encoding="utf-8",+ )+ init_mod._ensure_codex_provider(config, 8787)+ assert "port 9200" in capsys.readouterr().err+ assert 'base_url = "http://127.0.0.1:8787/v1"' in config.read_text(encoding="utf-8")+++class TestInitPortResolution:+ def _ctx(self, args: list[str]) -> click.Context:+ group = main.commands["init"]+ return group.make_context("init", list(args), resilient_parsing=False)++ def test_explicit_port_wins(self, monkeypatch) -> None:+ monkeypatch.setattr(init_mod, "reconcile_default_port", lambda p, **k: 1)+ ctx = self._ctx(["--port", "9500"])+ assert init_mod._resolve_init_port(ctx, 9500) == 9500++ def test_env_port_used_when_no_flag(self, monkeypatch) -> None:+ monkeypatch.setattr(init_mod, "reconcile_default_port", lambda p, **k: 1)+ monkeypatch.setenv("HEADROOM_PORT", "9400")+ ctx = self._ctx([])+ assert init_mod._resolve_init_port(ctx, 8787) == 9400++ def test_default_reconciles_with_live_proxy(self, monkeypatch) -> None:+ monkeypatch.setattr(init_mod, "reconcile_default_port", lambda p, **k: 9200)+ ctx = self._ctx([])+ assert init_mod._resolve_init_port(ctx, 8787) == 9200++ def test_hook_subcommand_skips_discovery(self, monkeypatch) -> None:+ def fail(*a: Any, **k: Any) -> int:+ raise AssertionError("hook must not run discovery")++ monkeypatch.setattr(init_mod, "reconcile_default_port", fail)+ ctx = self._ctx([])+ ctx.invoked_subcommand = "hook"+ assert init_mod._resolve_init_port(ctx, 8787) == 8787+++# ---------------------------------------------------------------------------+# 3. init hook ensure alignment warning+# ---------------------------------------------------------------------------+++class TestHookAlignment:+ @pytest.fixture+ def claude_settings(self, home: Path, monkeypatch) -> Path:+ path = home / ".claude" / "settings.json"+ path.parent.mkdir(parents=True)+ monkeypatch.setattr(init_mod, "claude_settings_path", lambda: path)+ monkeypatch.setattr(init_mod, "load_manifest", lambda profile: _manifest(profile, 8787))+ monkeypatch.setattr(init_mod, "_ensure_profile_running", lambda profile: None)+ return path++ def _route_claude(self, path: Path, port: int) -> None:+ path.write_text(+ json.dumps({"env": {"ANTHROPIC_BASE_URL": f"http://127.0.0.1:{port}"}}),+ encoding="utf-8",+ )++ def test_aligned_returns_none(self, claude_settings: Path) -> None:+ self._route_claude(claude_settings, 8787)+ assert init_mod.alignment_warning("claude", "init-user", probe=lambda p: True) is None++ def test_mismatch_to_dead_port_suggests_managed_port(self, claude_settings: Path) -> None:+ self._route_claude(claude_settings, 9200)+ message = init_mod.alignment_warning("claude", "init-user", probe=lambda p: False)+ assert message is not None+ assert "9200" in message and "8787" in message+ assert "headroom init -g --port 8787 claude" in message++ def test_mismatch_to_live_port_suggests_live_port(self, claude_settings: Path) -> None:+ self._route_claude(claude_settings, 9200)+ message = init_mod.alignment_warning("claude", "init-user", probe=lambda p: p == 9200)+ assert message is not None+ assert "headroom init -g --port 9200 claude" in message++ def test_codex_mismatch_uses_codex_home(self, home: Path, tmp_path: Path, monkeypatch) -> None:+ custom = tmp_path / "custom-codex"+ custom.mkdir()+ (custom / "config.toml").write_text(+ 'model_provider = "headroom"\n[model_providers.headroom]\n'+ 'base_url = "http://127.0.0.1:9200/v1"\n',+ encoding="utf-8",+ )+ monkeypatch.setenv("CODEX_HOME", str(custom))+ monkeypatch.setattr(init_mod, "load_manifest", lambda profile: _manifest(profile, 8787))+ message = init_mod.alignment_warning("codex", "init-user", probe=lambda p: False)+ assert message is not None and "--port 8787 codex" in message++ def test_session_start_emits_hook_json(self, claude_settings: Path) -> None:+ self._route_claude(claude_settings, 9200)+ result = CliRunner().invoke(+ main,+ [+ "init",+ "hook",+ "ensure",+ "--profile",+ "init-user",+ "--marker",+ "headroom-init-claude",+ ],+ input=json.dumps({"hook_event_name": "SessionStart"}),+ )+ assert result.exit_code == 0, result.output+ payload = json.loads(result.output.strip().splitlines()[-1])+ assert "9200" in payload["systemMessage"]+ assert payload["hookSpecificOutput"]["hookEventName"] == "SessionStart"+ assert payload["hookSpecificOutput"]["additionalContext"] == payload["systemMessage"]++ def test_pre_tool_use_stays_silent(self, claude_settings: Path) -> None:+ self._route_claude(claude_settings, 9200)+ result = CliRunner().invoke(+ main,+ [+ "init",+ "hook",+ "ensure",+ "--profile",+ "init-user",+ "--marker",+ "headroom-init-claude",+ ],+ input=json.dumps({"hook_event_name": "PreToolUse"}),+ )+ assert result.exit_code == 0+ assert result.output.strip() == ""++ def test_never_raises(self, claude_settings: Path, monkeypatch) -> None:+ def boom(*a: Any, **k: Any) -> str:+ raise RuntimeError("broken")++ monkeypatch.setattr(init_mod, "alignment_warning", boom)+ result = CliRunner().invoke(+ main,+ ["init", "hook", "ensure", "--profile", "init-user", "--marker", "headroom-init-codex"],+ input=json.dumps({"hook_event_name": "SessionStart"}),+ )+ assert result.exit_code == 0+ assert result.output.strip() == ""+++# ---------------------------------------------------------------------------+# 4. Doctor: readiness, hooks, live proxy elsewhere+# ---------------------------------------------------------------------------+++class TestDoctorAdditions:+ def test_readiness(self) -> None:+ live = {"service": "headroom-proxy"}+ base = "http://127.0.0.1:8787"+ assert doctor_mod.check_proxy_readiness(None, None, base).status == doctor_mod.SKIP+ assert doctor_mod.check_proxy_readiness(live, None, base).status == doctor_mod.WARN+ assert (+ doctor_mod.check_proxy_readiness(live, {"ready": True}, base).status == doctor_mod.PASS+ )++ def _hooks_file(self, path: Path, command: str) -> None:+ path.parent.mkdir(parents=True, exist_ok=True)+ path.write_text(+ json.dumps(+ {+ "hooks": {+ "SessionStart": [+ {+ "matcher": "startup",+ "hooks": [{"type": "command", "command": command}],+ }+ ]+ }+ }+ ),+ encoding="utf-8",+ )++ def test_hooks_present(self, tmp_path: Path) -> None:+ exe = tmp_path / "headroom-bin"+ exe.write_text("", encoding="utf-8")+ hooks = tmp_path / "hooks.json"+ self._hooks_file(hooks, f"{exe.as_posix()} init hook ensure --marker headroom-init-codex")+ result = doctor_mod.check_installed_hooks(+ [("codex", "user", hooks, "headroom init -g codex")]+ )+ assert result.status == doctor_mod.PASS, result++ def test_hooks_missing(self, tmp_path: Path) -> None:+ result = doctor_mod.check_installed_hooks(+ [("claude", "user", tmp_path / "settings.json", "headroom init -g claude")]+ )+ assert result.status == doctor_mod.WARN+ assert "headroom init -g claude" in (result.hint or "")++ def test_hook_program_missing(self, tmp_path: Path) -> None:+ hooks = tmp_path / "settings.json"+ gone = (tmp_path / "gone" / "headroom").as_posix()+ self._hooks_file(hooks, f"{gone} init hook ensure --marker headroom-init-claude")+ result = doctor_mod.check_installed_hooks(+ [("claude", "user", hooks, "headroom init -g claude")]+ )+ assert result.status == doctor_mod.WARN+ assert "not found" in result.summary++ def test_no_init_means_skip(self) -> None:+ assert doctor_mod.check_installed_hooks([]).status == doctor_mod.SKIP++ def test_expected_hooks_from_manifests(self, home: Path, tmp_path: Path, monkeypatch) -> None:+ custom = tmp_path / "custom-codex"+ monkeypatch.setenv("CODEX_HOME", str(custom))+ monkeypatch.setattr(doctor_mod, "claude_settings_path", lambda: home / "settings.json")+ local = init_mod._local_profile(Path.cwd())+ expected = doctor_mod.expected_init_hooks(+ [+ _manifest("init-user", 9200, ["claude", "codex"]),+ _manifest(local, 8787, ["claude"]),+ _manifest("someone-else", 8787, ["claude"]),+ ],+ cwd=Path.cwd(),+ )+ assert ("codex", "user", custom / "hooks.json", "headroom init -g --port 9200 codex") in (+ expected+ )+ assert (+ "claude",+ "project",+ Path.cwd() / ".claude" / "settings.local.json",+ "headroom init claude",+ ) in expected+ assert len(expected) == 3++ def test_doctor_names_live_proxy_on_other_port(self, home: Path, monkeypatch) -> None:+ def fake_probe(url: str, timeout: float = 2.0) -> dict[str, Any] | None:+ if url == "http://127.0.0.1:9200/livez":+ return {"service": "headroom-proxy", "alive": True, "version": "1"}+ return None++ monkeypatch.setattr(doctor_mod, "probe_json", fake_probe)+ monkeypatch.setattr(doctor_mod, "list_manifests", lambda: [_manifest("prod", 9200)])+ monkeypatch.setattr(doctor_mod, "check_deployments", lambda manifests: None)+ monkeypatch.setattr(doctor_mod, "claude_settings_path", lambda: home / "settings.json")+ monkeypatch.setattr(doctor_mod, "savings_path", lambda: home / "savings.json")+ result = CliRunner().invoke(main, ["doctor", "--json"])+ payload = json.loads(result.output)+ assert payload["exit_code"] == 2 # still a failure at the probed port+ proxy = next(c for c in payload["checks"] if c["name"] == "proxy")+ assert "port 9200" in proxy["summary"]+ assert "headroom doctor --port 9200" in proxy["hint"]+++# ---------------------------------------------------------------------------+# wrap selfheal: warn (never repoint) when a live proxy exists elsewhere+# ---------------------------------------------------------------------------+++class TestSelfhealWarning:+ def test_warns_with_live_port(self, monkeypatch, capsys) -> None:+ monkeypatch.setattr(pd, "find_live_proxy_elsewhere", lambda requested, **k: 9200)+ wrap_mod._warn_live_proxy_after_selfheal({"port": 8787})+ err = capsys.readouterr().err+ assert "headroom wrap claude --port 9200" in err++ def test_silent_without_live_proxy(self, monkeypatch, capsys) -> None:+ monkeypatch.setattr(pd, "find_live_proxy_elsewhere", lambda requested, **k: None)+ wrap_mod._warn_live_proxy_after_selfheal({"port": 8787})+ assert capsys.readouterr().err == ""diff --git a/tests/test_cli_doctor.py b/tests/test_cli_doctor.pyindex 7b6ff021c..f257578ac 100644--- a/tests/test_cli_doctor.py+++ b/tests/test_cli_doctor.py@@ -796,6 +796,9 @@ class TestDoctorCommand:"""Point all filesystem/network surfaces at controlled fakes."""monkeypatch.setattr(doctor_mod, "claude_settings_path", lambda: tmp_path / "settings.json")monkeypatch.setattr(doctor_mod, "codex_config_path", lambda: tmp_path / "config.toml")+ monkeypatch.setattr(+ doctor_mod, "codex_project_config_path", lambda: tmp_path / "project-codex.toml"+ )monkeypatch.setattr(doctor_mod, "savings_path", lambda: tmp_path / "savings.json")monkeypatch.setattr(doctor_mod, "list_manifests", lambda: [])for var in (