feat(desktop): multi-connection registry — named agent sources (schema v2 + IPC + Settings UI)

[teknium1]

Summary

The desktop can now register ANY number of named agent sources — the local runtime, remote gateways (LAN/Tailscale/internet), Hermes Cloud instances, and SSH hosts — persisted together in one registry, instead of a single global connection with per-profile overrides bolted on.

This is PR 1 of the multi-source campaign: schema + storage + IPC + Settings UI. Routing/pool generalization to composite (connection, profile) keys, the multi-source agent roster, the plugin-SDK surface (Bot Mode), and fan-out updates follow as separate PRs.

Changes

• electron/connection-registry.ts (new, pure): v2 registry model. Required, case-insensitively-unique labels (device names) enforced at save; agentHandle() is the single home of the @name-device disambiguation rule for duplicate profile names across sources; normalizeRegistry degrades corrupt files to local-only; migrateV1ToRegistry imports the v1 global block + per-profile overrides (deduped by URL/SSH fingerprint) exactly once.
• electron/main.ts: connections.json beside connection.json (v1 file untouched — older builds keep working) with the same secret posture: safeStorage-encrypted tokens, 0600, tighten-before-parse, mtime cache. New IPC: hermes:connections:list/save/remove/set-primary/test; test maps entries onto the existing testDesktopConnectionConfig probe stack (zero new probe code).
• electron/preload.ts + src/global.d.ts: typed hermesDesktop.connections bridge; token bytes never cross IPC (preview + set flag only).
• Settings → Connections panel: list/add/edit/remove/test/make-primary with forced naming; the local entry is non-removable; removing the primary retargets to local. en + zh locales (other locales fall back via defineLocale).

Validation

Check	Result
connection-registry.test.ts (labels, validation, migration, ops)	21/21
connections-settings.test.tsx (list, required-label save, set-primary, test)	4/4
Full electron/ suite	1085 passed
tsc renderer + electron configs	clean
eslint on touched files	clean

Infographic

[github-actions]

૮ >ﻌ< ა ci review

_{ran on 08abe2e — fix(desktop): address connections-registry review findings}

⚠️ Warnings

OSV vulnerability scan · View job

5 known vulnerabilities found in pinned dependencies.

• CVE-2026-67213 in package-lock.json
• CVE-2026-67213 in website/package-lock.json
• CVE-2026-70608 in package-lock.json
• CVE-2026-56876 in package-lock.json
• CVE-2026-70606 in package-lock.json

How to fix:

Review the findings in the Security tab. Update the affected dependencies if a patched version is available.

---

debug info

CI timings

CI timings · View report · View job

Wall time 3m2s vs 3m27s (-12.1%). 9 job(s) slower, 4 faster, 5 unchanged.

• JS & TS checks / web / check: +13.0s
• JS & TS checks / apps/desktop / check:test:ui:shard-3of3: +12.0s
• JS & TS checks / apps/bootstrap-installer / check: +11.0s
• OSV scan / Scan lockfiles / osv-scan: +9.0s
• JS & TS checks / apps/desktop / check:test:desktop:platforms: +7.0s

[trevorgordon981]

Solid structure overall — the pure connection-registry.ts module with centralized agentHandle/label-slug rules, defensive normalizeRegistry that degrades corrupt files to local-only, and migration dedup by fingerprint is genuinely well done. Token bytes correctly never cross the IPC boundary. A couple of things need attention before merge.

1. The new Settings UI can't actually save a fresh token (blocking)

saveRegistryConnection (main.ts) calls resolvePersistedRemoteToken({ ..., persistToken: true, allowPlainText: input.allowPlainTextToken, ... }) and then unconditionally rejects with "Remote gateway session token is required." when !decryptDesktopSecret(entry.token).

