Files
headroom/tests/test_install/test_paths.py
Rod BoevandJD Davis 44db755ee6 fix(install): replace the launchd wrapper with the proxy listener (#3224)
## Description

The persistent service path can leave a wrapper, listener, native
supervisor, or Docker container with conflicting ownership. Rebuild
runtime ownership so launchd directly owns Python, Docker owns Docker
across service/task presets, status and stop require deployment
identity, readiness cannot be health-only, and failed cleanup preserves
rollback state. Closes #3208

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (feature that would cause existing behavior to
change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- Make the launchd-owned Python service exec the listener in place.
- Classify Docker ownership from both runtime and preset, with no
competing native supervisor.
- Route Docker service/task start, restart, recovery, and teardown
through the Docker owner.
- Verify exact process command, port, deployment profile, and runtime
before status or stop.
- Add POSIX, macOS, and Windows process identity fallbacks without
requiring psutil.
- Require identity on readiness and fail closed when cleanup cannot
prove the new owner stopped.
- Persist an inactive previous-deployment snapshot, keep active state
durable before owner start, and make environment/provider mutation
activation transactional.
- Surface cleanup, persistence, supervisor, Docker, and
recovery-snapshot deletion failures with actionable recovery guidance.

## Testing

- [x] Unit tests pass (`uv run --locked pytest
tests/test_provider_package_init.py::test_install_registry_apply_provider_scope_mutations_skips_missing_and_none
tests/test_install/test_providers.py tests/test_cli/test_install_cli.py
tests/test_install/test_runtime.py
tests/test_install/test_supervisors.py tests/test_install/test_paths.py
tests/test_install/test_state.py -q`)
- [x] Linting passes (`uv run --locked ruff check` on changed install,
provider, supervisor, and focused test files)
- [x] Type checking passes (`uv run --locked mypy headroom
--ignore-missing-imports`)
- [x] New tests added for the regression
- [ ] Manual testing performed through live process/supervisor
environments

### Test Output

```text
uv run --locked pytest tests/test_provider_package_init.py::test_install_registry_apply_provider_scope_mutations_skips_missing_and_none tests/test_install/test_providers.py tests/test_cli/test_install_cli.py tests/test_install/test_runtime.py tests/test_install/test_supervisors.py tests/test_install/test_paths.py tests/test_install/test_state.py -q
============================= 197 passed in 1.07s =============================
uv run --locked ruff check .
All checks passed!
uv run --locked ruff format --check .
1534 files already formatted
uv run --locked mypy headroom --ignore-missing-imports
Success: no issues found in 527 source files
git diff --check
passed; the only worktree change is the pre-existing unstaged uv.lock line-ending change
```

## Real Behavior Proof

- Environment: Windows focused process and supervisor tests, with
platform-specific launchd and Docker owner paths represented by fakes.
- Exact command / steps: run the focused lifecycle and state suite
listed above, targeted Ruff and format checks, and the full-head mypy
check.
- Observed result: each persistent mode has one owner; mismatched,
malformed, or unavailable identity cannot authorize cleanup; active
state is durable before owner start; failed cleanup retains recovery
state; mutation rollback preserves unreverted records.
- Not tested: owner-level POSIX exec, a live macOS launchd job, and a
Docker daemon

## Runtime Rollout Safety

- Rollout-managed feature(s): None. This changes the default persistent
install and recovery ownership paths.
- Minimum rollout channel: Stable, after platform-specific CI and
maintainer review.
- Stable/default behavior changed: Yes. Persistent Python service
ownership and Docker supervisor routing change.
- Kill switch / disable path: `headroom uninstall` removes the managed
deployment; users can reinstall with another supported preset or
runtime.
- Unsafe override required: No.
- Qualification impact: launchd, Docker, and Windows identity paths
require their platform-owned environments; local proof uses focused
tests and process/supervisor fakes.
- Rollback path: Revert the rollback-ordering commits in this PR, then
reinstall the prior deployment if needed. Uncertain cleanup retains the
active new manifest and inactive previous snapshot until the new owner
is removed and recovery is completed.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective
- [x] New and existing unit tests pass locally with my changes
- [x] I have updated the CHANGELOG.md if applicable

## Additional Notes

The changelog is generated by the release pipeline. Live launchd and
Docker-owner behavior remains platform-owned proof; local tests do not
claim those owner environments. Final implementation head: `4004e4a5`.

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/3224"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

---------

Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-10-05 08:34:42 -05:00

97 lines
3.8 KiB
Python

from __future__ import annotations
from pathlib import Path
import click
import pytest
from headroom.install import paths as install_paths
def test_validate_profile_name_accepts_and_rejects_values() -> None:
assert install_paths.validate_profile_name("good.profile-1_2") == "good.profile-1_2"
for value in (".", "..", "bad/name", "bad space", ""):
with pytest.raises(click.ClickException, match="Invalid profile name"):
install_paths.validate_profile_name(value)
def test_profile_and_artifact_paths(monkeypatch, tmp_path: Path) -> None:
monkeypatch.setattr("headroom.install.paths._paths.deploy_root", lambda: tmp_path / "deploy")
assert install_paths.deploy_root() == tmp_path / "deploy"
assert install_paths.profile_root("demo") == tmp_path / "deploy" / "demo"
assert install_paths.manifest_path("demo") == tmp_path / "deploy" / "demo" / "manifest.json"
assert install_paths.recovery_manifest_path("demo") == (
tmp_path / "deploy" / "demo.recovery.json"
)
assert install_paths.log_path("demo") == tmp_path / "deploy" / "demo" / "runner.log"
assert install_paths.pid_path("demo") == tmp_path / "deploy" / "demo" / "runner.pid"
assert (
install_paths.unix_run_script_path("demo")
== tmp_path / "deploy" / "demo" / "run-headroom.sh"
)
assert install_paths.unix_ensure_script_path("demo") == (
tmp_path / "deploy" / "demo" / "ensure-headroom.sh"
)
assert install_paths.windows_run_script_path("demo") == (
tmp_path / "deploy" / "demo" / "run-headroom.ps1"
)
assert install_paths.windows_run_cmd_path("demo") == (
tmp_path / "deploy" / "demo" / "run-headroom.cmd"
)
assert install_paths.windows_ensure_script_path("demo") == (
tmp_path / "deploy" / "demo" / "ensure-headroom.ps1"
)
assert install_paths.windows_ensure_cmd_path("demo") == (
tmp_path / "deploy" / "demo" / "ensure-headroom.cmd"
)
def test_env_target_and_config_paths(monkeypatch, tmp_path: Path) -> None:
monkeypatch.setattr(Path, "home", lambda: tmp_path)
monkeypatch.setattr("headroom.install.paths.sys.platform", "linux")
assert install_paths.unix_user_env_targets() == [
tmp_path / ".bashrc",
tmp_path / ".zshrc",
tmp_path / ".profile",
]
assert install_paths.unix_system_env_targets() == [Path("/etc/profile.d/headroom.sh")]
monkeypatch.setattr("headroom.install.paths.sys.platform", "darwin")
assert install_paths.unix_system_env_targets() == [
Path("/etc/profile"),
Path("/etc/zprofile"),
Path("/etc/bashrc"),
]
assert install_paths.claude_settings_path() == tmp_path / ".claude" / "settings.json"
assert install_paths.codex_config_path() == tmp_path / ".codex" / "config.toml"
assert install_paths.openclaw_config_path() == tmp_path / ".openclaw" / "openclaw.json"
assert (
install_paths.opencode_config_path() == tmp_path / ".config" / "opencode" / "opencode.json"
)
def test_opencode_config_path_honors_opencode_home(monkeypatch, tmp_path: Path) -> None:
monkeypatch.setattr(Path, "home", lambda: tmp_path / "unused")
other_home = tmp_path / "custom-opencode-home"
other_home.mkdir()
monkeypatch.setenv("OPENCODE_HOME", str(other_home))
assert install_paths.opencode_config_path() == other_home / "opencode.json"
(other_home / "opencode.jsonc").write_text("{}", encoding="utf-8")
assert install_paths.opencode_config_path() == other_home / "opencode.jsonc"
def test_opencode_config_path_opencode_config_env_wins_over_home(
monkeypatch, tmp_path: Path
) -> None:
monkeypatch.setenv("OPENCODE_HOME", str(tmp_path / "home"))
explicit = tmp_path / "explicit.json"
monkeypatch.setenv("OPENCODE_CONFIG", str(explicit))
assert install_paths.opencode_config_path() == explicit