feat(gateway): HERMES_MEDIA_EXTRA_ROOTS to widen /api/media read roots

[maxtrigify]

Summary

GET /api/media (remote image display) is confined to ~/.hermes/{images,screenshots,cache}. That's the right default, but it means a desktop client connected to a remote gateway can't display images an agent generated outside that tree — e.g. into its project/output directory. Those requests return 403 {"detail":"Path outside media roots"} and render as dead "Open …png" links instead of inline images.

This adds an opt-in HERMES_MEDIA_EXTRA_ROOTS env var (an os.pathsep-separated list of absolute directories) that operators can set to allow additional read roots.

Why

Common multi-host setup: gateways on one machine, desktop on another. The agent writes generated images (charts, cards, screenshots) into its working/output dir — outside ~/.hermes — so they can't be displayed remotely today. There's no way to widen the allowlist without editing source.

Safety

The widening is deliberate and scoped:

• Each extra root is resolved symlink-safe (same .resolve() + root in target.parents check as the built-in roots).
• The image-extension allowlist and size cap are unchanged — this only adds directories, it doesn't relax the other guards.
• Default behavior is identical when the env var is unset (single-profile / single-host users are unaffected).

Changes

• hermes_cli/web_server.py — _media_serve_roots() appends HERMES_MEDIA_EXTRA_ROOTS entries.
• tests/hermes_cli/test_web_server.py — new test: a dir is 403 by default, served once opted in via the env var, and a sibling dir not listed stays 403 (scoping).

Verified: pytest tests/hermes_cli/test_web_server.py -k get_media → 6 passed.

🤖 Generated with Claude Code

[liuhao1024]

Verified — no issues found.

Security review notes on the HERMES_MEDIA_EXTRA_ROOTS widening:

• The existing _path_is_within boundary check and suffix/size guards remain in effect, so the widening is additive-only — operators explicitly opt in directories, and files outside those directories remain 403.
• Symlinks are resolved before the boundary check (line 830+), so a symlink inside an extra root that points outside is correctly rejected.
• The test coverage confirms scoped widening: an opted-in directory is served, a sibling directory stays forbidden.

The opt-in model (explicit env var, no wildcard expansion, default empty) is the right trade-off for a media-serving endpoint.

LGTM on the security posture.

[liuhao1024]

Positive Verification — Media Serving Security Review

Reviewed the full diff in hermes_cli/web_server.py and test.

Changes verified:

• Extra roots from HERMES_MEDIA_EXTRA_ROOTS are appended before the existing symlink-safe resolution loop — no path traversal bypass
• The sibling-dir test confirms the widening is strictly scoped (only opted-in dirs are served)
• raw.strip() handles whitespace in env var values correctly
• os.pathsep is the correct cross-platform separator for path lists
• Operator-controlled env var (not user-facing web input) — appropriate threat model

No issues found. Clean opt-in mechanism for operators needing wider media serving roots.

[teknium1]

Thanks for the scoped implementation and the preserved symlink, suffix, and size checks. This is an automated hermes-sweeper review.

• Current main intentionally confines /api/media to Hermes-managed roots in hermes_cli/web_server.py:1542-1584; the related [Bug]: Desktop remote mode: chat file links are silent dead ends (file:// fallback targets the gateway's path on the client; no display path for PDFs/non-images) #44523 discussion also recognizes that fence as deliberate.
• This PR introduces HERMES_MEDIA_EXTRA_ROOTS as a user-facing behavioral setting (11c181cca2fb), but the repository policy in AGENTS.md:102-105 requires new non-secret configuration to use config.yaml, not a new HERMES_* environment variable.
• If configurable media roots remain desired, please re-scope this as a documented, profile-aware config.yaml allowlist (with any required internal environment bridge kept internal) and preserve the existing containment checks.

---

Closed as not-planned per standing maintainer policy (env-var-for-config). This is a design-direction decision, not a code-quality judgment — see the Contribution Rubric in AGENTS.md for what the project is looking for. If you believe this policy was misapplied to your change, comment here and a maintainer will take a look.