But the new ConnectionsSettings.tsx save handler builds its payload with only {kind, label, id, url, authMode, token, host, user, port, keyPath} — it never sends allowPlainTextToken. So creating a brand-new token-authed remote depends entirely on encryptDesktopSecret(incomingToken, { allowPlainText: false }) succeeding and round-tripping. That path has zero test coverage in this PR — all connection-registry.test.ts cases are pure-module and the React test mocks the bridge entirely, so hermes:connections:save is untested. If encryptDesktopSecret throws when safeStorage is unavailable (headless/CI/local without keychain), creating a token remote silently fails at the IPC layer. The v1 flow explicitly threads allowPlainTextToken from input and has a focused regression test on that seam; this new handler ships the same secret-handling responsibility bare. At minimum add an IPC-level test for the required-token branch and confirm the UI can persist a fresh token.

2. Editing remote token→oauth leaves a dangling token

When editing (id present), existingToken is inherited unconditionally. Switching a remote from token to oauth keeps the stale token envelope on the entry, which decryptDesktopSecret still reads. Not a leak (still encrypted, never crosses IPC), but it's dead secret material on a connection that no longer needs it. Clear token when authMode is non-token, mirroring the v1 leavingCloud reset.

3. First-run migration is a read-then-write race

readDesktopConnectionsRegistry() does migrate-then-write on first boot. Two racing processes (updater relaunch, second window) both migrate and both write; the later write wins but labels were derived independently in each. Stable in practice under single-instance, but the write isn't guarded against a concurrent first-run.

Tests

connection-registry.test.ts is excellent (21 cases covering labels/handles/validation/normalize/migration/ops) and connections-settings.test.tsx gives good component smoke coverage. The gap is the main-process IPC layer — save/remove/set-primary/test have no coverage, and save is the one that handles secrets, which is exactly the finding in #1.

[helix4u]

The registry foundation looks strong: keeping normalization and migration pure, centralizing label and handle rules, leaving connection.json intact for compatibility, and preventing token bytes from crossing into the renderer are all good choices. I do think the user-facing and secret-handling seams need another pass before this lands.

The fresh Hermes Cloud path currently looks unusable. “Add connection” allows cloud, but a new editor defaults to authMode: 'token', the Cloud form exposes neither the auth selector nor a token input, and it does not use the existing Cloud sign-in/discovery flow. That produces a manually entered Cloud URL with token auth and no token, despite the UI describing Cloud instances as account-discovered. Migrated OAuth Cloud entries can survive, but creating a new one through this panel does not appear to produce a dialable entry. I would either wire this through the existing Cloud discovery flow or hide Cloud creation until that part lands.

“Make primary” is also exposed before anything consumes the v2 primary for routing. It updates connections.json and moves the badge, but the active Desktop connection still comes from the v1 configuration. The panel also says these sources can be used side by side, even though routing and roster support are explicitly deferred. That gives the user a successful-looking action that currently has no operational effect. I would gate the panel, remove the primary action for this slice, or make the storage-only state explicit until the routing PR lands.

The token-storage concern from the earlier review is valid on keyring-less Linux. The existing Gateway flow can ask for explicit plaintext-storage consent and resend with allowPlainTextToken; this panel has no equivalent path, so a supported machine without secure storage cannot save a token connection here. Switching an existing remote from token auth to OAuth also inherits the old encrypted token because an omitted token means “preserve existing.” The new save path should reuse the existing consent behavior and explicitly clear the token when the selected auth mode no longer uses it.

Could we also add focused coverage around the actual hermes:connections:save boundary? The pure registry tests are good, but the renderer test mocks the bridge, so neither layer currently exercises encryption failure and consent, required-token enforcement, token preservation versus clearing, or the Cloud payload that is persisted. Those are the behaviors most likely to break users in this slice.

[kshitijk4poor]

Ran a full review pass (targeted suites 21/21 + 4/4, whole electron/ project 1136 passed, tsc renderer+electron clean, eslint clean, plus a 3-angle reuse/quality/regression review with each finding verified against the code before reporting). No regressions to existing flows — the diff is purely additive, no new write sites for v1 connection.json, migration is lazy and mtime-cached. Findings below are all within the new feature; the first three seem worth folding in before the routing PRs start consuming the registry.

1. HIGH — editing an entry wipes fields the editor doesn't carry

