feat: implement desktop account switcher for codex-auth

[bnistor4]

Add a new desktop widget that allows users to switch active Codex accounts from the system tray or menu bar across Windows, macOS, and Linux. The feature enhances user convenience by providing a lightweight background process and a menu for account selection, while reusing existing registry and switch workflows. Initial implementation includes basic command parsing and menu layout, with plans for further enhancements in future phases.

[greptile-apps]

Greptile Summary

This PR swaps out the previous-account-switch brainstorm document (now implemented) for a new design document covering a cross-platform desktop tray/menu-bar account switcher (codex-auth desktop). No production code is changed.

• The new design proposes a phased rollout: shared non-GUI foundation → Windows MVP → macOS → Linux → polish, deliberately reusing the existing activateAccountByKey registry path and previous_active_account_key field.
• Several risks (concurrent instances, Linux D-Bus variability, Wayland incompatibility) are documented but the single-instance guard is deferred to Phase 5 despite being relevant from Phase 2 onwards.

Confidence Score: 5/5

Documentation-only change; no production code is touched and the deleted brainstorm document covers an already-implemented feature.

Both changed files are design brainstorm documents. The deleted file describes a feature (previous_active_account_key) that is already fully implemented across the registry, switch workflow, and tests. The new file is a well-structured design spec that correctly references existing APIs (activateAccountByKey, replaceFilePreservingPermissions, previous_active_account_key) and explicitly calls out risks. The one design gap — single-instance guard timing — is a future-phase concern with no impact on the current codebase.

No files require special attention; both are documentation artifacts with no runtime impact.

Important Files Changed

Filename	Overview
docs/brainstorm/2026-05-31-previous-account-switch-design.md	Deleted brainstorm document for the previous-account-switch feature, which is already implemented across registry, switch workflow, and tests — deletion is appropriate.
docs/brainstorm/2026-06-04-desktop-account-switcher.md	New design document for the desktop tray widget; well-structured and risk-aware, but the single-instance guard is deferred to Phase 5 while duplicate-instance confusion can occur from Phase 2 MVP onward.

Sequence Diagram

sequenceDiagram
    participant User
    participant TrayIcon as Platform Adapter<br/>(windows/macos/linux)
    participant MenuModel as menu_model.zig
    participant SwitchAction as switch_action.zig
    participant Registry as registry (account_ops)
    participant AuthFile as auth.json

    User->>TrayIcon: Click tray icon
    TrayIcon->>MenuModel: Build account menu
    MenuModel->>Registry: Load registry.json
    Registry-->>MenuModel: Account list + active/previous keys
    MenuModel-->>TrayIcon: Menu entries (stable account_keys)
    TrayIcon-->>User: Show account menu

    User->>TrayIcon: Select account
    TrayIcon->>SwitchAction: switch(account_key)
    SwitchAction->>Registry: "Load & sync registry"
    SwitchAction->>Registry: activateAccountByKey(account_key)
    Registry->>AuthFile: replaceFilePreservingPermissions
    Registry-->>SwitchAction: display label
    SwitchAction-->>TrayIcon: label / error
    TrayIcon-->>User: Native notification "Switched to label"

Loading

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
docs/brainstorm/2026-06-04-desktop-account-switcher.md:299-313
**Single-instance guard deferred too late**

The Risks section notes "Multiple desktop processes could confuse users. Add a single-instance guard before startup install support," but the guard itself is placed in Phase 5 (Polish) while the Windows MVP lands in Phase 2. This means every Phase 2 user who accidentally runs `codex-auth desktop` twice ends up with two tray icons and two concurrent processes independently writing `auth.json`, with no protection until Phase 5 ships. Consider adding a lightweight single-instance check (e.g. a named mutex on Windows, a lock file under `CODEX_HOME`) to Phase 2 rather than only requiring it before startup install.

_{Reviews (1): Last reviewed commit: "feat: implement desktop account switcher..." | Re-trigger Greptile}

[greptile-apps]

Single-instance guard deferred too late

The Risks section notes "Multiple desktop processes could confuse users. Add a single-instance guard before startup install support," but the guard itself is placed in Phase 5 (Polish) while the Windows MVP lands in Phase 2. This means every Phase 2 user who accidentally runs codex-auth desktop twice ends up with two tray icons and two concurrent processes independently writing auth.json, with no protection until Phase 5 ships. Consider adding a lightweight single-instance check (e.g. a named mutex on Windows, a lock file under CODEX_HOME) to Phase 2 rather than only requiring it before startup install.

Prompt To Fix With AI

This is a comment left during a code review.
Path: docs/brainstorm/2026-06-04-desktop-account-switcher.md
Line: 299-313

Comment:
**Single-instance guard deferred too late**

The Risks section notes "Multiple desktop processes could confuse users. Add a single-instance guard before startup install support," but the guard itself is placed in Phase 5 (Polish) while the Windows MVP lands in Phase 2. This means every Phase 2 user who accidentally runs `codex-auth desktop` twice ends up with two tray icons and two concurrent processes independently writing `auth.json`, with no protection until Phase 5 ships. Consider adding a lightweight single-instance check (e.g. a named mutex on Windows, a lock file under `CODEX_HOME`) to Phase 2 rather than only requiring it before startup install.

How can I resolve this? If you propose a fix, please make it concise.