›_ Codex Issues
Codex Issues / #26454

Windows desktop launch can be blocked by stale main processes and shared SQLite locks; add safer health diagnostics

Open 💬 3 comments Opened Jun 4, 2026 by lukisch
💡 Likely answer: A maintainer (github-actions[bot], contributor) responded on this thread — see the highlighted reply below.

Summary

Codex Desktop on Windows can get into a state where a later launch fails or appears to fail because local Codex state is still held by another process. I have repeatedly seen two related patterns:

  1. a stale/hung Codex desktop main process remains after the window is closed, with no renderer/window attached, and can keep the singleton/startup state blocked;
  2. a separate Codex app-server / extension process can hold shared ~/.codex SQLite state (state_5.sqlite, logs_2.sqlite, plus -wal/-shm sidecars), which can then conflict with the desktop app startup path.

This overlaps with existing Windows reports such as:

I am opening this issue instead of an unsolicited PR because openai/codex currently asks external contributors to start with issue analysis and only submit code when invited.

Why this matters

The first failed launch is often the first domino. A user sees Codex not starting, then tries Store repair/reset/update/reinstall flows. Those Store/AppX operations can hang or make the situation harder to diagnose, while the original blocker may have been a much smaller stale-process or lock-state problem.

A conservative built-in Windows health check could avoid that escalation by showing a clear diagnosis before the user reaches for destructive repair steps.

Reproduction pattern / observed states

The failure mode I have observed is roughly:

  1. Run Codex Desktop on Windows.
  2. Close the visible Codex window.
  3. A Codex main process can remain without a renderer/window, or an extension/app-server process can keep shared Codex SQLite files open.
  4. Launch Codex Desktop again.
  5. Startup fails, silently exits, or appears blocked by local file/process state.

I do not think a generic taskkill codex.exe workaround is safe. The Codex CLI and extension/app-server processes can also be legitimate, and background tasks may still be active even when no window is visible.

What I think would help upstream

A Windows-specific doctor / startup-health path could report these states before attempting repair:

  • enumerate Codex-related processes with executable-path-aware classification, not substring matching;
  • distinguish desktop main process vs Electron renderer/helper processes using --type= where available;
  • detect a stale main process only when it has no renderer descendant and is older than a short threshold;
  • detect shared SQLite lock sidecars and relevant app-server processes;
  • avoid touching the node-based Codex CLI unless explicitly requested;
  • warn if the process tree is still active rather than assuming "no window" means idle;
  • suggest next steps without automatically killing or resetting Store/AppX state.

If an actual repair path is added, I would strongly recommend a conservative gate:

  • never run SQLite maintenance while any relevant Codex process is active;
  • before killing a windowless process, check process-tree CPU activity so ongoing background work is not interrupted;
  • keep Store/AppX repair as a later, explicit path after the local process/lock diagnosis has been exhausted.

Reference implementation / diagnostic prototype

I built an unofficial local Windows tray + CLI utility that implements these ideas as a reference/prototype:

https://github.com/dev-bricks/CareCenter-for-Codex

Relevant pieces in that project:

  • process classification: src/codex_logdatenbank_wartung/processes.py
  • startup diagnosis: src/codex_logdatenbank_wartung/health.py
  • conservative watchdog tick: src/codex_logdatenbank_wartung/watchdog.py
  • safe SQLite maintenance boundaries: src/codex_logdatenbank_wartung/maintenance.py
  • Store/AppX repair lessons and timeouts: src/codex_logdatenbank_wartung/repair_workflow.py, repair_live.py

This is not proposed as a drop-in upstream dependency. It is an external prototype that may be useful as empirical design input.

Current local verification for that prototype:

182 pytest tests passed on Windows / Python 3.12

The test coverage includes:

  • exact executable-path matching rather than loose substring matching;
  • rejecting the node-based Codex CLI as a desktop-maintenance target;
  • detecting Electron helper process types;
  • detecting stale main process + missing renderer cases;
  • refusing to repair active desktop sessions;
  • refusing to act when a windowless Codex process tree is still CPU-active;
  • creating backups before SQLite maintenance;
  • handling Store/AppX repair timeouts as blockers rather than continuing to stack repair operations.

Privacy / safety note

I am intentionally not attaching raw local Codex logs or SQLite files here. They may contain prompts, local paths, command history, or workspace details. I can provide sanitized diagnostics or specific excerpts if maintainers say what would be most useful.

Proposed next step

If this direction aligns with the Codex Windows roadmap, I can extract a much smaller upstream-oriented proposal or invited PR focused only on Windows startup diagnostics, without the external tray app, branding, or Store tooling.

View original on GitHub ↗

3 Comments

github-actions[bot] contributor · 2 months ago

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

  • #26327

Powered by Codex Action

lukisch · 2 months ago

Thanks for the duplicate suggestion. I reviewed #26327. It is related at the helper/app-server lifecycle level, but I do not think this issue is a duplicate.

#26327 focuses on long-session performance degradation from accumulated Node REPL/MCP/stdio app-server helper stacks, and it was later retracted by its author pending a cleaner trigger isolation.

