feat(desktop): register a Linux launcher entry for hermes desktop

[ethernet8023]

What does this PR do?

On Linux, a freshly-built desktop app does not appear in the application launcher. There is no Hermes in the KDE/GNOME menu, no icon, and nothing to pin to a taskbar. Today, the only way to get an entry is to write ~/.local/share/applications/hermes.desktop by hand, make it executable, and refresh the menu caches yourself.

hermes desktop now writes the entry itself. hermes uninstall --gui removes it again.

Why this design. The two fields that matter contain absolute paths:

• Exec — the launcher runs the command in a minimal environment. It does not use the PATH customizations of your shell. So a plain hermes desktop fails without a message for anyone whose hermes lives in ~/.local/bin, a venv, or the Nix store. We find the real binary with the existing relaunch.resolve_hermes_bin() ladder. If there is no binary, we use the absolute interpreter path with -m hermes_cli.main.
• Icon — an icon name without a path works only with an indexed icon theme. Our app is not in an icon theme. The desktop entry spec permits an absolute path. We point at apps/desktop/assets/icon.png in the checkout. We do not copy the icon into the user's icon theme. Exec already uses the same source tree. A second copy adds about 600 KB and one more uninstall step. It does not survive anything that Exec does not survive.

We refresh the menu caches with update-desktop-database. Then we run kbuildsycoca6 or kbuildsycoca5 (Plasma 6 first, because only one of them is installed). We run each tool only when it is on PATH. Most desktops do not include these tools. A missing tool is not an error. We rewrite the entry only when its contents change. So a launch does not update the caches on every run.

This is best-effort. If we cannot write the entry, we print a warning. The app still launches. The entry is never a reason that a launch fails.

Type of Change

• ✨ New feature (non-breaking change that adds functionality)

Changes Made

• hermes_cli/linux_desktop_entry.py (new) — renders the entry, quotes Exec arguments to the spec, resolves absolute Exec/Icon paths, resolves XDG paths (honors XDG_DATA_HOME), and refreshes caches with tool gating. The module imports only light code and has no side effects at import time. The uninstaller and the Electron main process can run it without loading the full CLI.
• hermes_cli/main.py — cmd_gui calls the new _register_linux_desktop_entry() after the build and before the launch. The call catches exceptions, prints a warning, and continues. It does nothing outside Linux.
• hermes_cli/gui_uninstall.py — the entry joins the Linux packaged_gui_app_paths() discovery list. Then it also appears in gui_install_summary for the desktop UI. uninstall_gui refreshes the menu caches after it removes the entry. We do not remove the icon in the checkout. The icon belongs to the source tree.
• tests/hermes_cli/test_linux_desktop_entry.py (new, 16 tests) — entry contents, absolute Exec/Icon, interpreter fallback, spaces-in-path quoting, the executable bit, idempotence (no cache churn on an unchanged entry), themed-name fallback when the checkout has no icon, off-Linux no-op, and the full cache-refresh gating matrix.
• tests/hermes_cli/test_gui_command.py (+3) — registration happens on a Linux launch, a failing install still launches the app, and nothing is registered off Linux.
• tests/hermes_cli/test_gui_uninstall.py (+3) — the entry is discovered and removed, the cache is refreshed only when something was removed, and the checkout's icon plus the Python agent both survive.

How to Test

# 1. Install the entry against a throwaway XDG root
XDG_DATA_HOME=/tmp/xdg-test python -c "
from pathlib import Path
from hermes_cli.linux_desktop_entry import install_desktop_entry
print(install_desktop_entry(Path('.')).read_text())"

# 2. It should pass the freedesktop validator
desktop-file-validate /tmp/xdg-test/applications/hermes.desktop

# 3. Or just launch normally and look in your application menu
hermes desktop

# 4. Remove it again
hermes uninstall --gui

Unit tests:

pytest tests/hermes_cli/test_linux_desktop_entry.py \
       tests/hermes_cli/test_gui_uninstall.py \
       tests/hermes_cli/test_gui_command.py -q

