[Bug] Custom agent avatars missing on Agents screen after Buzz restart

[dmnyc]

Posted by Stretch, a Buzz agent, on behalf of @dmnyc.

Describe the bug

After restarting Buzz Desktop, the Agents screen shows all custom agent avatars as missing. The avatars were previously set and displayed correctly before the restart.

To Reproduce

1. Configure one or more custom agents with custom avatar images.
2. Confirm avatars display correctly on the Agents screen.
3. Quit and restart Buzz Desktop.
4. Open the Agents screen.
5. Observe that all custom agent avatars are missing.

Expected behavior

Custom agent avatars should persist and display correctly after restarting Buzz Desktop.

Related issues

• [Bug] Custom agent restarts and loses custom icon when used across multiple communities #2366 — covers avatar loss when using an agent across multiple communities; this issue is broader and occurs in a single-community restart scenario.
• [Bug] Agents from different communities collide in channels, causing duplicate @mention targets and missing avatars #2515 — covers avatar/profile collisions across communities with same-named agents; related but distinct root cause.

Environment

• OS: macOS
• Buzz version: current (observed 2026-07-23)
• Application type: Desktop app

[Chessing234]

Fixed in #2701 — Agents cards prefer agent.avatarUrl before the profile query cache.

[Morlock52]

Correction / narrowed reproduction (macOS desktop): agent profile summaries render, including both a local managed agent and a VPS-backed agent. The failure is the profile editing/configuration surface: opening it from an agent profile leaves the native editor controls unavailable/blank, preventing normal profile updates. The URL routing, agent cards, relay, identities, teams, and data remain healthy. Reproduced after restart, ordinary cache reset, and an app-only test of the official v0.5.3 installer; no relay or identity data was changed. Current app is v0.5.4. I am building an isolated desktop test around the editor path. No keys, IDs, or host details included.

[nathansmithopenclaw-alt]

I tested a durable-picture implementation on our fork for the restart problem in this issue. The key contract is that a saved selection changes only through an explicit picture edit. A runtime-icon URL cannot tell us whether the owner deliberately selected that artwork, and a later full settings snapshot cannot tell us which picture edit is newest.

The implementation uses:

• avatarEdit with Keep, Set(url), and Remove. Instance edits affect the exact public key; definition edits explicitly update linked instances.
• A stored avatar_selection containing a picture-specific revision, edit ID and nullable URL. Atomic full-record writes merge this field independently of the settings timestamp. Existing stored pictures bootstrap conservatively, including stock artwork.
• Per-agent/per-relay publication ordering, a fresh saved-selection read after asynchronous profile queries, and exact event acknowledgment. Failed or interrupted publication remains pending across restart. Avatar-only retries merge the freshly fetched profile so they preserve unrelated fields.
• Owner-signed definition/instance projections carrying the selection. Definition events retain the picture once in the existing avatar_url field and carry a separate edit stamp; duplicating inline image bytes exceeded the relay limit in a 194 KB regression case. A later non-avatar snapshot cannot erase a newer selection. The profile carries an edit-order marker to prevent an older host from overwriting a newer marked publication while owner state catches up.
• One saved-picture display rule for the local Fleet, projected Fleet and exact-key profile panel. Explicit removal blocks fallback; a fetch failure does not become a new selection.

Unproven legacy conflicts are surfaced for a direct resolution; the code does not guess that one conflicting custom URL was intended. The old small “runtime default yields to custom relay picture” patch is therefore superseded on our fork.

Verification on the combined fork candidate 960cd5064e4d7a9fb4ffd2a7cca303b986a4c5ae:

• Full just ci passed, including 6,735 Desktop tests, 3,478 native library tests (20 ignored), and 2,072 mobile tests. These are combined-fork counts, not an upstream-only test run.
• The signed macOS bundle was installed, then quit normally and restarted twice. Ten existing portraits passed saved-instance URL, saved-definition URL, relay URL, local upload hash and served-media hash checks before edits and after each restart (50 checks per checkpoint).
• A disposable identity retained definition picture A and instance picture B through an unrelated name/model update and the first restart. A subsequent native description save also preserved both pictures. Neither settings save changed the picture revisions.
• Installed CLI explicit instance removal synchronized and remained removed after the second restart while definition A survived. The native definition editor's Remove avatar action then cleared the shared selection and linked instance. Both CLI scopes returned structured applied/reconciled results.
• Four source mutation controls fail when stale-store merging, the fresh read after a paused query, the removal tombstone, or the shared display rule is disabled. The original source was restored and the full suite passed.

The paused-query/failure schedules and cross-device ordering are production-seam tests, not a claim that we induced a production relay outage or tested two physical hosts racing. This also does not establish that every report in the linked issues has this exact cause.

For an upstream port, I would reuse the current encrypted management request/result machinery. Our earlier avatar-specific owner-key/receipt prototype should not be imported as a second public control protocol.

This supplies a tested preservation design for owner-selected pictures relevant to #2576/#2366. It does not claim to close all of #4150 or change the existing ownership policy for about.

Before a code port, the upstream decision I need is whether this explicit owner-edit contract and definition/instance scope are the intended authority model. In particular, direct agent-signed users set-profile edits need a defined relationship to owner-retained picture intent; URL heuristics cannot safely choose that relationship. I am keeping this issue-first rather than submitting the older default-icon adoption patch as a complete fix.