Windows Desktop: switching Agent environment to WSL2 fails startup with state db backfill handshake timeout

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

• MSIX package: OpenAI.Codex_26.727.4816.0_x64
• Desktop build observed in logs / MCP env: 26.727.40816 / package 26.727.4816.0
• WSL-side CLI available: codex-cli 0.146.0

What subscription do you have?

ChatGPT Pro (desktop signed in)

What platform is your computer?

• Windows 11 25H2, build 26200, x64
• WSL2 distro: Ubuntu-24.04 (default, Running)
• WSL kernel: 6.18.33.2-microsoft-standard-WSL2
• Windows user: Lenovo
• WSL user: xdreamer (/home/xdreamer)

What issue are you seeing?

After changing Settings → Agent environment from Windows native to WSL2 / Windows Subsystem for Linux, Codex Desktop fails to start and shows:

ChatGPT failed to start.
Codex app-server initialize handshake timed out

Desktop logs show the app-server is launched inside WSL, then blocks on a state DB backfill from the Windows Codex home mounted at /mnt/c/..., and the Desktop 30s initialize handshake times out.

Sanitized Desktop log excerpt:

[wsl] eligible distro list listResult="NAME            STATE           VERSION\n* Ubuntu-24.04    Running         2"
[spawn-async] Spawning process inside WSL
[StdioConnection] stdio_transport_spawned
  executablePath=C:\Users\<user>\.codex\bin\wsl\<hash>\codex
  spawnCommand=wsl.exe
[AppServerConnection] Transport start success transport=stdio
[AppServerConnection] Initialize handshake still pending
  connectionError={"code":"connection-failed","message":"state db backfill is running at /mnt/c/Users/<user>/.codex; waiting up to 30s before retrying startup initialization"}
  durationMs=30011
initialize_handshake_result outcome=failure
  errorMessage="Codex app-server initialize handshake timed out"
app_server_connection.closed code=1
  reason="Error: failed to initialize sqlite state runtime under /home/<wsl-user>/.codex/sqlite: timed out waiting for state db backfill at /mnt/c/Users/<user>/.codex after 30s (status: running)"
Desktop bootstrap failed to start the main app phase=bootstrap-import-main

Important recovery detail:

• %USERPROFILE%\.codex\.codex-global-state.json had "runCodexInWindowsSubsystemForLinux": false
• but %USERPROFILE%\.codex\config.toml still had:

[desktop]
runCodexInWindowsSubsystemForLinux = true

Desktop continued spawning WSL until config.toml was set to false. After that:

stdio_transport_spawned executablePath=...\WindowsApps\OpenAI.Codex_...\app\resources\codex.exe
initialize_handshake_result durationMs=225 outcome=success

So WSL mode left the app unlaunchable, and the dual config sources made recovery non-obvious.

What steps can reproduce the bug?

1. Use Codex Desktop on Windows with an existing local profile under %USERPROFILE%\.codex.
2. Ensure WSL2 is installed with a default Ubuntu distro that is eligible (wsl -l -v shows Running / Stopped version 2).
3. Open Codex Desktop in Windows native mode (works).
4. Go to Settings and switch Agent environment to WSL / Windows Subsystem for Linux.
5. Quit and relaunch Codex Desktop.
6. Observe the fatal dialog:

Codex app-server initialize handshake timed out

1. Inspect Desktop logs and observe WSL spawn + 30s state db backfill timeout from /mnt/c/Users/<user>/.codex into /home/<wsl-user>/.codex/sqlite.
2. Set [desktop] runCodexInWindowsSubsystemForLinux = false in %USERPROFILE%\.codex\config.toml and relaunch.
3. Observe Windows-native codex.exe spawn and a successful handshake in a few hundred ms.

Local size context (not multi-GB session history)

At failure time, approximate sizes under %USERPROFILE%\.codex:

logs_2.sqlite       ~438 MB
logs_2.sqlite-wal   ~14 MB
state_5.sqlite      ~1.7 MB
sessions            ~645 MB (127 files)
archived_sessions   ~103 MB (137 files)

This is much smaller than the multi-tens-of-GiB history case in #35674, but still enough for WSL-mode startup backfill over /mnt/c to exceed the fixed 30s Desktop handshake budget.

There was also a non-fatal warning while launching WSL mode:

bundled_executable_relocation_failed
executableName=bwrap
sourcePath=...\app\resources\codex-resources\bwrap
ENOENT

That appears secondary; the fatal path is the state db backfill timeout.

What is the expected behavior?

1. Switching Agent environment to WSL2 should either:

• complete first-run / state backfill successfully, or
• open the app with a progress/recovery UI instead of a fatal handshake timeout.

1. State DB backfill / SQLite init performed over /mnt/c should not be on a hard 30s critical path that prevents Desktop bootstrap.
2. If WSL mode fails, Desktop should provide a one-click fallback to Windows native mode without requiring manual edits of config files.
3. runCodexInWindowsSubsystemForLinux should have a single source of truth. Having .codex-global-state.json say false while config.toml [desktop] still says true (and Desktop obeys the latter) makes recovery confusing when the app cannot open Settings.
4. Diagnostic logs / DB maintenance should not block app launch; if backfill is required, it should be resumable and backgrounded.

Additional information

Related issues (same failure family, different emphasis):

• #35674 — large long-lived session history blocks startup during state DB backfill
• #27741 — large logs_2.sqlite causes startup SQLite/pool timeout (often under WSL /mnt/c)
• #32902 — WSL switch fails during provisioning / history display issues
• #28087 — stuck on sqlite state backfill
• #17254 / older WSL agent mode startup failures

This report is specifically about:

1. Agent environment → WSL2 as the trigger
2. Desktop spawning WSL app-server
3. fatal state db backfill ... after 30s during initialize handshake
4. dual config sources (config.toml vs .codex-global-state.json) complicating recovery

Workaround that restored launch on this machine:

# %USERPROFILE%\.codex\config.toml
[desktop]
runCodexInWindowsSubsystemForLinux = false

I can provide additional sanitized Desktop log excerpts if useful. I am not attaching raw session JSONL / auth / full SQLite dumps because they contain local paths and conversation content.