fix(hub): platform-aware artifact selection for binary hub agents

[itomek]

Closes #2084

Installing the Email Triage agent from the Agent UI hub failed on every platform: the hub manifest's legacy singular artifact field always points at the first-published platform binary (email-agent-darwin-arm64), the installer read only that field, and language: python routed the macOS executable into uv pip install — the exit-2 error in #2084. The installer now selects the right entry from versions[v].artifacts[] for the host platform and installs a binary as a binary (checksum-verified, atomic, chmod +x), so the only agent in the live hub catalog actually installs — verified end-to-end on a Windows 11 + Radeon machine (the reporter's environment class) and on macOS.

Also in the change, because the email install dir doubles as the running sidecar's own binary cache: the UI shuts a running sidecar down before install/uninstall/rollback, a Windows locked-file failure becomes an actionable error instead of a stack trace, updates replace the binary in place (no dir-level backup that would yank a live process's directory), and health/status report a correct binary install as healthy instead of demanding the gaia.agent entry point binaries don't ship. Wheel- and C++-agent behavior is byte-identical (regression-tested). Deferred follow-ups (binary-agent trust gate, wheel-publishing hazards, small install hardening) are tracked in #2085 with the full analysis.

Test plan

• python -m pytest tests/unit/test_hub_installer.py tests/unit/test_hub_router.py tests/unit/test_hub_lifecycle.py tests/unit/test_hub_compatibility.py -q → 121 passed (includes the new T1–T14 contract: platform selection, wheel/cpp regression guards, loud no-match errors, sentinel back-compat, locked-file/update paths, sidecar-shutdown hook, kind-aware health, platform-key parity with the sidecar's own mapping)
• Regression net: tests/unit/test_hub_catalog.py tests/unit/test_agent_hub_api.py → 21 passed, 4 skipped
• python util/lint.py --all → ALL QUALITY CHECKS PASSED
• Real-world before→after on Windows 11 + Radeon and on macOS (evidence below)

Evidence (real hub, cold state — ~/.gaia/agents/email deleted before each phase)

Before — main (a02ae714), Windows 11: POST /api/agents/install {"id":"email"} → install-status:

{"id":"email","status":"failed","error":"'uv pip install' failed (exit 2): error: Failed to parse: `...\\gaia-hub-k1pdt_rr\\email-agent-darwin-arm64` ... Expected path to end in a supported file extension: `.whl`, ..."}

After — this branch (924c8449), same box, cold: same request →

{"id":"email","status":"completed","phase":"completed","percent":100,"version":"0.4.0","error":null}

email-agent.exe SHA-256 = 206a9c12…93f8 — exact match with the live manifest's win32-x64 artifact; GET /api/agents/email/health → {"state":"healthy"}.

🔍 More evidence: locked-file error, update-in-place, macOS

Windows, install while the agent binary is running (holds the exe open) — actionable error instead of a stack trace, and no .backup/ dir is created:

{"status":"failed","error":"Could not write email-agent.exe to C:\\Users\\...\\agents\\email: [WinError 5] Access is denied ... The agent appears to be running — close it and retry."}

After closing the process, the same request completes and replaces the binary in place (SHA re-verified).

macOS (darwin-arm64), cold: same install → completed, ~/.gaia/agents/email/email-agent written with -rwx--x--x, SHA-256 = 26bcf05b…bf (exact manifest match), health healthy, ./email-agent --help runs.

Tested by driving the real POST /api/agents/install / install-status / health endpoints of gaia.ui.server against the live hub on both machines.

[github-actions]

Verdict: Approve — clean, well-tested, scope-tight.

This fixes the Email Triage agent failing to install from the hub on every platform: the installer read only the manifest's legacy singular artifact (always the macOS binary) and fed it into uv pip install. It now classifies the artifact set, selects the right per-platform binary, and installs a binary as a binary (checksum-verified, atomic write, chmod +x), while leaving wheel and C++ install paths byte-identical. The three failure modes that fall out of treating an install dir as a live sidecar's cache — locked-file writes, dir-level backups, and health probes demanding an entry point binaries don't ship — are each handled and turned into actionable errors. No blocking issues found; the fail-loudly discipline (loud no-match error, no silent wheel substitution) is exactly right.

🔍 Technical details

Strengths

• Correctness-first classification order (installer.py:253-288): cpp classified first, then artifacts[] set membership, then legacy singular — and critically it classifies the set, not artifacts[] presence, so the worker's habit of writing artifacts: [artifact] on every publish doesn't misfire binaries. The wheel-only-artifacts[] regression (T4b) and cpp-with-artifacts[] case (T4c) both have dedicated guards.
• No silent fallback: a binary manifest with no platform match raises a loud InstallError naming the platform and every available filename (installer.py:257-264), never substituting a wheel from elsewhere in the list. Matches CLAUDE.md's fail-loudly rule.
• Path-traversal guard on the artifact filename before any path-join (_sanitize_artifact_filename, installer.py:188-195), covered for both singular and artifacts[] shapes (T9).
• Cold-state + real-flow testing: tests drive the real installer.install() and the real router endpoints rather than stubbing the selection, and the sidecar/platform-key parity is asserted against gaia.ui.email_sidecar.platform directly (T10) — so the duplicated current_platform_key can't silently drift. This is the "test the call is valid, from the user's real state" bar CLAUDE.md asks for.
• Layer boundary respected: gaia.hub never imports gaia.ui; the sidecar-shutdown bridge lives only in the router (hub.py:541-555), and the shutdown fires synchronously before the background install task is queued (hub.py:190-203) — correct ordering, no race with the worker.

Minor observations (non-blocking, no change requested)

• 🟢 _shutdown_email_sidecar hardcodes agent_id != "email" (hub.py:549). Fine while email is the only sidecar agent and it's clearly commented, but worth a registry-driven "is this a sidecar agent" check once a second one lands, so this doesn't become a spot to forget.
• 🟢 On the wheel-only artifacts[] branch (installer.py:267-275), wheels[0] after the sort will be an sdist if no .whl is present. That's a valid pip target, so behavior is correct — just noting it's intentional, not a .whl-guaranteed path.

No doc-sync obligation here: this is core installer internals, not a hub-agent package doc surface, and no docs/ page documents artifact selection.

[itomek]

Linux evidence added — the fix is now verified on all three OS targets, plus the earlier Windows CI failure is resolved.

Ubuntu 24.04 (linux-x64), cold state — fresh ubuntu:24.04 container (linux/amd64), branch cloned at 924c8449, pip install -e ".[ui]", no prior ~/.gaia; drove the real endpoints:

POST /api/agents/install {"id":"email"}  →  {"id":"email","status":"queued"}
install-status → {"id":"email","status":"completed","phase":"completed","percent":100,"version":"0.4.0","error":null}

-rwx--x--x 1 root root 68354952 /root/.gaia/agents/email/email-agent
sha256: 7015be1ea212fddf967cbb631fe4a848dedda8d7d51ad38b9a3fdc67ac256973   (exact match: manifest linux-x64 artifact)
GET /api/agents/email/health → {"id":"email","state":"healthy",...}
./email-agent --help → usage: email-agent [-h] [--host HOST] [--port PORT] [--print-openapi]

Ran in a container because both physical Linux test boxes were unavailable at the time (one reserved by a long eval run, the other is the dual-boot machine currently booted into Windows); the install path is hardware-independent and the installed binary executes.

Per-OS summary: Windows 11 (physical, Radeon — the reporter's environment class): before→after + locked-file + update-in-place, SHA-verified ✅ · macOS (darwin-arm64, physical): SHA + exec bit + health ✅ · Ubuntu 24.04 (linux-x64, container): SHA + exec bit + health ✅.

CI: the "Test GAIA CLI on Windows (Full Integration)" failure was a runner loss (job killed at 11m mid-step, log blob never uploaded; workflow green on the last 5 main commits) — rerun passed, all checks green.