fix(app): stabilize local-source desktop startup

[NubsCarson]

Summary

Stabilizes local-source/package-mode desktop startup and keeps the Windows packaged desktop path working against current local Eliza source.

• Keeps the desktop app on the app-core provider/shell path needed by local-source startup.
• Hardens Vite local-source aliases so eliza/packages/* source wins over stale package dist fallbacks where Milady intentionally builds from the nested checkout.
• Routes @elizaos/ui browser/state imports through canonical local source entries and dedupes @elizaos/ui with React/app-core to avoid renderer module identity splits.
• Replays a fail-closed local-source patch that stores the UI AppContext singleton on globalThis, so duplicate renderer module ids cannot produce useApp must be used within AppProvider at runtime.
• Replays a Windows packaged-agent PATH fallback so Explorer/manual launches that expose Path instead of uppercase PATH do not crash before the embedded agent starts.
• Keeps that PATH patch compatible with both latest Eliza and the release workflow's pinned Eliza ref.
• Replays a narrow LifeOps automation registration patch so packaged Bun imports @elizaos/app-core/api/automation-node-contributors instead of the broad @elizaos/app-core root barrel; this fixes the latest-Eliza @elizaos/plugin-lifeops startup import failure (Unexpected as).
• Adds packaged Windows Playwright coverage for the visible renderer reaching a nonblank app surface without the error boundary / useApp provider crash, with uppercase PATH removed.
• Keeps generated build output out of the Milady commit.

Current State

• Milady PR head: 63448ea5ac97af5281739bffdb5cb0aa0c44361f
• Nested Eliza checkout used for latest validation: 77e0dc23308c5fdf13bdf9be23cf711845929352
• Standalone Eliza checkout also fast-forwarded to 77e0dc23308c5fdf13bdf9be23cf711845929352
• The release workflow pins Eliza f7a4e0bc50f966174ea42c41db787359ca6d8e67; the PATH patch matcher was verified against that older source block.
• The full Windows build log confirmed local source linking for @elizaos/core, @elizaos/shared, @elizaos/ui, @elizaos/agent, @elizaos/app-core, @elizaos/cloud-sdk, and local plugin packages.

Validation

Validated locally on Windows on 2026-05-19 after fetching remotes and fast-forwarding both Eliza checkouts to latest develop.

git diff --check
bun run verify:format:changed
bunx vitest run apps/app/test/package-mode-aliases.test.ts apps/app/test/vite/ui-source-aliases.test.ts
bun run --cwd eliza/packages/app-core build:dist
bun run --cwd eliza/plugins/plugin-lifeops build
node scripts/run-milady-desktop-build.mjs build --variant=base
bun run test:desktop:packaged:windows
bun run test:desktop:playwright:windows

Results:

• Whitespace check passed.
• Changed-file Biome format check passed.
• Focused alias/patch tests passed: 2 files, 16 tests.
• Targeted app-core + plugin-lifeops rebuild passed.
• Packaged-Bun import probe passed inside Resources/app/eliza-dist for @elizaos/app-core/api/automation-node-contributors and @elizaos/plugin-lifeops.
• Fresh Windows desktop stage+package build passed after deleting generated dist and Electrobun build output first.
• Generated packaged runtime contains the Windows Path/PATH fallback and the LifeOps narrow app-core import fix.
• Windows packaged backend smoke passed with HTTP 200.
• Packaged startup Playwright spec passed: 1 test, including the visible-renderer error-boundary assertion and uppercase-PATH-removed launch environment.
• Detached manual ShellExecute launch reached http://127.0.0.1:31337/api/status with HTTP 200 and startup-status.json reported state=running, phase=ready, lastError=null.
• Manual launch logs showed @elizaos/plugin-lifeops pre-registered and migrated successfully; no Unexpected as, existingPath.split, Agent not ready, Something went wrong, or useApp must be used within AppProvider markers were present.

Known warnings during the fresh build are existing upstream/package warnings: Vite/Rolldown dynamic import/chunk warnings, optional package skips, and Electrobun rcedit icon embedding warnings. The build exited 0.

CI Status

GitHub validation has started on 63448ea5a; normal CI and release workflow are expected to rerun for the final cleanup head. The previous e464611a run had normal CI, CodeQL, and release workflow green; the remaining visible red Agent Review/Auth P0 gate is the known pull_request_target package-mode workflow limitation from base develop, not this desktop startup change.

Previous head f96687406 was green for CI and Validate Electrobun Release Workflow. e464611a added the LifeOps packaged import fix found during detached manual startup validation against latest Eliza; 63448ea5a only removes the unused isPillWindowShell import flagged by code-quality review.

Note

Stabilize local-source desktop startup with new build orchestrator and runtime repair pipeline

• Adds run-milady-desktop-build.mjs as a new desktop build CLI with explicit preflight, stage, package, build, and run subcommands that apply patches, repair packaged runtime payloads, publish avatar assets, and validate plugin/vendor package contents.
• Fixes run-eliza-app-core-script.mjs to disable local-source mode when ELIZA_SOURCE=packages or upstream skips are set, and injects MILADY_ELIZA_SOURCE=local into the child env when using a local script without an explicit source env.
• Introduces elizaUiStateSingletonPlugin in vite.config.ts to deduplicate the useApp hook module and prevent duplicate React context singletons; also pins React/ReactDOM to concrete resolved paths and adds @elizaos/cloud-sdk local source aliasing.
• Extends apply-eliza-ci-patches.mjs with new patchers for UI AppContext global singleton, voice onboarding skip button, onboarding avatar component, remote capability endpoint provider, and additional plugin/package hoisting rules.
• Adds new host window routing utilities in host-window-routing.ts and a self-contained voice-pill-runtime.tsx component with full voice/chat pill UI.
• CI workflows now conditionally skip local eliza core builds and package linking when the eliza/ checkout is absent.
• Risk: startLiveApiServer in E2E tests no longer proxies a real upstream runtime — it now returns canned JSON responses only, which may mask regressions in actual API contract behavior.

^{Macroscope summarized ac9f525.}

[github-actions]

Credit balance is too low

[github-actions]

Credit balance is too low

[github-actions]

Credit balance is too low

[github-actions]

Credit balance is too low

[github-actions]

Credit balance is too low

[github-actions]

Credit balance is too low

[github-actions]

Credit balance is too low

[github-actions]

Credit balance is too low

[NubsCarson]

Status refresh (2026-05-19): no new source changes pushed here. Normal CI lanes remain green from the latest run; the visible red checks are the same shared Auth P0 / Agent Review pull_request_target package-mode limitation. The active guard follow-up is #2158, stacked after #2153; #2155 should not need extra local-source desktop changes from this refresh.

[github-actions]

Credit balance is too low

[github-actions]

Credit balance is too low

[github-actions]

Credit balance is too low

[github-actions]

Credit balance is too low

[github-actions]

Credit balance is too low

[NubsCarson]

Validation update for ac9f525f9:

• Focused overlay coverage passes locally: bunx vitest run apps/app/test/package-mode-aliases.test.ts -> 17/17.
• Fresh hidden Windows package build passed: node scripts/run-milady-desktop-build.mjs build --variant=base.
• The Windows artifact exists with launcher.exe, eliza-dist/entry.js, packaged @elizaos/ui/dist/index.js, renderer index.html, webgpu_dawn.dll, and d3dcompiler_47.dll.
• Artifact grep confirms the voice-onboarding skip and avatar hitbox fixes are present: voice-prefix-skip-prefix, Skip voice setup, eliza-ob-agent-canvas, and pointerEvents.
• Build logs confirm local @elizaos/* package linking and packaged runtime payload repair, so this was not testing stale npm-only Eliza code.
• The new overlay patch handles both latest Eliza source and the older pinned release-contract ref (f7a4e0bc...); I validated the patch function against both shapes.

Known remaining red check: Auth tests (P0 gate) is still failing because the pull_request_target job uses develop's workflow copy, where the auth gate still runs cd eliza/packages/core when package-mode has no eliza/ checkout. This PR branch already contains the guarded workflow version, but GitHub does not use PR workflow edits for pull_request_target until the base workflow is updated.

[NubsCarson]

Final Windows validation update after syncing the nested Eliza source:

• fix(ui): make voice onboarding skippable elizaOS/eliza#7831 is merged at c115fbf532.
• Rebuilt the Milady Windows dev package from the rebased/local Eliza source.
• Re-ran the packaged Windows Playwright smoke detached from the terminal; it exited 0 and apps/app/test-results/.last-run.json reports passed with no failed tests.
• Verified the rebuilt package contains the voice onboarding skip path / avatar hitbox patch in the packaged renderer artifact.
• Local generated build dirt from the nested Eliza checkout was stashed after validation; source worktrees are clean.

Known remaining red status is the existing Agent Review auth gate, not the Windows package/runtime path covered here.

[codacy-production]

Pull Request Overview

This PR focuses on stabilizing the desktop application's startup by resolving module identity conflicts and hardening environment variable handling for Windows. Codacy analysis indicates the changes are 'up to standards' with no new quality issues detected.

Despite the structural improvements, there are concerns regarding the validation of these fixes. Specifically, several critical acceptance criteria—such as the Windows environment variable fallback and Vite alias prioritization—lack corresponding test coverage in the current submission. Additionally, the transition to canned JSON for E2E API testing reduces the suite's ability to detect breaking changes in the actual runtime contract. While the use of globalThis resolves the immediate 'useApp' errors, it should be monitored as a potential source of technical debt.

About this PR

• The E2E test utility 'startLiveApiServer' has been modified to return canned JSON instead of proxying a real runtime. This change prevents the tests from validating actual API contract behavior and may mask regressions in the communication layer.
• Storing the AppContext singleton on 'globalThis' is a 'fail-closed' patch. While it resolves module identity splits in the React tree, it may indicate underlying issues in the build or module resolution strategy that could require long-term maintenance.

Test suggestions

• Verify that Vite aliases correctly prioritize local package source files over built distribution files.
• Verify that the AppContext singleton is correctly stored and retrieved from globalThis in the renderer.
• Verify that the Windows packaged-agent starts successfully when the environment contains 'Path' instead of 'PATH'.
• Verify that @elizaos/plugin-lifeops successfully registers with the narrow automation-node-contributors import.
• Playwright test asserting the visible renderer reaches the app surface without triggering an error boundary.

Prompt proposal for missing tests

Consider implementing these tests if applicable:
1. Verify that Vite aliases correctly prioritize local package source files over built distribution files.
2. Verify that the AppContext singleton is correctly stored and retrieved from globalThis in the renderer.
3. Verify that the Windows packaged-agent starts successfully when the environment contains 'Path' instead of 'PATH'.
4. Verify that @elizaos/plugin-lifeops successfully registers with the narrow automation-node-contributors import.
5. Playwright test asserting the visible renderer reaches the app surface without triggering an error boundary.

_{TIP Improve review quality by adding custom instructions
TIP How was this review? Give us feedback}

[codacy-production]

Not up to standards ⛔

🔴 Issues 22 critical · 13 high · 24 medium · 41 minor

Alerts:
⚠ 100 issues (≤ 0 issues of at least minor severity)

Results:
100 new issues

Category	Results
Compatibility	2 medium
BestPractice	1 medium
ErrorProne	4 medium 13 high
Security	22 critical
CodeStyle	41 minor
Complexity	17 medium

View in Codacy

🟢 Metrics 370 complexity · 2 duplication

Metric	Results
Complexity	370
Duplication	2

View in Codacy

AI Reviewer: first review requested successfully. AI can make mistakes. Always validate suggestions.

_{TIP This summary will be updated as you push new changes.}

[Dexploarer]

Update after reading the author comments and validation history: this branch had substantial Windows/local-source validation, including focused package-mode tests, fresh hidden Windows package builds, packaged Playwright smoke, artifact inspection, and checks against both latest Eliza source and an older pinned release-contract ref. I should have read that thread before posting this review.

The current-state concern remains, but it should be read as a refresh/split request, not as a dismissal of that validation. Since #2160/#2161 have landed, this branch is stale against current source-install and CI hardening, and a mechanical conflict resolution could replace current workflow/contract behavior in agent-review, CI, release-electrobun, and the bootstrap contract tests.

One blocker still stands and is also called out by Codacy: startLiveApiServer changes from a real app-core-backed API server to canned JSON responses. That may be useful for a renderer-only smoke, but it weakens proof for the runtime contract behind the desktop startup path. Please keep a live-runtime assertion for the startup fix, or split the canned-response helper into a separately scoped renderer smoke.

Keeping changes requested until the branch is refreshed onto current develop while preserving the current guards/contracts and the runtime validation remains representative.

[lalalune]

Closing as part of the Milady -> elizaOS/eliza PR migration sweep. This PR has requested changes/conflicts and is mostly Milady wrapper/local-source desktop plumbing against paths that do not exist in current upstream. It should not be migrated as-is; any still-needed behavior should be reopened as a fresh elizaOS/eliza PR against the current packages/* layout.