merge: integrate remote learning module safely

.project-docs/30-worklog/tasks/20260813-sync-push-main-9c2f71.md

@@ -109,6 +109,13 @@ Gate result:
 - Audit also rejected the remote Prompt Museum route because it forwarded unknown upstream/local error text and unvalidated success JSON. The merge adds strict bounded list/detail projection with HTTPS URL validation, fixed safe error mapping, stable 401-refresh failure handling, and focused regression tests. A remote E2E assertion was corrected to match the documented latest-message sidebar preview rather than an older user message.
 - Gate result: Passed for completing the current normal merge, canonical promotion, proportionate merged-tree verification, independent final review, and a non-forced push. If the remote advances again before push, fetch and integrate that new tip before publishing.
 
+### 2026-08-16 Remote `01bee31` Race Resume
+
+- After creating reviewed merge commit `bb16c1d12a24b2957149db960edba6e6660691aa`, the mandatory pre-push fetch detected that authoritative `origin/main` had advanced from `26b52d7` to `01bee3188be4b03b6b358c2da60f1f9ed22d707f`. The push was stopped before any remote ref changed; local `main` is clean and is 13 commits ahead / 1 commit behind the new remote tip.
+- The new remote commit is a direct child of the already integrated `26b52d7` and adds the enabled AI Learning module, Main-owned learning services/routes/runtime, verified external player-artifact packaging, profile/navigation changes, and focused tests. It also removes the transient bundled `game-engine` Skill and changes `planning-with-files` project output placement.
+- This remote product change supersedes canonical statements that Learning is disabled and that `game-engine` is bundled. It does not authorize weakening the existing Robot native-network, Canvas cloud-workspace, Host API, authentication, or packaging boundaries. The merge must retain the reviewed Prompt Museum DTO/redaction fixes, the regenerated single-version `isbinaryfile@5.0.7` graph, Koffi packaging, and the cross-platform Robot hotspot path.
+- Gate result: Passed for a second normal no-ff merge of `origin/main=01bee31`, semantic reconciliation of overlapping source and project memory, proportionate full verification, another independent final Sol review, and a non-forced push only after a fresh remote-race check.
+
 ### 2026-08-16 Cross-Platform Robot Hotspot Integration Resume
 
 - Reused the existing Integration owner because it exclusively owns clean local `main` at `abecd5f34485ab467e5f032c618083d88e34b74d`; `task_context.py touch` refreshed the reservation and the registry reports this exact `main` worktree/branch owner.
@@ -176,6 +183,13 @@ Gate result:
 3. Install the frozen lockfile and run focused Prompt Museum/Canvas/language/Skill plus Robot regressions, the full unit suite, typecheck, lint, production build, selected Electron E2E, project-document gates, and whitespace/topology checks.
 4. Obtain an independent read-only Sol Standards/Spec PASS, create the normal merge commit with local `9af6c52` as first parent and remote `26b52d7` as second parent, fetch once more to detect races, then push without force and verify `origin/main` equals local `main`.
 
+### 2026-08-16 Remote `01bee31` Race Plan
+
+1. Merge freshly fetched `origin/main=01bee31` into clean local merge commit `bb16c1d` without rewriting history; resolve overlaps by retaining the reviewed local Robot/Canvas/security/lock fixes and the remote Learning product behavior.
+2. Reconcile README, AGENTS product guidance, and canonical project memory for enabled Learning, removed `game-engine`, changed planning-file placement, and the Main-owned learning/player-artifact boundary without claiming unavailable cloud, signed-package, or physical-device evidence.
+3. Run frozen-lock validation, Learning/Robot/Canvas focused tests, the bounded full unit suite, typecheck, lint, production build, relevant Electron E2E, document gates, whitespace/unmerged checks, and exact merge-topology checks.
+4. Obtain a new independent read-only Sol Standards/Spec PASS on the final tree, create the second normal merge commit, fetch again for races, push without force, and verify local `main` exactly equals `origin/main`.
+
 ### 2026-08-16 Cross-Platform Robot Hotspot Integration Plan
 
 1. Merge reviewed source `c1326a2` into local `main` with a normal no-ff merge while preserving source history; exclude the source-owned task record and proposal from the integrated tree.
