codex - 💡(How to fix) Fix Windows Desktop + WSL needs an end-to-end release gate across config, state, plugins, exec, and recovery

Summary

Windows Desktop + WSL appears to have a systemic integration gap. Several independent Codex Desktop subsystems cross the Windows/WSL boundary with different assumptions about paths, config homes, runtime platform, plugin cache roots, SQLite state, browser/computer-use helpers, and session recovery.

This is not one isolated bug. It is a pattern across multiple user-visible failures where each component works in one environment model, but the combined Windows Desktop + WSL product path breaks because there is no single authoritative environment contract.

This issue is intended as an umbrella / release-gate issue. The concrete bugs should remain in their individual issues, but they likely need a common Windows+WSL validation matrix rather than one-off fixes.

Current status

Remote control itself worked in the latest tested setup. The user was able to enable/use remote control after the update.

The failures were concentrated in the WSL-backed Desktop integration path:

• local SQLite migration compatibility after update
• WSL vs Windows config/home selection
• Windows/WSL path normalization
• bundled plugin cache reconciliation
• Chrome/browser-use bridge setup
• computer-use native helper availability
• unified exec process launch routing
• long-running goal/session recovery from Windows-hosted rollout files

Affected environment shape

Sanitized representative setup:

Product: Codex Desktop Windows Store app
Windows package family: OpenAI.Codex_*_x64__2p2nqsd0c76g0
Mode: run Codex in Windows Subsystem for Linux enabled
Codex home: Windows profile path, visible to WSL as /mnt/c/Users/<user>/.codex
Workspace: WSL/Linux project path or /mnt/c-backed project path
App-server: Linux/WSL Codex runtime launched by the Windows Desktop app

This hybrid mode is not equivalent to either pure Windows-native or pure Linux-native Codex. It needs dedicated coverage.

Concrete failures already filed

Config and runtime identity

• #22759: Windows Desktop + WSL app-server can read WSL ~/.codex instead of the Windows Codex home, causing split-brain config behavior.
• #22185: Windows Desktop + WSL workspace with unified_exec=true tries to CreateProcess /bin/bash and fails with ENOENT.

Plugin/path bridge

• #22760: Recommended skills refresh can create malformed literal Windows-path directories under vendor_imports in WSL mode.
• #21971: Chrome plugin Node REPL bootstrap fails from WSL due to Windows path/trust mismatch.
• #24268: Bundled plugin cache path is synthesized as invalid C:\mnt\c\Users\... instead of a real Windows or WSL path.

Current-build data point for #24268:

Codex Desktop package: OpenAI.Codex_26.527.3686.0_x64__2p2nqsd0c76g0
Desktop release string in logs: 26.527.31326
bundled_plugins_marketplace_install_failed ... C:\mnt\c\Users\<user>\.codex\plugins\cache\openai-bundled\chrome\26.527.31326

State and update safety

• #23777: Windows Desktop WSL app-server fails to launch due to CRLF/LF SQLx migration checksum mismatch after update.
• #23053: Desktop update prompt should show target versions, component diff, and environment impact.

Session/history scalability and recovery

• #25215: /goal can make Desktop threads unrecoverable by growing rollout JSONL beyond resume/list limits.
• #24263: Renderer reload left turn state out of sync and spammed Item not found in turn state.
• #24260: gpt-5.5 xhigh turn stalled before first output; WSL Desktop logs lacked durable diagnostics to distinguish queueing/retry/reconnect/backend state.
• #24262: Performance trace upload timeout did not retain local trace artifact, reducing debuggability.

Project-location ergonomics

• #22532: Desktop should avoid OneDrive-backed Documents as the default Windows project location. This is amplified in WSL because /mnt/c filesystem costs and sync-layer churn stack together.

Additional current-build computer-use evidence

In the latest tested Windows Store build family, remote control worked but computer-use/native-helper setup did not in WSL-backed mode.

Sanitized log lines:

