fix(desktop): keep attached images renderable across session switches and restarts

[OutThisLife]

An attached image in the desktop chat only rendered for the life of the turn that sent it. The gateway persisted the message text it had built for the model — a vision description plus an image_url:<path> hint, or a flattened parts list — and the renderer only understands @image:<path>. So history had no form the UI could turn back into an image: after a restart the caption survived alone, and on a session switch the warm cache disagreed with the stored text and the frontend "rescued" the image by appending it after the caption.

run_conversation already supports persist_user_message for exactly this "what the model sees" vs "what gets stored" split. This wires it up for the attachment path and makes the stored form actually renderable in both image-input modes, then fixes the two frontend bugs that were dormant until refs started reaching history — a duplicated user bubble from comparing raw text, and the thumbnail sitting inside the bubble's ~2-line clamp where it pushed the caption out of view.

Supersedes #70720 and #68176, whose work this builds on directly.

Beyond the superseded PRs

Two gaps that kept the original fix from covering the bug:

• Natively-vision-capable models were still broken, which is most users. Those turns send content as a parts list, and the session store deliberately ignores a plain-string persist override for a list payload (a text override must not erase a turn's image summary), so the override was silently dropped. The stored row kept only the caption plus a literal [Image attached at: …] / [screenshot]. The override now mirrors the shape — the @image: ref replaces the text part and the image parts stay, so the model still has the pixels for the rest of the session.
• Any path with a space produced a broken ref. The unquoted alternative in the directive pattern is \S+, so @image:/Users/me/Library/Application Support/…/a.png parsed as @image:/Users/me/Library/Application and stranded the tail as loose text. Composer images live in the app's userData dir, which on macOS is ~/Library/Application Support/<App>/ — so this hit every pasted or dropped image there. Refs are now quoted through a format_reference_value helper that sits next to REFERENCE_PATTERN and mirrors formatRefValue on the TS side.

Testing

• scripts/run_tests.sh tests/test_tui_gateway_server.py tests/agent/test_context_references.py tests/run_agent/test_run_agent.py tests/test_lazy_session_regressions.py tests/gateway/test_message_timestamps.py tests/cli/test_cli_interrupt_ack_race.py — 955 passed.
• npm --workspace apps/desktop test — 2874 passed, 3 skipped. typecheck clean, lint 0 errors.
• New coverage asserts the durable row carries a renderable ref for both image-input modes (the native one going through the real session-store flush, not a mock), that a formatted ref round-trips back through the parser for spaced/quoted/parenthesised paths, and that [screenshot] is dropped only when a ref was lifted from the same message.

Closes #70772
Closes #68092

Co-authored-by: alelpoan alelpoan@proton.me
Co-authored-by: 墨綠BG s5460703@gmail.com

[github-actions]

૮ >ﻌ< ა ci review

_{ran on a7182e2}

ℹ️ 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)

[alt-glitch]

This was generated by AI during triage.

Related to closed predecessors #70720 and #68176 and the attachment-history reports #68092/#70772. This active successor covers the persisted-reference, native-vision, quoting, reconciliation, and rendering gaps together.