Desktop direct thread resume fails with invalid transport in mcp_servers.codex_app unless Web UI resumes it first

[hitsmaxft]

Environment: macOS 27 arm64, codex-bridge v0.2.4 (37b9962), bundled Codex app-server 0.153.4.

After installing with ./scripts/install-macos.sh --web-ui and relaunching Desktop, opening an existing thread directly in Desktop fails:

thread/read succeeds, but thread/resume returns -32600:
failed to load configuration: invalid transport in mcp_servers.codex_app

~/.codex/config.toml contains no mcp_servers.codex_app entry and passes normal CLI loading. The MCP configuration is injected dynamically by Desktop.

If the same thread is opened in the Web UI first, codex-bridge sends thread/resume without the Desktop MCP override. After that, Desktop can access the already-loaded thread. This is only a preload workaround.

Expected: a thread should resume directly from Desktop when interposition is enabled, without requiring Web UI preloading.

Suggested fixes:

1. Add a Desktop-direct thread/resume compatibility test.
2. Determine which Desktop request field becomes the invalid codex_app transport.
3. Preserve or reconstruct Desktop’s dynamically injected MCP launch configuration for the managed app-server.
4. Until compatible, detect the affected Desktop/app-server version and disable desktop_interposition by default instead of leaving Desktop threads unusable.

Supported workaround: set desktop_interposition = false, restart the bridge, and unset both launchd environment variables.

[hitsmaxft]

Confirmed root cause and proposed fix

The failing Desktop request does go through ws-unix-bridge. At failure time the Desktop process had an established TCP connection to 127.0.0.1:18790, and its log reported transport=websocket with initialization completed.

A temporary redacted probe of the Desktop-to-app-server thread/resume frame showed these relevant config keys:

mcp_servers.codex_app.enabled_tools

There was no mcp_servers.codex_app.command, .url, or complete mcp_servers.codex_app table in the request. This is valid with Desktop's private stdio app-server because Desktop normally supplies the complete codex_app MCP transport as a process-level -c override. The bridge-managed app-server was started without that base:

codex app-server --listen unix://...

When Codex merges the per-thread enabled_tools field into an app-server with no base transport, it creates a codex_app entry with neither command nor url. Codex then returns exactly invalid transport in mcp_servers.codex_app.

An isolated A/B test against bundled app-server 0.153.4 confirmed this:

• no process-level base + mcp_servers.codex_app.enabled_tools: thread/start fails with -32600 invalid transport;
• disabled process-level base + the same per-thread config: thread/start succeeds.

The fix is in the bridge-managed app-server startup command, while keeping ws-unix-bridge transparent and preserving the single app-server/writer boundary:

codex -c 'mcp_servers.codex_app={command="",enabled=false}' app-server --listen unix://...

The disabled entry provides a structurally valid transport base for Desktop's incremental thread config. It does not start a fake MCP server. Standalone mode keeps the original command.

Local patch: managed_app_server_args(socket, desktop_interposition) adds the base only when Desktop interposition is enabled. Validation passed: 46 library tests, 53 daemon tests including the new startup-argument regression, and the transparent ws-unix-bridge forwarding test.

This supersedes the earlier workaround of disabling Desktop interposition. Disabling interposition breaks the intended shared app-server topology and should not be the resolution.

[hitsmaxft]

Correction: the disabled MCP base is only a resume-parser compatibility workaround, not a complete codex_app integration.

mcp_servers.codex_app={command="",enabled=false} prevents Desktop's incremental mcp_servers.codex_app.enabled_tools field from creating a transport-less table, so direct thread/resume can succeed. However, enabled=false also means the codex_app MCP is unavailable.

Live inspection of Desktop 26.903.61454 in WebSocket mode found:

• Desktop is connected through ws-unix-bridge to the shared app-server;
• the Desktop process has no CODEX_APP_TOOLS_PIPE_PATH environment value;
• it owns no codex-app-tools pipe and starts no codex-app-tools MCP process;
• only browser-use native sockets are present;
• its resume request supplies mcp_servers.codex_app.enabled_tools, but no command, url, env, or pipe path.

Therefore Bridge cannot restore a working codex_app MCP merely by changing the app-server startup argv. Starting the full launcher command without the Desktop-created private pipe would produce a nonfunctional MCP server. The v0.2.5/v0.2.6 startup seed should be described as direct-resume compatibility with codex_app disabled, not as preservation of the complete Desktop MCP configuration.

A complete fix needs a supported Desktop-to-shared-app-server capability handoff: Desktop must expose and send the full codex_app transport plus its live host pipe when using CODEX_APP_SERVER_WS_URL, or app-server/Desktop must provide an equivalent native host-tools channel for external WebSocket mode. Until then, these are separate acceptance criteria:

