fix(electron-apps): move codex CDP port off 9222 to avoid browser-bridge collision (#1630)

* fix(electron-apps): move codex CDP port off 9222 to avoid browser-bridge collision

`src/electron-apps.ts` had `codex: { port: 9222 }`, but `9222` is the
default Chrome DevTools port that opencli's own browser-bridge Chrome
binds whenever `opencli doctor` is OK. On every normal opencli install
the bridge owns 9222 first, so Codex Desktop can never bind it, and
`opencli codex status` (plus every other codex command) fails with:

  App launched but CDP not available on port 9222 after 15s

`~/.opencli/apps.yaml` is documented as "additive only, does not
override builtins", so users have no supported way to relocate the
port from the user side.

Reported in #1626 with full repro (Codex Desktop + active opencli
browser-bridge Chrome) and root-cause pointer at
`dist/src/electron-apps.js:13`. Every other electron app in the
builtin registry already uses a distinct port in the 9224-9236
band (cursor 9226, doubao-app 9225, chatwise 9228, discord-app 9232,
antigravity 9234, chatgpt-app 9236); codex was the only one that
collided with the browser bridge.

Move codex to 9238 (the next free slot in that band, also the value
the reporter recommended). Update the test that asserts the port and
the two docs references that mention codex=9222. The pitfall entry
in `docs/advanced/electron.md` is also annotated to explicitly call
out 9222 as the bridge's port to avoid future collisions.

Closes #1626.

Verified live: `opencli codex status -v` now emits
`[verbose] [launcher] Probing CDP on port 9238...` (was 9222 before
the fix), confirming the code path picks up the new port. Full
end-to-end with a real Codex Desktop install is left to the reporter
and reviewer; the change here is a single-value config update plus
docs/tests sync.

Unit tests: 7 / 7 in `src/electron-apps.test.ts` pass (the codex-port
assertion updated to 9238). Both audit gates pass.

* docs(electron): sync codex CDP port guidance

---------

Co-authored-by: jackwener <jakevingoo@gmail.com>

docs/adapters/desktop/codex.md

@@ -8,13 +8,13 @@ Control the **OpenAI Codex Desktop App** headless or headfully via Chrome DevToo
 2. Launch it via the terminal and expose the remote debugging port:
    ```bash
    # macOS
-   /Applications/Codex.app/Contents/MacOS/Codex --remote-debugging-port=9222
+   /Applications/Codex.app/Contents/MacOS/Codex --remote-debugging-port=9238
    ```
 
 ## Setup
 
 ```bash
-export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9222"
+export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9238"
 ```
 
 ## Commands

docs/advanced/electron.md

@@ -14,7 +14,7 @@ Electron apps are essentially local Chromium browser instances. By exposing a de
 
 ### Launching the Target App
 ```bash
-/Applications/AppName.app/Contents/MacOS/AppName --remote-debugging-port=9222
+/Applications/AppName.app/Contents/MacOS/AppName --remote-debugging-port=<unique-port>
 ```
 
 ### Verifying Electron
@@ -82,7 +82,7 @@ await page.wait(1); // Wait for re-render
 
 ## Environment Variable
 ```bash
-export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9222"
+export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:<unique-port>"
 ```
 
 ## Non-Electron Pattern (AppleScript)
@@ -108,7 +108,7 @@ Core techniques:
 
 ## Pitfalls & Gotchas
 
-1. **Port conflicts (EADDRINUSE)**: Only one app per port. Use unique ports: Codex=9222, ChatGPT=9224, Cursor=9226, ChatWise=9228, Discord=9232
+1. **Port conflicts (EADDRINUSE)**: Only one app per port. Use unique ports matching the builtin registry: Codex=9238, Doubao=9225, Cursor=9226, ChatWise=9228, Discord=9232, Antigravity=9234, ChatGPT=9236. Avoid `9222`, the default Chrome DevTools port the opencli browser bridge already binds.
 2. **IPage abstraction**: OpenCLI wraps the browser page as `IPage` (`src/types.ts`). Use `page.pressKey()` and `page.evaluate()`, NOT direct DOM APIs
 3. **Timing**: Always add `await page.wait(0.5)` to `1.0` after DOM mutations. Returning too early disconnects prematurely
 4. **AppleScript requires Accessibility**: Terminal app must be granted permission in System Settings → Privacy & Security → Accessibility
