Skip to content

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.

fix(cli): name the broken Codex config, write init configs atomically, keep the identity check (#4129)

Tejas Chopra976aa714ef3e
diff --git a/headroom/cli/init.py b/headroom/cli/init.py
index 4cf293918..abf950be7 100644
--- a/headroom/cli/init.py
+++ b/headroom/cli/init.py
@@ -16,6 +16,7 @@ from hashlib import sha1
from pathlib import Path
from typing import Any
+from headroom import fsutil
from headroom._subprocess import run
try:
@@ -69,15 +70,6 @@ from .main import main
logger = logging.getLogger(__name__)
-def _wait_for_runtime_ready(manifest: Any, timeout_seconds: int) -> bool:
- """Keep hook recovery gated by both readiness and runtime identity."""
- try:
- return wait_ready(manifest, timeout_seconds=timeout_seconds, require_identity=True)
- except TypeError:
- # Compatibility for test doubles that predate the keyword-only guard.
- return wait_ready(manifest, timeout_seconds=timeout_seconds)
-
-
_VERBOSE_HANDLER_ATTR = "_headroom_init_verbose_handler"
_GLOBAL_PROFILE = "init-user"
@@ -208,7 +200,7 @@ def _json_file(path: Path) -> dict[str, Any]:
def _write_json(path: Path, payload: dict[str, Any]) -> None:
logger.debug("write json: %s (keys=%s)", path, sorted(payload.keys()))
path.parent.mkdir(parents=True, exist_ok=True)
- path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+ fsutil.write_text(path, json.dumps(payload, indent=2) + "\n")
def _ensure_claude_hooks(path: Path, profile: str, port: int) -> None:
@@ -491,7 +483,7 @@ def _ensure_codex_provider(path: Path, port: int) -> None:
)
path.parent.mkdir(parents=True, exist_ok=True)
tomllib.loads(content)
- path.write_text(content, encoding="utf-8")
+ fsutil.write_text(path, content)
# Codex filters its history menu by the active model_provider, so existing
# native threads vanish once we switch to "headroom". Retag them to match the
# active provider so the history stays whole (#961), mirroring the install
@@ -621,7 +613,7 @@ def _ensure_codex_feature_flag(path: Path) -> None:
content.rstrip() + "\n\n[features]\n\n" + _codex_feature_block() + "\n"
).lstrip()
path.parent.mkdir(parents=True, exist_ok=True)
- path.write_text(content, encoding="utf-8")
+ fsutil.write_text(path, content)
def _ensure_codex_hooks(path: Path, profile: str) -> None:
@@ -883,17 +875,22 @@ def _ensure_profile_running(profile: str) -> None:
return
if manifest is None:
return
+ failure: str | None = None
with _suppress_hook_output():
- if _wait_for_runtime_ready(manifest, timeout_seconds=1):
+ if wait_ready(manifest, timeout_seconds=1, require_identity=True):
return
try:
with acquire_runtime_start_lock(manifest.profile) as acquired:
if not acquired:
return
- if _wait_for_runtime_ready(manifest, timeout_seconds=1):
+ if wait_ready(manifest, timeout_seconds=1, require_identity=True):
return
if runtime_status(manifest) == "running":
- if _wait_for_runtime_ready(manifest, _STARTUP_READY_TIMEOUT_SECONDS):
+ if wait_ready(
+ manifest,
+ timeout_seconds=_STARTUP_READY_TIMEOUT_SECONDS,
+ require_identity=True,
+ ):
return
stop_runtime(manifest)
if runtime_ownership(manifest) == "docker-supervisor":
@@ -902,9 +899,21 @@ def _ensure_profile_running(profile: str) -> None:
start_supervisor(manifest)
else:
start_detached_agent(manifest.profile)
- _wait_for_runtime_ready(manifest, 45)
- except Exception:
- return
+ if not wait_ready(manifest, timeout_seconds=45, require_identity=True):
+ failure = "it did not become ready within 45s"
+ except (click.ClickException, RuntimeError, OSError, subprocess.SubprocessError) as exc:
+ # Supervisor and runtime starts raise these; anything else is a bug
+ # and should surface. Report outside the suppressed block so the
+ # one line reaches stderr while stdout stays clean for the hook.
+ failure = str(exc)
+ if failure is not None:
+ logger.warning(
+ "headroom: could not start persistent proxy %r: %s. "
+ "Check it with `headroom install status --profile %s`.",
+ manifest.profile,
+ failure,
+ manifest.profile,
+ )
def _probe_init_targets(global_scope: bool) -> list[tuple[str, str | None]]:
diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.py
index 58615a45c..0f751073d 100644
--- a/headroom/cli/wrap.py
+++ b/headroom/cli/wrap.py
@@ -171,6 +171,7 @@ from headroom.providers.grok import (
)
from headroom.providers.grok_build import render_setup_lines as _render_grok_build_setup_lines
from headroom.providers.grok_build.config import (
+ grok_config_paths,
inject_grok_provider_config,
restore_grok_provider_config,
)
@@ -3641,12 +3642,31 @@ def _inject_codex_provider_config(port: int) -> str | None:
_snapshot_codex_config_if_unwrapped(config_file, backup_file)
if config_file.exists():
- content = _read_text(config_file)
+ original = _read_text(config_file)
# Remove any prior Headroom-managed blocks before re-injecting so
# the operation is idempotent and supports port changes.
- content = _strip_codex_headroom_blocks(content)
+ content = _strip_codex_headroom_blocks(original)
content = _strip_existing_codex_headroom_provider_table(content)
+ # Report a broken file in the user's own terms. The candidate
+ # validated below is the merged text, so its parse error would
+ # name a line the user never wrote. Only the user's part has to
+ # parse: stripping a stale Headroom block may be what repairs it.
+ try:
+ tomllib.loads(content)
+ except tomllib.TOMLDecodeError:
+ try:
+ tomllib.loads(original)
+ reason = "it is no longer valid TOML once Headroom's block is removed"
+ except tomllib.TOMLDecodeError as exc:
+ reason = f"it is not valid TOML ({exc})"
+ click.echo(
+ f" Warning: could not update Codex config {config_file}: {reason}; "
+ "Codex WebSocket traffic will bypass Headroom. Fix or remove the file, "
+ "then re-run."
+ )
+ return None
+
# Bare top-level keys must precede any [section] in TOML, and
# TOML rejects duplicate top-level keys. Rewrite any existing
# top-level ``model_provider`` / ``openai_base_url`` in place
@@ -3697,7 +3717,7 @@ def _inject_codex_provider_config(port: int) -> str | None:
# history list stays whole once it routes through Headroom. Best-effort.
retag_to_headroom(_codex_home_dir())
except Exception as e:
- click.echo(f" Warning: could not update Codex config: {e}")
+ click.echo(f" Warning: could not update Codex config {config_file}: {e}")
return None
return custom_upstream_base_url
@@ -4516,17 +4536,6 @@ def _find_persistent_manifest(port: int) -> Any:
return manifests[0] if manifests else None
-def _wait_for_runtime_ready(manifest: Any, timeout_seconds: int) -> bool:
- """Keep wrap recovery gated by both readiness and runtime identity."""
- from headroom.install.runtime import wait_ready
-
- try:
- return wait_ready(manifest, timeout_seconds=timeout_seconds, require_identity=True)
- except TypeError:
- # Compatibility for test doubles that predate the keyword-only guard.
- return wait_ready(manifest, timeout_seconds=timeout_seconds)
-
-
def _recover_persistent_proxy(port: int) -> bool:
"""Start or recover a matching persistent deployment for the requested port."""
from headroom.install.models import SupervisorKind
@@ -4535,6 +4544,7 @@ def _recover_persistent_proxy(port: int) -> bool:
runtime_ready,
start_detached_agent,
start_persistent_docker,
+ wait_ready,
)
from headroom.install.supervisors import start_supervisor
@@ -4569,7 +4579,7 @@ def _recover_persistent_proxy(port: int) -> bool:
)
return False
- if _wait_for_runtime_ready(manifest, 45):
+ if wait_ready(manifest, timeout_seconds=45, require_identity=True):
click.echo(f" Recovered persistent deployment '{manifest.profile}' on port {port}")
return True
@@ -4585,6 +4595,7 @@ def _restart_persistent_proxy(manifest: Any, port: int) -> bool:
start_detached_agent,
start_persistent_docker,
stop_runtime,
+ wait_ready,
)
from headroom.install.supervisors import start_supervisor
@@ -4609,7 +4620,7 @@ def _restart_persistent_proxy(manifest: Any, port: int) -> bool:
)
return False
- if _wait_for_runtime_ready(manifest, 45):
+ if wait_ready(manifest, timeout_seconds=45, require_identity=True):
click.echo(f" Restarted persistent deployment '{manifest.profile}' on port {port}")
return True
@@ -7815,7 +7826,7 @@ def grok_build(
config_file = inject_grok_provider_config(port, project=project)
click.echo(f" Grok config: injected Headroom proxy override into {config_file}")
except Exception as e:
- click.echo(f" Warning: could not update Grok config: {e}")
+ click.echo(f" Warning: could not update Grok config {grok_config_paths()[0]}: {e}")
return
def _print_grok_build_setup(actual_port: int) -> None:
@@ -7824,7 +7835,7 @@ def grok_build(
click.echo(f" Grok config: injected Headroom proxy override into {config_file}")
click.echo()
except Exception as e:
- click.echo(f" Warning: could not update Grok config: {e}")
+ click.echo(f" Warning: could not update Grok config {grok_config_paths()[0]}: {e}")
click.echo()
for line in _render_grok_build_setup_lines(actual_port, project=project):
click.echo(line)
diff --git a/tests/test_cli/test_init_cli.py b/tests/test_cli/test_init_cli.py
index 0566ea476..c8710726e 100644
--- a/tests/test_cli/test_init_cli.py
+++ b/tests/test_cli/test_init_cli.py
@@ -1259,7 +1259,8 @@ def test_ensure_profile_running_covers_runtime_modes(monkeypatch) -> None:
monkeypatch.setattr(init_cli, "acquire_runtime_start_lock", fake_start_lock)
- def fake_wait_ready(manifest, timeout_seconds: int) -> bool:
+ def fake_wait_ready(manifest, timeout_seconds: int, require_identity: bool) -> bool:
+ assert require_identity is True
wait_calls.append((manifest.profile, timeout_seconds))
return False
@@ -1297,7 +1298,9 @@ def test_ensure_profile_running_suppresses_hook_recovery_output(monkeypatch, cap
)
monkeypatch.setattr(init_cli, "load_manifest", lambda profile: manifest)
- monkeypatch.setattr(init_cli, "wait_ready", lambda manifest, timeout_seconds: False)
+ monkeypatch.setattr(
+ init_cli, "wait_ready", lambda manifest, timeout_seconds, require_identity: False
+ )
def noisy_start_supervisor(manifest) -> None:
print("python stdout")
@@ -1324,7 +1327,9 @@ def test_ensure_profile_running_returns_when_ready_or_on_exception(monkeypatch)
)
detached_calls: list[str] = []
monkeypatch.setattr(init_cli, "load_manifest", lambda profile: manifest)
- monkeypatch.setattr(init_cli, "wait_ready", lambda manifest, timeout_seconds: True)
+ monkeypatch.setattr(
+ init_cli, "wait_ready", lambda manifest, timeout_seconds, require_identity: True
+ )
monkeypatch.setattr(
init_cli,
"start_detached_agent",
@@ -1340,7 +1345,9 @@ def test_ensure_profile_running_returns_when_ready_or_on_exception(monkeypatch)
monkeypatch.setattr(init_cli, "acquire_runtime_start_lock", fake_start_lock)
monkeypatch.setattr(init_cli, "runtime_status", lambda manifest: "stopped")
- monkeypatch.setattr(init_cli, "wait_ready", lambda manifest, timeout_seconds: False)
+ monkeypatch.setattr(
+ init_cli, "wait_ready", lambda manifest, timeout_seconds, require_identity: False
+ )
monkeypatch.setattr(
init_cli,
"start_detached_agent",
@@ -1363,7 +1370,9 @@ def test_ensure_profile_running_skips_spawn_when_start_lock_is_held(monkeypatch)
yield False
monkeypatch.setattr(init_cli, "load_manifest", lambda profile: manifest)
- monkeypatch.setattr(init_cli, "wait_ready", lambda manifest, timeout_seconds: False)
+ monkeypatch.setattr(
+ init_cli, "wait_ready", lambda manifest, timeout_seconds, require_identity: False
+ )
monkeypatch.setattr(init_cli, "acquire_runtime_start_lock", fake_start_lock)
monkeypatch.setattr(
init_cli,
@@ -1391,7 +1400,8 @@ def test_ensure_profile_running_does_not_spawn_again_during_slow_startup(monkeyp
def fake_start_lock(profile: str):
yield True
- def fake_wait_ready(manifest, timeout_seconds: int) -> bool:
+ def fake_wait_ready(manifest, timeout_seconds: int, require_identity: bool) -> bool:
+ assert require_identity is True
wait_calls.append(timeout_seconds)
return bool(detached_calls and timeout_seconds == init_cli._STARTUP_READY_TIMEOUT_SECONDS)
@@ -1711,3 +1721,137 @@ def test_local_profile_distinguishes_identical_non_ascii_names(monkeypatch, tmp_
second.mkdir(parents=True)
assert init_cli._local_profile(first) != init_cli._local_profile(second)
+
+
+def test_write_json_keeps_the_existing_file_when_the_write_fails(monkeypatch, tmp_path) -> None:
+ """``init`` rewrites user-owned files such as ~/.claude/settings.json.
+
+ A plain ``write_text`` truncates first, so a failure mid-write (ENOSPC,
+ SIGKILL) left a half-written file; the write must be atomic.
+ """
+ init_cli, _ = _load_init_module(monkeypatch)
+ settings = tmp_path / ".claude" / "settings.json"
+ settings.parent.mkdir(parents=True)
+ settings.write_text('{"theme": "dark"}\n', encoding="utf-8")
+
+ def fail_fsync(_fd: int) -> None:
+ raise OSError(28, "No space left on device")
+
+ monkeypatch.setattr("headroom.fsutil.os.fsync", fail_fsync)
+
+ with pytest.raises(OSError, match="No space left"):
+ init_cli._write_json(settings, {"theme": "dark", "env": {"A": "1"}})
+
+ assert settings.read_text(encoding="utf-8") == '{"theme": "dark"}\n'
+ assert [p.name for p in settings.parent.iterdir()] == ["settings.json"]
+
+
+def test_ensure_profile_running_never_retries_wait_ready_without_identity(monkeypatch) -> None:
+ """A TypeError from wait_ready must surface, not trigger an unchecked retry.
+
+ A removed fallback caught TypeError and re-called wait_ready without
+ require_identity=True, silently dropping the runtime identity check.
+ """
+ init_cli, _ = _load_init_module(monkeypatch)
+ manifest = SimpleNamespace(
+ preset=init_cli.InstallPreset.PERSISTENT_TASK.value,
+ supervisor_kind=init_cli.SupervisorKind.NONE.value,
+ profile="task-profile",
+ )
+ calls: list[dict[str, object]] = []
+
+ def strict_wait_ready(manifest, **kwargs) -> bool:
+ calls.append(kwargs)
+ if "require_identity" in kwargs:
+ raise TypeError("boom")
+ return False
+
+ @contextmanager
+ def held_lock(profile: str):
+ yield False
+
+ monkeypatch.setattr(init_cli, "load_manifest", lambda profile: manifest)
+ monkeypatch.setattr(init_cli, "wait_ready", strict_wait_ready)
+ monkeypatch.setattr(init_cli, "acquire_runtime_start_lock", held_lock)
+
+ with pytest.raises(TypeError, match="boom"):
+ init_cli._ensure_profile_running("task-profile")
+
+ assert calls == [{"timeout_seconds": 1, "require_identity": True}]
+
+
+def test_ensure_profile_running_logs_a_failed_recovery(monkeypatch, caplog) -> None:
+ init_cli, _ = _load_init_module(monkeypatch)
+ manifest = SimpleNamespace(
+ preset=init_cli.InstallPreset.PERSISTENT_TASK.value,
+ supervisor_kind=init_cli.SupervisorKind.SERVICE.value,
+ profile="service-profile",
+ )
+
+ @contextmanager
+ def fake_start_lock(profile: str):
+ yield True
+
+ monkeypatch.setattr(init_cli, "load_manifest", lambda profile: manifest)
+ monkeypatch.setattr(init_cli, "acquire_runtime_start_lock", fake_start_lock)
+ monkeypatch.setattr(init_cli, "runtime_status", lambda manifest: "stopped")
+ monkeypatch.setattr(init_cli, "runtime_ownership", lambda manifest: "service")
+ monkeypatch.setattr(
+ init_cli,
+ "wait_ready",
+ lambda manifest, timeout_seconds, require_identity: timeout_seconds == 45,
+ )
+ monkeypatch.setattr(init_cli, "start_supervisor", lambda manifest: None)
+
+ with caplog.at_level("WARNING", logger="headroom.cli.init"):
+ init_cli._ensure_profile_running("service-profile")
+ assert not [r for r in caplog.records if r.name == "headroom.cli.init"]
+
+ monkeypatch.setattr(
+ init_cli,
+ "start_supervisor",
+ lambda manifest: (_ for _ in ()).throw(RuntimeError("launchctl bootstrap failed")),
+ )
+ with caplog.at_level("WARNING", logger="headroom.cli.init"):
+ init_cli._ensure_profile_running("service-profile")
+
+ messages = [r.getMessage() for r in caplog.records if r.name == "headroom.cli.init"]
+ assert messages == [
+ "headroom: could not start persistent proxy 'service-profile': launchctl bootstrap "
+ "failed. Check it with `headroom install status --profile service-profile`."
+ ]
+
+
+def test_ensure_profile_running_logs_a_recovery_that_never_becomes_ready(
+ monkeypatch, caplog
+) -> None:
+ init_cli, _ = _load_init_module(monkeypatch)
+ manifest = SimpleNamespace(
+ preset=init_cli.InstallPreset.PERSISTENT_TASK.value,
+ supervisor_kind=init_cli.SupervisorKind.NONE.value,
+ profile="task-profile",
+ )
+ started: list[str] = []
+
+ @contextmanager
+ def fake_start_lock(profile: str):
+ yield True
+
+ monkeypatch.setattr(init_cli, "load_manifest", lambda profile: manifest)
+ monkeypatch.setattr(init_cli, "acquire_runtime_start_lock", fake_start_lock)
+ monkeypatch.setattr(init_cli, "runtime_status", lambda manifest: "stopped")
+ monkeypatch.setattr(init_cli, "runtime_ownership", lambda manifest: "task")
+ monkeypatch.setattr(
+ init_cli, "wait_ready", lambda manifest, timeout_seconds, require_identity: False
+ )
+ monkeypatch.setattr(init_cli, "start_detached_agent", started.append)
+
+ with caplog.at_level("WARNING", logger="headroom.cli.init"):
+ init_cli._ensure_profile_running("task-profile")
+
+ assert started == ["task-profile"]
+ messages = [r.getMessage() for r in caplog.records if r.name == "headroom.cli.init"]
+ assert messages == [
+ "headroom: could not start persistent proxy 'task-profile': it did not become ready "
+ "within 45s. Check it with `headroom install status --profile task-profile`."
+ ]
diff --git a/tests/test_cli/test_wrap_codex.py b/tests/test_cli/test_wrap_codex.py
index 872e55966..6422128fe 100644
--- a/tests/test_cli/test_wrap_codex.py
+++ b/tests/test_cli/test_wrap_codex.py
@@ -437,6 +437,27 @@ class TestCodexMemoryMcpConfig:
class TestInjectAndRestoreRoundTrip:
"""End-to-end wrap → unwrap cycle operating directly on a temp $HOME."""
+ def test_invalid_user_config_is_named_and_left_untouched(
+ self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path, capsys: pytest.CaptureFixture[str]
+ ) -> None:
+ """A broken config.toml is reported by path, with the user's own line.
+
+ The merged candidate used to be the first thing parsed, so the warning
+ named a line in Headroom's generated text and no file at all.
+ """
+ _set_test_home(monkeypatch, tmp_path)
+ config_file = tmp_path / ".codex" / "config.toml"
+ config_file.parent.mkdir(parents=True)
+ config_file.write_text("model = [unterminated\n", encoding="utf-8")
+
+ assert wrap_mod._inject_codex_provider_config(8787) is None
+
+ out = capsys.readouterr().out
+ assert f"could not update Codex config {config_file}: it is not valid TOML" in out
+ assert "line 1" in out
+ assert "Fix or remove the file, then re-run." in out
+ assert config_file.read_text(encoding="utf-8") == "model = [unterminated\n"
+
def test_wrap_unwrap_restores_empty_state(
self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
diff --git a/tests/test_cli/test_wrap_persistent.py b/tests/test_cli/test_wrap_persistent.py
index 6f156308f..828e84abb 100644
--- a/tests/test_cli/test_wrap_persistent.py
+++ b/tests/test_cli/test_wrap_persistent.py
@@ -48,7 +48,8 @@ def test_ensure_proxy_recovers_matching_persistent_deployment(monkeypatch) -> No
lambda manifest: calls.append(f"start:{manifest.profile}"),
)
monkeypatch.setattr(
- "headroom.install.runtime.wait_ready", lambda manifest, timeout_seconds=45: True
+ "headroom.install.runtime.wait_ready",
+ lambda manifest, timeout_seconds=45, require_identity=False: True,
)
monkeypatch.setattr(
wrap_cli,
@@ -81,7 +82,8 @@ def test_ensure_proxy_recovers_persistent_deployment_when_socket_is_bound(monkey
lambda manifest: calls.append(f"start:{manifest.profile}"),
)
monkeypatch.setattr(
- "headroom.install.runtime.wait_ready", lambda manifest, timeout_seconds=45: True
+ "headroom.install.runtime.wait_ready",
+ lambda manifest, timeout_seconds=45, require_identity=False: True,
)
monkeypatch.setattr(
wrap_cli,
@@ -332,12 +334,15 @@ def test_recover_persistent_proxy_routes_docker_task_to_docker_supervisor(monkey
"headroom.install.runtime.start_persistent_docker",
lambda manifest: calls.append("docker"),
)
+ waits: list[dict[str, object]] = []
monkeypatch.setattr(
- "headroom.install.runtime.wait_ready", lambda manifest, timeout_seconds=45: True
+ "headroom.install.runtime.wait_ready",
+ lambda manifest, **kwargs: waits.append(kwargs) or True,
)
assert wrap_cli._recover_persistent_proxy(8787) is True
assert calls == ["docker"]
+ assert waits == [{"timeout_seconds": 45, "require_identity": True}]
def test_ensure_proxy_restarts_idle_stale_ephemeral_proxy(monkeypatch) -> None: