codex - 💡(How to fix) Fix Windows Codex app Black window after app-server transport stop; only force-kill recovers

Summary

On the Windows MSIX build of Codex Desktop, the main process and its 5 child processes stay alive (and Windows marks them all Responding = True) but the window renders entirely black and the tray icon is hidden, after either:

1. The app-server transport stops mid-session (observed in logs after what looks like a laptop sleep/wake - see log excerpt below), or
2. Right-click tray icon → Quit, followed by relaunching from Start (reported reproducibly by me; not captured in today's log, but produces the identical end state).

The app is unrecoverable from this state through any in-app action - the renderer never paints, no tray menu accepts input, and no further log lines are written. Force-killing the entire Codex.exe process tree (Stop-Process -Name Codex -Force) and relaunching from Start fully restores the app, without a reboot. A reboot also works, presumably because it implicitly kills the same processes.

This is distinct from #23624: that reporter's app stays black across clean reinstall + Reset-AppxPackage, suggesting persistent disk/state corruption. Mine is purely in-session - disk state is fine, only the live OS process tree is wedged.

Environment

Reproduction

Path A - observed today in logs:

1. Launch Codex normally; use it.
2. Leave the laptop alone for a few hours (likely sleep/wake - there is a 3.5h gap in the log).
3. Return - window is black, tray icon gone, app does not respond to clicks. Main + 5 child processes still alive, all Responding = True.

Path B - repeats reliably across sessions:

1. Launch Codex.
2. Right-click the tray icon → Quit.
3. Relaunch Codex from Start menu.
4. New instance opens with a black window and no visible tray icon.

In both paths the recovery is identical (see Workaround).

Symptoms

• Window: completely black client area; title bar / window frame render. No content paints.
• Tray icon: registered in HKCU:\Control Panel\NotifyIconSettings\<UID> with ExecutablePath pointing at Codex.exe, but IsPromoted is empty so Windows 11 keeps it in the ^ overflow. (Separate cosmetic issue but worth mentioning - the icon is registered, just hidden.)
• Processes: 1 main Codex.exe parented to explorer.exe, plus 5 helper Codex.exe children. All Responding = True per Get-Process. No crash dump in WER.
• IPC: Per the log, AppServerConnection was actively routing requests (skills/list, hooks/list, model/list, plugin/list, mcpServerStatus/list, etc.) until the transport stop event, then went silent. The main process stays alive after that point with zero further log output.

Diagnostic evidence

Last meaningful log lines from the dead session (%LOCALAPPDATA%\Packages\OpenAI.Codex_2p2nqsd0c76g0\LocalCache\Local\Codex\Logs\2026\05\28\codex-desktop-7cb02d82-7231-43b3-8d4f-2ecc3c800418-1948-t0-i1-000544-0.log):

2026-05-28T05:09:21.385Z info [browser-session-registry] IAB_LIFECYCLE removed browser session window windowId=1
2026-05-28T05:09:21.428Z info [AppServerConnection] Stopping app-server transport connectionId=1 transport=stdio
2026-05-28T05:09:21.432Z info [AppServerConnection] app_server_connection.state_changed cause=stop_process connectionError=null currentConnectionId=null currentState=connected hasConnection=false hostId=local initialized=false initializeInFlight=false next=disconnected pendingClientRequests=0 pendingInternalRequests=0 previous=connected reconnectAttempt=0 reconnectTimerScheduled=false restartInFlight=false targetConnectionId=null targetReadyState=null transport=stdio

After that line the file has zero further entries even though the process tree stayed alive for another 8 hours before I killed it. So after cause=stop_process the main process never attempts a reconnect, never logs anything, and never closes - it just sits there with a dead renderer.

The only non-info entries in the entire log are three identical warnings from electron-sampler failing to run a PowerShell telemetry command - believed unrelated:

warning [electron-sampler] Failed to collect child process snapshot errorMessage="Command failed: powershell.exe -NoProfile -NonInteractive -Command $ErrorActionPreference = 'Stop'; ... | ConvertTo-Json -Depth 2"

Process tree at the moment of the black screen (parent → main → children):

explorer.exe (11764) → Codex.exe (1948) ─┬─ Codex.exe (3120)
                                          ├─ Codex.exe (3752)
                                          └─ Codex.exe (15032)
all four marked Responding = True by Get-Process

What I ruled out

• GPU driver / hybrid graphics: relaunch on the same hardware with the same drivers renders fine; force-kill alone recovers without a driver or graphics-preference change.
• Persistent disk state: relaunch after kill works without touching LocalState, LocalCache, Settings, or registry; no Reset-AppxPackage needed.
• MSIX package corruption: Get-AppxPackage OpenAI.Codex reports Status = Ok.
• Singleton lock files: searched the package tree for SingletonLock, SingletonCookie, SingletonSocket, lockfile, .lock - none present.
• Zombie processes from a previous launch: process tree showed a single clean parent chain rooted at explorer.exe - no orphans.

Workaround

Don't use the tray's Quit Codex menu item, and treat any post-sleep/wake recovery the same way. Close Codex with either:

Stop-Process -Name Codex -Force

…or via Task Manager → right-click any Codex process → End task → End process tree. Then relaunch normally. The next instance is clean.

Why this isn't #23624

• #23624's app stays black after clean reinstall, Reset-AppxPackage, GPU-disabled env vars, and userData wipe - implying persistent state corruption.
• In my case the disk state is fine and only the live process tree is wedged. A simple Stop-Process -Name Codex -Force restores the app, no reinstall, no reboot. That suggests this is a main-process state-machine bug after cause=stop_process, not a renderer-init or state-corruption bug.

What I can attach if helpful

• Full broken-session log file (codex-desktop-7cb02d82-...-t0-i1-000544-0.log, 54 KB)
• Corresponding renderer-thread log (...-t1-i1-000544-0.log, 6 KB - entirely git-origins worker-complete info entries)
• Working-session log from the same day after force-kill, for comparison