[Feature]: First-class OpenCodeX integration for Codex and Claude Code sessions

[str0203]

Problem or use case

Orca can run Codex, Claude Code, and arbitrary CLI agents, but users who route those agents through OpenCodeX must currently maintain manual command overrides and environment setup. This is fragile across macOS, Windows, Linux, and Orca's isolated ORCA_CODEX_HOME runtime.

OpenCodeX already owns provider credentials, models, routing policy, quotas, and account pools. Recreating those settings inside Orca would duplicate sensitive state and create competing configuration owners. The desired workflow is for Orca to remain the session/worktree UI while OpenCodeX remains the routing backend.

This is related to, but intentionally narrower than, #2314. That issue proposes native multi-provider Claude account management in Orca. This request instead adds an opt-in adapter to an external routing service and does not ask Orca to store provider credentials.

For a given session, OpenCodeX routing mode and Orca-managed provider/account injection must be mutually exclusive. Otherwise both tools can write authentication and model environment state for the same agent process.

The companion OpenCodeX proposal is lidge-jun/opencodex#1416.

Proposed solution

Add an opt-in “Use OpenCodeX routing” integration for Codex and Claude Code:

1. Detect ocx on PATH.
2. Consume and validate the proposed versioned manifest from ocx export --client orca --json.
3. Run the manifest-provided readiness/prelaunch operation in the same environment and effective home as the Orca agent session.
4. Build the Codex or Claude Code launch plan from argv arrays and pass prompts/resume arguments through unchanged.
5. Show a compact OpenCodeX health indicator with retry and “Open dashboard” actions.
6. Keep all provider keys, OAuth tokens, account pools, model routing, and quota policy in OpenCodeX; do not copy them into Orca settings or logs.
7. Disable or label Orca's own provider/account selector as “managed by OpenCodeX” for an OpenCodeX-backed session; require an explicit choice if both modes are configured.
8. When the integration is disabled, unavailable, or incompatible, preserve Orca's existing native launch path and show an actionable message. Never switch an already-running session silently.

First phase scope: local macOS, Windows, and Linux sessions. Full dashboard embedding and SSH-host integration can be follow-ups.

Acceptance criteria:

• Opt-in can be enabled independently for Codex and Claude Code.
• Native launch behavior is unchanged when disabled.
• Missing/unhealthy OpenCodeX has a clear retry/native fallback.
• Unsupported manifest versions fail closed.
• ORCA_CODEX_HOME is preserved and passed consistently to manifest generation, prelaunch, and agent processes.
• Orca and OpenCodeX credential/account injection cannot both be active for one session.
• No OpenCodeX secrets are persisted in Orca settings, logs, or session metadata.
• Tests cover launch, prompt/resume pass-through, fallback, platform quoting, and home mismatch handling.

Alternatives or additional context

• Manual command overrides such as wrapping Codex startup and launching Claude through ocx claude; workable but not a stable integration.
• Implement providers and account pools directly in Orca (Add multi-provider auth methods and per-account model mapping to Claude managed accounts #2314); useful independently, but it duplicates OpenCodeX for users who already rely on its routing layer.
• Embed the OpenCodeX dashboard; deferred until a stable launch/status contract exists.

Related repositories and code:

• OpenCodeX integration contract proposal: feat(integrations): add a versioned Orca launch manifest lidge-jun/opencodex#1416
• OpenCodeX repository: https://github.com/lidge-jun/opencodex
• OpenCodeX Orca home diagnostic: https://github.com/lidge-jun/opencodex/blob/main/src/codex/home.ts
• Orca launch configuration: https://github.com/stablyai/orca/blob/main/src/shared/tui-agent-config.ts
• Related Orca request: Add multi-provider auth methods and per-account model mapping to Claude managed accounts #2314