# Task: Explain the first-click teacher welcome bubble

## Identity

- Task ID: 20260928-teacher-welcome-diagnosis-4fb809c2
- Mode: Feature
- Branch: codex/20260928-teacher-welcome-diagnosis-4fb809c2-teacher-welcome-diagnosis
- Worktree: /Users/chillishark/Makelore 麦洛/.codex-worktrees/makelore/20260928-teacher-welcome-diagnosis-4fb809c2
- Base commit: 4495345fb0a9ea1abef8e603629ce9b51d73eb05
- Owner: codex
- Status: Ready for Integration

## Scope

- Diagnose and fix the first-click teacher welcome bubble at baseline 4495345. Entering consultation consumes the static welcome and preserves true unread proactive messages.

## Intent And Constraints

- User first asked why the screenshot bubble appears, then explicitly requested the proposed fix.
- Concurrent and Planning Gates passed in this owned checkout; task identity, branch, absolute path and base verified on resume. Relevant project memory and peer scopes reviewed. Adjacent cleanup and truncation tasks remain isolated.
- Preserve published greeting content inside the consultation panel, account/project scope, real unread check-ins, cloud configuration, model requests and conversation state.
- No main merge, live trial restart, cloud publication or paid model request in this task.

## Outcome

- Cause: welcome_message displayed after config load until explicit dismissal; avatar entry only opened the panel, leaving the welcome bubble visible and changing its CTA to 看看智能体说的.
- The hook now hides static welcome immediately when consultation is open, then records welcome-dismissed for the current account/project. This also handles entering before async config completes, closing before config completes, same-agent selection and reload.
- The effect runs after scope initialization and changes only welcomeDismissed. Real invitations and seen receipts are untouched; a real check-in still requires explicit viewing/dismissal.
- Updated current README and focused unit/Electron coverage. Independent review found no actionable issue.

## Verification

- New unit tests first reproduced three failures on the prior source; unread check-in preservation already passed.
- corepack pnpm 10.33.4: teacher-companion.test.tsx, 33 passed.
- pnpm run typecheck, scoped ESLint, pnpm run build:vite and git diff --check passed.
- Electron welcome test passed: avatar entry, close/reopen, renderer reload, panel greeting retained, no model/topic POST.
- Electron proactive test passed: entry/close does not consume unread message; explicit CTA consumes it, original focus/draft/layout/timer assertions retained. Initial modified test had an invalid remount-focus expectation when opening an already-open panel; restored its original close-then-CTA sequence and reran successfully. Final total: 2 relevant Electron scenarios passed.
- Verification uses the existing mocked Host fixture with isolated test profiles; no real provider or trial application updated.

## Follow-ups

- Integrate this small source change with the current main/trial version through its owning integration task. Build outputs, test profiles and dependency symlink are not committed.

## Promotion Candidates

- Target: canonical classroom interaction/current-state docs during an integration task.
- Proposal: entering consultation consumes and persists the static welcome per account/project; actual unread proactive messages remain until explicitly viewed/dismissed.
- Evidence: explicit user request, hook change, 33 unit tests and two Electron scenarios.
- Future impact: prevents redundant first-entry invitations without hiding real messages.
- Semantic conflicts: supersedes the older welcome-until-manual-dismissal behavior only. No further human confirmation needed for this accepted behavior; canonical promotion remains integration-only.