remoteControl/status/read ... errorCode=null
browser_use_availability_resolved available=false browserPane=true platform=Windows reason=wsl-disabled release=26.527.31326
[computer-use-native-pipe] computer-use native pipe startup failed errorMessage="Windows Computer Use helper paths are unavailable"

A Settings > Computer use plugin toggle also failed once with:

Failed to update plugin enabled state
Configuration was modified since last read. Fetch latest version and retry.

This suggests remote pairing and computer-use helper availability should be validated independently in the Windows+WSL matrix.

Root cause hypothesis

The recurring root cause is not one bad path conversion call. It looks like there is no single environment contract shared by Desktop, app-server, plugins, exec, state, and helper processes.

Different subsystems appear to infer environment state independently:

• Some paths are treated as Windows paths.
• Some paths are treated as WSL /mnt/c paths.
• Some Windows APIs receive WSL/Linux absolute paths like /bin/bash.
• Some WSL-side/plugin operations receive Windows drive-letter paths.
• Some native Desktop code synthesizes invalid mixed paths like C:\mnt\c\....
• SQLite migrations are shared across Windows and WSL runtimes even though migration bytes/checksums differed by line endings.
• The app update flow does not appear to preflight active WSL-backed state, long-running goals, or large rollout recovery risk.

Expected behavior

Windows Desktop + WSL should be a first-class supported mode with a stable contract:

• one authoritative Codex home/config/state decision per launched app-server;
• explicit Windows path and WSL path forms available where needed;
• no subsystem should concatenate/convert paths ad hoc;
• plugin and helper processes should know whether they run Windows-native, WSL-native, or cross-boundary;
• update should preflight WSL-specific risks before replacing the runtime;
• if computer use is unavailable in WSL mode, the UI should say that clearly and avoid offering a broken toggle path;
• long-running sessions/goals should survive app updates and be recoverable even when local rollout files are large.

Suggested product fixes

1. Define a single launch-time environment contract object for Desktop-launched app-servers, including:

codex_home_windows
codex_home_wsl
workspace_windows
workspace_wsl
runtime_platform
host_platform
shell_platform
feature_capabilities
plugin_cache_root_windows
plugin_cache_root_wsl

1. Centralize Windows<->WSL path conversion and forbid manual string concatenation such as C: + /mnt/c/....

2. Add integration tests for at least these modes:

Windows-native Desktop, Windows home
Windows Desktop + WSL app-server, Windows home via /mnt/c
Windows Desktop + WSL app-server, WSL-native home
Windows Desktop + WSL workspace on /home/<user>
Windows Desktop + WSL workspace on /mnt/c
OneDrive-backed Windows Documents workspace

1. Add release-gate smoke tests for:

app-server startup after update
SQLite state/log DB compatibility
thread/list and thread/resume
long rollout / latest-compaction recovery
unified exec / shell command startup
skills/recommended-skills refresh
bundled plugin reconcile
Chrome/browser-use bootstrap
computer-use availability/toggle
remote control status/read and pairing

1. Make update UX WSL-aware. Before accepting an update, Desktop should warn when:

WSL mode is enabled
active goals exist
rollout files exceed a safe threshold
state DB is shared across Windows/WSL runtimes
bundled plugin cache is in a mixed Windows/WSL path mode

1. Improve diagnostics so user-facing crash dialogs and logs show the actual failing subsystem, not just the most recent stderr warning.

Why this matters

The Windows+WSL path is likely the natural path for many Windows developers using Codex Desktop. When this mode breaks, it can affect startup, config, shell tools, plugins, browser/computer-use, update safety, and recovery of long-running agent work.

The latest incident chain was especially expensive: the user paused a useful long-running /goal to update to a build with remote control/computer-use features, hit Windows+WSL startup/state problems, then could not resume the large goal rollout and had to recover via backups and a hand-built continuation handoff.

Privacy note

All paths, user names, thread IDs where unnecessary, and project details are redacted. Raw .codex state, rollouts, and logs are not attached because they contain private conversation and local project data.