Materialize fresh ACP sessions at the first consuming operation

[taras]

Problem

The xmd prompt prototype exposes a lifecycle mismatch between XMD session establishment and Codex persistence.

XMD currently treats <Session> as eager:

1. place the logical session;
2. publish or adopt its construction route;
3. create or resume the ACP backend session;
4. retain the provider identity;
5. close the ACP handle;
6. expand the <Session> body; and
7. reconnect when <Prompt> starts.

A fresh Codex app-server thread does not have a durable rollout until its first turn/start. Closing the zero-turn handle and reconnecting therefore tries to resume an identity that Codex cannot yet load. openai/codex#31158 contains a direct reproduction of that persistence boundary.

This blocks the Markdown prototype for #260 even though generation uses the existing Agent components correctly.

Contract

A fresh session is a placement until an operation consumes it:

• <Session> resolves the agent, computes the provider placement, and returns an opaque provider-issued pending Session value.
• A fresh placement creates no construction route, ACP runtime, ACPX record, or backend session.
• A self-closing fresh <Session /> therefore validates agent availability and placement only.
• An already-established session retains eager reattachment validation, because its durable identity is meaningful and must be proven reachable.
• The first subscribed <Prompt> is the acp-first constructor. Under the existing ownership and turn-serialization boundaries it publishes or adopts the route, ensures the backend session, and starts the first turn through that same live handle with no intervening close.
• <Session.Launch> is the client-native constructor when it is the first consumer. A pending Session value by itself does not preselect acp-first.
• Construction routes remain create-once and never convert. Once an ACP-first materialization attempt has published its route, a later native launch cannot reinterpret it as client-native.
• Later prompts reconnect normally after the first turn has materialized durable provider history.

fresh placement
 ├─ first subscribed <Prompt> → acp-first → materialized
 └─ <Session.Launch> → client-native → materialized

Materialization and identity

ensureSession() completion is not proof that a fresh conversation is resumable. The current provider calls sessions.established() from ensureFromPrepared() before startTurn(), and ACPX saves a session record during ensure. startTurn() itself returns before the asynchronous backend turn has been accepted, while the public started event is synthesized by XMD.

Introduce an explicit runtime materialization boundary that proves the backend accepted the first turn. Only after that boundary may:

• the ACPX record assert a resumable provider identity; and
• the workflow host commit sessions.established().

A failure before materialization must leave no workflow mapping and no ACPX assertion that later resolution could mistake for resumable history. If provider contact may have occurred, retain the already-published acp-first route but discard or mark the pending ACPX arrangement as non-asserting so a later ACP-first attempt starts fresh.

Do not infer materialization from human-readable errors or recover by matching -32600. Codex uses that code for unrelated configuration failures as well as missing rollouts; openai/codex#28496 documents the ambiguity.

Preserved protections

The lifecycle change preserves:

• provider-issued Session validation and rejection of forged or stale values;
• agent and placement identity checks;
• create-once construction routes and refusal to convert retained history;
• exact native-session identity, executable-build binding, and retained-arrangement reconciliation;
• ownership, cancellation, teardown, and handle accounting; and
• eager validation of established ACP-first and client-native sessions.

The old rule that eager <Session> always wins over a nested native launch is intentionally amended: a fresh placement does not authorize either constructor until its first consuming operation.

Specification

Update:

• specs/acp-client-spec.md to distinguish placement, pending session values, materialization, and established-session validation;
• specs/native-agent-session-launch-spec.md to state that the first consuming operation chooses the immutable construction route; and
• existing eager-session wording and evidence identifiers that assert <Session> publishes acp-first by itself.

Use present-tense contracts and name the subscribed prompt as the materializing operation; prompt() remains cold until subscribed.

Acceptance criteria

• <Session><Prompt>…</Prompt></Session> starts the fresh backend session and first turn through one uninterrupted live handle; no zero-turn reconnect occurs.
• A self-closing fresh <Session /> creates no construction route, ACPX record, or backend session.
• A failure before first-turn materialization leaves no workflow mapping or resumable ACPX identity assertion.
• Retrying after a pre-materialization failure remains ACP-first and creates fresh backend state rather than resuming the zero-turn identity.
• Two sequential prompts continue one conversation.
• Concurrent first prompts within one installed provider serialize to one backend creation. Cross-process serialization for agents outside the native-handoff ownership boundary is not introduced here.
• A native launch may win from a fresh pending placement, after which ACP attaches only under the retained native identity.
• Existing ACP-first, forged, stale, client-native, and native-launched sessions retain their current identity and ownership protections.
• The Add xmd prompt: turn a request into an approved executable Plan #260 Markdown prototype returns and prints the generated executable Markdown source.

Evidence

Add focused provider regressions for:

• fresh placement without provider effects;
• ensure → materialization → identity-retention ordering;
• pre-materialization failure and retry;
• same-handle first prompt;
• sequential and concurrent prompts;
• pending-placement native launch precedence; and
• established, forged, stale, and native-launched sessions.

Add or retain a CLI Markdown test that runs the prompt prototype and observes the generated source. Run that test explicitly because the subprocess and executable-document boundary is not completely selected through imports.

Out of scope

• substring recovery for Codex -32600 errors;
• changes to Codex app-server persistence;
• cross-process ownership expansion for agents that do not participate in native handoff;
• automatic repair of unrelated stale provider sessions; and
• the remaining generation, inspection, approval, and execution behavior of Add xmd prompt: turn a request into an approved executable Plan #260.

Sequencing

Complete this lifecycle amendment before implementing the remaining #260 flow so generation does not depend on reconnecting a zero-turn session.