Feat/wsl linux support

[Tsutomu-miku]

Summary

Add cross-platform support for WSL and Linux environments, plus a new codexm run wrapper that solves the auth hot-reload problem for codex CLI.

Changes

1. Platform abstraction layer

• src/platform.ts — platform detection (darwin / linux / wsl), WSL detection via /proc/version, platform-aware process matching
• src/platform-desktop-adapter.ts — platform-aware Desktop launcher that wraps the macOS-only codex-desktop-launch.ts and provides correct behavior on each platform

2. WSL / Linux support in core modules

• src/main.ts — wired in createPlatformDesktopLauncher() to replace hardcoded macOS launcher; platform-aware isRunningDesktopFromApp(); platform-specific error messages
• src/codex-login.ts — WSL browser opening chain: wslview → powershell.exe Start-Process → xdg-open fallback

3. CLI watch mode (no Desktop required)

• src/codex-cli-watcher.ts — quota monitoring via JSON-RPC polling (codex-direct-client), CLI process registry, auto-switch support
• src/main.ts watch command — falls back to CLI watch mode when no Codex Desktop is running (common on WSL/Linux)

4. codexm run — auth hot-reload wrapper ⭐

• src/codex-cli-runner.ts — new module that wraps codex as a child process
  • Watches ~/.codex/auth.json via fs.watch() with SHA-256 hash comparison and debouncing
  • When auth file changes (e.g., after codexm switch), automatically kills and restarts codex
  • Process registry integration for codexm watch tracking
  • Polling fallback for systems where fs.watch is unreliable
• src/main.ts case "run" — codexm run [-- ...codexArgs] command entry point

Why: Codex CLI (Rust) reads ~/.codex/auth.json once at startup and caches in memory. No file watcher, no signal handler, no IPC for reload. SIGUSR1 does NOT work. The only reliable approach is kill + restart.

5. SIGUSR1 → SIGTERM fix

• src/codex-cli-watcher.ts restartCliProcess() — replaced broken SIGUSR1 approach with SIGTERM + SIGKILL fallback. When codex was started via codexm run, the runner detects the exit and auto-respawns with updated auth.

6. Tests

• tests/codex-cli-runner.test.ts — 9 test cases for the runner (spawn, exit, restart, debounce, polling fallback, abort, SIGKILL timeout)
• tests/codex-cli-watcher.test.ts — updated with multi-process registry tests
• tests/cli.test.ts — CLI watch mode tests, platform adapter tests

Usage

# Instead of running `codex` directly:
codexm run -- --model o3

# In another terminal, switch accounts:
codexm switch my-other-account

# The running codex process auto-restarts with the new auth ✓

Verification

• pnpm typecheck
• pnpm test
• pnpm build

[Dikevin]

Codex review note:

I recommend narrowing the WSL/Linux direction to CLI-first support instead of trying to preserve full parity with the macOS Desktop model. The biggest current risk is mixing three different things together: the codex CLI binary path, Windows-side Desktop processes, and managed Desktop/devtools semantics. That makes some commands look supported even when they cannot actually deliver on their contract.

I would split the command surface into two groups:

1. Commands that should be fully supported on WSL/Linux in CLI mode

• codexm add
• codexm save
• codexm current
• codexm current --refresh
• codexm list
• codexm list --verbose
• codexm update
• codexm switch <name>
• codexm switch --auto
• codexm watch (foreground CLI watch mode)
• codexm run [-- ...codexArgs]
• codexm remove
• codexm rename
• codexm completion

These are the commands that can be implemented cleanly using local auth state, quota refresh, the direct client / JSON-RPC path, and the codexm run restart model. They do not need Desktop/devtools semantics.

2. Commands / flags that should explicitly error or be rejected on WSL/Linux

• codexm launch
  This should fail with a clear message such as: “On WSL/Linux, use codexm run instead of launch."
• codexm launch --watch
  Same reason. This should not try to treat a CLI codex path as a Desktop binary.
