fix(hub): let Intel Macs install the gaia and email agents

[kovtcharov]

Intel Mac users running gaia hub install gaia or gaia hub install email were refused before any download, even though both agents' releases build and publish a darwin-x64 binary and both lock files list it. The manifests now declare darwin-x64, so the install gate matches what ships; the email README also lists Intel macOS (best-effort, as SPEC.md already says). A new unit test fails whenever a binary hub agent's declared platforms drift from its binaries.lock.json, in either direction.

No version bump: manifest-only fixes land under Unreleased, as #3866 did. The live hub picks this up on each agent's next publish.

Test plan

• python -m pytest tests/unit/test_hub_agent_platforms.py -q: 2 failed on origin/main (darwin-x64 in the lock, not in the manifest), 3 passed with the fix
• python -m pytest tests/unit/ -q -k "hub or manifest or compat or platform": 864 passed
• python -m pytest hub/agents/gaia/python/tests/test_publish_to_r2_by_reference.py hub/agents/gaia/python/tests/test_capability_matrix.py -q: 30 passed
• black and isort are clean on the new test file
• On an Intel Mac: gaia hub install email passes the compatibility check (needs a republished manifest)

Fixes #4218

[github-actions]

Verdict: Approve

This unblocks Intel Mac users who were turned away from installing the gaia and email agents even though both releases already publish an Intel binary. The fix is a one-word manifest change per agent plus a drift test that fails whenever an agent's advertised platforms stop matching the binaries it actually ships — which is the part that keeps this from recurring.

One thing worth confirming rather than changing: for the email agent the Intel binary is explicitly best-effort, and a release is allowed to drop it. On such a release Intel users will now get past the install check and hit a clear "no Intel binary for this version" error at download instead of being refused up front. That's the tradeoff the README and the release pipeline already describe, so it looks intentional — just make sure it's the behaviour you want.

Real-world evidence

N/A — manifest, docs, and tests only; no evidence bundle was produced for this PR. The one surface a user touches (the install gate) only changes once each agent republishes its manifest, and it can only be exercised on an Intel Mac, which the test plan leaves unchecked with that reason stated. I verified the change statically instead: both lock files list the Intel platform, the platform name is one the manifest schema accepts, and the install check compares against exactly the list this PR edits. The new test's logic reproduces as passing for both agents:

email darwin-arm64,darwin-x64,linux-x64,win32-x64  ==  lock  → MATCH
gaia  darwin-arm64,darwin-x64,linux-x64,win32-x64  ==  lock  → MATCH

🔍 Technical details

Verification performed

• hub/agents/email/npm/binaries.lock.json → binaries keys are win32-x64, darwin-arm64, darwin-x64, linux-x64; hub/agents/gaia/npm/binaries.lock.json → components.sidecar.platforms is the same set (the tui component covers six, as the test comment notes). Both manifests now match after the change.
• darwin-x64 is in VALID_PLATFORMS (src/gaia/hub/manifest.py:99), so _validate_platforms accepts it.
• The gate compares detect_platform() against reqs.platforms (src/gaia/hub/compatibility.py:236), and current_platform() (src/gaia/hub/native_launcher.py:130) yields darwin-x64 for x86_64 macOS — so the added triple is the one an Intel Mac actually reports.
• No pre-existing test cross-checks manifest platforms against binaries.lock.json, so tests/unit/test_hub_agent_platforms.py is genuinely new coverage, not a duplicate of test_hub_manifest.py / test_hub_compatibility.py.
• Doc bundle is consistent: hub/agents/gaia/npm/{README,SKILL,SPEC}.md already list darwin-x64 in their coverage tables, and hub/agents/email/npm/SPEC.md:896 already called it best-effort — the README edit brings the last surface in line. No docs/ page claims a platform set for these agents.

Notes (non-blocking)

🟢 Best-effort Intel vs. an unconditional manifest (hub/agents/email/python/gaia-agent.yaml:53). release_agent_email.yml drops email-agent-darwin-x64 when the build or the macOS-15 compat check fails, but publish ships the manifest from its repo path, so the published manifest still declares darwin-x64. Intel users on that release pass check_compatibility and fail later in resolveEntry (hub/agents/email/npm/src/platform.ts:92) with an actionable PlatformError. That matches the workflow's own warning text ("Intel-mac users will hit a loud install error until an Intel binary is published") and the README wording added here, so I read it as designed — flagging only so the choice is explicit.

🟢 Same refusal still applies to the pure-Python agents. chat, hello-world, word-count, and connectors-demo all declare [win-x64, linux-x64, darwin-arm64] despite shipping no platform-specific binary at all, so gaia hub install chat still refuses an Intel Mac for no build-related reason. Out of scope here (and gaia pulls gaia-agent-chat via pip, which ignores the manifest), but it's the same defect class as #4218 and the new test can't catch it — those agents have no lock file to compare against. Worth a follow-up issue.

🟢 _lock_platforms raises a bare KeyError for a schema-3 lock with no sidecar component (tests/unit/test_hub_agent_platforms.py:121). A future component rename would surface as an opaque traceback rather than a message naming the drift:

    components = lock.get("components") or {}
    if "sidecar" not in components:
        raise AssertionError(
            f"lock has no 'sidecar' component; found {sorted(components)}. "
            "Update _lock_platforms if the sidecar component was renamed."
        )
    return set(components["sidecar"]["platforms"])

Strengths

• The test asserts equality in both directions, so it catches the inverse bug too (a manifest advertising a platform no release publishes) — that's what makes it a real guard rather than a one-off regression test for fix(hub): Intel Macs are refused by gaia hub install gaia and gaia hub install email #4218.
• test_binary_agents_are_discovered prevents the classic parametrize-over-a-glob failure where the glob stops matching and the suite goes quietly green with zero cases.
• Manifest-only fix kept out of a version bump with the precedent cited, and the two CHANGELOGs lead with the user-visible outcome rather than the field that changed.

[kovtcharov-amd]

Replicated as #4367 on a branch we can push to — fork push access (kovtcharov/gaia) was revoked mid-review, so this PR could no longer be refreshed against main. Same content, cherry-picked cleanly onto current main with no conflicts. Closing in favor of the replacement.