makelore/.project-docs/30-worklog/tasks/20261012-agent-ui-restore-58d7c941.md

Task: Restore accepted Agent homepage and add platform pixel avatars

Identity

• Task ID: 20261012-agent-ui-restore-58d7c941
• Mode: Feature
• Branch: codex/20261012-agent-ui-restore-58d7c941-agent-ui-restore
• Worktree: /Users/chillishark/Makelore 麦洛/.codex-worktrees/makelore/20261012-agent-ui-restore-58d7c941
• Base commit: 7a7d1f7fd8
• Owner: codex
• Status: Ready for Integration

Scope

• Restore the accepted personal-Agent homepage and creation/configuration refinements from committed source 01fc7d0 on latest remote baseline 7a7d1f7, and add platform pixel-avatar selection alongside personal uploads.

Intent And Constraints

• User explicitly requests the referenced earlier conversation's UI and platform pixel avatars. Preserve all peer worktrees, remote/primary branches, Main-owned credentials, existing avatar storage contract and explicit save/apply policy. No paid model calls or real cloud mutations during verification.
• Preserve desktop focus: no UI automation, window activation or foreground switching. Build and screenshots use a headless browser. Any temporary-app update must account for the concurrently active trial-update peer before process replacement; installed app and profile data remain untouched.

Outcome

• Restored the accepted warm-white homepage, blue/peach/lilac cards, lifecycle badges, direct chat/adjust/continue actions and More menu from committed01fc7d0. Retained its current name/avatar → model/full-prompt flow and preserved the latest shared-conversation avatar header.
• Reused all16 existing pixel portraits. Avatar fields expose selectable thumbnails; Main accepts only allowlisted preset IDs and uploads bundled PNG bytes through the existing authenticated Yuxi avatar contract, with no file dialog or new server schema. Canonical icon persistence, explicit save/application, upload cancellation, failure and account isolation remain.
• Unset/broken images use a deterministic local pixel fallback consistently across the homepage/editor/share/version components. Narrow selection uses4 columns; desktop uses8, with keyboard focus and selected/loading states.
• The other trial-update task had already produced source872d4b2 and replaced PID1748 with11944. Compared that committed product source, preserving its refinements; took a fresh current-runtime snapshot before replacement and retained it as rollback metadata.
• Updated the running temporary app from this tested owned checkout: PID17709, Host API52733. Stopped only previous trial11944 and its process tree. Reused the existing trial profile and direct-network preference; installed/primary/peer source and remote branches remain untouched.
• Temporary background entry uses open -g, showInactive during startup and suppresses automatic focus only for startup; then restores ordinary user-driven window controls. It contains literal UTF-8 profile/artifact paths, since LaunchServices mangled non-ASCII environment path values in the isolated probe. No native UI automation or foreground activation was used.

Verification

• Required pnpm10.33.4 typecheck passed;5 focused unit files/108 tests passed. Scoped ESLint and git diff --check passed after correcting test-formatting lint. Dependencies reused only after byte-identical package/lockfile comparison.
• Production Renderer/Main/Preload/utility build passed. Verified all16 original PNG SHA-256 values are embedded in built Main, supporting packaged preset selection without source-asset filesystem paths. -5 headless browser cases passed using the actual CloudAgents components and typed Host API through an IPC fixture. Covered both375px/1366px, exact three card colors/actions, all16 assets loading, selected preview, create/save/reopen, and failed selection/save preserving prior values. Screenshots inspected in background; no Electron test windows were opened.
• Native replacement independently reported a ready, visible but unfocused window loading this checkout's built index.html. Foreground ASN remained unchanged across replacement and the startup interval. Actual Electron public health was DIRECT/HTTP200; local Host API returned expected401. No real cloud avatar upload or paid model request was performed during verification.
• Build manifest, previous-runtime snapshot, source-aware background entry and launch logs retained under .trial-runtime/agent-ui-pixels-20261012-58d7c941. New pointer refers to this source; all compiled artifact hashes are recorded.
• The optional broad tsconfig.node check reviewed by the avatar agent still reports unrelated pre-existing Main/composite diagnostics; standard required typecheck and production build passed. No unrelated config/type workaround was added.

