fix(desktop): support session auth for env remote URLs

[nainaism]

Summary

• allow HERMES_DESKTOP_REMOTE_URL to use a gateway's advertised session authentication when no static token is provided
• preserve the existing static-token path when HERMES_DESKTOP_REMOTE_TOKEN is set
• keep sign-in/sign-out controls available for environment-controlled gateways without overwriting the saved fallback connection
• distinguish a first-time remote sign-in from an expired session in recovery copy and document both environment variables

Problem

Desktop currently treats HERMES_DESKTOP_REMOTE_URL as token-only and fails unless HERMES_DESKTOP_REMOTE_TOKEN is also set. That conflicts with Gateway settings and the environment-variable docs, which support session-based OAuth or username/password sign-in. It also lets a saved fallback token leak into the environment-controlled settings view, hiding the sign-in path.

Implementation

• probe the gateway's public auth metadata for URL-only environment overrides
• select session auth when the gateway advertises it; otherwise require a static token with a targeted error
• prevent environment-controlled URLs from inheriting saved fallback tokens
• return tokenless environment overrides immediately as initial session-auth UI state instead of blocking Settings on a main-process probe or inheriting stale saved auth
• let the renderer's existing asynchronous probe refine the displayed mode while the connect path independently enforces the gateway's advertised auth mode
• allow session sign-in without persisting the environment URL into connection.json
• keep profile-specific overrides unchanged

Related work

• Builds on feat(desktop): username/password login for remote gateways #38851, which added username/password sign-in for remote gateways.
• Partially addresses the remote-client onboarding gap in Desktop: add first-class remote-client onboarding for existing Hermes instances #36970.
• Related reports: Hermes Desktop never shows sign-in UI when connecting to remote backend with basic auth #51873 and Hermes Desktop remote gateway reaches backend but UI still shows startup error / falls back to local backend unless env-forced #38332.
• OAuth WebSocket-ticket transport-error classification is intentionally not duplicated here; fix(desktop): only treat real 401/403 as OAuth session expiry #59238 and fix(desktop): harden remote connection lifecycle in Electron main #58108 already cover that policy and are awaiting maintainer direction/TypeScript ports.

Validation

• targeted auth/settings tests — 70 passed
• npm test — 1,781 passed, 1 skipped; 4 unrelated high-load UI failures in messaging/skills passed 5/5 when rerun in isolation
• npm run typecheck — passed
• npm run lint — passed (10 pre-existing warnings, 0 errors)
• npm run build — passed
• git diff --check — passed

[tonydwb]

Code Review Summary

Verdict: Approved

Looks Good

• Clean enhancement: supports session auth for env remote URLs in desktop
• Refactored effectiveRemoteToken helper cleanly handles the priority: envOverride > envToken > decrypted block.token
• Updated documentation in HERMES_DESKTOP_REMOTE_URL table clarifies the session provider behavior
• No security issues — token decryption path preserved for cases without env override

---

Reviewed by Hermes Agent

[tonydwb]

Code Review Summary

Verdict: Comment

Supports session auth for env remote URLs in desktop (201 additions / 34 deletions). Prior COMMENT activity noted.

Desktop auth extension for remote URLs. No security issues. No hardcoded secrets.

---

Reviewed by Hermes Agent (cron batch 2026-07-17)

[teknium1]

Thanks for addressing a real current-main inconsistency: apps/desktop/electron/main.ts:6129-6137 currently rejects a URL-only override, while website/docs/reference/environment-variables.md:508 says users can sign in from Gateway settings.

Problems

• The new initial oauth mode still does not make first-time URL-only sign-in available immediately. The unchanged authResolved gate in apps/desktop/src/app/settings/gateway-settings.tsx:301-307 is false while the probe is pending or has errored when there is neither a saved token nor an existing OAuth cookie. Consequently the OAuth controls at :978-1009 remain hidden despite the new initial state.

Suggested changes

• Make the renderer explicitly handle the tokenless environment candidate during probe-pending/error states, while letting a completed probe remain authoritative for token-only gateways. Cover that rendered control behavior rather than only the new pure helper.

Automated hermes-sweeper review.