fix(install): use safe model backends for persistent services (#3646)

## Description

Native persistent-service manifests now explicitly select CPU for the
memory embedder and ONNX for Kompress by default. This avoids selecting
Metal-specific model backends during supervised startup, while
preserving explicit backend overrides.

Closes #3604

## Type of Change

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

## Changes Made

- Add `HEADROOM_EMBEDDER_RUNTIME=cpu` and
`HEADROOM_KOMPRESS_BACKEND=onnx` to native `persistent-service`
manifests only.
- Keep explicit `extra_env` values last so users can intentionally opt
into another backend.
- Add planner regression coverage for service defaults, overrides, and
non-service presets.
- Document the independent backend settings and the explicit MPS opt-in
boundary.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [ ] Manual testing performed

### Test Output

```text
python -m pytest -q tests/test_install/test_planner.py tests/test_install/test_supervisors.py tests/test_install/test_runtime.py tests/test_cli/test_install_cli.py
133 passed

ruff check headroom/install/planner.py tests/test_install/test_planner.py
All checks passed

ruff format --check headroom/install/planner.py tests/test_install/test_planner.py
All checks passed

git diff --check
passed
```

## Real Behavior Proof

- Environment: Ubuntu/Linux development host; native macOS launchd and
Apple Silicon Metal were not available.
- Exact command / steps: Ran the focused planner, supervisor, runtime,
and install CLI test suite plus Ruff and diff checks listed above.
- Observed result: The planner emits CPU/ONNX defaults for native
persistent services, preserves explicit backend overrides, and leaves
persistent-task and Docker manifests unchanged; the focused suite
passed.
- Not tested: Real Apple Silicon macOS 26 behavior, launchd restart
recovery, and ambient exported backend variables. The current base
source also does not prove that a clean persistent-service install
injected MPS; this PR is defensive safe-default hardening rather than a
claim of reproducing the reported crash.

## Runtime Rollout Safety

- Rollout-managed feature(s): None.
- Minimum rollout channel: Standard release.
- Stable/default behavior changed: Native `persistent-service` manifests
use CPU/ONNX model backends by default.
- Kill switch / disable path: Explicit `--env
HEADROOM_EMBEDDER_RUNTIME=pytorch_mps` and/or `--env
HEADROOM_KOMPRESS_BACKEND=pytorch_mps`, subject to platform and
dependency support.
- Unsafe override required: No.
- Qualification impact: Persistent services no longer select
Metal-specific model backends by default.
- Rollback path: Revert this PR.

## 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] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

N/A — this is a manifest, test, and documentation change.

## Additional Notes

`mypy` was not locally runnable because the maturin editable build
failed: the installed Rust toolchain lacked an applicable cargo
component. The PR does not claim CI success or real macOS runtime
validation.
This commit is contained in:
lorenzozane
2026-10-01 15:57:06 -05:00
committed by GitHub
parent d1ad189819
commit 7287589d23
3 changed files with 45 additions and 0 deletions
+4
View File
@@ -169,6 +169,10 @@ def build_manifest(
"HEADROOM_MODE": proxy_mode,
"HEADROOM_BACKEND": backend,
}
if effective_preset == InstallPreset.PERSISTENT_SERVICE.value:
# Keep native services away from Metal-specific model backends by default.
base_env["HEADROOM_EMBEDDER_RUNTIME"] = "cpu"
base_env["HEADROOM_KOMPRESS_BACKEND"] = "onnx"
if anyllm_provider:
base_env["HEADROOM_ANYLLM_PROVIDER"] = anyllm_provider
if region:
+32
View File
@@ -50,6 +50,8 @@ def test_build_manifest_for_persistent_docker_sets_expected_defaults() -> None:
# exist inside the container and would keep /readyz at 503 (#2803). The proxy
# resolves the DB under its own cwd, which is the bind-mounted ~/.headroom.
assert "--memory-db-path" not in manifest.proxy_args
assert "HEADROOM_EMBEDDER_RUNTIME" not in manifest.base_env
assert "HEADROOM_KOMPRESS_BACKEND" not in manifest.base_env
def test_build_manifest_python_runtime_keeps_explicit_memory_db_path() -> None:
@@ -97,6 +99,8 @@ def test_build_manifest_falls_back_from_windows_service_to_task(monkeypatch) ->
assert manifest.preset == InstallPreset.PERSISTENT_TASK.value
assert manifest.supervisor_kind == "task"
assert "HEADROOM_EMBEDDER_RUNTIME" not in manifest.base_env
assert "HEADROOM_KOMPRESS_BACKEND" not in manifest.base_env
def test_build_manifest_uses_provider_slice_env_builders_for_all_supported_targets() -> None:
@@ -365,3 +369,31 @@ def test_build_manifest_extra_env_wins_over_grok_xai_default() -> None:
assert manifest.base_env["OPENAI_TARGET_API_URL"] == "https://gateway.example/v1"
idx = manifest.proxy_args.index("--openai-api-url")
assert manifest.proxy_args[idx + 1] == "https://gateway.example/v1"
def test_build_manifest_for_persistent_service_uses_safe_model_backends() -> None:
manifest = build_manifest(**_base_manifest_kwargs())
assert manifest.base_env["HEADROOM_EMBEDDER_RUNTIME"] == "cpu"
assert manifest.base_env["HEADROOM_KOMPRESS_BACKEND"] == "onnx"
def test_persistent_service_explicit_model_backends_override_safe_defaults() -> None:
manifest = build_manifest(
**_base_manifest_kwargs(
extra_env={
"HEADROOM_EMBEDDER_RUNTIME": "pytorch_mps",
"HEADROOM_KOMPRESS_BACKEND": "pytorch_mps",
}
)
)
assert manifest.base_env["HEADROOM_EMBEDDER_RUNTIME"] == "pytorch_mps"
assert manifest.base_env["HEADROOM_KOMPRESS_BACKEND"] == "pytorch_mps"
def test_persistent_task_does_not_inherit_service_backend_defaults() -> None:
manifest = build_manifest(**_base_manifest_kwargs(preset=InstallPreset.PERSISTENT_TASK.value))
assert "HEADROOM_EMBEDDER_RUNTIME" not in manifest.base_env
assert "HEADROOM_KOMPRESS_BACKEND" not in manifest.base_env
+9
View File
@@ -27,6 +27,15 @@ headroom install status
This installs a background service on the current machine, applies persistent tool wiring, and keeps the proxy healthy on port `8787`.
Native `persistent-service` manifests explicitly default the memory embedder to
`cpu` and Kompress to `onnx`. This avoids selecting the Apple Silicon Metal
backends during supervised startup, where a native MPS abort cannot be handled
by Python. These are safe defaults only: explicit `--env
HEADROOM_EMBEDDER_RUNTIME=pytorch_mps` or
`--env HEADROOM_KOMPRESS_BACKEND=pytorch_mps` still opts into MPS and requires
the matching platform and optional dependencies. The two settings are
independent; the Kompress setting does not control memory embedding.
### Persistent watchdog task
```bash