Follow-ups

• Temporary app remains running. Main/remote integration and real cloud-storage acceptance are not performed by this feature task.

Promotion Candidates

• Targets: personal-cloud-Agent ADR and integrated current state during serialized integration. Proposal: promote the user-approved personal homepage/name-avatar/full-prompt refinement and16 platform pixel portraits, preserving canonical cloudicon and explicit save/apply. Evidence: user request/reference, source01fc7d0,108 unit checks,5 headless cases and the built/native trial. Future impact: creation/editing can use platform portraits without personal file selection. Supersedes older purpose-starter/preview UX only; user authorization already supplied.
• Target: temporary-launch workflow. Proposal: explicitly include the requested committed feature branches in trial source selection and preserve desktop focus via background launch, startup showInactive and literal UTF-8 paths. Evidence: initial remote-only omission, source comparison, non-ASCII probe correction and unchanged foreground during successful replacement. No canonical workflow or primary source was edited.

Project Context Loaded

Task context:

• Task ID: 20261012-agent-ui-restore-58d7c941
• Mode: feature
• Branch: codex/20261012-agent-ui-restore-58d7c941-agent-ui-restore
• Worktree: /Users/chillishark/Makelore 麦洛/.codex-worktrees/makelore/20261012-agent-ui-restore-58d7c941
• Base commit: 7a7d1f7fd8
• Ownership: bundled start exited 0; status JSON confirms task, mode, branch, worktree and reservation.
• Other active local tasks: every registry peer's Scope, Intent And Constraints and Promotion Candidates reviewed read-only. Relevant peers are Agent design review (committed 01fc7d0), purpose-page removal (85030a8), latest-source trial and active combined-trial update. Older teacher tasks are unrelated; child-language scope remains undefined.
• Overlap assessment: import only committed Agent product source. The user explicitly requested reviewing/restoring the named source conversation; no arbitrary dirty peer files are adopted. Active combined-trial peer shares the launcher target, so defer replacement until its run has settled; it does not prevent independent feature implementation here.

Read:

• AGENTS.md; planning entry, memory-index and planning-gate; this task record.
• Project positioning and integrated current-state (including merged-avatar entry); decision index; system-overview (Main/cloud/Agents boundaries).
• Personal-cloud-Agent ADR; relevant domain, success criteria, evidence/reflection indexes and commitments.
• Registry peer sections and referenced conversation user/assistant messages.

Relevant understanding:

• Goal: creator/student desktop product with Main-owned auth, transport and runtime; personal Agents use cloud execution and creator billing.
• Integrated focus: remote7a includes Agent icon uploading and display but excludes local01fc homepage/configuration refinement.
• Scope: retain warm-white light styling and blue/peach/lilac cards, direct chat/adjust actions and current identity/model/full-prompt creation flow; add selectable existing platform pixel portraits.
• Constraints: use typed Host API, persist cloud icon through existing Yuxi storage, keep upload cancellation/errors/unsaved edits and published snapshot semantics.
• Decisions: referenced user approval supersedes older starter-selection/preview descriptions. No teacher positioning or canonical documentation change.
• Evidence: earlier source/test commit preserved; all16 existing pixel assets are available. Old trial build matched remote exactly, explaining the omission.
• Modules: CloudAgents UI/CSS, existing avatar helper/assets, typed Host API and Main avatar transport, focused tests and README.
• Unknowns: real remote upload/storage not exercised; current user's visible UI not inspected. Concurrent trial replacement must be sequenced after the peer.

Gate result:

• Passed for isolated implementation and selective committed-source import; preserve peers and defer any concurrent trial mutation.

Implementation Plan

• Import only the six committed Agent UI/CSS source files and related focused tests from01fc; preserve latest backend/avatar contracts and canonical docs.
• Expose16 bundled pixel portraits in avatar selection; Main uploads an allowlisted bundled preset through the existing avatar service without a file dialog. Use a local pixel fallback for missing/broken icons.
• Verify typecheck, focused unit tests, scoped lint, production build and headless UI interactions/screenshots; update README and this record.
• After the peer trial update settles, prepare and verify the new temporary bundle from this exact tested source, preserving direct-network configuration/profile and desktop focus.