@@ -117,8 +117,10 @@ Core techniques:
 
 | App | Port | Mode |
 |-----|------|------|
-| Codex | 9222 | CDP |
-| ChatGPT | 9224 | CDP / AppleScript |
+| Codex | 9238 | CDP |
+| Doubao | 9225 | CDP |
 | Cursor | 9226 | CDP |
 | ChatWise | 9228 | CDP |
 | Discord App | 9232 | CDP |
+| Antigravity | 9234 | CDP |
+| ChatGPT | 9236 | CDP / AppleScript |

docs/guide/electron-app-cli.md

@@ -35,13 +35,13 @@ If Electron is present, the next step is usually to launch the app with a debugg
 ### 2. Launch it with CDP enabled
 
 ```bash
-/Applications/AppName.app/Contents/MacOS/AppName --remote-debugging-port=9222
+/Applications/AppName.app/Contents/MacOS/AppName --remote-debugging-port=<unique-port>
 ```
 
 Then point OpenCLI at that CDP endpoint:
 
 ```bash
-export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9222"
+export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:<unique-port>"
 ```
 
 ### 3. Start with the 5-command pattern

docs/zh/guide/electron-app-cli.md

@@ -31,13 +31,13 @@ ls /Applications/AppName.app/Contents/Frameworks/Electron\ Framework.framework
 ### 2. 带 CDP 端口启动应用
 
 ```bash
-/Applications/AppName.app/Contents/MacOS/AppName --remote-debugging-port=9222
+/Applications/AppName.app/Contents/MacOS/AppName --remote-debugging-port=<unique-port>
 ```
 
 然后把 OpenCLI 指到这个端口：
 
 ```bash
-export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9222"
+export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:<unique-port>"
 ```
 
 ### 3. 先做 5 个基础命令

src/electron-apps.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { getElectronApp, isElectronApp, loadApps } from './electron-apps.js';
+import { builtinApps, getElectronApp, isElectronApp, loadApps } from './electron-apps.js';
 
 describe('electron-apps registry', () => {
   it('returns builtin app entry for cursor', () => {
@@ -12,7 +12,14 @@ describe('electron-apps registry', () => {
   it('returns builtin app entry for codex', () => {
     const app = getElectronApp('codex');
     expect(app).toBeDefined();
-    expect(app!.port).toBe(9222);
+    expect(app!.port).toBe(9238);
+  });
+
+  it('keeps builtin Electron app CDP ports unique and off the browser-bridge port', () => {
+    const ports = Object.values(builtinApps).map((app) => app.port);
+
+    expect(new Set(ports).size).toBe(ports.length);
+    expect(ports).not.toContain(9222);
   });
 
   it('returns undefined for non-Electron sites', () => {

src/electron-apps.ts

@@ -27,7 +27,7 @@ export interface ElectronAppEntry {
 
 export const builtinApps: Record<string, ElectronAppEntry> = {
   cursor:        { port: 9226, processName: 'Cursor',      bundleId: 'com.todesktop.runtime.Cursor',   displayName: 'Cursor' },
-  codex:         { port: 9222, processName: 'Codex',        bundleId: 'com.openai.codex',               displayName: 'Codex' },
+  codex:         { port: 9238, processName: 'Codex',        bundleId: 'com.openai.codex',               displayName: 'Codex' },
   chatwise:      { port: 9228, processName: 'ChatWise',     bundleId: 'com.chatwise.app',               displayName: 'ChatWise' },
   'discord-app': { port: 9232, processName: 'Discord',      bundleId: 'com.discord.app',                 displayName: 'Discord' },
   'doubao-app':  { port: 9225, processName: 'Doubao',       bundleId: 'com.volcengine.doubao',          displayName: 'Doubao' },