feat(pairing): profile-correct approvals, and a desktop surface to do them from

[OutThisLife]

Pairing worked end-to-end only if you had a shell. Desktop had no surface at all, and the endpoints behind the GUIs read the wrong profile's store. This closes both, and absorbs the open PRs on each layer.

Two defects, one flow

Desktop had no pairing surface. Someone DMs the bot, gets a code, and lands in pending — where only the dashboard or hermes pairing approve could let them in. That gap is part of why #74427's defect survived so long: desktop users never saw the flow.

The endpoints ignored the profile. The gateway keeps one PairingStore per served profile (gateway/run.py), but every /api/pairing endpoint built the global one. An operator managing a named profile saw the wrong pending list, and approving wrote a grant into a whitelist their running gateway never consults — the user stays locked out while the UI shows them approved.

Proven against a live TestClient, two profiles, real stores:

global pending: ['GlobalGuy']      work pending: ['WorkGal']
POST approve {request_id, profile: work} -> 200
gateway store sees it: True        leaked to global?: False
bad profile:            404

The desktop surface

On the messaging page, not a new route. /messaging is already master-detail by platform, already polls every 6s, and already owns "who can talk to this bot" — the allowlist env vars in that same detail pane are exactly what an approval writes into via _sync_allowlist_add. A separate /pairing route would be empty 99% of the time and nobody would think to open it, which is the current failure mode restated.

• Count badge on the platform row — the discovery mechanism. Open Messaging for any reason and you see Telegram 2. Reuses the page's existing PILL_TONE.warn.
• Pending block above the credential fields — approving is the hot path.
• Approved list + revoke behind the shared ConfirmDialog.
• Neither renders when empty; approvals are rare and a permanent empty state would be chrome on a page otherwise about credentials.

ListRow and standard Button variants throughout — no new primitives, colors, or section chrome. Approval sends the row's request_id, never a code: the code is the requester's proof the channel is theirs and is never returned by the API. Rows paint optimistically and roll back visibly on failure; a 429 gets its own message since the code path's lockout is something the operator can only wait out.

Consolidation

Three open PRs cover the profile-scoping layers. Both code-bearing ones are cherry-picked, so authorship survives in git history rather than being reimplemented:

PR	Author	Disposition
#70932	@wgu9	Cherry-picked — the store resolver. Also fixes profile="default" resolving to profiles/default/ instead of the real global store
#60564	@briandevans	Cherry-picked — _all_platforms scanned the module-global PAIRING_DIR while every path helper used self._dir, so a profile store confirmed a user via is_approved() yet returned [] from list_approved()
#37758	@TreyDong	Subsumed — #70932's DM hint already emits the -p <profile> form

One test from #70932 reimplemented _pairing_store_for inside the test body and asserted against the copy; dropped per the AGENTS.md rule against tests that can pass while the real code is broken. #60564's assertion pinned the pre-consolidation profiles/<n>/pairing layout, updated to the platforms/pairing path #70932 introduces and repointed at the seam that actually resolves it (get_default_hermes_root, not get_hermes_home — a profile anchors to the hermes root, and that distinction is the bug).

Endpoint + client plumbing

_pairing_store(profile) resolves per profile and validates the name (400/404 on unknown). No _profile_scope needed — PairingStore resolves the profile's home itself, so nothing process-global is swapped across an await.

Both GUIs had to follow. The listing rides the query param, which for the dashboard meant deleting pairing from the "machine-global, must NOT be rewritten" exclusion list — a comment this change makes false. The mutating endpoints read the profile off the body, which no query-param rewrite reaches, so approve/revoke send it explicitly on both surfaces. That asymmetry is covered by a regression rather than a comment.

Verification

Rendered the real component with pending rows and read the output instead of trusting the tests, which caught two things: an unnamed requester printed its user id as both title and description, and the age was in the monospace/45%-opacity hint slot meant for env-var keys. Now Bee / 7712345 · just now and 8899001 / 12m ago.

Regressions added: profile isolation end-to-end through the HTTP layer; unknown profile rejected; approve/revoke carry the profile in the body and omit it entirely for single-profile users; approval sends the request id and nothing code-derived; a failed approve restores the row; no affordance renders when nobody is waiting; platforms still render when the pairing endpoint fails.

94 passed across the pairing/authz/multiplex, dashboard, and change-watcher suites; 577 passed in the desktop renderer; desktop and web tsc --noEmit clean, both lints 0 errors.

Live updates

A pairing request has to reach the page on its own signal. platforms.changed — which #74422 had just moved this page onto — is the mtime of gateway_state.json, where the gateway persists connect/disconnect health, and a new pending code moves none of it. Riding it would have left someone invisible in the pending list until an unrelated reconnect happened to fire.

So pairing.changed joins the change watcher, signed off the pending/approved ledgers across the global store and every profile's own. _rate_limits.json is deliberately excluded: it moves on every unauthorized DM, including ones that produce no new row, so signalling on it would refetch for nothing. Verified directly — a pending request moves the pairing signature and provably does not move the platforms one.

That also removes the need for the arrival toast to justify itself as a separate feature: the badge now appears within a watcher tick of the DM landing. A toast on top would need an event bus between the messaging gateway and the desktop WS server (separate processes today) — a real architectural seam, and not one to smuggle in here.

---

Supersedes #70932
Supersedes #60564
Supersedes #37758

[github-actions]

૮ >ﻌ< ა ci review

_{ran on 3c5da53}

ℹ️ Info

Desktop E2E visual evidence · View test artifacts · View job

1 visual diff.

_{inline evidence upload failed.}

Failed to upload diff-665a0833239e-onboarding-overlay-diff.png with gh image (exit code 1): Error uploading /home/runner/work/_temp/e2e-evidence/diff-665a0833239e-onboarding-overlay-diff.png: step 0 (get upload token): uploadToken not found on repo page — do you have write access to NousResearch/hermes-agent? (or, if NousResearch enforces SAML SSO, authorize at https://github.com/orgs/NousResearch/sso)