Launch a deterministically prepared Agent session in its native UI

[taras]

Story

As a repository user, I want an executable document target to construct a
coding-agent session deterministically and open that exact session in the
agent's native UI, so I enter Claude Code, Codex, or another compatible UI with
the selected instructions and filesystem configuration already established.

The intended experience is:

xmd AGENTS.md#Implementor

The filename is not special. Existing document target selection chooses
Implementor; executing that target prepares and launches the session.

Delivery contract

Add one general Agent operation and its executable component:

Agent.launch(instructions, options)

<Session.Launch>
  ...explicitly prepared instructions...
</Session.Launch>

The component body is evaluated before launch, and only the resulting value
crosses the agent boundary as prepared instructions. Surrounding Markdown
remains human-facing output.

launch must:

• use the current lexical Agent and Session configuration;
• allocate or resolve one provider-native session identity without performing a
  model turn;
• establish the prepared instructions through a proven provider instruction
  channel before the person's first native turn;
• preserve the configured cwd, ordered additional directories, model,
  permissions, and environment without widening authority;
• retain provider-backed identity provenance: either the provider returns the
  identity, or a proven native adapter allocates it through a
  provider-supported client-supplied identity parameter;
• establish that no ACP owner remains before starting the native process,
  detaching one when present;
• spawn the native UI as a foreground child while XMD remains the supervising
  parent;
• suspend document execution until the native process exits;
• resume document execution after a successful native exit; and
• allow a later Prompt to reattach to the same durable provider session and
  retained history.

This is ownership transfer to the provider's native UI, not an XMD terminal
chat frontend. XMD does not proxy terminal turns, and native conversation
history remains provider-owned.

Identity and construction

A provider-native identity is never inferred from UUID shape or copied from an
unrelated ACP or ACPX identifier.

Two provenance forms are valid:

1. Provider-returned: a provider explicitly returns the native resume
   identity for an existing session.
2. Client-allocated: a proven native adapter supplies an XMD-allocated
   identity through a provider-supported input such as Claude Code's
   --session-id.

In the client-allocated form, XMD owns allocation but never conversation state.
The native process constructs and owns the provider session. Prepared
instructions may cross through an invocation-private restrictive file such as
Claude Code's --system-prompt-file; raw prepared text still appears in
neither argv nor environment.

Acceptance criteria

• xmd AGENTS.md#Implementor executes only the selected target; target
  discovery/help has no preparation, provider, or process side effects.
• The launched session receives exactly the explicitly rendered launch body.
  The whole document is not implicitly injected.
• Launch performs zero Prompt calls and zero model turns before the person's
  first native turn.
• A provider without a proven zero-turn instruction channel refuses before
  ownership transfer.
• Native identity carries provider-backed provenance and is never inferred,
  parsed, translated, or copied from an unrelated ACP identifier.
• Prepared instructions and secrets are absent from process arguments and
  environment variables. A private instruction-file path may appear in argv;
  its contents may not.
• Filesystem mappings preserve declared authority: read-only access never
  becomes writable, and access outside the declared cwd/directories is not
  added implicitly.
• ACP and the native UI never own one session concurrently. Native launch
  starts only after any ACP owner is detached or after XMD proves no ACP owner
  exists.
• XMD remains the parent process, forwards cancellation/signals, waits for the
  foreground child, reaps it, restores terminal state, and removes temporary
  instruction artifacts before provider teardown.
• A normal native exit succeeds and document execution continues. A nonzero or
  signaled exit fails the launch component with the native outcome.
• A later ACP Prompt reattaches to the same provider-native identity and
  retained history.
• The execution journal records prepared-context provenance and digests,
  provider/model/configuration, authority mappings, identity and its
  provenance, ownership transitions, launch metadata, and exit outcome.
  Secret-bearing text follows the existing journal redaction/encryption policy.
• Replay of a completed launch does not start the native UI again. Replay or
  retry of an incomplete launch retains the same identity and never silently
  substitutes another one.
• The core behavior is deterministic under the existing TestAgent
  infrastructure and a controlled native launcher. Author-facing component
  behavior is proven in executable Markdown; TypeScript remains for protocol,
  process, and real-provider seams the document cannot observe.
• A provider adapter earns support only through a real integration proving
  native construction/resume, first-turn availability of prepared
  instructions, retained identity, later ACP reattachment, exit handling, and
  teardown.

Initial implementation scope

The core API and component are provider-neutral. The first coherent delivery
may support one native provider adapter; each additional adapter independently
earns support through the same capability and integration contract.

This story owns:

• Agent.launch and Session.Launch;
• capability-checked native identity provenance, allocation, and resume command
  construction;
• foreground terminal-process supervision and ownership transitions;
• journal/replay semantics for the handoff; and
• ordinary native-launch support for the already specified Agent.AddDir /
  ACP additionalDirectories configuration needed by a role.

PR #518 supplies the provider-neutral foundation. Issues #519 and #520 validate
the first direct Claude path. Agent.AddDir remains open under this umbrella
and is deliberately outside that validation stack.

Out of scope

• an XMD-provided interactive chat loop;
• any bootstrap prompt or hidden model turn;
• automatic discovery or injection of nested AGENTS.md files;
• simultaneous interactive ownership by multiple sessions;
• mirroring every native UI event into the XMD journal;
• workflow role scheduling or mediated workflow-agent semantics; and
• claiming support for a provider whose native construction, resume,
  instruction installation, and later ACP reattachment have not been proven.

An explicit bootstrap turn for providers that cannot install native session
instructions remains a separate future extension in #514 and does not block
this story. Workflow-agent issues such as #302 retain their existing authority
contract and do not gain direct directory access through this work.

Architecture

The normative design is captured in
specs/native-agent-session-launch-spec.md on the implementation stack. The
2026-08-20 amendment accepts provider-backed client allocation through a proven
native adapter. The implementation plan freezes an acceptance/evidence matrix
from this contract before production work begins.