# Task: Render AI Design agent activity progress

## Identity

- Task ID: 20260907-design-agent-activity-client-b6d913e4
- Mode: Feature
- Branch: codex/20260907-design-agent-activity-client-b6d913e4-design-agent-activity-client
- Worktree: D:\Datas\OthersProjects\.codex-worktrees\makelore\20260907-design-agent-activity-client-b6d913e4
- Base commit: da29294979da4ce041edf992b590ee6ea170a44f
- Owner: codex-root
- Status: Ready for Integration

## Scope

- Consume operation-scoped AI Design activity events through the existing Main-owned
  Works Square transport.
- Render one transient activity area attached to the optimistic user message, update
  meaningful steps in place, and settle it correctly on final reply or terminal error.
- Cover reconnect/replay, transport-unknown, stale-operation, and compact responsive
  presentation without duplicating the right-side Design summary.

## Intent And Constraints

- User messages remain immediately visible and final assistant replies remain normal
  conversation content.
- Activity is presentation state, not canonical Design state or a durable chat bubble.
- Show at most a few youth-safe phase/action/outcome lines; never render raw reasoning,
  tool arguments, prompts, provider output, or technical error details.
- Preserve stable operation identity across uncertain transport outcomes and ignore
  progress that belongs to another Workspace/direction/operation.

## Project Context Loaded

- Project goal: a youth-friendly desktop creation flow with Electron Main as the only
  network authority and server-owned Design Specification semantics.
- Current integrated focus: Living Form V2 and immediate optimistic user messages are
  integrated; the experimental `050d78d` progress UI is not assumed present.
- Decisions: ADR-007 keeps Renderer drafts temporary and Gateway operations stable;
  the activity view may observe events but cannot become another authority.
- Evidence/commitments: real paid Design production smoke remains separate and is not
  claimed by this client presentation task.
- Relevant peers: the Enter-key E2E task is test-only; older generic-error tasks have
  undefined scope. No semantic conflict was found.
- Likely modules: Main Workspace adapter/DTO mapping, Renderer store event reduction,
  Design conversation pane, and focused unit/Electron E2E tests.
- Unknowns to resolve in source: current stream event DTO shape and the best existing
  operation-to-optimistic-message association seam.
- Gate result: Passed.

## Outcome

- Added a dedicated `AI 处理过程` panel beneath the optimistic user message. Active
  steps update in place; completed processing collapses into a compact, user-toggleable
  summary while the final assistant reply continues to stream as normal conversation.
- Added Main-owned normalization for the four public progress stages. Main maps stages
  to fixed youth-safe copy instead of trusting arbitrary server/provider text.
- Preserved exact operation association across optimistic, streaming, canonical, and
  transport-unknown states by recording the pre-command turn sequence and matching the
  earliest exact canonical user turn after that boundary.
- Added Gateway command terminal-event handling so accepted commands converge after a
  polling disconnect. WebSocket-terminal-first races remain authoritative, stale
  connections cannot mutate current state, duplicate chunks advance the replay cursor,
  and late results from another Workspace cannot replace the active Workspace.
- Activity remains transient presentation state: it is filtered by Workspace and
  direction, never becomes a chat message or right-side Design authority, and contains
  no raw model reasoning, prompts, tool arguments, or technical provider output.

## Verification

- `pnpm exec vitest run tests/unit/image-workspace-store.test.ts
  tests/unit/image-canvas-page.test.tsx
  tests/unit/works-square-design-workspace.test.ts
  tests/unit/image-workspace-route.test.ts` — 67 passed.
- `pnpm exec tsc --noEmit` — passed.
- Focused ESLint across all eight changed TypeScript/TSX files — passed.
- `pnpm run build:vite` — passed; only existing chunk-size, dynamic-import, and stale
  Browserslist-data warnings were reported.
- `git diff --check` — passed.
- Independent client and lifecycle reviews were repeated after the terminal-race,
  exact-turn-association, and Workspace A→B→A fixes — PASS; no reachable P1/P2
  remained.

## Follow-ups

- Add an explicit snapshot/cursor reseed contract for a Gateway `cursor expired`
  response in a separate transport-resilience task. That pre-existing recovery gap is
  broader than the AI activity presentation slice.

## Promotion Candidates

- Target canonical documents: ADR-007 and the client/Main transport architecture.
- Proposal: document operation-scoped AI activity as transient Renderer state fed by
  Main-normalized public Gateway events; generic Gateway terminal events must settle
  uncertain writes without changing operation identity.
- Evidence: fixed public stage projection, exact turn association, terminal/poll race
  tests, stale-source and cross-Workspace tests, 67 passing focused tests, typecheck,
  lint, and production build.
- Future impact: future Agents SDK lifecycle hooks can reuse the same UI seam, while
  canonical Design state continues to come only from Workspace snapshots/events.
- Semantic conflicts: none identified; this preserves ADR-007's Main ownership and
  temporary Renderer-state boundaries.
- Human confirmation required: yes, during a future integration-mode promotion to
  canonical architecture documentation.