@@ -241,6 +255,18 @@ Gate result:
 
 ## Outcome
 
+- A mandatory pre-push fetch found authoritative `origin/main` had advanced to `01bee3188be4b03b6b358c2da60f1f9ed22d707f`, so no stale push was attempted. Started a second normal `--no-ff --no-commit` merge with reviewed local merge `bb16c1d12a24b2957149db960edba6e6660691aa` as first parent and `01bee31` as second parent; README was the only textual conflict and was reconciled to preserve both the enabled Learning module and the detailed Robot hotspot flow.
+- Preserved the remote Learning product scope, four-module navigation, profile reuse, removal of `game-engine`, and project-root `planning-with-files` output. The merged tree no longer depends on a sibling OpenMAIC checkout: CI/release packaging requires the fixed manifest artifact, while an explicit local source remains development-only.
+- Closed merge-audit security/correctness findings across Learning: strict Host/service DTO and safe-error projection; bounded Agent/ASR/runtime and ZIP consumption; Main-derived opaque account partitions for generation, local courses, IPC and player registration; fixed-binding checks across token acquisition, fetch and 401 refresh; stale account/epoch result rejection; 512 MiB archives; same-Works-origin redirects with a 5-hop cap and no resource Bearer; a nonce-protected account-bound player HTTP session; and an exact-source/origin single-document iframe bridge.
+- Closed Renderer integration findings: ordinary OpenCode errors are visible again; Learning deep links cannot bypass the required profile gate; course/module loads use latest-request guards; generation state is account-scoped; and published-project resubmission explicitly preserves existing metadata/cover while uploading only a new version.
+- Added a real Electron Learning navigation smoke and corrected three OpenCode slash-command E2E setup races by entering Code through the module chooser after setup. Production behavior was unchanged by the OpenCode test correction.
+- Fixed the repository E2E script to invoke the declared `@playwright/test@1.59.0` CLI directly. The prior `pnpm playwright test` path selected a transitive alpha `playwright` CLI from `@playwright/mcp`, producing a false version-mismatch failure.
+- The first independent final Learning merge review returned `FAIL` on four P1, three P2 and one P3 findings: Renderer-self-asserted course identity, account-switch token TOCTOU, old player/progress/form reuse, same-origin navigation bridge recovery, overlay-only profile gating, non-authoritative published status, premature documentation claims, and direct Renderer event IPC. The merge now revalidates installed/registered course identity in Main, threads captured binding guards through token/fetch/401 boundaries, closes and rotates player sessions, partitions/clears Renderer state, permanently disables a navigated iframe bridge, blocks Learning Outlet execution until profile readiness, re-reads strict project status after 409, corrects canonical nonce wording, and routes events through an allowlisted API-client seam.
+- The second independent Learning merge review returned `FAIL` on two P1 and four P2 findings: Agent/runtime could register the requested course before checking active-player identity; executable same-origin course assets could message before a second iframe load; profile sync errors could leave an empty deep link; Works cover/metadata lacked atomic concurrency; material-generation IPC was not fully strict; and canonical evidence overclaimed closure. The final code separates side-effect-free `resolveClassroom` from explicit player registration, validates pre-existing active registration before Agent/runtime resolution, restricts course media to exact passive MIME/extension pairs with nosniff/sandbox CSP, renders a retryable profile error gate, strictly projects generation upload DTOs before auth/network, and adopts an honest coverless-first-create / existing-version-only Works workflow whose races fail closed without cover or PATCH side effects.
+- The third independent Learning merge review returned `FAIL` on one P2 integration mismatch: the package consumer admitted `fonts/*`, while the player server only routed `audio|media`, so a declared playable font would install and then 404. Consumer and server now share the exact root/module `audio|media|fonts` directory contract and passive extension/MIME set; unsupported directories fail installation/HTTP lookup, and real registered ZIP-to-HTTP tests verify root WOFF and module WOFF2 with the expected MIME and security headers.
+- The fourth independent Learning merge review returned `FAIL` on one remaining P2 composition bug: allowing a manifest-relative `modules/<id>/...` path caused the authoritative module root to be prepended twice. Manifest media paths now begin only with relative `audio|media|fonts`; the module prefix comes solely from `location.root`. A consumer-to-classroom-URL-to-registered-ZIP-to-real-HTTP test proves exactly one module prefix, correct WOFF2 bytes/MIME/security headers, and rejection of manifest-supplied `modules/` or other directories.
+- The fifth and final independent Learning merge review returned `PASS` on Standards and Spec with no P0-P3 findings. It confirmed the consumer-generated modular font URL traverses the registered ZIP and real player HTTP response with one module prefix, and found no regression in registration, media safety, profile recovery, Works version-only behavior, generation DTOs, identity guards, canonical documents, packaging, Robot/Canvas, or the lock graph.
+- The second merge remains uncommitted pending final project-document gates and independent Sol review. No remote ref has changed and no force option has been or will be used.
 - On 2026-08-16, resumed the unfinished merge with local `main` at `9af6c526a9500a0dbfb88e39ba0dee1eb7e1d097` and freshly fetched remote `main` at `26b52d76e3dedd754ca1b1c428abaa074b7f98da`; `bfcb88cfefe714a60927a77822ae5a727ebe6604` is their merge base. README was the only textual conflict and now preserves both remote Canvas Prompt Museum wording and local Windows/macOS Robot hotspot behavior.
 - Integrated the remote Canvas enhancements: editable server-repriced generation Quotes, result detail/download UX, exact-name project deletion, Prompt Museum, Chinese-only locale normalization, cloud-default development entry, and optional bundled `game-engine` Skill. Existing local Robot hotspot source, default-on rollback semantics, Koffi 2.16.3, packaging configuration, and firmware-zero-change boundary remain intact.
 - Repaired the automatically merged lockfile by restoring the package-declared `isbinaryfile` override; frozen installation now succeeds. Corrected README's development-mode paragraph to match the remote cloud-default package script.
