[fix] dev tag for sea binary should never be used

[pirate]

Summary by cubic

Ensure the SEA binary never uses -dev or prerelease tags by always picking the latest stable server release and defaulting the cache key to the package version. This stabilizes local downloads and PyPI builds.

• Bug Fixes
  • GitHub workflow selects the highest stable stagehand-server-v3/vX.Y.Z tag (skips drafts and prereleases).
  • In scripts/download-binary.py, _parse_server_tag rejects tags with - or +, and normalize_server_tag enforces stable input; download_binary() now uses it.
  • resolve_binary_path falls back to package __version__ when STAGEHAND_VERSION is unset to keep cached binaries stable.
  • Tests cover tag normalization, ignoring -dev releases when resolving latest, and the cache version default.

^{Written for commit 2dc6ef7. Summary will update on new commits. Review in cubic}

[cubic-dev-ai]

1 issue found across 5 files

Confidence score: 3/5

• There is a concrete medium-risk gap in scripts/download-binary.py: stable-tag validation applies to auto-resolved tags, but --version can still fetch -dev/+build artifacts.
• Because this is severity 6/10 with high confidence (9/10), it introduces a realistic regression/policy-bypass risk for users who pass explicit versions.
• Pay close attention to scripts/download-binary.py - align --version handling with stable-tag enforcement to prevent unintended non-stable downloads.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="scripts/download-binary.py">

<violation number="1" location="scripts/download-binary.py:63">
P2: Stable-tag validation is only enforced for auto-resolved tags; `--version` still allows `-dev`/`+build` tags to be downloaded.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant GHA as GitHub Workflow / Script
    participant GH_API as GitHub Releases API
    participant SEA as Runtime Library (sea_binary.py)
    participant Cache as Local Binary Cache

    Note over GHA, GH_API: Version Selection (CI or Manual Download)

    GHA->>GH_API: Fetch stagehand-server-v3 releases
    GH_API-->>GHA: Return release list (tags, drafts, prereleases)
    
    rect rgb(240, 240, 240)
        Note right of GHA: NEW: Version Filtering Logic
        GHA->>GHA: Skip 'draft' or 'prerelease' flags
        GHA->>GHA: CHANGED: _parse_server_tag() rejects tags with '-' or '+' (e.g., -dev)
        GHA->>GHA: Select highest stable X.Y.Z version
    end

    GHA->>GH_API: Download binary for selected stable version
    GH_API-->>GHA: Binary stream

    Note over SEA, Cache: Runtime Path Resolution

    SEA->>SEA: resolve_binary_path()
    
    alt STAGEHAND_VERSION env var set
        SEA->>SEA: Use version from environment
    else STAGEHAND_VERSION is unset
        SEA->>SEA: CHANGED: Default to package __version__ (previously "dev")
    end

    SEA->>Cache: Check for binary at /cache/{version}/{filename}
    
    alt Binary exists in cache
        Cache-->>SEA: Return Path
    else Binary missing
        SEA->>Cache: NEW: Copy embedded resource to versioned cache
        Cache-->>SEA: Return Path
    end

    SEA-->>GHA: Final executable path

Loading

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}