codex - 💡(How to fix) Fix Windows-native Codex Desktop incorrectly enables WSL path resolution when WSL_DISTRO_NAME exists, causing UI freezes

What version of the Codex App are you using (From “About Codex” dialog)?

26.506.31421

What subscription do you have?

ChatGPT Pro

What platform is your computer?

Microsoft Windows NT 10.0.26200.0 x64

What issue are you seeing?

Codex Desktop was freezing on Windows even though Agent environment was set to Windows native.

After investigating performance traces, I found that the Electron main process was synchronously invoking wsl.exe during a codex-home request. The freeze path disappeared after removing WSL_DISTRO_NAME from the Windows environment and rebooting.

The problematic environment variable was:

WSL_DISTRO_NAME=Ubuntu

The app appeared to treat this as a signal to enable WSL path resolution, even though Codex Desktop was running in Windows-native mode.

A trace showed a main-process stall around this stack:

codex_desktop:message-from-view
RunMicrotasks
codex-home
resolveCodexHome
resolveCodexHomeFromWsl
spawnSync
wsl.exe

The expensive command was effectively:

wsl.exe /usr/bin/env bash -lc 'printf %s "${CODEX_HOME:-$HOME/.codex}"'

On my machine this took about 3 seconds on cold WSL startup and about 100 ms when WSL was warm. Because this happens synchronously from the Electron main process, the UI can freeze.

What steps can reproduce the bug?

1. Use Codex Desktop on Windows with WSL installed.
2. Set Agent environment to Windows native.
3. Make sure the Windows process environment contains WSL_DISTRO_NAME, for example:

[Environment]::SetEnvironmentVariable("WSL_DISTRO_NAME", "Ubuntu", "User")

1. Restart the Windows session or launch Codex from a parent process that has this variable.
2. Start Codex Desktop.
3. Trigger a flow that requests codex-home.
4. Observe that Codex Desktop invokes wsl.exe synchronously from the main process.
5. If WSL is cold, the UI can freeze for seconds.

Workaround:

[Environment]::SetEnvironmentVariable("WSL_DISTRO_NAME", $null, "User")

Then fully reboot Windows or log out and back in.

What is the expected behavior?

When Agent environment is set to Windows native, Codex Desktop should not enable WSL path resolution solely because the Windows process environment contains WSL_DISTRO_NAME.

Expected behavior:

• Windows-native mode should use Windows path resolution.
• WSL path resolution should only be enabled by an explicit Codex WSL setting or a stronger check that the app is actually running in a WSL context.
• wsl.exe should not be invoked synchronously from the Electron main process for Windows-native codex-home resolution.

Additional information

I could not find an exact duplicate.

Related but not identical issues I found:

• #13762: WSL mode uses Windows CODEX_HOME and creates worktrees under /mnt/c.
• #18506: Windows app + WSL UNC cwd/config/worktree handling.
• #14461: crash when WSL mode and WSL terminal are explicitly enabled.
• #16374 / #20867: broader Windows desktop freezes, but without this specific WSL_DISTRO_NAME -> sync wsl.exe -> codex-home root cause.

Root cause evidence from the packaged Desktop JavaScript bundle looked equivalent to:

var preferWsl = !!process.env.WSL_DISTRO_NAME

That makes WSL_DISTRO_NAME too strong as a Windows-side signal. Windows applications can inherit this variable accidentally from terminals, launcher scripts, stale session environments, or user-level environment variables.

After removing WSL_DISTRO_NAME and rebooting, the current Codex Desktop process no longer had the variable:

WSL_DISTRO_NAME
Process = <empty>
User    = <empty>
Machine = <empty>

After that, this specific freeze path appeared to be gone.