# Task: Diagnose distributed agent avatar propagation

## Identity

- Task ID: 20260926-agent-avatar-ml-3c3686ec
- Mode: Feature
- Branch: codex/20260926-agent-avatar-ml-3c3686ec-agent-avatar-ml
- Worktree: D:\Datas\OthersProjects\.codex-worktrees\makelore\20260926-agent-avatar-ml-3c3686ec
- Base commit: 9147b509c71f3ea765e5aaa8f542fd0a74bd4653
- Owner: codex
- Status: Ready for Integration

## Scope

- Diagnose and repair the missing Yuxi icon across publication, distribution and client rendering. User authorized implementation after the source diagnosis.

## Intent And Constraints

- Preserve immutable publication/replay and old-topic semantics, student billing, source storage ownership and existing local avatar fallback.
- No live configuration, deployment, automatic synchronization, main-branch merge or modification of peer worktrees.
- Concurrent ownership and Planning Gate passed in the same isolated task worktree. Same-base project memory and peer task scopes were retained from diagnosis; no new peers at resumption. Historical placeholder peer scopes remain unknown with no identified semantic conflict.
- Plan completed: froze the icon in Yuxi, resolved and preserved it in Works Square, rendered it consistently in Makelore, then verified each boundary. The one user-authorized fresh read-only reviewer approved the complete change with no blocking findings.

## Outcome

- Added optional icon_url to the distributed TeacherDefinition. TeacherAvatar handles the configured image and falls back to avatar_id when absent or when loading fails; new image URLs can be attempted after an earlier failure.
- Topbar entries, legacy/history companion entry, invitation speaker, panel header, welcome and assistant message rows use TeacherAvatar. Custom images use normal rendering; bundled pixel art keeps pixelated rendering.
- Updated README and added actual UI/browser regressions.

## Verification

- RED: both new tests failed with built-in avatar src instead of the expected cloud URL before implementation.
- GREEN: pnpm exec vitest run tests/unit/teacher-companion.test.tsx tests/unit/coding-teacher-ui.test.tsx: 56 passed.
- pnpm exec tsc --noEmit and focused ESLint passed. pnpm run build:vite passed for renderer, Main, preload and utility worker; existing Browserslist/chunk warnings remain.
- Real Edge Playwright distributed-icons case passed, including actual image decoding, independent 404 fallback, normal image rendering and the invitation speaker. Screenshot inspected in test-results; test route supplies deterministic image bytes, not production OSS.
- No installed Electron package or live production visual acceptance.

## Follow-ups

- Independent review passed. One non-blocking evidence gap remains: no combined test updates catalog metadata while an old topic is already open; existing separate data-flow tests and source inspection support the pinned-topic behavior.
- Task documentation drift checks passed across all three repositories; commit the scoped result for integration.
- Deploy compatible Yuxi, Works Square and Makelore versions, then use Operations sync to publish the existing agent's icon. Older topics keep their original published definitions.

## Promotion Candidates

- Target: .project-docs/20-architecture/system-overview.md and integrated current-state when useful.
- Proposal: record the versioned icon contract: native Yuxi icon becomes a frozen teacher snapshot field, WS resolves the public URL, client renders it with local fallback.
- Evidence: production diff plus regression results above. Future impact: visual identity follows the same publication boundary as other agent metadata.
- Semantic conflicts: none identified. Human confirmation: implementation authorized; canonical promotion and main-branch merge remain a separate integration task.