fix: reject prerelease binary versions

Author: monadoid

scripts/download-binary.py

@@ -120,6 +120,17 @@ def resolve_latest_server_tag() -> str:
     return best[1]
 
 
+def normalize_server_tag(version: str) -> str:
+    """Normalize explicit CLI input to a stable stagehand-server-v3 tag."""
+    tag = version if version.startswith("stagehand-server-v3/v") else f"stagehand-server-v3/{version}"
+    if _parse_server_tag(tag) is None:
+        raise ValueError(
+            "Invalid stagehand server version. Expected a stable tag like "
+            "'v3.2.0' or 'stagehand-server-v3/v3.2.0'."
+        )
+    return tag
+
+
 def download_binary(version: str) -> None:
     """Download the binary for the current platform."""
     plat, arch = get_platform_info()
@@ -128,7 +139,7 @@ def download_binary(version: str) -> None:
 
     # GitHub release URL
     repo = "browserbase/stagehand"
-    tag = version if version.startswith("stagehand-server-v3/v") else f"stagehand-server-v3/{version}"
+    tag = normalize_server_tag(version)
     url = f"https://github.com/{repo}/releases/download/{tag}/{binary_filename}"
 
     # Destination path

tests/test_sea_binary.py

@@ -3,6 +3,8 @@
 import importlib.util
 from pathlib import Path
 
+import pytest
+
 from stagehand.lib import sea_binary
 from stagehand._version import __version__
 
@@ -22,7 +24,7 @@ def _load_download_binary_module():
 
 
 def test_resolve_binary_path_defaults_cache_version_to_package_version(
-    monkeypatch,
+    monkeypatch: pytest.MonkeyPatch,
     tmp_path: Path,
 ) -> None:
     resource_path = tmp_path / "stagehand-test"
@@ -31,7 +33,10 @@ def test_resolve_binary_path_defaults_cache_version_to_package_version(
     captured: dict[str, object] = {}
 
     monkeypatch.delenv("STAGEHAND_VERSION", raising=False)
-    monkeypatch.setattr(sea_binary, "_resource_binary_path", lambda _filename: resource_path)
+    def _fake_resource_binary_path(_filename: str) -> Path:
+        return resource_path
+
+    monkeypatch.setattr(sea_binary, "_resource_binary_path", _fake_resource_binary_path)
 
     def _fake_copy_to_cache(*, src: Path, filename: str, version: str) -> Path:
         captured["src"] = src
@@ -54,13 +59,27 @@ def test_parse_server_tag_rejects_prerelease_tags() -> None:
     assert download_binary._parse_server_tag("stagehand-server-v3/v3.20.0+build.1") is None
 
 
-def test_resolve_latest_server_tag_ignores_dev_releases(monkeypatch) -> None:
+def test_normalize_server_tag_rejects_prerelease_input() -> None:
+    try:
+        download_binary.normalize_server_tag("v3.20.0-dev")
+    except ValueError as exc:
+        assert "stable tag" in str(exc)
+    else:
+        raise AssertionError("Expected prerelease version input to be rejected")
+
+
+def test_resolve_latest_server_tag_ignores_dev_releases(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
     releases = [
         {"tag_name": "stagehand-server-v3/v3.20.0-dev"},
         {"tag_name": "stagehand-server-v3/v3.19.1"},
         {"tag_name": "stagehand-server-v3/v3.19.0"},
     ]
 
-    monkeypatch.setattr(download_binary, "_http_get_json", lambda _url: releases)
+    def _fake_http_get_json(_url: str) -> list[dict[str, str]]:
+        return releases
+
+    monkeypatch.setattr(download_binary, "_http_get_json", _fake_http_get_json)
 
     assert download_binary.resolve_latest_server_tag() == "stagehand-server-v3/v3.19.1"