@@ -351,6 +377,19 @@ Gate result:
 
 ## Verification
 
+- Remote `01bee31` merged-tree `pnpm install --frozen-lockfile` passed with the package-pinned pnpm 10.33.4; Electron 40.10.6 was restored with `pnpm rebuild electron` before desktop smoke.
+- Learning/Robot/Canvas/publish/OpenCode focused selection — 26 files / 418 tests passed.
+- Bounded full unit suite — 175 files / 1944 tests passed.
+- `pnpm run typecheck` passed. `pnpm run lint:check` passed with 0 errors and 7 existing warnings.
+- `pnpm run build:vite` passed for Renderer, Electron Main, and Preload; only existing mixed-import and large-chunk warnings remain.
+- Corrected official `pnpm run test:e2e -- <selected specs>` passed 9/9 across Learning navigation, module navigation, Canvas workspace, first chat, OpenCode slash/compaction/layout, and project Skills.
+- Learning player/account-focused joint selection passed 22/22 before final review. After the review findings were fixed, the combined 12-file selection passed 122/122, including fixed-binding token/fetch/refresh guards, authoritative course identity, A→B player/progress/form isolation, permanent post-navigation bridge denial, executable profile gating, strict project status/409 races, and the allowlisted event subscription seam.
+- Post-review final bounded unit suite — 175 files / 1973 tests passed. Final `pnpm run typecheck` passed; `pnpm run lint:check` passed with 0 errors and the same 7 existing warnings; Renderer/Main/Preload `build:vite` passed with only existing mixed-import/chunk-size warnings.
+- Post-review Electron E2E selection — 9/9 passed across Learning/module navigation, Canvas workspace, first chat, OpenCode slash/compaction/layout, and project Skills.
+- Fourth-review final combined regression selection — 9 files / 161 tests passed across course library/IPC identity, consumer-generated classroom URL through real player HTTP, package media paths, generation DTO, profile gate, Works route and publish UI.
+- Fourth-review final full suite — 175 files / 2028 tests passed. `pnpm run typecheck` passed; `pnpm run lint:check` passed with 0 errors and the same 7 warnings; Renderer/Main/Preload `pnpm run build:vite` passed with only existing mixed-import/chunk-size warnings.
+- Fifth independent final review — Standards `PASS`, Spec `PASS`, overall `PASS`; no P0-P3 findings. It rechecked exact merge topology, clean staged state, the real consumer→URL→registered ZIP→HTTP font path, and all prior review closures.
+- Second-review final Electron E2E — 4/4 passed for four-module layout, Learning enter/return, sidebar return, and project Skill behavior using the corrected declared Playwright CLI.
 - Remote `26b52d7` merged-tree frozen install — passed with pnpm 10.33.4 after restoring the exact top-level lockfile override.
 - Combined Prompt Museum/Canvas/language/Skill/Robot regression selection — 16 files / 284 tests passed before the Prompt Museum hardening; post-hardening Museum selection — 3 files / 12 tests passed.
 - Prompt Museum hardening tests first reproduced all three audit findings, then passed after the fix. The final 3 files / 13 tests cover stable refresh-auth failure, successful `forceRefresh` with the new Bearer and one retry, unknown upstream/local detail redaction, and malformed/unsafe success DTO rejection. Typecheck and focused ESLint passed.
