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

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:

• https://github.com/openai/codex/issues/21782
• https://github.com/openai/codex/issues/22428
• https://github.com/openai/codex/issues/23814
• https://github.com/openai/codex/issues/24598

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.