feat: integrate pixel teacher presence and resilient classroom preview

.project-docs/30-worklog/tasks/20260922-teacher-presence-a38c72e1.md

@@ -0,0 +1,224 @@
+# Task: Add teacher presence and proactive classroom check-ins
+
+## Identity
+
+- Task ID: 20260922-teacher-presence-a38c72e1
+- Mode: Feature
+- Branch: codex/20260922-teacher-presence-a38c72e1-teacher-presence
+- Worktree: /Users/chillishark/Makelore 麦洛/.codex-worktrees/makelore-teacher-presence
+- Base commit: 12d800ec519aface444052b1478843d7caa70f34
+- Owner: codex
+- Status: Ready for Integration
+
+## Scope
+
+- Keep the teacher in the upper-right header, with direct consultation through its published avatar/name, periodic contextual teacher speech bubbles, and continuity with project teacher history.
+- Open the current work automatically from the work tab, reusing a running page or asking the coding Agent to prepare it through an internal product action.
+
+## Work Preview Excess Whitespace Follow-up
+
+- Same feature task resumed with matching registry/worktree/branch/base; current and read-only classroom peer records rechecked. Prior project context remains applicable; established light classroom layout takes precedence over generic design recommendations. Peer scope is already the integrated base and has no new semantic conflict. Gate passed. No subagents. User now requires consent before operating their live application; do not launch, raise, reload, or focus it during this repair.
+- Evidence: the supplied screenshot shows a large empty band above Work. CSS reserves 144 px (116 px on short windows) whenever any teacher bubble is visible, regardless of horizontal overlap. With consultation open, the bubble sits over the right pane but still pushes the separate work pane down. Even without consultation, the fixed reservation ignores the existing preview toolbar height.
+- Plan: remove fixed full-pane padding and measure the bubble against the actual native viewport. Add only the required clearance when their horizontal ranges overlap, recompute for message/window/pane size changes, and remove clearance on dismissal or non-overlap. Preserve bubble visibility, native preview bounds, drafts, and existing occlusion handling. Validate focused unit tests plus isolated headless layout rendering without touching the user's live window; update the Electron regression for the same geometry.
+- Completed: removed the 144/116 px work padding. The actual bubble element is passed to the embedded preview, where a layout effect measures native-page overlap and adds only missing clearance after accounting for existing DOM toolbars. ResizeObserver follows bubble/viewport dimensions and window resizing; repeated observations subtract the previously applied offset to avoid oscillation. Separate side panes and short messages need no extra gap, and dismissal/unmount immediately restore space. README and the existing Electron geometry assertion are updated.
+- Verification: 4 focused unit suites / 58 tests passed, including non-overlap, exact minimal clearance, observer stability, pane changes, toolbar clearance and cleanup. Typecheck, scoped ESLint, production Renderer/Main build, and whitespace checks passed. Added an isolated headless browser layout fixture using the real TeacherCompanion, AgentBrowserPanel and classroom styles with mocked local transport; three runs passed at 1440×900, 1180×720 and 1000×640, covering side-pane width changes, long/short text, dismissal, and native-viewport non-overlap. Inspected the large and compact screenshots: Work begins 20 px below the tabs beside the teacher pane, with no reserved empty band.
+- Validation environment: bundled headless Chromium was absent and its download stalled; stopped only that task-owned download and ran the fixture in an isolated headless installed Chrome session. An initial fixture mock returned an asynchronous unsubscriber; corrected it to the actual synchronous transport contract and reran all three sizes successfully. No user app/window/session was controlled, relaunched, focused or refreshed. Native Electron spec assertions were updated but not executed in this follow-up to avoid opening a foreground test window. The existing live trial will load the built Renderer on the user's next refresh; native live-window verification is not claimed.
+- Promotion candidate: replace fixed full-pane teacher clearance with measured native-page overlap in classroom interaction guidance. Evidence: user screenshot, fixed CSS diagnosis, focused unit and headless rendering tests. This restores the approved layout without changing teacher behavior or user work. Canonical changes remain for integration.
+
+## Missing Bubble Visibility Follow-up
+
+- Same task resumed with matching ownership, prior project/design context and peer registry checked; gate passed. User still cannot see teacher bubbles. No subagents.
+- Evidence: only two completed proactive turns exist in the real teacher topic, most recently 2026-09-23 00:15 UTC, while ordinary teacher exchanges continue through 02:50 UTC. Main permanently skips a previously seen operation-text fingerprint without considering newer teacher discussion. Renderer resets its five-minute deadline on every mount and has no fallback read if the topic stream disconnects. Only completed unread check-ins render a bubble; the published welcome text is unused there.
+- Plan: show the published welcome once per account/project on entry without a model call, let genuine unread replies take precedence, persist the periodic deadline across reloads, reconcile running teacher replies via bounded read-only polling, include completed student/teacher discussion in source-change detection, and allow unchanged-context check-ins at a slower fifteen-minute interval. Preserve dismissal, existing five-minute minimum, project/account boundaries, real Agent output, drafts and preview clearance. Verify with focused tests, Electron interaction and a native UI attempt.
+- Completed: the operations-configured welcome appears once per account/project with no model call; unread real check-ins take priority, and explicit dismissal acknowledges the visible message without exposing a second greeting. The periodic attempt timestamp survives reloads. Main includes completed ordinary teacher discussion in its context fingerprint, ignores check-ins themselves, and limits unchanged-context checks to fifteen minutes instead of permanently suppressing them. Pending topic results reconcile every fifteen seconds while visible through read-only requests, without resubmitting a model action or changing the selected teacher topic. Busy work defers to the next polling tick rather than restarting a full five-minute wait. Native preview clearance covers both welcome and actual guidance.
+- Verification: teacher service, companion, and chat panel suites passed (112 tests before the final read-only selection regression; the affected service/companion suites then passed all 82 tests, for 113 relevant cases overall). Typecheck, scoped ESLint, production Renderer/Main build, and whitespace checks passed. All three selected Electron interactions passed, including immediate published greeting without a model call, later real guidance, preserved student draft/focus, teacher entry selecting Work, and actionable work recovery. The first proactive E2E run exposed an ambiguous duplicate teacher-name test locator; the selector was narrowed to the identity button and the spec passed on rerun.
+- Native evidence: temporary Electron PID 72163 runs this task's checkout with the existing isolated profile. After earlier stale/no-op UI observations, the user's correction prompted a fresh app binding. Its actual route is `/chat`, and both accessibility and screenshot now show the real pale-green bubble below the upper-right published teacher avatar. It starts with “咱刚聊到「你自己做出来那一下是什么感觉」” and offers “和老师聊聊” / “等会儿聊”. The user does not need to return to the home screen. The installed Makelore process is a different app on project configuration and was only inspected; it was not updated. No student message or game action was sent during this verification.
+- Runtime limitation: the final non-selecting poll safeguard was built after PID 72163 launched; its service/UI behavior is covered by the 82-test final run and will load on the next trial launch. The visible native greeting/check-in fixes were already loaded and are verified in the current conversation window. Avoided another disruptive restart after obtaining the requested visible result.
+- Promotion candidate: document immediate operations-owned welcome, reload-stable periodic timing, ordinary discussion as progress context, fifteen-minute unchanged-context cadence, and read-only pending-result reconciliation. Evidence: observed missing bubbles, targeted regression coverage, Electron interaction tests, and actual trial bubble screenshot. No additional product approval is needed; canonical promotion remains an integration responsibility.
+
+## Actionable Failure Recovery Follow-up
+
+- Same-task ownership and project context checked; gate passed. User approved replacing generic failures with useful next actions. No subagents.
+- Evidence: the trial's latest failed internal work-open turn contains an empty assistant error and a Works Square expired-login 401. Projection loses the login reason and the hidden internal prompt removes its context.
+- Plan: preserve structured login failures; show one contextual recovery card for the latest failed action; route login back to the same account/project/action; preserve operation drafts during continuation; reuse the Main work action for checking/opening; bound transport retries with the same request identity. Keep uncertain dispatches from being automatically replayed. Validate service, hook, timeline, login and Electron interactions, then build.
+- Completed: expired Works Square login messages now project safe structured auth notices. Latest failed turns offer login/continue/check-work/refresh/model/account actions outside collapsed process details; empty assistant errors no longer repeat a generic failure. A healthy work preview removes its old work-failure entry. Internal continuation instructions remain hidden and do not name conversations.
+- Recovery preserves the current operation text and stored draft attachments while submitting a separate continuation using durable history. It refreshes state first, avoids active/uncertain requests, checks account/project scope after runtime recovery, and suppresses double clicks. Login return carries a one-use account/project/conversation target and requires fresh login even when Renderer auth looks valid; changed accounts or projects do not resume the old action. Existing teacher/friend drafts retain their own persisted storage.
+- Work startup reports structured auth errors; renderer transport checks retry at most twice with the same action identity, then expose explicit reconnect. Known terminal work failures require an explicit new attempt. No raw provider diagnostics are exposed as recovery copy.
+- Verification: 9 focused unit suites passed (155 tests), then 2 added matching-account login-return cases passed with the complete chat panel suite (31 tests). Final changed-component regressions passed (41 tests). Typecheck, scoped ESLint, production Renderer/Main build, git diff whitespace check, and three Electron regressions passed. Electron coverage includes failed work → check/open → ready, removal of recovery UI, retained draft, and one fresh explicit action identity. Reviewed the captured recovery screen visually.
+- Native trial: both inputs were empty and no file was selected before updating. Relaunched only the isolated trial with its existing profile (PID 71039); installed production app and game source were untouched. Native AX verified the new build route, alice account, 219 px sidebar, and known 5179 work address. Native click control again reported user/window changes and AX clicks did not reliably switch tabs; the work canvas capture was blank, so no claim of live-page rendering or native recovery-button verification. Login/continuation actions were validated with fixtures, not by submitting user credentials or deliberately triggering a live provider failure.
+- Promotion candidate: document contextual failure recovery, bounded idempotent transport checks, and account-bound login return in the Code workspace interaction contract during integration. No canonical docs modified here.
+
+
+## Hide Student Preview Diagnostics
+
+- Same-task feature ownership resumed; current/peer scope and prior planning context rechecked, gate passed. User asks to hide the Console/Network strip below their work. Limit this change to the embedded student work preview, preserving the Agent's backend debugging tools and the standalone developer browser.
+- Completed: embedded work previews omit the entire Console/Network diagnostics strip and its Renderer diagnostics subscriptions. Standalone developer preview and backend Agent debugging remain available. Updated README and existing unit/Electron assertions.
+- Verification: browser panel unit suite 9/9 passed, project typecheck and scoped ESLint passed, Vite/Electron build passed, Electron work-tab regression 1/1 passed, and git diff whitespace check passed.
+- Native verification: both student and teacher inputs were empty before refreshing. Reloaded only the Renderer using View > Force Reload; Main process and signed-in alice account stayed alive. After bringing the temporary window to the front, the actual game at http://127.0.0.1:5179/ rendered inside Work and the Console/Network strip was absent in both accessibility tree and screenshot. Left the trial on the functioning work preview. No game action, model message, or project source edit was performed.
+- Promotion candidate: Code workspace UI documentation should record that embedded student work hides developer diagnostics while Agent tools retain them. Evidence: explicit user request, regression assertions and native preview verification. No semantic conflict or further approval required; canonical updates belong to integration.
+
+## Intent And Constraints
+
+- User approved development after product discussion; at most one subagent. Teacher identity is cloud operations-owned. Keep existing light classroom UI, source-text context, student-owned implementation, friend, and existing drafts. No added visual teaching system or automatic coding tasks. Prior student-only invocation rule is superseded by explicit authorization for periodic proactive teacher messages.
+- User subsequently requested removal of the separate hand-raise button. Avatar/name remains the consultation entry, and closing the consultation returns keyboard focus there.
+
+## Outcome
+
+- Implemented the teacher identity using the existing published name/avatar in the upper-right header; it stays visible in operation chat and work tabs. The separate hand-raise button and its copy/styles were removed following user feedback.
+- Periodic foreground checks invoke the real teacher pipeline with completed source conversation context after five minutes. Main enforces account/project ownership, enabled configuration, cooldown, source-change fingerprinting, request idempotency, and running-request guards. System-originated check-ins do not fabricate student messages.
+- Teacher output appears in a compact bubble below the upper-right avatar with chat/later actions, or in the already-open consultation. Opening/dismissing retains the same project history. Main composer and consultation drafts, focus, work view, and friend role are preserved; unfinished teacher drafts defer automatic checks. The work tab temporarily reserves space above the native preview while the bubble is visible, preventing Electron's native view from covering it.
+- Added an isolated trial launcher and opened the new checkout with the existing trial profile. No production installation, merge, or server changes.
+- Removed the normal-message technical acceptance notice. Fixed accepted-request reconciliation with the matching run's terminal state, including completion before the HTTP acknowledgment. Renderer optimistic nodes no longer count as Main receipt evidence. Session projection preserves confirmed same-generation terminal identity and matches persistent message IDs before text, preventing repeated messages from borrowing another request identity.
+
+## Verification
+
+- TypeScript typecheck passed; scoped ESLint and git diff whitespace checks passed.
+- Focused Vitest: 4 files / 118 tests passed, including teacher API/service/context and UI timer/history/draft protections; repeated successfully after removing the hand-raise button.
+- Production Vite/Electron build passed; existing bundle-size/Browserslist warnings only.
+- Electron Playwright: 2 interaction tests passed, covering persistent presence across tabs, proactive bubble without focus theft, same-history chat, dismissal, retained student drafts, and existing teacher/friend consultation. Both passed again after the button removal, including focus restoration to the teacher identity. Native preview was rebuilt/relaunched and confirmed the button is absent, the published identity remains visible on both tabs, and clicking it opens consultation.
+- Native trial confirmed published teacher identity and consultation opening. Current trial conversation has no completed source content, so automatic guidance correctly has no context to send. Successful live model completion was not verified; existing historical trial requests already showed generic model failures. Proactive preview screenshots are explicitly fixture-backed examples.
+- Upper-right follow-up: 72 relevant UI/titlebar/browser unit tests and both Electron interaction tests passed; typecheck, scoped ESLint, production build, and whitespace checks passed. E2E verifies the bubble is below the avatar, right-aligned, completely visible, and above the native work-preview rectangle. Trial relaunched from the updated checkout. Native UI automation could observe the module selector but failed to click it with `noWindowsAvailable`; the actual Electron interaction and screenshot were verified by E2E. Copied the fixture-backed screenshot to `/Users/chillishark/Makelore 麦洛/课堂工作区预览/teacher-bubble-top-right.png` and opened it in Codex for immediate review.
+- Stalled-send follow-up: notice-removal UI tests 44/44 passed; store/session-projector/runtime/chat regression tests 86/86 passed, including 11 new cases (10 reproduced failures before the fix). Typecheck, scoped ESLint, production build and whitespace checks passed. Electron E2E 4/4 passed, including matched-run release without client-tagged history, rejection of an older run's completion, preserved next draft, no duplicate submit, first-message startup, consultations and proactive bubble.
+- Native trial restarted from the corrected build. Verified the orphan third hello and acceptance notice are absent, Send is enabled, operation/work tabs respond, and the exact unsent draft "我的游戏在哪里哦" is restored. No student message was sent, no project/history files were edited, and the installed application was untouched.
+
+## Follow-ups
+
+- User review of the teacher location and proactive bubble. Verify a successful live teacher model response with usable project context/configuration before release.
+
+## Promotion Candidates
+
+- Target: current-state, teacher architecture/ADR, and teacher domain rules. Proposal: extend explicit-only teacher consultation with user-authorized periodic contextual check-ins and persistent avatar/name presence. Evidence: explicit user request, implemented Main safeguards, 118 focused tests and Electron interaction evidence. Future impact: proactive invocations use existing model billing/configuration and must remain bounded/idempotent. Semantic conflict: earlier classroom/teacher docs say student-only invocation; this session explicitly authorizes the extension. No further human confirmation is needed for this feature direction, but canonical promotion remains an integration-task responsibility.
+- Target: conversation-state architecture and reliability evidence. Proposal: track accepted run identity through same-generation terminal hydration and resolve repeated messages by persistent identity before signature. Evidence: reproduced stale accepted blocking state and focused failing-then-passing regressions. Future impact: prevents permanent composer lock and wrong request association while retaining anti-duplicate guards. No semantic conflict or extra human confirmation required; canonical promotion belongs to integration.
+
+## Project Context Loaded
+
+- Task: 20260922-teacher-presence-a38c72e1, feature, branch codex/20260922-teacher-presence-a38c72e1-teacher-presence, owned worktree /Users/chillishark/Makelore 麦洛/.codex-worktrees/makelore-teacher-presence, base 12d800ec519aface444052b1478843d7caa70f34. Ownership and task reservation verified.
+- Read: AGENTS, README, memory-index, read-before-planning, planning-gate, task record, project-positioning, current-state, decision-index, system-overview, teacher ADR, relevant business-rules/success-criteria, commitments, and peer classroom task record.
+- Project goal: AI creation workspace with Main-owned Code execution and independent text-only teacher/friend consultation.
+- Peer classroom task is ready for integration and is the committed base. Shared code scope overlaps but this task has its own worktree; no peer edits. Its explicit-only trigger rule is intentionally extended by this user's new approved design.
+- Stale docs: project-positioning is a template; canonical teacher architecture predates project-level role consultations. Current README, committed code, and current user instructions govern this iteration. Real teacher model requests previously failed generically; successful external model response remains an integration uncertainty.
+- Affected modules: teacher service/context/routes/contracts, teacher UI and Code workspace, scoped regression tests and README. No server repository edits.
+- Gate: Passed.
+
+## Implementation Plan
+
+1. Add bounded, deduplicated proactive check-ins via the existing teacher pipeline, preserving cloud configuration and marking system-originated messages.
+2. Add a persistent teacher area with cloud identity, avatar/name consultation entry, short proactive bubble and chat/later actions; maintain same teacher topic and preserve drafts.
+3. Test timers, no duplicate/overlapping calls, project/account isolation, dismissal and chat handoff, then typecheck, build, Electron interaction verification.
+4. Launch the isolated iteration for user review and record limitations and outcome.
+
+## Right-corner Bubble Follow-up
+
+- Same task resumed with matching feature ownership, branch, worktree and recorded base; classroom peer remains ready for integration. Previously loaded project context still applies; peer scope and current task record rechecked. Gate passed. User explicitly moves teacher identity back to the upper-right header and keeps proactive speech bubbles. No separate hand-raise action.
+- Move the existing published-identity component into the header; anchor the short message below it. Preserve Agent pipeline, receipts, conversation continuity and composer focus. Show the actual rendered bubble using clearly identified test content so user can review it without waiting five minutes or requiring a working live model.
+- Completed: header avatar/name restored, bottom row removed, visible message indicator and anchored bubble added, work-preview space reserved only while speaking, all remaining hand-raise wording removed from the new companion flow. Preview is shown with explicit test-example attribution; no fake model reply was added to the user's conversation history.
+
+## Acceptance Notice and Stalled Send Follow-up
+
+- Same task resumed in its owned worktree; ownership, project-docs validation, current record and unchanged peer scope rechecked. Prior project context still applies. Gate passed. User explicitly asks to remove the technical acceptance notice and repair the apparently frozen trial.
+- Native evidence: window responds to closing the teacher panel; the operation draft is editable but Send is disabled. Timeline shows two durable hello messages (first failed, second answered), plus an orphan optimistic hello marked submitting. Existing trial session file contains only the two durable user messages. Native teacher history now includes a successful help response and a proactive check-in generated by the real pipeline.
+- Plan: remove only acceptance-status presentation; preserve receipt/idempotency gates. Reproduce missing terminal reconciliation and repeated-message identity issues with focused tests, fix the proven state transitions, rebuild and relaunch the isolated trial, restoring the student's unsubmitted draft without sending it.
+- Completed: implementation and regression evidence above; native application is responsive with the original unsent draft and enabled Send. Local session contents were read for diagnosis only. Successful teacher pipeline output was observed in existing user-generated history, superseding the earlier absence of live-response evidence; no new real model request was made during repair.
+
+## Automatic Work Preview Follow-up
+
+- Same-task ownership and planning context rechecked in the existing feature worktree; peer classroom task remains read-only. Gate passed. User approved an internal instruction that reuses a running work page or starts it when needed. User now forbids subagents; this follow-up is completed locally.
+- Plan: add a Main-owned, project-scoped preview request with a fixed startup instruction, known-page health check, busy waiting and duplicate protection; invoke it from the work tab, show simple progress/retry states, preserve drafts, and render the internal action as a short system entry. Validate with service/UI regressions, Electron interaction, typecheck and build; relaunch the isolated trial.
+- Completed: Renderer-capability-only `ensure-work` route resolves the active project in Main. A project-scoped service checks the known loopback page, serializes requests, waits for current project work, and sends one fixed internal action to the coding Agent if needed. The prompt instructs inspection/reuse before minimal startup and a real `agent_browser.open`. It does not consume student drafts/attachments or name the conversation. The timeline displays a short system-action entry. Work UI polls the same identity, shows preparation/waiting/failure, permits explicit retry, and ignores responses from prior projects. Existing manual browser controls and teacher occlusion remain supported.
+- Verification: 65 focused tests passed across preview service/hook, browser routes/panel, chat and title tests; an expanded service/hook/browser/timeline run passed 51 tests, including new system-entry rendering, failure/retry, and Renderer/project boundary checks. The final hook adjustment passed its 3 regressions. Scoped ESLint, normal `corepack pnpm run typecheck`, production build, and whitespace checks passed. Electron E2E passed 5 tests: automatic preview with unchanged draft and stable request identity, first-message behavior, settled-send recovery, teacher/friend consultation and teacher bubble. An additional Main-wide TypeScript check reports existing errors in untouched modules (composition, billing projections, fetch typings, etc.); no diagnostics reference the new preview service, its route, or title change. This broader check is not reported as passing.
+- Native verification: relaunched only the isolated trial, PID 60583. Before restart the current draft was empty. Clicked Work in `alice的游戏`: the real Agent inspected the project, found the existing Vite process serving port 5179, checked the page, and opened `http://127.0.0.1:5179/` with `agent_browser`. Native screenshot confirms the actual “我的同桌是宠物” game appears inside Work. Switching to chat shows only “已点击打开作品” for the internal instruction; switching back reuses the same page. Left the trial on Work. No server restart or new feature was requested from the project Agent; the no-running-service branch is covered by service/UI tests rather than stopping the user's existing service.
+- Promotion candidate: update Code workspace architecture/domain rules to include user-clicked work startup through the existing coding Agent, with reuse-first behavior, project scoping, busy waiting and request deduplication. Evidence: explicit user approval, regression tests, and successful native model/browser trace. Future impact: opening an unavailable work preview can invoke the configured model; it must remain separate from teacher/friend consultation and must preserve unsent input. No semantic conflict beyond extending the previously manual URL workflow; no additional human confirmation needed.
+
+## Work Preview Resume Repair
+
+- Same task resumed with matching feature ownership; current and peer records rechecked, earlier loaded project context still applies, gate passed. User reports the work is missing. Native state confirms an error placeholder while the actual game service still responds HTTP 200 at port 5179. Main logs and composition show background sleep closes the native browser; the trial uses E2E's accelerated 250 ms idle timer. The previous native verification covered first open and tab switching but missed this lifecycle transition.
+- Plan: preserve Main-known healthy work URLs across browser disposal, restore on foreground without asking the Agent again, and protect the opening operation from idle disposal. Add deterministic sleep/resume regressions and native verification after switching away and returning. Keep existing background cleanup and user drafts intact. No subagents.
+- Completed: Main retains up to 100 verified addresses bound to project ID and resolved path for this application session, probes them before restoring a disposed view, and holds an activity lease while preparing the preview. The work hook pauses checks when hidden and rechecks on visibility/focus using the same action identity, with overlapping checks deduplicated. Browser state application ignores older generations so a late closed-state response cannot replace a restored view. Existing runtime/background cleanup remains enabled. README updated. The user later permitted one subagent if necessary; none was needed or used.
+- Regression evidence: the new disposed-view and foreground-focus tests failed before the fix. Final focused run passed 41 tests across service/hook/browser/routes, including inactive-server fallback, hidden-state pause, duplicate focus events, stale snapshot ordering and lease acquisition/release. Typecheck, scoped ESLint, build and whitespace checks passed. Electron E2E passed all 4 selected tests, including work-tab restoration from a closed-state event on foreground, conversation resume, consultation and teacher bubble.
+- Native evidence: restarted only the isolated trial (PID 61454) after confirming both inputs were empty. This restart's new model request failed with the existing generic provider error; the trial is signed out and teacher now reports login required, so successful fresh model startup is not claimed for this follow-up. Restored the already-running game using its previously verified address through the normal address field, then re-entered Work so Main verified and retained the page. Hid the app using Cmd-H: native game content disappeared after the accelerated background cleanup. Raised the same window: the actual game reappeared automatically at port 5179 without another startup action. Opened teacher consultation alongside it and verified both panes remain visible. Left that window raised with Work selected. User's game process, source files, and gameplay data were not edited.
+- Limitation: the verified-address cache lasts for the Main process, not across application restarts. A fresh process with no known work address still uses the configured Agent and can show a real provider/login failure; the repair does not fabricate successful model execution. Durable preview-address persistence is outside this targeted sleep/resume fix.
+
+## Teacher Bubble Visibility and Workspace Proportions
+
+- Same feature task resumed with matching branch/worktree/base ownership; active and peer task records and planning context rechecked. Peer classroom task remains read-only and ready for integration. Gate passed. Retain the established light sage classroom design; generic design-skill suggestions do not replace it.
+- User asks why proactive speech is not visible, requests the left column at half width, a wider teacher pane, and a prompt-style “老师帮我看看” action in place of the footer hint. Latest instruction requires explicit permission before any subagent; none used.
+- Diagnosis: five-minute checks plus automatic dismissal while teacher consultation is open hide the bubble; matching unchanged source context also suppresses model calls by design.
+- Plan: keep periodic/cost guards, preserve new proactive invitations even with the pane open until explicitly viewed/dismissed, and avoid losing an unseen check-in when another reply follows. Narrow Code sidebar from 256 to 128 pixels with compact controls, widen consultation default from 380 to 508, and relocate the help shortcut into the composer footer. Update focused UI/Electron coverage, build, reload only the temporary Renderer, and verify.
+
+- Completed: Code rail and matching titlebar surface are 128px, with compact project toolbar, full-name tooltips, and preserved native window-control hit areas. Consultation defaults to 508px and can expand/resize to 640px; compact-window overlay rules remain. “老师帮我看看” is the single teacher shortcut, styled as a pill in the composer footer; removed the old footer hint and duplicate empty/history help buttons. Existing model intent and draft preservation remain.
+- Bubble fix: finds the latest unread completed check-in, including when later requests follow, and no longer treats an open teacher panel as an acknowledgment. Opening the avatar preserves the invitation; the invitation's view/later actions explicitly acknowledge it. No automatic model cadence or Main cooldown/fingerprint rules changed.
+- Verification: 51 focused unit tests passed (teacher UI/companion, titlebar, feature UI); final companion adjustment passed all 7 companion tests. Typecheck and scoped ESLint passed. Production build passed. Both Electron interaction specs passed: proportions/help/draft behavior, and periodic bubble with consultation already open. First E2E attempt read a transient missing sidebar bounding box; switched to waiting on computed width. A later clock-controlled attempt advanced before cleared-draft effects settled; synchronized controlled frames and the polling tick, then the bubble spec passed. No passing full-suite claim.
+- Native verification: refreshed only the trial Renderer with alice still signed in and operation draft empty. Screenshot confirmed half-width rail, healthy actual game at port 5179, and a real newly received proactive bubble discussing the user's pet game. The model call came from the existing periodic mechanism, not fabricated test content. Final minor avatar-acknowledgment adjustment was built and tested; native menu/click automation subsequently returned stale-element/noWindowsAvailable, so its final in-process reload and opening the wider pane could not be confirmed. No Main restart, game actions, student messages, or user-source changes were made. Wider pane and footer layout were visually inspected in the Electron test screenshot.
+- Promotion candidate: Code UI documentation should record half-width navigation, wider consultation, footer prompt shortcut, and explicit-only read acknowledgment for proactive invitations. Evidence: user request, implementation, UI/Electron coverage, native layout and real bubble. No semantic conflict with already-authorized periodic teacher checks; canonical changes remain for integration.
+
+## Adjustable Left Sidebar
+
+- Same-task ownership resumed; active and peer records rechecked, previously loaded project context and approved classroom design still apply. Gate passed. User requests one-third more than the current 128px width, with dragging up to twice that current width. Default 171px, range 128–256px. No subagent permission requested or used.
+- Plan: add a local persisted width shared by sidebar/titlebar/header; implement the right-edge pointer and keyboard resizer with bounds and reset, preserve sidebar collapse/peek and native chrome, then validate drag/persistence/header alignment in focused tests and Electron, build, and reload the temporary Renderer if native controls respond.
+- Completed: default width is 171px; a six-pixel right-edge separator supports pointer dragging within 128–256px, arrow/Home/End keyboard adjustment, and double-click reset. The local settings store remembers the width without backend writes. Sidebar, titlebar background, and conversation header share the same normalized width; collapsed peek behavior and native window-control safe areas remain intact. README reflects the new sizing.
+- Verification: 35 focused unit tests across five files passed; normal TypeScript check, scoped ESLint, production build and whitespace checks passed. The Electron consultation interaction test passed with new drag-to-maximum, keyboard bounds, collapse/expand, reload persistence, titlebar/header alignment and reset assertions, followed by existing teacher/friend draft-preservation coverage. Its screenshot was visually inspected.
+- Native verification: refreshed only the trial Renderer, preserving Main PID 61454 and signed-in alice. Accessibility confirms the new separator at 171px and a native screenshot confirms the wider sidebar. After refresh the conversation briefly showed the existing local-runtime unavailable state; the normal retry followed by bringing the window forward restored the original history and removed that error. No new student/model message was sent. Native coordinate drag verification was blocked by the automation surface reporting noWindowsAvailable; actual pointer dragging was verified in the Electron interaction test. Left the trial at the default width with operation conversation visible; no Main restart or user project edits.
+
+## Window Controls Investigation
+
+- Same task resumed in its owned feature worktree with matching branch/base/registry; active and peer records and project context rechecked. Classroom peer remains read-only; no conflicting scope. Gate passed for diagnosis. No subagent used.
+- User reports missing minimize/maximize/close controls. Current native Mac trial screenshot and accessibility tree show all three system traffic-light controls at the upper left. Source keeps native macOS chrome, custom three-button Windows controls, and native Linux chrome. No absence was reproduced in the current window; no speculative UI changes made.
+- Asked whether the user wants explicit dash/square/close controls, sees disappearance after navigation/fullscreen, or refers to Windows. Awaiting that detail before changing the platform design or a specific failing state.
+
+## Simplify Consultation Reply Actions
+
+- Same-task feature ownership, active/peer scope and previously loaded project context rechecked; gate passed. User approves hiding “我去试一试”, consultation “复制”, and the internal “已点击打开作品” timeline entry. No subagent used. The separate window-controls clarification remains pending.
+- Plan: remove the unused consultation return action and visible copy buttons; hide internal work-open prompt nodes while retaining Main startup/deduplication, durable history and real results/errors. Update existing focused unit/Electron assertions and README, then typecheck, build and reload only the trial Renderer after checking drafts.
+- Completed: removed consultation reply copy/return buttons and the unused return callback. Internal work-open user nodes render no UI, including existing history. The actual work startup pipeline, stored nodes, operation-chat reply copy, results/errors and admin-only legacy bring-back behavior remain intact. README synchronized.
+- Verification: 47 focused tests passed across teacher UI, timeline and feature UI; existing assertions now cover teacher/friend action absence and hidden startup instructions with preserved result/history. Typecheck, scoped ESLint, production build and whitespace checks passed. Both Electron interaction tests passed for consultation/draft preservation and automatic work preparation/resume; the consultation screenshot was visually inspected.
+- Native attempt: current trial account alice and both empty inputs were verified before Renderer refresh; preserved the user's new 219px sidebar width and Main process. Refreshed via the native View menu. Renderer reloaded but initially showed local-runtime unavailable, so invoked its normal retry as in the prior follow-up. Subsequent UI observation reported the Mac is locked and automatic unlock unavailable; final history/teacher-panel visibility could not be confirmed. Need manual unlock to complete native verification. No model message, project-source edit, Main restart, or native close/minimize action was performed.
+- Promotion candidate: update classroom UI guidance to keep consultation replies free of redundant return/copy actions and hide the internal work-open instruction in the student timeline. Evidence: explicit user request and focused unit/Electron checks. Only presentation changes; startup execution and history retention are unchanged. No semantic conflict or additional design approval needed; canonical promotion remains an integration responsibility.
+
+## Open Work Alongside Teacher Consultation
+
+- Same-task ownership and peer scope verified; previously loaded project context and approved classroom layout still apply, gate passed. User wants teacher conversations to default to the Work tab. No subagent used.
+- Plan: have the shared explicit teacher entry select Work, covering avatar and proactive bubble actions; preserve operation/consultation drafts and allow manual tab changes afterwards. Unattended proactive bubbles must not switch tabs. Reuse existing work preparation and native preview sizing, update interaction assertions and README, then validate and refresh the isolated trial if unlocked.
+- Completed: the shared `openTeacher` handler now selects Work alongside teacher consultation. Both avatar and invitation actions use it, including reopening from a friend conversation. Manual tab switches remain available and retained drafts are unchanged; receiving an unattended check-in does not switch tabs. README updated.
+- Verification: 35 focused chat/companion tests passed. Typecheck, scoped ESLint, production build and whitespace checks passed. All three Electron interaction specs passed: avatar-open Work and preserved drafts, proactive invitation-open Work without unsolicited tab switching, and work preparation/background restoration. Friend opening retains the current selected tab.
+- Native limitation: Mac is unlocked again; before refresh verified alice, 219px sidebar and both empty drafts, with the teacher pane open on Operation. Native View/Force Reload and Cancel repeatedly reported stale-element errors, including after rebinding the app; keyboard escape/reload did not change the menu state. Final in-process refresh could not be confirmed. Kept the Main session/account alive; no messages sent or user project edits. The build is ready for a manual Renderer reload, while native confirmation of this change remains pending.
+- Promotion candidate: document that explicitly entering teacher consultation selects Work by default, while incoming proactive speech preserves the student's current tab. Evidence: user instruction, shared handler, unit and Electron coverage. Reuses existing preview startup semantics and preserves user control; no conflicting decision or extra approval needed.
+
+## Persistent Failure Text Diagnosis
+
+- Same-task ownership and current/peer records rechecked; earlier planning context remains applicable, gate passed for read-only diagnosis. User asks why “本次处理失败。” keeps appearing. No subagent, model call, or source-code change.
+- Native tree shows the latest operation process group expanded, with the generic failure fallback. Read-only inspection of the bound Pi session found exactly two failed assistant messages, both empty with `401 Works Square login session is missing or expired`: the first hello at 2026-09-22 18:49:42 Asia/Shanghai, and an internal work-open action at 21:49:32. The last persisted operation message is that second failure; there are no newer operation failures in this session.
+- Cause: the timeline preserves history; an empty failed assistant message renders the fallback “本次处理失败。” inside its process group. The previous presentation change hid only the internal work-open user prompt, deliberately retaining results/process/error nodes. This leaves the old internal failure visible without its original action label. Background lifecycle stops in the current log are classified intentional background sleep, not new failed model turns.
+- Reported the historical 401 and the presentation omission to the user. No assertion that current coding credentials are valid was made; no fresh provider request was sent to test them. Current account label is alice. Any decision to hide or restructure the rest of internal startup turns should preserve current actionable startup errors in the Work area and durable history.
+
+
+## Pixel Teacher Speech Bubble Integration (2026-09-23)
+
+- Same task resumed successfully in feature mode, branch `codex/20260922-teacher-presence-a38c72e1-teacher-presence`, worktree `/Users/chillishark/Makelore 麦洛/.codex-worktrees/makelore-teacher-presence`, base `12d800ec519aface444052b1478843d7caa70f34`. Registry matches. The classroom peer is the inherited integration base, remains read-only, and has no conflicting newer scope. Existing uncommitted work belongs to this resumed task and is preserved.
+- Project context reloaded: memory entry, active/peer task records, positioning, integrated current-state, decisions, system overview, teacher ADR, relevant business/success rules, commitments, README and AGENTS. Template/stale positioning and source-scoped ADR details yield to the already-approved project consultation implementation. Gate passed.
+- User approved integrating the conversation prototype into the existing project and opening the temporary app; this explicitly authorizes this turn's launch/refresh, superseding the earlier live-app restriction for this task. No subagents. User clarified: remove the prototype's “老师偶尔来看看” switch, preserve existing proactive teacher messages and periodic backend behavior.
+- Plan: bundle the approved pixel portrait, use it consistently at the header and teacher panel; compact the proactive speech bubble and attach a small matching portrait only while there is a real message, preserving source/history/dismissal and native-page clearance. Do not ship prototype controls, fabricated project messages or the opt-in switch. Validate focused visibility/identity/dismissal/clearance cases, typecheck and build; open the same isolated temporary app and verify the visible result.
+
+- Implemented: copied the approved transparent pixel portrait into `src/assets/consultations/teacher-pixel.png`. Header/fallback header and student teacher consultation use the same bundled portrait, while operations draft preview retains its configured avatar. Actual welcome/unread teacher messages create a compact 232px text bubble beside a 48px portrait, both inside one presence group. No idle floating portrait, no checkbox, and no fake model response or new scheduling path. The existing header remains available after dismissal; both close and later actions remove the whole presence group. Native WebContents clearance now receives the entire presence group.
+- Validation: 68 focused cases across companion, teacher panel, preview clearance and chat panel passed; typecheck, scoped ESLint, production Renderer/Main/Preload/utility build and whitespace checks passed. The updated Electron proactive-message regression passed, covering portrait consistency, absence of the switch, message-only presence, grouped dismissal and whole-presence native clearance. All three responsive layout cases passed at 1440×900, 1180×720 and 1000×640 using installed headless Chrome. The initial layout attempt could not launch because bundled Chromium is absent; reran with the fixture's existing `MAKELORE_LAYOUT_BROWSER_CHANNEL=chrome` option. Visually inspected the Electron screenshot: the compact speech bubble is attached immediately left of the pixel portrait, with no extra band above the adjacent work pane.
+- Native verification: rebuilt and relaunched only the existing isolated trial/profile through `scripts/launch-teacher-trial.py` (PID 79535), then raised it and opened the current project with teacher consultation beside Work. Native screenshot confirms matching pixel portraits at the project header and teacher pane; no opt-in switch. This unpackaged build stores credentials only in memory (confirmed in its startup log), so restarting Main returned the trial to signed-out state. Real proactive history cannot load until the user signs in again; do not claim a live authenticated bubble was verified or fabricate one. Existing project/conversation history and 219px sidebar remain. The original running pet page was reached through its known address using the normal UI, confirmed by its native accessibility tree; after accelerated background cleanup, the final screenshot showed preparation/blank preview, so sustained preview rendering is not claimed. No game source, gameplay action or student message was edited/sent. The attempted automatic Work entry reported the existing login requirement.
+- Promotion candidate: document one bundled pixel teacher identity for student-facing header/consultation, message-only floating portrait and attached compact speech, whole-group dismissal/native clearance, and removal of the prototype opt-in switch while preserving real scheduled check-ins. Evidence: explicit user clarification, actual source integration, focused tests, Electron screenshots and native avatar verification. No conflicting teacher scheduling decision or additional product approval required; canonical promotion remains an integration responsibility. Only authenticated live-bubble verification remains dependent on the user signing in to the temporary app.
+
+## Student Work Preview Closed-State Recovery
+
+- Same task resumed in its owned feature worktree/branch/base; registry matches, classroom peer remains read-only without conflicting scope. Prior loaded product context remains applicable; active/peer records, entry/gate, evidence/reflection/commitments and AGENTS rechecked. Gate passed. No subagent used.
+- Native evidence confirms the user's exact raw “开发浏览器已关闭。” error above an indefinite opening placeholder. Main hides/disposes native views on host hide and background cleanup. The work hook permanently skips checks after a manual open, and a queued initial starting update can overwrite manual success. Main only remembers addresses during ensure-work, not when the normal address field opens a page. Presentation errors are surfaced verbatim and survive successful later snapshots.
+- Plan: retain successfully opened project URLs in Main for later verified reuse, restore closed views without a new model action, remove the manual-open recovery dead end while ignoring stale requests, handle presentation/closed-state races with bounded retry and actionable student language, then run focused regressions, build and verify the actual preview after hide/show. Preserve existing resource cleanup, draft/project boundaries and original game files.
+
+- Completed: successful browser open/navigation now records the project/path-bound address in the existing Main preview service. A manual open supersedes older startup checks without preventing future focus/closed-state recovery, and an older pending check cannot later submit an unnecessary Agent prompt. Renderer automatically rechecks on a closed snapshot and retries presentation failures twice, then offers “重新打开作品”. Embedded preview errors no longer surface raw browser diagnostics; successful snapshots clear stale error text. Standalone developer controls retain their behavior. README synchronized.
+- Regression evidence: four new hook/panel cases failed on the previous implementation (manual-open focus, queued starting overwrite, closed-state recovery without focus, and presentation-close race). Final focused run passed 53 tests across service, hook, panel and route suites, including pending manual supersession without a late prompt, project/path isolation, bounded retry and explicit recovery. Typecheck, scoped ESLint, production Renderer/Main/Preload/utility build and whitespace checks passed. Both Electron work-preview specs passed: manual address open followed by closed-state recovery without another focus event or a new request identity, preserved drafts, and failure recovery.
+- Native verification: both inputs were empty before replacing the isolated trial. Multiple live Electron previews shared the same bundle ID, so CUA resolved the other teacher-components demo even when given this worktree's runtime path. No demo conversation/project actions were performed. The trial launcher now clones the existing Electron app into the same temporary trial directory with a distinct trial-only bundle identity; shared dependencies and the installed production app remain unchanged. Successfully launched PID 81381 from the current build/profile and selected the exact trial. Reopened the known running pet page at port 5179 through the normal address field; native screenshot confirms actual “我的同桌是宠物” content, with no raw closed error or stuck loading state. Cmd-H removed the native page; raising the same window restored it automatically, verified in AX and screenshot without another URL entry or model request for restoration. Current account remains signed out; healthy local-preview restoration works independently of teacher/model login. No game actions, game-source changes or credential changes were made. Left the actual Work + teacher layout visible.
+- Limit: remembered page URLs remain scoped to the current Main process, as before. Full application restarts still need the existing first-open Agent path or an explicit known address; this follow-up fixes closed-view/sleep recovery and does not promise persistence of unsaved in-page JavaScript state across a native view recreation.
+- Promotion candidate: classroom preview documentation should state that manual and Agent-opened pages both participate in automatic project-scoped restoration, stale startup requests cannot override a ready work view, and transient presentation errors resolve automatically or through one student-facing retry action. Evidence: reproduced failures, 53 focused cases, 2 Electron cases and actual hide/show recovery while signed out. No change to resource cleanup, authentication or model-request authorization; no conflicting decision requiring approval. Workflow lesson: verify the exact native app source and use an isolated trial runtime identity when multiple Electron demos are open; a successful fixture alone does not prove the user's current preview is visible.
+
+## Main Integration Handoff
+
+- User explicitly requests merging the finished classroom/teacher/preview changes into main. Resumed this same owned feature task to prepare its commit; current registry/branch/base and peer scope rechecked, previously loaded project context remains applicable, gate passed. No subagents. All listed source changes belong to this accumulated teacher-presence task.
+- Main is still at e5d271b and contains 19 unrelated uncommitted legacy consensus files (13 tracked edits and 6 untracked files). A read-only copy of original files, binary patch, index patch and SHA-256 manifest was saved outside the repository at `/Users/chillishark/Makelore 麦洛/合并前备份/20260923-main-consensus`; original files remain untouched. Main checkout cleanup/adoption requires a user decision before final fast-forward.
+- The local `scripts/launch-teacher-trial.py` helper contains this machine's disposable profile path and stays outside the product commit. The actual product, tests, pixel asset and task record form the feature handoff; the running trial and its local helper remain available.
+
+- Final source handoff validation: all 17 changed/new unit suites passed (314 tests). Earlier typecheck, scoped ESLint, production build, responsive/Electron regressions and native hide/show checks remain applicable; this handoff changes no product code. Source commit excludes only the machine-local trial launcher.