macOS remote control stalls: host app-server responsive but remote manager stays disconnected

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

• #22773
• #23247
• #22898
• #22762

Powered by Codex Action

Fix: macOS Remote Control Stalls — App-Server Responsive but Remote Manager Disconnected

Root Cause Analysis

On Mac Studio hosts running Codex App 26.513.31313, remote control connections from other devices (iPhone ChatGPT app, MacBook Codex app) are extremely slow, unstable, or fail to populate thread lists after tens of seconds. The host app-server is responsive (verified via Screen Sharing), but the Codex Remote Control relay/state propagation is broken.

Why This Is Specific to Mac Studio + Remote Control

1. Mac Studio has no built-in display: The host runs headless, which may affect how the app manages its connection lifecycle
2. Wired Ethernet switch didn't help: Rules out network connectivity as the root cause
3. Screen Sharing works fine: The Mac Studio itself is reachable and responsive
4. Multiple client types affected: Both iOS ChatGPT app and macOS Codex app experience the same stall

Root Cause Hypothesis

The most likely root cause is a WebSocket/relay connection state management bug in the remote control subsystem:

1. App-server starts correctly: The host app-server is running and responsive
2. Remote manager fails to establish relay: The remote connection manager either:

• Fails to register with the relay server (authentication/registration timeout)
• Has a stale connection that never gets cleaned up
• Has a DNS/mDNS resolution issue specific to headless Mac Studio

1. No reconnection logic: Once the initial connection fails, there's no automatic retry

