Summary

Desktop connected to a remote gateway can now attach images and PDFs and display agent-written images — the whole remote-media round-trip works for the first time.

Previously the desktop passed a local file path to image.attach. On a remote gateway (VPS) that path doesn't exist, so the upload was silently dropped ("skipped unreadable path") and the vision model never saw the image. The reverse direction was broken too: images the agent wrote on the gateway rendered as dead links in the remote client.

This consolidates the competing remote-media PRs (#38876, #40317, #21908, #39437) into one coherent implementation, taking the strongest part of each and adding shared-helper cleanup + a security hardening of /api/media on top. Salvaged onto current main (PR #41203 went stale by 10 commits during review).

Changes

Gateway — tui_gateway/server.py

• image.attach_bytes: base64 byte upload, written into the gateway's own images/ dir and queued via the existing native-image-attach pipeline. Magic-byte extension sniffing, data-URL prefix + whitespace tolerance, 25 MB cap, structured error codes. Accepts content_base64/filename (canonical) and data/ext (older-desktop aliases).
• pdf.attach: renders each page to PNG via pdftoppm (poppler-utils) at 150 DPI and queues the pages as images; 50 MB / 25-page caps. Accepts host path or base64 upload.
• Shared helpers (_decode_attach_base64, _sniff_image_ext, _queue_attached_image) so the two new methods and the existing image.attach don't duplicate logic.

Gateway — hermes_cli/web_server.py

• GET /api/media: returns a gateway-local image as a base64 data URL so remote clients can display it. Auth-gated like every /api route, extension allowlist + size cap, and confined to the gateway's own media roots (images/screenshots/cache, resolved symlink-safe) so an authed caller can't read image-extension files anywhere on disk.

Desktop — apps/desktop

• syncImageAttachmentsForSubmit uploads bytes via image.attach_bytes when the connection mode is 'remote'; the local fast path is unchanged.
• media.ts gains isRemoteGateway() + gatewayMediaDataUrl(); directive-text and markdown-text fetch images over /api/media in remote mode.

scripts/release.py — AUTHOR_MAP entries for the salvaged contributors.

What's intentionally out of scope

• Per-profile gateway switching from feat(desktop): remote-mode image attach/display + per-profile gateway switching #38876 — a separable feature, left for a follow-up.
• TUI file uploads (feat(tui): generalized file uploads (any file type, TAB completion, inline previews) #40492) — a different surface, stays its own PR.

Validation

• 11 new tui_gateway tests + 5 /api/media endpoint tests + desktop media.remote unit tests.
• Live E2E over the real dashboard stack: started the real web_server (uvicorn) against an isolated HERMES_HOME, drove image.attach_bytes + pdf.attach over a genuine /api/ws WebSocket (tui_gateway.ws.handle_ws → dispatch — the exact dashboard path), and hit GET /api/media over authenticated HTTP. 9/9 live checks passed: attach → gateway disk → queue, gateway-path → data-URL display with byte-identical round-trip, out-of-root 403, symlink-escape 403, non-image 415, missing 404, bad-auth 401.

Credit

Consolidates the work of @maxtrigify (#38876), @Justlrnal4 (#40317), @ccook1963 (#21908), and @RyTsYdUp (#39437), preserved via Co-authored-by trailers on the commit. Each source PR will be closed pointing here.

Infographic