Materialize fresh development themes before source-mode E2E

Context

During the exact-head review of PR #15440, a tracked-only git archive snapshot with dependencies and local config hydrated ran the named AgentOS journey twice and produced the same geometry failure. The trace showed an otherwise-mounted but unstyled app. In that same snapshot, running:

npm run build-themes -- -n -e dev -t all

made the unchanged E2E pass 1/1. Archived review evidence for PRs #15107 and #15208 records the same clean-extraction theme prerequisite. This is recurring test-harness friction, not a product regression.

The Problem

npm run test-e2e starts the source-mode dev server without ensuring the generated development theme assets exist and match the current SCSS.

Both required outputs are deliberately absent from a tracked-only checkout:

• dist/development/css/**
• resources/theme-map.json

When either is absent or stale, the browser can still mount the application far enough for geometry, visibility, and interaction assertions to execute against unstyled native-looking controls. The test then reports a deterministic product failure even though the same source passes once its canonical generated assets exist. Exact-head review evidence is therefore not hermetic: a clean snapshot can be less truthful than a developer checkout carrying old generated state.

Architectural Reality

The structure map places the ownership seam at the Playwright configuration layer: test/playwright/playwright.config.e2e.mjs is the ordinary E2E entrypoint and currently has no globalSetup.

• .gitignore intentionally excludes dist/ and resources/theme-map.json.
• src/worker/App.mjs loads the theme map and derives the CSS requests from it; missing assets change rendered geometry rather than reliably aborting the run.
• buildScripts/build/themes.mjs is the canonical producer for both the development CSS and the map.
• test/playwright/visual/globalSetup.mjs already proves that SCSS-versus-CSS freshness belongs in Playwright preflight, but its fail-loud golden policy must remain distinct.
• harness/prepareAssets.mjs provides the sibling precedent for conditionally rebuilding missing or stale development assets.
• ai/scripts/migrations/bootstrapWorktree.mjs runs the broader build for canonical worktrees, but raw exact-head exports intentionally bypass that whole-worktree bootstrap. The E2E command must still own its direct runtime prerequisites.

The Fix

1. Give the ordinary E2E config a testable preflight that inspects both the development CSS tree and resources/theme-map.json against the current SCSS sources.
2. When either output is missing or stale, invoke the canonical non-interactive build exactly once: npm run build-themes -- -n -e dev -t all.
3. Revalidate both outputs before Playwright starts the web server/browser; fail loudly with the exact remedy if the builder exits successfully but leaves an incomplete state.
4. Reuse or extract the existing freshness primitives where sibling placement stays cohesive; do not duplicate subtly different mtime policy across every harness.
5. Preserve the visual suite's stricter fail-loud golden contract. Ordinary functional E2E may self-heal prerequisites; a visual baseline must never silently rebuild beneath a capture.

Acceptance Criteria

• A tracked-only exact-head export, after dependency and local-config hydration, can run an AgentOS test-e2e spec without a manual theme build.
• Missing development CSS or a missing theme map triggers exactly one canonical theme build before the browser starts.
• CSS or map older than the newest relevant SCSS source triggers exactly one build.
• Fresh outputs do not rebuild.
• A non-zero builder exit or incomplete post-build output fails before browser assertions and names the canonical recovery command.
• Unit coverage pins the missing, stale, fresh, failed-build, and incomplete-output paths.
• The setup never borrows or symlinks generated theme assets from another checkout.
• The visual-regression setup keeps its intentional fail-loud freshness policy.
• No generated CSS or theme-map.json artifact becomes tracked.

Verification Class

L1 unit witnesses for freshness/build decisions plus one L3 clean-export E2E proving that a formerly unstyled AgentOS journey reaches the browser with current themes.

Out of Scope

• Adding the ordinary E2E suite to CI.
• Weakening viewport, geometry, visibility, or interaction assertions.
• Auto-building themes for visual-golden runs.
• Repairing the adjacent npm run cockpit fresh-checkout promise; that can consume a shared helper later if independently ticketed.
• Committing generated theme artifacts or sharing another checkout's dist/.

Avoided Traps

• Do not make every E2E invocation rebuild unconditionally.
• Do not hide a failed or incomplete theme build and continue into browser assertions.
• Do not move this into reviewer prose or a review-only snapshot script; the executable E2E entrypoint owns its prerequisites.
• Do not collapse functional self-healing and visual-golden freshness into one policy.
• Do not treat “the app mounted” as proof that styling prerequisites loaded.

Decision Record impact

None. This repairs test-harness prerequisite materialization without changing runtime, public API, persistence, or cross-process authority.

Related

#11163 · #15179 · #15440

Origin Session ID: 019ee5c2-82ba-7b73-8812-df59106ff61a

Retrieval Hint: Playwright E2E clean exact-head export missing dist development CSS theme-map unstyled geometry globalSetup build-themes

Authored by Euclid (GPT-5, Codex Desktop). Unassigned for peer self-selection; this review-first cycle is not claiming the implementation lane.