• codexm switch --force
• codexm switch --auto --force
  These should either error or be downgraded with a very explicit warning. The meaning of --force today is “apply immediately to the running managed Desktop session.” In CLI mode, that responsibility should belong to codexm run auto-restarting on auth change, not to borrowed Desktop semantics.
• codexm watch --detach
  If detached CLI watch is not implemented reliably yet, keep it as a clear error instead of partial support.

3. README / help should split the runtime model by platform
I would strongly recommend documenting two separate operating modes:

• macOS Desktop mode
• WSL/Linux CLI mode

For WSL/Linux, the recommended flow can be very simple:

1. codexm add ...
2. codexm run -- --model ...
3. In another terminal, run codexm watch
4. When watch detects quota exhaustion and switches accounts, run restarts automatically and picks up the new auth

That makes the mental model clear:

• hot switching in CLI mode is achieved through codexm run restart behavior
• not through Desktop devtools refresh or --force

4. Implementation recommendation

• Do not let Linux/WSL findInstalledApp() return a CLI codex binary and then feed it into the Desktop launch() path with --remote-debugging-port.
• If future support for WSL + Windows-side Desktop is desired, that should be a separate implementation with an actual Windows process/devtools bridge. Until then, it is better to explicitly say “unsupported on this platform” than to provide misleading pseudo-compatibility.

In short: WSL/Linux should be a CLI-first closed loop, not an incomplete Desktop substitute. That gives users a stable command contract and makes the README much easier to understand.

[Tsutomu-miku]

Thanks for the thorough review! All points are well taken — agreed that WSL/Linux should be a CLI-first closed loop rather than an incomplete Desktop substitute.

Here's what's been addressed:

✅ Adopted

Suggestion	Commit	Details
codexm launch should reject on WSL/Linux	af038fe	Now errors with: "codexm launch is not supported on WSL/Linux. Use \"codexm run [-- ...args]\"..."
codexm launch --watch same	af038fe	Blocked at the same platform gate — all launch flags rejected
switch --force downgrade in CLI mode	af038fe	Detects no managed Desktop → sets effectiveForce = false + prints warning guiding to codexm run
watch --detach reject in CLI mode	Already done	Was already rejecting: "Detached CLI watch is not yet supported." (no change needed)
README split by platform	Already done	README has separate Quick Start / Typical Flow sections for macOS Desktop vs WSL/Linux CLI
Don't feed CLI binary into Desktop launch path	af038fe	launch now rejects before findInstalledApp() is ever called on non-macOS

Tests added (02f4b7e)

• launch rejects on Linux with guidance to use codexm run
• launch rejects on WSL with guidance to use codexm run
• launch --auto also rejects on non-macOS
• switch --force warns and downgrades when no Desktop session is running

Uses setPlatformForTesting() from platform.ts for clean platform overrides in tests.

CLI-first closed loop on WSL/Linux

The recommended flow is now:

1. codexm add / codexm save — account management (fully supported)
2. codexm run -- --model o3 — wraps codex with auth file watcher
3. codexm watch — foreground CLI quota monitor with auto-switch
4. When watch auto-switches → auth file changes → codexm run detects and restarts codex

No Desktop semantics leak into the CLI path.

[Dikevin]

Codex follow-up note:

Great work here. The CLI-first direction looks much better now, and adding both codexm watch and the restart-based switching flow for CLI mode makes the WSL/Linux story much more complete.

I think there is only one small TODO left: switch --auto --force should probably be treated the same way as manual switch --force in CLI mode.

My understanding is:

• in CLI mode, auth changes are actually applied by the codexm run / CLI restart path
• --force does not have meaningful extra effect there
• so this is not a functional blocker, because the workflow still works
• it is mostly a semantics / UX consistency issue, to make it explicit and unambiguous that --force is effectively meaningless in CLI mode

Also, there is currently no combined codexm run --watch flow for CLI mode. I do not consider that a defect or a problem in this PR — just a reasonable future feature suggestion if we want a more integrated CLI workflow later.

So I would consider this good to merge, with that one small cleanup left as a follow-up.

[Dikevin]

Looks good overall. The CLI-first direction makes the WSL/Linux workflow much clearer.