Bug: Codex Desktop crashes on every launch with Connection for host ID local not found after team-leave-during-login

TL;DR

After leaving a team organization mid-login, the Codex Desktop app froze on logout and now crashes on every launch with:

A JavaScript error occurred in the main process
Uncaught Exception: Error: Connection for host ID local not found
   at pb.getChronicleSidecarControlState (...)

The standard troubleshooting checklist (reinstall, clear caches, clear Preferences, clear Keychain) does not fix this. The poison is stored in ~/.codex/.codex-global-state.json — a state file shared between the Codex CLI and Desktop App, which is never cleaned by uninstalling the desktop app. A fresh reinstall reads this stale file and crashes the same way.

Environment

Trigger sequence (reproducible)

1. Log into Codex Desktop with a team account
2. While the login flow is in progress, leave the team organization (via the team admin panel in the browser)
3. Click "Log out" inside the desktop app
4. The app freezes; main process throws an uncaught JavaScript exception
5. From now on, every launch crashes immediately — login screen never reappears

Crash output (every launch)

A JavaScript error occurred in the main process

Uncaught Exception:
Error: Connection for host ID local not found
    at Kd.getConnection (/Applications/Codex.app/Contents/Resources/app.asar/.vite/build/workspace-root-drop-handler-B7KjFQ8M.js:247:13051)
    at pb.getChronicleSidecarControlState (/Applications/Codex.app/Contents/Resources/app.asar/.vite/build/main-BKLZ6R5S.js:472:44880)
    at pb.updateChronicleTrayIcon (/Applications/Codex.app/Contents/Resources/app.asar/.vite/build/main-BKLZ6R5S.js:420:21432)
    at Timeout._onTimeout (/Applications/Codex.app/Contents/Resources/app.asar/.vite/build/main-BKLZ6R5S.js:420:17842)
    at listOnTimeout (node:internal/timers:605:17)
    at process.processTimers (node:internal/timers:541:7)

The exception is thrown from a Timeout._onTimeout triggered by pb.updateChronicleTrayIcon, which calls pb.getChronicleSidecarControlState, which asks Kd.getConnection for a connection bound to host id "local". The exception is not caught, so the main process dies. The dialog only offers an "OK" button which exits the app.

What did NOT fix the crash

All of the following were tried, in order, on the same machine. None of them helped — the very first launch after each step crashes with the identical stack:

Standard cleanup

1. Reboot Mac
2. Reinstall (keeping data)
3. rm -rf ~/Library/Caches/com.openai.codex
4. rm -rf ~/Library/Logs/com.openai.codex
5. rm -f ~/Library/Preferences/com.openai.codex.plist
6. rm -rf ~/Library/Application\ Support/Codex

Hidden state (rarely on standard checklists)

1. rm -rf ~/Library/HTTPStorages/com.openai.codex*
2. rm -rf ~/Library/HTTPStorages/com.openai.sky.CUAService*
3. rm -rf ~/Library/Caches/com.openai.sky.CUAService
4. rm -f ~/Library/Preferences/com.openai.sky.CUAService.plist
5. rm -rf ~/Library/Application\ Scripts/2DC432GLL2.com.openai.sky.CUAService
6. rm -rf ~/Library/Group\ Containers/2DC432GLL2.com.openai.sky.CUAService
7. rm -f ~/Library/Sounds/codex-notification.wav
8. rm -f ~/Library/Application\ Support/CrashReporter/Codex_*.plist

Keychain

1. security delete-generic-password -s "Codex Safe Storage"
2. security delete-generic-password -s "Codex Key"

Nuclear option

1. Combine all of #1–#16, then download a fresh latest build (26.422.30944) from openai.com and reinstall

→ Still crashes on first launch with the identical error.

Diagnostic that pinpointed the cause

Created a fresh new macOS user account on the same Mac. Same machine, same OS, same /Applications/Codex.app binary.

This rules out:

• Mac hardware / OS-level state
• The app bundle itself
• The OpenAI server-side account state

The poison must be somewhere in the original macOS user's home directory that survives every uninstall.

Root cause

This file:

~/.codex/.codex-global-state.json

Key facts:

• This is the Codex CLI state directory
• The Codex Desktop App reads/writes the same file as the CLI (Electron-related keys like electron-main-window-bounds, electron-persisted-atom-state, electron-saved-workspace-roots live here)
• Uninstalling the desktop app does NOT clean this file
• It is invisible on every standard troubleshooting checklist

