fix(version): mark source-checkout builds as -dev (#2072)

## Description

`headroom --version` and the dashboard show `0.32.0` from a source
checkout, but the latest published release is `0.31.0`. That `0.32.0` is
not a real release: on a git checkout `get_version()` predicts the
*next* release from conventional commits since the last tag (`v0.31.0` +
`feat:` commits → `0.32.0`) and renders it identically to a shipped
version — so a dev build looks published.

This appends `-dev` on the source-checkout path so a dev build is never
mistaken for the published release.

Closes #

## Type of Change

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

## Changes Made

- `headroom/_version.py`: the source-checkout branch of `get_version()`
now returns `f"{source_version}-dev"`.
- `tests/test_package_init_lazy.py`: updated the source-tree version
test to assert the `-dev` suffix.

Released installs are unaffected: pip wheels and Docker images with a
baked `BUILD_VERSION` never take the source-checkout path, so they still
report clean release versions (`0.31.0` / `v0.31.0`). The suffix makes
`is_release_version()` return `False` and `normalize_release_version()`
return `None`, which every comparison site already handles — e.g.
`wrap.py`'s `_proxy_needs_version_restart` requires both sides to
normalize, so a dev build short-circuits to "no restart" (no behavior
change).

## Testing

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

### Test Output

```text
$ python -m pytest tests/test_package_init_lazy.py tests/test_cli_doctor.py -q
============================== 12 passed in 1.79s ==============================
============================== 51 passed in 0.56s ==============================

$ ruff check headroom/_version.py tests/test_package_init_lazy.py
All checks passed!

$ mypy headroom/_version.py
Success: no issues found in 1 source file
```

## Real Behavior Proof

- Environment: local source checkout (macOS), `.venv`, latest release
tag `v0.31.0`
- Exact command / steps: `headroom --version`
- Observed result:
- Before: `headroom, version 0.32.0` — indistinguishable from a release
  - After: `headroom, version 0.32.0-dev`
- Not tested: behavior inside a built Docker image / installed pip wheel
— unchanged by design, since those paths never compute a source-tree
version.

## 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
- [ ] 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
- [ ] I have updated the CHANGELOG.md if applicable

## Additional Notes

Scope kept to a bare `-dev` marker, which answers "is this a release?".
Appending the short git SHA (`-dev+g<sha>`) to distinguish individual
dev builds in bug reports is an easy follow-up if wanted. Docs/CHANGELOG
unchecked as N/A for a dev-only version-string fix.

---------

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>

headroom/_version.py

@@ -107,7 +107,10 @@ def get_version() -> str:
     if root is not None:
         source_version = _source_tree_version(root)
         if source_version:
-            return source_version
+            # A source checkout sits ahead of the last release tag, so this is
+            # the next version we'd cut, not a shipped one. Tag it -dev so a
+            # dev build is never mistaken for the published release.
+            return f"{source_version}-dev"
 
     build_version = _packaged_build_version()
     if build_version:

headroom/cli/wrap.py

@@ -2683,7 +2683,9 @@ 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)
-    current_release = _normalize_release_version(_HEADROOM_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.
+    current_release = _normalize_release_version(_HEADROOM_VERSION.removesuffix("-dev"))
     return (
         running_release is not None
         and current_release is not None

tests/test_cli/test_wrap_persistent.py

@@ -163,6 +163,32 @@ def test_ensure_proxy_restarts_idle_stale_persistent_deployment(monkeypatch) ->
     assert calls == ["restart:default:8787"]
 
 
+def test_ensure_proxy_restarts_stale_proxy_from_dev_build(monkeypatch) -> None:
+    """A source (-dev) CLI still restarts a stale proxy: the -dev marker is
+    display-only and must not disable a real version-mismatch restart."""
+    calls: list[str] = []
+    health = {
+        "version": "0.0.1",
+        "runtime": {"websocket_sessions": {"active_sessions": 0, "active_relay_tasks": 0}},
+        "config": {"pid": 12345},
+    }
+    monkeypatch.setattr(wrap_cli, "_HEADROOM_VERSION", "0.32.0-dev")
+    monkeypatch.setattr(wrap_cli, "_find_persistent_manifest", lambda port: _Manifest())
+    monkeypatch.setattr("headroom.install.health.probe_ready", lambda url: True)
+    monkeypatch.setattr(wrap_cli, "_query_proxy_health", lambda port: health)
+    monkeypatch.setattr(
+        wrap_cli,
+        "_restart_persistent_proxy",
+        lambda manifest, port: calls.append(f"restart:{manifest.profile}:{port}") or True,
+    )
+
+    proc, actual_port = wrap_cli._ensure_proxy(8787, False)
+
+    assert proc is None
+    assert actual_port == 8787
+    assert calls == ["restart:default:8787"]
+
+
 def test_ensure_proxy_leaves_active_stale_persistent_deployment_running(monkeypatch) -> None:
     health = {
         "version": "0.0.1",

tests/test_package_init_lazy.py

@@ -131,7 +131,9 @@ def test_version_prefers_source_tree_release_history() -> None:
         patch.object(version_module, "_source_tree_version", return_value="0.21.17"),
         patch.object(version_module, "version", return_value="0.9.1") as package_version,
     ):
-        assert version_module.get_version() == "0.21.17"
+        # Source checkouts are marked -dev so a dev build is never mistaken
+        # for the published release.
+        assert version_module.get_version() == "0.21.17-dev"
 
     package_version.assert_not_called()