1. existing threads resume directly without Web UI preloading;
2. mcp_servers.codex_app reaches ready and its tools actually work.

The current disabled-base change satisfies only criterion 1.

[hitsmaxft]

Runtime follow-up

The host binaries and Bridge daemon have been upgraded to v0.2.6, but I intentionally did not cold-restart the existing shared app-server after confirming the limitation above. The currently adopted app-server therefore still has its original argv and remains connected to Desktop through the WebSocket bridge.

Reason: a cold restart with the v0.2.6 command would permanently apply mcp_servers.codex_app={command="",enabled=false} to that app-server process. This would make direct resume parse successfully while knowingly leaving the Desktop codex_app MCP disabled. Applying it should not be reported as a complete MCP fix.

Recommendation: retain the current process while investigating the capability handoff, and change the release wording/status to distinguish the parser workaround from full MCP availability. The final acceptance test must verify both direct Desktop resume and mcpServerStatus/list reporting codex_app as ready with a working tool call.

[hitsmaxft]

v0.2.7 main and reinstall follow-up

I checked and installed current main at 4d1083c / v0.2.7. This release does not add the missing Desktop MCP capability handoff:

• ws-unix-bridge still forwards Desktop frames unchanged;
• managed Desktop startup still seeds mcp_servers.codex_app={command="",enabled=false};
• no full codex_app command, environment, or CODEX_APP_TOOLS_PIPE_PATH is supplied in WebSocket mode.

Therefore the conclusion from the previous comment is unchanged: v0.2.7 fixes direct-resume config parsing only. It does not make the codex_app MCP available on the shared app-server.

The reinstall also exposed a separate service-availability failure. ./scripts/install-macos.sh --web-ui successfully built and installed all three v0.2.7 binaries, preserved the existing config, and validated the plist, but then failed after unloading the old LaunchAgent:

Bootstrap failed: 5: Input/output error

At that point the user service was unavailable even though installation had otherwise completed. Re-running the following without sudo restored it:

launchctl enable gui/501/local.codex-bridge.daemon

launchctl bootstrap gui/501 ~/Library/LaunchAgents/local.codex-bridge.daemon.plist

Post-recovery verification:

• codex-bridge and codexctl: 0.2.7;
• Bridge protocol: 25, status ready;
• Web UI listens on 0.0.0.0:18791;
• loopback and LAN requests return 401 without credentials and 200 with the configured password;
• Desktop reconnected to 127.0.0.1:18790 and logged successful WebSocket initialization and thread/resume.

The existing app-server was intentionally adopted rather than cold-restarted, because a v0.2.7 cold start would apply the incomplete disabled codex_app base described above. The full MCP acceptance criterion remains unresolved.

Installer suggestion: if the first launchctl bootstrap returns error 5 after a successful bootout, retry launchctl enable plus bootstrap, and fail with an explicit service-unavailable message only after checking the label and control socket.

[hitsmaxft]

v0.2.8 follow-up

Released in v0.2.8: https://github.com/hitsmaxft/codex-bridge/releases/tag/v0.2.8

Resolved in Bridge:

• Direct Desktop thread/resume remains compatible with the incremental mcp_servers.codex_app.enabled_tools configuration.
• Both WebSocket legs now accept 64 MiB frames and messages. A bidirectional regression test covers payloads above the previous 16 MiB limit, and a 48,314,807-byte / 115-turn response was accepted through the deployed bridge.
• The macOS installer now recovers from launchd bootstrap error 5 by enabling the per-user service, retrying bootstrap only when the label is still absent, verifying the loaded LaunchAgent, and waiting for the control socket before reporting success.
• Runtime status now reports this topology as connected · limited rather than implying full Desktop MCP availability.

The private codex_app MCP remains an upstream capability-handoff limitation, not a WebSocket forwarding bug. Inspection of the current Desktop package shows that its request interceptor replaces codex_app with { command: "", enabled: false } whenever app-server is not local stdio. In external-WebSocket mode Desktop also does not create or export CODEX_APP_TOOLS_PIPE_PATH, while the bundled codex-app-tools server requires that pipe to reach Desktop host capabilities.

Therefore the current acceptance state is:

1. Direct resume without Web UI preloading: passing.
2. Large thread responses through the bridge: passing.
3. codex_app reports ready and its private tools work: still unavailable in Desktop external-WebSocket mode.

A transparent bridge cannot safely reconstruct the missing native host channel. This issue should remain open for the full MCP criterion until Desktop/app-server provides a supported transport and pipe handoff.