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(install): write deployment manifest atomically and tolerate corrupt manifests (#1303)

Leoy42bdf23d2413
diff --git a/headroom/install/state.py b/headroom/install/state.py
index 03070a329..9480f4b5d 100644
--- a/headroom/install/state.py
+++ b/headroom/install/state.py
@@ -4,8 +4,11 @@ from __future__ import annotations
import json
import logging
+import os
import shutil
+import tempfile
from dataclasses import asdict
+from pathlib import Path
from .models import ArtifactRecord, DeploymentManifest, ManagedMutation, iso_utc_now
from .paths import deploy_root, manifest_path, profile_root
@@ -17,18 +20,42 @@ class ManifestError(Exception):
"""A deployment manifest exists on disk but could not be parsed."""
+def _atomic_write_text(path: Path, data: str) -> None:
+ """Write ``data`` to ``path`` atomically.
+
+ The payload is written to a temporary file in the same directory, flushed and
+ fsynced, then moved into place with :func:`os.replace` (an atomic rename on
+ both POSIX and Windows). A crash between truncate and full write therefore
+ leaves either the previous file or the complete new one on disk, never a
+ truncated manifest.
+ """
+ directory = path.parent
+ fd, tmp_name = tempfile.mkstemp(dir=directory, prefix=f".{path.name}.", suffix=".tmp")
+ tmp_path = Path(tmp_name)
+ try:
+ with os.fdopen(fd, "w", encoding="utf-8") as handle:
+ handle.write(data)
+ handle.flush()
+ os.fsync(handle.fileno())
+ os.replace(tmp_path, path)
+ except BaseException:
+ tmp_path.unlink(missing_ok=True)
+ raise
+
+
def save_manifest(manifest: DeploymentManifest) -> None:
"""Persist a deployment manifest to disk.
- Gracefully handles read-only filesystems by logging a warning
- instead of crashing.
+ The write is atomic so an interrupted save (SIGKILL, system restart, OOM)
+ cannot leave a truncated ``manifest.json`` behind. Gracefully handles
+ read-only filesystems by logging a warning instead of crashing.
"""
try:
root = profile_root(manifest.profile)
root.mkdir(parents=True, exist_ok=True)
manifest.updated_at = iso_utc_now()
path = manifest_path(manifest.profile)
- path.write_text(json.dumps(asdict(manifest), indent=2) + "\n", encoding="utf-8")
+ _atomic_write_text(path, json.dumps(asdict(manifest), indent=2) + "\n")
except OSError as e:
logger.warning("Cannot save deployment manifest: %s — continuing without persistence", e)
diff --git a/tests/test_install/test_state.py b/tests/test_install/test_state.py
index eb751dd53..a053a4d8f 100644
--- a/tests/test_install/test_state.py
+++ b/tests/test_install/test_state.py
@@ -2,8 +2,16 @@ from __future__ import annotations
from pathlib import Path
+import pytest
+
from headroom.install.models import ArtifactRecord, DeploymentManifest, ManagedMutation
-from headroom.install.state import delete_manifest, list_manifests, load_manifest, save_manifest
+from headroom.install.state import (
+ ManifestError,
+ delete_manifest,
+ list_manifests,
+ load_manifest,
+ save_manifest,
+)
def _manifest() -> DeploymentManifest:
@@ -36,6 +44,33 @@ def test_save_and_load_manifest_round_trip(monkeypatch, tmp_path: Path) -> None:
assert loaded.artifacts[0].kind == "script"
+def test_load_manifest_raises_manifest_error_on_corrupt_payload(
+ monkeypatch, tmp_path: Path
+) -> None:
+ monkeypatch.setattr(Path, "home", lambda: tmp_path)
+ # Simulate a crash mid-write: a truncated/garbage manifest left on disk.
+ profile_dir = tmp_path / ".headroom" / "deploy" / "default"
+ profile_dir.mkdir(parents=True)
+ (profile_dir / "manifest.json").write_text("{not json", encoding="utf-8")
+
+ # A present-but-corrupt manifest surfaces a typed ManifestError so callers can
+ # report cleanly or degrade, rather than a raw JSONDecodeError traceback.
+ with pytest.raises(ManifestError):
+ load_manifest("default")
+
+
+def test_save_manifest_writes_atomically(monkeypatch, tmp_path: Path) -> None:
+ monkeypatch.setattr(Path, "home", lambda: tmp_path)
+
+ save_manifest(_manifest())
+
+ # No leftover temp file from the atomic write; only the manifest itself.
+ profile_dir = tmp_path / ".headroom" / "deploy" / "default"
+ assert sorted(p.name for p in profile_dir.iterdir()) == ["manifest.json"]
+ # And the persisted manifest still round-trips.
+ assert load_manifest("default") is not None
+
+
def test_list_manifests_ignores_invalid_payloads(monkeypatch, tmp_path: Path) -> None:
monkeypatch.setattr(Path, "home", lambda: tmp_path)
valid = _manifest()