@@ -463,6 +502,9 @@ Gate result:
 
 ## Follow-ups
 
+- Before releasing Learning, run a real Works account through catalog, generation/material/cancel-resume, bounded download, offline multi-module playback, progress, Agent, ASR and PBL/scoring using the exact production Stage artifact. Validate packaged loopback cookie/nonce behavior on Windows and a signed macOS build; current automation is not that acceptance.
+- Before restoring project cover upload or editing metadata on an existing draft/published project, add and verify a server-owned revision/ETag plus draft-only conditional write and atomic cover attachment or cleanup. Until then the client intentionally creates new projects without a cover and treats existing projects as version-only.
+- Packaging audit follow-ups outside this merge remain: verify macOS/Linux OpenCode multi-architecture staging, remove any unsupported Windows ARM64 advertising, pin the uv installer by digest, and replace unauthenticated curl-style installer paths before those release lanes are trusted.
 - Before releasing Prompt Museum and the expanded Canvas deletion/repricing workflow, use a real Works account to validate Museum list/detail/pagination/attribution/CDN content, latest Quote pricing/confirmation, project soft-delete visibility, queued reservation release, and running-task settlement. Client tests do not prove the content backend or production billing/deletion semantics are deployed.
 - Before claiming complete compatibility for the default-on Robot journey, verify the exact shipped firmware/fixed portal, six-digit issuer/validator freshness and consumption semantics, real Host API/native opener behavior, and a physical-device provisioning + Binding smoke. Keep exact `NIANCODE_AI_HARDWARE_GUIDED_HOTSPOT_BINDING=0` in support rollback instructions.
 - The earlier default-false production instruction is superseded by the user's explicit default-on decision. Keep exact value `0` only as rollback, and do not touch `D:\Datas\HardwareProjects\xiaozhi-esp32-firmware` for this V1.
@@ -484,6 +526,7 @@ Gate result:
 
 ## Promotion Candidates
 
+- Remote `01bee31` facts and the reviewed merge hardening were promoted into README, AGENTS, success criteria, current state, architecture/data flow, business rules, glossary, evidence and commitments: Learning is enabled but remains Main-owned, account-partitioned, bounded, artifact-verified and pending real Works/signed-package acceptance; `game-engine` is removed and planning files belong in the project root.
 - Remote `26b52d7` facts were promoted into current state, architecture, domain rules, glossary, evidence, README, and release commitments: Prompt Museum remains read-only/server-driven, Quote pricing is service-owned, Canvas deletion is an explicit Workspace mutation, development is cloud-default, UI language is Chinese-only, and `game-engine` is an optional bundled Skill. Production Museum content and real-account billing/deletion acceptance remain pending commitments rather than completed evidence.
 - The default-on candidate from `b78fc07` was promoted into ADR-002, current state, decision/success criteria, Robot architecture/domain/glossary, README, and a concrete release-validation commitment. No unresolved canonical candidate remains; the missing native/physical evidence is tracked as a pending commitment rather than overclaimed.
 - The implementation truth from `b7a1590` was originally promoted as implemented/default-off. `b78fc07` now supersedes only that default; its former enablement evidence requirements remain tracked as default-on release validation and rollback commitments.