This issue is scoped to Windows Desktop startup/launch health: stale desktop main processes, shared SQLite locks, and a conservative diagnostic path before users reach for Store/AppX repair flows. The overlap is useful context, but the requested upstream surface here is narrower: startup-health diagnostics and safe process/lock classification.

FuqingZh · 2 months ago

I’m seeing a recurring Windows Codex Desktop local state/profile recovery issue that looks related to stale Codex/app-server processes and locked ~/.codex SQLite state.

Environment

  • OS: Windows 11 x64
  • Earlier affected package observed during stale-process / SQLite-lock investigation:

OpenAI.Codex_26.601.2237.0_x64__2p2nqsd0c76g0

  • Current package after reset/update:

OpenAI.Codex_26.602.3474.0_x64__2p2nqsd0c76g0

  • AppX local state:

C:\Users\<user>\AppData\Local\Packages\OpenAI.Codex_2p2nqsd0c76g0

  • Codex home:

C:\Users\<user>\.codex

Failure pattern

Codex Desktop can fail to launch with:

Unable to start Codex because there was a problem opening your profile. Please restart Codex.

This did not look like a simple install/version issue. After closing the visible Codex window, I observed stale Codex.exe / codex.exe app-server processes still running. While those processes were alive, these shared SQLite files under ~/.codex remained locked or failed to open cleanly:

logs_2.sqlite
state_5.sqlite
memories_1.sqlite
goals_1.sqlite

Other observations:

  • logs_2.sqlite had grown to about 854 MB.
  • After rotating/rebuilding it, it dropped to about 7.2 MB, and startup/exit behavior improved.
  • Windows Event Viewer showed a Codex.exe hang:
  • Event name: AppHangTransient
  • Time: 2026-06-01 12:55:33
  • There was also a separate git.exe hang around 2026-06-03 22:49:25.
  • Codex logs contained many git watcher / git origin resolution failures and aborts. This may not be the direct root cause, but it appears to slow shutdown and increase the chance of stale processes/file locks.

Latest update/reset observation

After updating again, Codex Desktop could not open after the update. A normal restart was not enough. Resetting Codex from Windows Settings made it launch successfully.

I did not capture the stale-process / SQLite-lock state before resetting this time, so I cannot confirm the exact same lock condition recurred. But the recovery pattern was similar: update/restart left the app unable to open, and a full Windows app reset restored it.

Current state after reset:

Codex launches successfully.
logs_2.sqlite is about 20 MB.
SQLite files are locked only while Codex is running, which seems expected.
No current profile-open failure is visible after the reset.

Workarounds

The Windows Settings reset path works, but it is heavy:

Windows Settings
→ Apps
→ Installed apps
→ Codex
→ Advanced options
→ Terminate / Repair / Reset 
# Repair did not recover it in my case; Reset did.

In my case, resetting Codex from Windows Settings made the app launch successfully again. The same heavy reset can also be done with:

Get-AppxPackage OpenAI.Codex | Reset-AppxPackage

Before doing a full reset, smaller targeted workarounds are:

# 1. Kill stale Codex processes first.
Get-Process Codex,codex -ErrorAction SilentlyContinue | Stop-Process -Force
Get-Process Codex,codex -ErrorAction SilentlyContinue

# 2. If the profile error persists after Codex is fully closed,
#    rotate the oversized logs DB.
$stamp = Get-Date -Format 'yyyyMMdd-HHmmss'
$backup = "$env:USERPROFILE\.codex\maintenance-backups\win-app-profile-clean-$stamp"
New-Item -ItemType Directory -Path $backup -Force

Move-Item "$env:USERPROFILE\.codex\logs_2.sqlite"     "$backup\logs_2.sqlite"     -ErrorAction SilentlyContinue
Move-Item "$env:USERPROFILE\.codex\logs_2.sqlite-wal" "$backup\logs_2.sqlite-wal" -ErrorAction SilentlyContinue
Move-Item "$env:USERPROFILE\.codex\logs_2.sqlite-shm" "$backup\logs_2.sqlite-shm" -ErrorAction SilentlyContinue

# 3. If Chromium profile state is affected, rotate only the Chromium
#    profile cache instead of resetting the whole AppX package.
$profile = "$env:LOCALAPPDATA\Packages\OpenAI.Codex_2p2nqsd0c76g0\LocalCache\Local\Chromium\User Data"

if (Test-Path $profile) {
  Move-Item $profile "$backup\Chromium User Data"
}

Expected behavior

Codex Desktop should recover from stale local state automatically, or provide a targeted recovery action instead of requiring a full Windows app reset.

Possible recovery actions:

  • terminate stale Codex.exe / codex.exe app-server processes;
  • rebuild/rotate logs_2.sqlite;
  • reset only the local Chromium profile cache;
  • add a codex doctor-style check for stale processes, locked SQLite files, oversized logs DBs, and Chromium profile locks.

This looks closest to the stale-process / local-state recovery problem in this issue. It may also be related to the helper-process accumulation described in #26327 as a contributing factor, but the direct failure mode here is startup/profile recovery after stale or inconsistent local state.