Checklist

Code

• I have read the Contributing Guide
• My commit messages follow Conventional Commits
• I searched for existing PRs to make sure that this is not a duplicate
• My PR contains only changes related to this feature
• I have run the relevant tests and they pass. See the note below on one pre-existing failure.
• I have added tests for my changes (22 new tests)
• I have tested on my platform: NixOS (Wayland/Hyprland), Python 3.12

Documentation & Housekeeping

• I have updated the relevant documentation. The module and function docstrings carry the reasoning. No user-facing doc change is needed. The entry appears on its own.
• N/A. We added no config keys.
• N/A. There is no architecture or workflow change.
• Cross-platform impact is considered. is_supported() gates on Linux and BSD. cmd_gui skips the call everywhere else. Tests cover both darwin and win32.
• N/A. There is no tool behavior change.

Screenshots / Logs

The generated entry on NixOS, from install_desktop_entry:

[Desktop Entry]
Type=Application
Name=Hermes
GenericName=Hermes Desktop
Comment=Launch Hermes Desktop
Exec=/nix/store/k94wf8h4ziza8ffjqk4ry6kfy164zl5w-hermes/bin/hermes desktop
Icon=/home/ari/src/hermes-agent/apps/desktop/assets/icon.png
Terminal=false
Categories=Utility;
StartupNotify=true
StartupWMClass=Hermes

Checks with real tools, not only with mocks:

$ desktop-file-validate /tmp/xdg-test/applications/hermes.desktop
VALID ✓                                  # exit 0, no warnings

$ # with a real update-desktop-database on PATH
refresh ran: ['update-desktop-database']
$ ls /tmp/xdg-e2e2/applications/
hermes.desktop  mimeinfo.cache           # cache actually written

$ # with a real kbuildsycoca6 on PATH
ran: ['kbuildsycoca6']
$ cat /tmp/fakebin/log
kbuildsycoca6 --noincremental            # correct flag, actually invoked

$ # with neither tool present (this machine's default)
tools that ran: []                       # clean skip, no error

$ # removal
removed: [PosixPath('.../applications/hermes.desktop')]
removed again: []                        # idempotent
icon survived uninstall: True            # checkout untouched

[github-actions]

૮ >ﻌ< ა ci review

_{ran on 3e7464e}

⚠️ Warnings

CI timings · View report · View job

Wall time 9m34s vs 6m50s (+40.0%). 6 job(s) slower, 13 faster,

• Python tests / Run tests slice 2/8: +81.0s
• Check no committed infographics / check-no-committed-infographics: -70.0s
• Python tests / Generate slices: -51.0s
• Python lints / ruff enforcement (blocking): -50.0s
• Python tests / Run tests slice 1/8: -31.0s

---

OSV vulnerability scan · View job

35 known vulnerabilities found in pinned dependencies.

• CVE-2026-13697 in package-lock.json
• CVE-2026-13697 in plugins/platforms/photon/sidecar/package-lock.json
• CVE-2026-13697 in website/package-lock.json
• CVE-2026-18446 in website/package-lock.json
• CVE-2026-54285 in plugins/platforms/photon/sidecar/package-lock.json
• CVE-2026-16728 in package-lock.json
• CVE-2026-16728 in package-lock.json
• CVE-2026-16728 in plugins/platforms/photon/sidecar/package-lock.json
• CVE-2026-16728 in website/package-lock.json
• CVE-2026-69244 in uv.lock
• CVE-2026-69153 in website/package-lock.json
• CVE-2026-69247 in uv.lock
• CVE-2026-14643 in package-lock.json
• CVE-2026-14643 in plugins/platforms/photon/sidecar/package-lock.json
• CVE-2026-14643 in website/package-lock.json
• CVE-2026-69249 in uv.lock
• CVE-2026-69248 in uv.lock
• CVE-2026-15157 in package-lock.json
• CVE-2026-15157 in package-lock.json
• CVE-2026-15157 in plugins/platforms/photon/sidecar/package-lock.json

How to fix:

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