Codex lacks documentation for migrating existing chats from Windows-native execution to WSL

What is the type of issue?

Documentation is missing

What is the issue?

Codex does not document how existing local projects and chats behave when the execution environment is changed from Windows-native execution to WSL2.

After making this change, existing chats retained Windows-specific working-directory, shell, workspace-root, sandbox, and permission-profile metadata. Those chats then failed under WSL with errors including:

AbsolutePathBuf deserialized without a base path

data did not match any variant of untagged enum PermissionProfileDe

New chats created directly under WSL worked correctly, but existing chats could not be safely rebound or migrated through the Codex UI.

There is no clear documentation explaining:

• where local Codex chats and project state are stored
• what is stored in rollout JSONL files versus SQLite databases
• whether moving a chat between projects changes its working directory
• whether “Continue in new chat” preserves obsolete execution metadata
• how Windows paths should be translated to WSL paths
• how to back up local chats before changing execution environments
• how to migrate existing chats without losing accumulated context
• how to validate or roll back the migration
• which local files may be safely inspected or modified
• what recovery procedures are officially supported

The lack of documentation forced manual inspection of local Codex state, including session JSONL files and SQLite databases, to determine that the conversation history was intact and the failure was caused by incompatible environment metadata.

OpenAI should publish an official guide covering local chat storage, backup, Windows-to-WSL migration, project and chat rebinding, validation, rollback, and recovery from environment-schema errors.

The Codex app should also warn users before changing execution environments when existing chats may contain incompatible environment-specific state.

Where did you find it?

I encountered this while using the Codex Windows app and changing the local execution environment from Windows-native execution to WSL2 / Ubuntu.

Codex version:
26.727.6591.0

Platform:
Windows 11 Pro x64
WSL2
Ubuntu 24.04.4

Affected areas:

• Codex Windows app settings for the local execution environment
• existing Codex projects and chats created under Windows-native execution
• local session files under ~/.codex/sessions
• local state databases under ~/.codex/sqlite

I searched the available Codex and OpenAI documentation but could not find a documented migration, backup, rebinding, rollback, or recovery procedure for this scenario.