The poisoned content:

{
  "electron-persisted-atom-state": {
    "agent-mode-by-host-id": {
      "local": "full-access"     // ← poison: stale host id from the broken team session
    },
    ...
  },
  ...
}

Boot sequence that crashes:

1. Desktop app starts → reads ~/.codex/.codex-global-state.json
2. Sees agent-mode-by-host-id referencing host id "local"
3. pb.updateChronicleTrayIcon timer fires after a short delay
4. Calls pb.getChronicleSidecarControlState("local")
5. The freshly-installed Chronicle sidecar has not registered any host called "local" — it was reset on reinstall, but the persisted state still references it
6. Kd.getConnection throws Connection for host ID local not found
7. Uncaught → main process dies

Reinstalling the app resets the Chronicle sidecar's runtime registry, but the state file in ~/.codex/ is never reset, so the mismatch persists indefinitely.

Workaround (verified)

# 1. Kill any running Codex processes
pkill -9 -f "Codex"

# 2. Quarantine the poisoned state files (rename, don't delete, in case you want forensic data)
TS=$(date +%s)
mv ~/.codex/.codex-global-state.json     ~/.codex/.codex-global-state.json.poisoned-$TS
mv ~/.codex/.codex-global-state.json.bak ~/.codex/.codex-global-state.json.bak.poisoned-$TS
mv ~/.codex/auth.json                    ~/.codex/auth.json.poisoned-$TS

# 3. Re-launch
open -a "Codex"

✅ Login screen appears immediately. Re-login → fully functional.

User-specific fields (prompt-history, electron-saved-workspace-roots, project-order, etc.) can be selectively merged back from the quarantined file. agent-mode-by-host-id must NOT be merged back — it is the poison.

Suggested fixes

1. Short-term: catch the exception and self-heal

// Currently:
const state = await getChronicleSidecarControlState(hostId);

// Suggested:
try {
  const state = await getChronicleSidecarControlState(hostId);
} catch (e) {
  if (/Connection for host ID .* not found/.test(e.message)) {
    await purgeStaleHostIdFromGlobalState(hostId);
    return DEFAULT_CHRONICLE_STATE;
  }
  throw e;
}

This alone would prevent every user who hits this state from being permanently locked out.

2. Medium-term: fix the lifecycle

• The Desktop App's uninstaller should clean Electron-prefixed keys in ~/.codex/.codex-global-state.json (or move desktop state to a separate file like ~/.codex/desktop-global-state.json decoupled from the CLI).
• The login flow should detect and gracefully handle "team membership revoked mid-session" instead of writing a half-completed agent-mode-by-host-id entry.

3. Recovery UI

The crash dialog currently only has an "OK" button which exits. Add a "Reset local state and relaunch" button that runs the workaround above.

4. Documentation

Add the workaround above to the desktop app's troubleshooting docs. Right now there is zero documentation on ~/.codex/ being shared with the Desktop App, so users have no way to find this on their own.

Suggested QA reproduction

1. Test team account A in organization X
2. Fresh macOS, install Codex Desktop
3. Begin login as A
4. While login is in progress, an admin removes A from organization X (or A leaves X via the web)
5. Click "Log out" in the Desktop app
6. Observe freeze / crash
7. Restart app → expect Connection for host ID local not found on every launch

Impact

Any user whose team membership changes during a login flow can land in this unrecoverable state. Because:

• ~/.codex/ is hidden by default in Finder
• The fact that the Desktop App and CLI share state is undocumented
• Standard "uninstall + reinstall + clear caches + reset Keychain" doesn't touch it

…most affected users will likely wipe their machine or buy a new one before discovering this fix. This is a very expensive failure mode for what is ultimately a small piece of stale JSON.

Evidence preserved (available on request)

• ~/.codex/.codex-global-state.json.poisoned-<ts> — original poison file
• ~/.codex/.codex-global-state.json.bak.poisoned-<ts> — its bak
• ~/.codex/auth.json.poisoned-<ts> — old auth
• ~/Library/Application Support/Codex.broken-<ts>/ — full snapshot of old user-data-dir
• macOS DiagnosticReports/Codex_<ts>.diag — system crash report from first crash

I'm happy to share these privately with the engineering team if helpful.