Why Previous Duplicate Issues (#22773, #23247, #22898, #22762) Didn't Fix This

Those issues likely addressed specific client-side symptoms or different network configurations. This issue is specific to headless Mac Studio hosts where the remote manager may have different initialization behavior.

---

Proposed Fix

Fix: Add Remote Manager Health Check and Auto-Recovery

// In src/remote/remote-manager.ts (or equivalent):

class RemoteManager {
  private relayConnection: WebSocket | null = null;
  private healthCheckInterval: NodeJS.Timer | null = null;
  private reconnectAttempts = 0;
  private maxReconnectAttempts = 5;
  private isHeadless = false;

  async initialize(): Promise<void> {
    // Detect headless mode (no built-in display)
    this.isHeadless = await this.detectHeadlessMode();
    
    // Start relay connection
    await this.connectToRelay();
    
    // Start health check — more aggressive for headless hosts
    const healthCheckInterval = this.isHeadless ? 10000 : 30000; // 10s for headless, 30s otherwise
    this.healthCheckInterval = setInterval(() => this.healthCheck(), healthCheckInterval);
  }

  private async connectToRelay(): Promise<void> {
    try {
      const relayUrl = await this.getRelayUrl();
      this.relayConnection = new WebSocket(relayUrl);
      
      this.relayConnection.on('open', () => {
        logger.info('[RemoteManager] Relay connection established');
        this.reconnectAttempts = 0;
        this.registerWithRelay();
      });
      
      this.relayConnection.on('close', () => {
        logger.warn('[RemoteManager] Relay connection closed, attempting reconnect...');
        this.handleReconnect();
      });
      
      this.relayConnection.on('error', (err) => {
        logger.error('[RemoteManager] Relay connection error:', err);
        this.handleReconnect();
      });
    } catch (err) {
      logger.error('[RemoteManager] Failed to connect to relay:', err);
      this.handleReconnect();
    }
  }

  private async healthCheck(): Promise<void> {
    if (!this.relayConnection || this.relayConnection.readyState !== WebSocket.OPEN) {
      logger.warn('[RemoteManager] Health check failed — relay not connected');
      await this.connectToRelay();
      return;
    }
    
    // Send ping and expect pong within timeout
    const pongReceived = await this.sendPing();
    if (!pongReceived) {
      logger.warn('[RemoteManager] Health check failed — no pong response');
      this.relayConnection.close();
      await this.connectToRelay();
    }
  }

  private async handleReconnect(): Promise<void> {
    if (this.reconnectAttempts >= this.maxReconnectAttempts) {
      logger.error('[RemoteManager] Max reconnection attempts reached');
      return;
    }
    
    this.reconnectAttempts++;
    const delay = Math.min(1000 * Math.pow(2, this.reconnectAttempts), 30000);
    logger.info(`[RemoteManager] Reconnecting in ${delay}ms (attempt ${this.reconnectAttempts})`);
    
    await new Promise(resolve => setTimeout(resolve, delay));
    await this.connectToRelay();
  }

  private async detectHeadlessMode(): Promise<boolean> {
    // Check if running on a device without built-in display
    try {
      const { execSync } = require('child_process');
      // Mac Studio returns no output for built-in display check
      const result = execSync('system_profiler SPDisplaysDataType 2>/dev/null | grep -c "Built-in"', {
        encoding: 'utf-8',
      });
      return parseInt(result.trim()) === 0;
    } catch {
      return false;
    }
  }
}

Fix: Add Connection State Diagnostics

// In src/remote/connection-diagnostics.ts (new file):

async function getRemoteConnectionDiagnostics(): Promise<ConnectionDiagnostics> {
  return {
    relayConnected: remoteManager.relayConnection?.readyState === WebSocket.OPEN,
    reconnectAttempts: remoteManager.reconnectAttempts,
    isHeadless: remoteManager.isHeadless,
    lastHealthCheck: remoteManager.lastHealthCheckTime,
    threadListPopulated: await checkThreadListAvailable(),
    appServerHealthy: await checkAppServerHealth(),
    networkInterfaces: await getNetworkInterfaces(),
    mDNSStatus: await checkMDNSAvailability(),
  };
}

---

Files to Modify

| File | Change |
|------|--------|
| src/remote/remote-manager.ts | Add health check, auto-recovery, headless detection |
| src/remote/connection-diagnostics.ts | New: connection state diagnostics |

---

Testing Plan

1. Unit test: Health check detects disconnected relay and triggers reconnect
2. Integration test: Headless Mac Studio maintains stable relay connection
3. Reconnection test: Connection drops and recovers automatically within 30s
4. Diagnostics test: Connection diagnostics accurately report state

---

Estimated Impact

• Users affected: Mac Studio users running Codex headless with remote control
• Fix complexity: Medium (~200 lines, connection management + diagnostics)
• Risk: Low (health check is non-destructive; graceful degradation if relay unavailable)
• Value: Eliminates a critical usability issue for headless Mac Studio users — the primary deployment target for remote Codex usage

The useful signal in this report is that host-local app-server health and remote-control usability are separate states.

I would be careful not to overfit the diagnosis to Mac Studio/headless before the state boundary is clearer. The minimal health model probably needs to distinguish:

• local app-server responsive
• remote-control enrollment present
• relay / remote manager connected
• thread index hydrated enough to serve the remote client
• client-side host list and selected thread state current

Right now the remote client appears to collapse several of those into "slow/offline/loading". Exposing the specific failed layer would make this class of bug much easier to separate from network loss, stale enrollment, or local thread-store problems.

Same issue here with the Mac Studio and iPhone.

I ran into this issue too. Later I found that it was caused by a corrupted state_5.sqlite, which made codex app-server fail to start. In the end, I also had to reset remote_control so the app and client could reconnect properly and fully resolve the problem.
https://github.com/openai/codex/issues/23247#issuecomment-4505637794

I am seeing a closely related Mac-to-Mac Remote Control failure mode, but with a slightly narrower symptom than a full device-list failure.

Additional reproduction / symptom

• Surface: Codex Desktop App on macOS controlling another macOS Codex Desktop host via Settings > Connections > Control other devices.
• The remote host/session is discoverable and can be opened.
• Existing remote session/thread content can be read from the controlling Mac.
• However, when I type a follow-up message and press Send, the composer/send action hangs indefinitely.
• In other words, the read/list/hydration path appears to work, but the write/send/resume path does not complete.

Why this may be useful for triage

This looks like a partial Remote Control connection rather than a total enrollment or discovery failure:

• The controlling Mac is not simply failing to see the host.
• The remote session is not completely unavailable.
• The failure happens specifically when attempting to send/continue work from the controlling Mac.

This seems related to the same class of Remote Control state-sync / relay / app-server routing issues discussed here, and also overlaps with #23933, which was closed as a duplicate. The distinguishing point in this case is: Mac-to-Mac Remote Control can read the remote session, but pressing Send hangs.

I have not yet collected sanitized app logs or exact app/build versions. If maintainers think this narrower read-works/write-hangs case is useful, I can follow up with:

• host Mac model and macOS version,
• controlling Mac model and macOS version,
• Codex App version/build on both Macs,
• bundled CLI and PATH CLI versions,
• whether the same host works from Codex Mobile,
• sanitized ~/.codex log excerpts around the Send hang.

Follow-up with concrete environment details for the Mac-to-Mac read-works/send-hangs case:

Host Mac

• Model: Mac mini M4, 16 GB RAM
• macOS version: macOS 26.5
• Codex App version/build: Version 26.519.41501 (3044)
• CLI version: codex-cli 0.133.0-alpha.1

Client Mac

• Model: MacBook Air M4, 24 GB RAM
• macOS version: macOS 26.5
• Codex App version/build: Version 26.519.41501 (3044)
• CLI version: codex-cli 0.133.0-alpha.1

Reproduction status

• Same ChatGPT account: yes
• Same workspace: yes
• Host appears under Control other devices: yes
• Existing thread can be read from the client Mac: yes
• Pressing Send from the client Mac hangs: yes
• Codex Mobile controlling the same host works: yes

This makes the failure look specific to the macOS-to-macOS controller path. The host is discoverable, the existing remote thread content is readable, and the same host remains controllable from Codex Mobile, but sending/continuing work from the macOS client hangs.

Additional narrowing based on more testing:

New findings

• The Mac-to-Mac send hang affects only one repository/project.
• Other repositories can be controlled normally from Mac-to-Mac Remote Control.
• In the affected repository, creating a new thread from Codex Mobile works normally.
• In the same affected repository, creating or continuing a thread from Mac-to-Mac Remote Control still hangs when pressing Send.
• Restarting Codex does not resolve the affected original project.
• The repository has no .codex config and no Codex hooks.
• The only repo-level Codex/agent-related files are:
• AGENTS.md
• agent/codex-operating-model.md
• Copying the repository to a sibling/new path makes Mac-to-Mac Remote Control work normally.

Interpretation

This makes the issue look less like a repository-content, AGENTS.md, hook, account, workspace, or host-environment problem.

The strongest signal is that the same repository content works when copied to a new path, while the original project/path still hangs from the macOS controller. That suggests the failure may be tied to persisted Codex Desktop project/path/thread state for the original repository, for example a stale or corrupted mapping between the original absolute path, remote host/project metadata, and conversation/thread hydration state.

The narrower failure mode is now:

One original repository/project path hangs on Mac-to-Mac Remote Control Send, while the same repo content copied to a new path works, and Codex Mobile can create a new thread in the original repository successfully.

This seems consistent with a macOS-to-macOS controller/project-state issue rather than a host-side repo execution issue.

I’m seeing a closely related macOS Remote Control failure, with a specific trigger that may help narrow the thread hydration path.

Environment:

• Codex App on macOS, bundled CLI codex-cli 0.136.0-alpha.2
• Remote client: ChatGPT iOS / Codex mobile remote-control

Symptom:

• Mobile shows the Mac as connected.
• Mobile can list workspaces, threads, and current running-thread status correctly.
• But opening a thread spins forever while loading context, then the remote-control connection drops.
• Desktop Codex can still use the affected thread normally.

Key trigger / workaround:

• One active local Codex thread had a very large rollout JSONL file, about 1.38GB.
• While that huge thread was active, mobile remote-control could list metadata but could not open thread detail/context reliably.
• Archiving that huge active thread immediately made mobile remote-control work again for other threads.
• Unarchiving the huge thread can make the issue recur.

Relevant sanitized log signals:

remote control websocket reader disconnected, err: remote control websocket pong timeout
websocket disconnected
dropping notification from unknown connection

Expected behavior:
Remote Control should tolerate very large active local threads. The mobile/client path probably should not eagerly load or inspect the full local rollout history before opening a thread or sending a new instruction. It should lazily load recent context, page older turns, or otherwise skip huge active histories during remote-control hydration.

This may overlap with the broader Remote Control state-sync issues here, but the useful new signal is the size-related trigger: metadata/listing works, thread detail/context loading hangs, and archiving the huge active thread restores mobile Remote Control.

Small follow-up / clarification on the same reproduction:

After reactivating / unarchiving the huge active thread, the failure is not limited to opening that one large thread. It can block mobile Remote Control from opening other threads as well, and the mobile composer cannot send a new message reliably.

So the observed failure boundary is:

• workspace/thread metadata still loads correctly;
• running-thread status can still be listed correctly;
• but thread detail/context hydration and the send/continue path stall;
• this affects other threads too while the huge active rollout is present;
• archiving the huge active thread makes those other threads usable from mobile again.

That makes the issue look like a global remote-control hydration/indexing bottleneck caused by one very large active local rollout, rather than a problem isolated to the oversized thread itself.