Launch Codex sessions with `<Session.Launch>`

[taras]

Story

As an executable-document author, I want <Session.Launch> to open a prepared Codex session in Codex's native UI, so the same role document can launch either Claude or Codex by selecting its Agent.

Example

<Agent name="codex">
  <Session.Launch session="implementor">
    Implement the accepted plan.
  </Session.Launch>
</Agent>

The document prepares one durable Codex conversation with those instructions, hands that exact conversation to the Codex terminal UI, and continues after the UI exits.

The same invocation works inside a terminal pane:

<Terminal title="Codex">
  <Agent name="codex">
    <Session.Launch session="implementor">
      Implement the accepted plan.
    </Session.Launch>
  </Agent>
</Terminal>

Current gap

XMD knows the native resume command shape for Codex—codex resume <session-id>—and the installed Codex CLI accepts a UUID or session name. The adapter is nevertheless absent from the advertised native-launch set, so the component refuses before creating or resuming a session:

agent "codex" is not advertised as native-launch capable. An adapter is advertised only once its integration proof shows the native UI resumes the session ACP created and the prepared instructions are in force on its first turn. Adapters with a known command shape: claude, codex.

The command shape and controlled adapter tests are insufficient evidence. Codex uses the provider-returned identity path: ACP creates the conversation and reports its identity, then the native UI must prove that it resumes that exact conversation rather than opening a replacement.

Contract

<Session.Launch> advertises codex only after an opt-in integration proof against an installed Codex establishes the complete provider-returned launch contract:

1. ACP creation materializes a durable Codex conversation and returns its native identity.
2. codex resume <native-session-id> opens that exact conversation in the native terminal UI.
3. The rendered <Session.Launch> body is already in force as the prepared instruction layer on the first native user turn; launch performs no bootstrap model turn.
4. The selected working directory and permission configuration survive the ACP-to-native handoff without widening.
5. ACP ownership is fully released before the native UI attaches, so the two interfaces never own the session concurrently.
6. Exiting the native UI preserves the resumable conversation, including a session exited before any user turn.
7. A later ACP operation can reattach to the same conversation and observe the history created in the native UI.

Once that proof passes, Deno xmd run and the compiled binary include codex in their native-launch advertisement. Root launches and launches inside <Terminal> use the same adapter, coordinator, retained phases, and session identity.

Advertisement records the exact tested Codex and ACP adapter compatibility point. A different installed build is not silently assumed compatible when the proven contract depends on its behavior.

Prepared instructions do not enter argv or environment, provider-private history is not inspected, and no identity is inferred merely because a value resembles a UUID. A missing session, identity disagreement, ownership conflict, unsupported build, or failed proof refuses without creating a substitute conversation.

Completed replay launches no process. Incomplete replay follows the existing prepared/detached phase contract and resumes the retained Codex identity without allocating another one.

Node and Bun retain their existing native-launch provider boundary unless they independently acquire the coordinator, route store, executable observation, and terminal capabilities required by the launch contract.

Acceptance

• The opt-in real-provider proof creates a Codex session through ACP and opens that exact session through codex resume <id>.
• A marker in the prepared instruction layer governs the first native user turn without an extra model turn.
• A marker written in the native UI is observable after ACP reattaches to the same session, proving continuity rather than transcript reconstruction.
• A zero-turn native exit preserves the same session and later resumes it without replacement.
• The proof verifies working-directory and permission behavior across the handoff and fails if native launch widens either.
• ACP and the native UI are never active owners of the session at the same time.
• A missing or mismatched native identity refuses instead of opening Codex's session picker, using --last, or creating another conversation.
• Successful proof adds codex to the production native-launch advertisement and updates the regression test that currently requires Claude to be the only advertised adapter.
• <Agent name="codex"><Session.Launch>…</Session.Launch></Agent> works at the root and inside <Terminal> under supported hosts.
• Completed replay launches nothing, and incomplete replay preserves the retained Codex identity.
• Claude native launch and client-allocated identity behavior remain unchanged.
• architecture.md, specs/acp-client-spec.md, and specs/native-agent-session-launch-spec.md record the Codex compatibility point and provider-returned proof.

Evidence

Add an opt-in executable integration proof at packages/acp/src/CodexNativeLaunch.test.md, following the real-provider proof boundary used for Claude without assuming Claude's client-allocated construction route.

Run the focused adapter, component, CLI, and terminal integration suites:

deno task test packages/acp/tests/native-launch.test.ts packages/core/tests/agent-session-launch.test.ts packages/cli/tests/session-launch-cli.test.ts

The real-provider proof is the delivery evidence for advertisement. Controlled tests continue to cover refusal when Codex is not advertised or when any identity, ownership, phase, build, working-directory, or permission assertion fails.

Out of scope

• Capturing the launch result from <Session.Launch> (Return launch details from <Session.Launch> #753).
• Capturing or reconstructing the native Codex transcript.
• Adding a read-only session policy.
• Changing terminal-grid layout or lifecycle behavior (Quest: Add interactive terminal grids to executable documents #717 and Launch native Agent sessions in independent terminal panes #731).

Related

• Launch a deterministically prepared Agent session in its native UI #517 established the provider-neutral native session launch and fail-closed advertisement gate.
• Prove and advertise Claude native session launch in XMD #520 and its delivered proof are the corresponding Claude capability.