saveRegistryConnection rebuilds the entry wholesale from the renderer payload; only token is inherited from the existing row. EditorState never carries cloud org or ssh remoteHermesPath/remoteProfile, so renaming a migrated entry silently drops them. Repro (real imports through migrateV1ToRegistry → normalizeConnectionInput):

migrated ssh entry:  {"id":"homelab-lan","kind":"ssh",...,"remoteHermesPath":"/opt/hermes","remoteProfile":"research"}
after label-only edit: {"id":"homelab-lan","kind":"ssh","label":"Renamed box","host":"homelab.lan","user":"k","port":2222,"keyPath":"/k/id"}
  → remoteHermesPath / remoteProfile gone
migrated cloud entry after label-only edit → org gone

org matters downstream (update-skip for platform-managed instances). One fix covers both: inherit unspecified fields from existing in saveRegistryConnection, the same way token already does.

2. HIGH — hidden stale ssh user/port beat the visible host input on edit

The ssh editor shows a single host field (user@host:22) but the payload also re-sends the stored user/port from editorFromConnection, and normalizeSshConfig gives explicit fields precedence over host-string parsing (entry.user || parsedUser, explicitPort ?? parsedPort). Editing a stored tek@spark1:2222 and retyping the host as admin@newbox:2200 persists tek@newbox:2222. Fix: reconstruct the composite into the host field when opening the editor and stop sending separate user/port (keyPath has no parse conflict and can stay inherited).

3. MED-HIGH — registry "Test" inherits v1 state

hermes:connections:test maps entries onto testDesktopConnectionConfig, which coerces against readDesktopConnectionConfig() (v1) as existing:

• Cloud/remote entry with no decryptable token → resolvePersistedRemoteToken returns the v1 global remote block's token, which is then decrypted and sent to the registry entry's URL — cross-host credential transmission plus a false "reachable ✓" for an entry whose own token is broken/absent.
• Testing the local entry calls testDesktopConnectionConfig({mode:'local'}) → resolveRemoteBackend(null) → the v1 global connection. If v1 mode is remote/cloud it probes that gateway and reports it as "This device"; if v1 mode is ssh, bootstrapSshConnection can refresh a token and write v1 connection.json — reachable from the new button even though the new code never writes v1 directly.

Fix: build the probe directly from the registry entry (or pass an empty existing into the coerce), and have kind:'local' probe the app-managed local backend.

4. MED — id:'local' guard missing at the validation boundary

normalizeConnectionInput accepts a caller-supplied input.id, including 'local', for a non-local kind — a crafted IPC payload ({id:'local', kind:'remote', ...}) replaces the local entry via upsertConnection, violating the "always exactly one local" invariant on disk. connectionIdForLabel carefully never mints 'local', but nothing rejects it when supplied. The UI can't produce this; one guard line closes it.

5. LOW polish

• Label-dedup while (…) label = `${label} 2` is written 3× and appends " 2" repeatedly — third collision yields Homelab 2 2 instead of Homelab 3 (the id scheme counts -2/-3 properly). A shared uniqueLabel() with a counter fixes both.
• Remote/cloud field-shaping (url → authMode → token → cloud-org guard) is triplicated across normalizeConnectionInput / normalizeRegistry / addRemoteLike.
• Migration-derived labels (URL hosts can be 253 chars) aren't clamped to LABEL_MAX (64), so such an entry fails validation on any later edit until manually renamed.
• If the first-run migration write throws (full disk / read-only), the exception escapes readDesktopConnectionsRegistry and hermes:connections:list hard-fails every call — the corrupt-file degrade only covers the file-exists branch. try/catch around the write (keep in-memory, retry next read) matches the documented "degrades rather than throwing" contract.
• notifyError(new Error(result.error || s.testFailed), conn.label) puts the bare label in the toast title with no failure wording (and duplicates it into the message for long errors).
• Unused i18n keys: connections.loading, connections.testing.

Verified clean: token bytes never cross IPC (preview + set flag, matching v1 sanitize); safeStorage/0600/tighten-before-parse/atomic-write all correctly reused from hardening.ts; en/zh key parity exact (35/35); migration URL/SSH fingerprint dedup works as described; settings nav/type/icon wiring complete.