feat(desktop): boot-failure recovery + live API-key validation - #35864
Merged
Conversation
… on entry
Fresh installs that hit a gateway boot failure had no recovery path: the
shell rendered dead ("gateway offline"), logs were undiscoverable, and a
mistyped API key was accepted because onboarding only checked credential
presence, not validity.
- Add BootFailureOverlay: a top-level recovery surface (Retry, Repair
install, Use local gateway, Open logs + inline recent logs) that mounts
on any hard boot failure, including post-install. Trims the now-redundant
recovery button from the onboarding Preparing panel.
- Add hermes:logs:reveal / :recent IPC (reveal desktop.log) and a
hermes:bootstrap:repair IPC that drops the bootstrap marker to force a
clean reinstall. Surface "Open logs" in Gateway settings too.
- Add POST /api/providers/validate: a live per-provider probe
(OpenRouter/OpenAI/xAI/Gemini key check, local endpoint connectivity)
wired into saveOnboardingApiKey so a rejected key blocks before it's
persisted, while an unreachable probe falls through (offline-safe).
alt-glitch
added
type/feature
austinpickett
approved these changes
May 31, 2026
1 task
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fresh-install failure paths in the desktop app were dead ends. Observed on a fresh macOS VM and again reopening
hermes.exe: the gateway failed to come up, the shell rendered bricked ("gateway offline", dead composer, only a toast), logs were undiscoverable, and a mistyped OpenRouter key was accepted because onboarding only checked credential presence, not validity.This adds self-healing + repair affordances and real key validation.
Boot-failure recovery
BootFailureOverlaymounts on any hard boot failure (gateway never connected, backend exited during startup, latched bootstrap failure) — including post-install, which previously had zero recovery UI. Actions: Retry, Repair install, Use local gateway, Open logs, plus collapsible recent log lines.hermes:bootstrap:repairIPC drops the bootstrap-complete marker so the next launch re-runs the installer (refreshes a broken/partial venv). Clearly labeled as slow.Preparingpanel (the overlay supersedes it).Logs
hermes:logs:reveal(revealsdesktop.login the file manager) +hermes:logs:recent. Surfaced in the recovery overlay and as a Diagnostics → Open logs row in Gateway settings.Live API-key validation
POST /api/providers/validate: a cheap live probe per provider — OpenRouter (/api/v1/key), OpenAI/xAI (/v1/models), Gemini (/v1beta/models?key=), and connectivity-only for local/custom endpoints.saveOnboardingApiKeynow validates before persisting: a rejected key (reachable + 401/403) blocks with a real error; an unreachable probe (offline / provider down) falls through and saves, so offline users aren't stranded.Notes
hermes_cli/gateway.pywas intentionally left out of this branch.Test plan
apps/desktopnpm run type-checkcleaneslintclean on changed files (pre-existing warnings untouched)scripts/run_tests.sh tests/hermes_cli/test_web_server.py— 178 passed (incl. 6 new network-free validation-branch tests)