fix(wrap): strip -dev from running proxy version in restart check (#3200)

## Description

`headroom wrap` is supposed to restart an already-running proxy whose
Headroom version differs from the CLI's. The check,
`_proxy_needs_version_restart`, strips the `-dev` suffix only from the
CLI's own version. A source-built proxy reporting e.g. `0.34.0-dev`
fails the `^v?\d+\.\d+\.\d+$` release regex, normalizes to `None`, and
the check silently never fires — so any stale dev-built proxy is reused
forever. The docstring already claims the opposite behavior ("a dev CLI
still restarts a stale proxy on a real version difference"); this PR
makes the code match it.

Observed in production on a maintainer machine: a 21-day-old
`0.34.0-dev` proxy (zero attached clients) was silently reused by a
`0.37.0-dev` wrap, which then also inherited its incompatible routing
config (see linked companion PR for the routing half).

Closes #3197

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)

## Changes Made

- `headroom/cli/wrap.py`: `_proxy_needs_version_restart` now strips
`-dev` from the *running* proxy version before normalization (mirroring
the CLI side), with a comment pinning the version scheme (`<base>-dev`
from `get_version`) so future suffix styles get stripped too.
- `tests/test_cli/test_wrap_persistent.py`: regression tests — dev proxy
vs dev CLI with different base releases restarts; same base does not;
release proxy vs dev CLI restarts; unparseable/missing versions still
never restart.

## Testing

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

### Test Output

```text
$ uv run pytest tests/test_cli/test_wrap_persistent.py -q
32 passed in 0.63s
$ uv run pytest tests/test_cli/test_wrap_persistent.py tests/test_cli/test_wrap_helpers.py -q
90 passed in 0.57s
$ uv run ruff format headroom/cli/wrap.py tests/test_cli/test_wrap_persistent.py
2 files left unchanged
$ uv run ruff check headroom/cli/wrap.py tests/test_cli/test_wrap_persistent.py
All checks passed!
$ uv run mypy headroom/cli/wrap.py
Success: no issues found in 1 source file
```

## Real Behavior Proof

- Environment: macOS 26.5 arm64, Python 3.13, local source build
0.37.0-dev (integration overlay), live stale proxy: `headroom proxy
--port 8789` running 0.34.0-dev for 21 days with zero attached wrap
clients.
- Exact command / steps: `GET http://127.0.0.1:8789/health` before and
after; then from the fixed build, `python -c "from headroom.cli import
wrap as w; w._ensure_proxy(8789, False, agent_type='codex')"`.
- Observed result: before fix the same call printed "Proxy already
running" (reused). After fix: `/health` before = `version 0.34.0-dev,
pid 63454, augment_api_url set`; the call killed PID 63454 and started a
fresh proxy; `/health` after = `version 0.37.0-dev, pid 48365,
augment_api_url None`. Against a second stale proxy (port 8788) with one
live wrapper attached, the check correctly deferred ("Leaving it running
because 1 attached wrapper(s)") instead of killing a live session's
proxy.
- Not tested: the persistent-deployment variant of the version-restart
path (unit-tested only); Windows (code path is platform-independent
string handling).

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: N/A
- Stable/default behavior changed: yes — wraps now actually restart
stale dev-built proxies instead of reusing them. Release-built proxies
(no `-dev` suffix) are byte-identical in behavior.
- Kill switch / disable path: none needed; stopping the old proxy
manually restores prior behavior.
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert the commit; reuse of stale dev proxies resumes.

## 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)

## Additional Notes

Adversarially reviewed by a second model (glm-5.2, high reasoning)
before submission; verdict ready, one nit (version-scheme comment)
accepted and applied. Companion PRs (same incident): routing-config
reuse check, orphan-proxy watchdog.

Co-authored-by: JD Davis <mxjerrett@gmail.com>
This commit is contained in:
rNoz
2026-09-30 11:19:38 -05:00
committed by GitHub
co-authored by JD Davis
parent 7e73438dc5
commit bd0296b5e7
2 changed files with 31 additions and 2 deletions
+9 -2
View File
@@ -3835,9 +3835,16 @@ def _proxy_version(payload: dict[str, Any] | None) -> str | None:
def _proxy_needs_version_restart(payload: dict[str, Any] | None) -> bool:
"""Return True when a running Headroom proxy uses a different package version."""
running_version = _proxy_version(payload)
running_release = _normalize_release_version(running_version)
# -dev is a display marker for source builds; compare the base release so a
# dev CLI still restarts a stale proxy on a real version difference.
# dev CLI still restarts a stale proxy on a real version difference. The
# suffix must be stripped from the running version too: with it intact,
# "0.34.0-dev" fails the release regex, normalizes to None, and the check
# below silently never fires for source-built proxies. The scheme is always
# "<base>-dev" (get_version in headroom/_version.py); any future "-rcN" or
# "-dev.N" style would need stripping here as well.
running_release = _normalize_release_version(
running_version.removesuffix("-dev") if running_version is not None else None
)
current_release = _normalize_release_version(_HEADROOM_VERSION.removesuffix("-dev"))
return (
running_release is not None
+22
View File
@@ -365,6 +365,28 @@ def test_proxy_version_restart_ignores_non_release_source_labels(monkeypatch) ->
assert wrap_cli._proxy_needs_version_restart({"version": "0.29.0"}) is True
def test_proxy_version_restart_strips_dev_suffix_on_both_sides(monkeypatch) -> None:
"""A dev-built proxy must be compared by its base release, like the CLI is.
Regression: "0.34.0-dev" failed the release regex, normalized to None, and
the check never fired, so a stale source-built proxy was silently reused
forever (observed: a 21-day-old 0.34.0-dev proxy reused by a 0.37.0-dev
wrap).
"""
monkeypatch.setattr(wrap_cli, "_HEADROOM_VERSION", "0.37.0-dev")
assert wrap_cli._proxy_needs_version_restart({"version": "0.34.0-dev"}) is True
assert wrap_cli._proxy_needs_version_restart({"version": "0.37.0-dev"}) is False
assert wrap_cli._proxy_needs_version_restart({"version": "0.36.4"}) is True
monkeypatch.setattr(wrap_cli, "_HEADROOM_VERSION", "0.37.0")
assert wrap_cli._proxy_needs_version_restart({"version": "0.36.4-dev"}) is True
# Unparseable running versions still never trigger a restart.
assert wrap_cli._proxy_needs_version_restart({"version": "unknown"}) is False
assert wrap_cli._proxy_needs_version_restart(None) is False
assert wrap_cli._proxy_needs_version_restart({}) is False
def test_ensure_proxy_restarts_ephemeral_proxy_for_openai_api_url_mismatch(monkeypatch) -> None:
calls: list[object] = []
health = {