Status: Built Related: Executable.md ACP Client, Markdown Agents Vision, Workflow Workspace, native session launch story, future bootstrap prompts
Ordinary ACP prompts require the private acceptance barrier only when their adapter declares it. Native launch keeps its adapter-specific materialization requirements and asserted native identity checks; a standard ACP loading target is never a native handoff identity.
An executable document can prepare a coding-agent session and then place the user in that agent's native interactive UI. The document decides which rendered context the session receives; the host's Agent context determines its filesystem permissions. The provider owns the mapping from the logical XMD session to the durable native session and the command that resumes it.
The common repository entry point is an ordinary document target:
xmd AGENTS.md#ImplementorThe target executes deterministic preparation, establishes one durable agent session, releases XMD's ACP ownership of that session, and starts the provider's native UI. XMD remains the parent process and waits. Document execution resumes only after the native UI exits.
This is session construction followed by an ownership handoff. XMD does not become a chat frontend, proxy terminal input, or interpret the native UI's turns.
A session constructed that way is still a conversation, and a document can join
it afterwards. A <Session> or <Prompt> naming one attaches through ACP under
the identity the route already carries, so the same named session continues
where the native UI left off. Attachment is never conversion: the route stays
client-native, the coordinator remains the one live owner, and the
provider's own history remains authoritative for what was said.
# Repository Agents
## Implementor
The implementor makes changes according to the approved plan.
<Agent>
<Session name="implementor">
<Session.Launch>
You are the repository implementor. Follow the supplied role contract,
architecture, and approved plan.
<File path=".agents/implementor.md" />
<File path="architecture.md" />
<File path=".xmd/approved-plan.md" />
</Session.Launch>
</Session>
</Agent>
## Architect
The architect reviews settled structural invariants.
<Agent>
<Session name="architect">
<Session.Launch>
You are the repository architect. Apply the supplied role contract and
authoritative architecture.
<File path=".agents/architect.md" />
<File path="architecture.md" />
</Session.Launch>
</Session>
</Agent>The paragraphs outside Session.Launch remain documentation and rendered
output. Only the rendered body of Session.Launch becomes prepared agent
instructions. A file that exists in the repository is not selected merely
because the provider can read it.
Agent keeps provider selection separate from role identity. With no authored
agent name, the current/default-agent rule in the ACP Client specification
selects Claude Code, Codex, or another compatible agent without changing what
Implementor means.
Native Agent sessions own the shared lifetime and enforcement rules. This specification owns the launch interfaces, phase records, compatibility exceptions and provider proof requirements. The feature reuses these contracts unchanged:
- a static heading target is the role entry point, and sibling targets do not execute;
- document help discovers targets without executing authored effects;
- ordinary XMD components gather, parse, and transform preparation inputs;
Agentselects the coding agent lexically, and is the availability boundary for what it wraps;Sessionidentifies stateful continuity lexically;- under ordinary
xmd runACPX session resolution, the contextual cwd participates in the resolved logical session key; - the Agent provider belongs to
DocumentExecutionand finishes teardown before the document completes; - completed durable effects restore without contacting their external provider; and
- a missing or unresumable provider session fails rather than being replaced by transcript reconstruction.
No behavior depends on the filename AGENTS.md. Any executable document target
can launch a prepared native session.
The ACP Client specification owns the complete six-operation AgentApi, the
caller-facing launchAgentSession(instructions, options) operation, and the
shared LaunchOptions and SessionLaunchResult types. Native launch adds no
second Agent or Session hierarchy. Its launch-specific routed request is:
interface AgentLaunchRequest {
readonly instructions: string;
readonly agent: Agent;
readonly session?: string | Session;
readonly cwd: string;
readonly additionalDirectories: readonly string[];
readonly permissionMode: PermissionMode;
with(changes: {
instructions?: string;
agent?: Agent;
session?: string | Session;
}): AgentLaunchRequest;
}launchAgentSession(instructions, options) is the canonical operation and the
only owner of what a launch settles on: it reserves the terminal, normalizes
the request, mints its durable identity, retains every phase, and derives the
SessionLaunchResult. It is available anywhere inside a live document
expansion, including a repository function component, and refuses outside one.
The launch route on the Agent Api is the public surface, and it routes
rather than performs. What travels on it is one frozen, one-use
AgentLaunchRequest describing the launch; middleware may inspect it, narrow it
through with(), refuse by throwing, or delegate it, and what a handler returns
is discarded. Identity is object identity: a rebuilt look-alike, a superseded
parent, a foreign request, or a second delegation of the same leaf describes the
same ask and authorizes none of it.
The right to run and retain a phase never travels on that chain. The Agent package
delivers one AgentLaunchCoordinator directly to the provider factory it
installs, as an argument the factory closes over — there is no context holding one, no request
member carrying one, and no reader for one. The coordinator validates the routed
request and the provider's installation generation, runs each absent phase once,
cross-checks the returned record against the request, retains it under the
component invocation identity Core issued the launching element before the next
live effect, and derives the result. A provider supplies the work; it never
supplies the verdict.
launcher is a stable provider-assigned adapter identity such as claude or
codex, not an executable path. The result describes a successful normal exit;
nonzero exit, signal, and cancellation do not produce it. It contains only
filtered stable evidence and exposes no process handle, ACP client, credential,
raw environment, or executable argument vector.
launchAgentSession() is distinct from prompt():
prompt()performs one model turn through ACP and returns the agent response;launchAgentSession()returns no agent response at all. It transfers the session to a native UI and returns only after that UI exits. It performs no model turn of its own except the one materialization turn described below, which an adapter may require to make a freshly created conversation resumable and which is never the launch's return value.
The base Agent.launch(request) routing handler fails. A provider must install
the route explicitly; availability of agent(), session(), and prompt()
does not imply native-launch support.
Session.Launch renders its body before invoking launchAgentSession(). An
empty body is valid and prepares no additional instructions. Its optional
agent and session props mirror Prompt; omitted props use lexical Agent
and Session configuration. Omitting the name prop from an enclosing
<Agent> uses the current/default-agent rule from the ACP Client specification;
launch defines no default of its own.
The Agent package hands the provider a normalized request containing:
agent
logical session
prepared instructions
primary cwd
ordered additional directories (the empty list in V1)
effective permission configuration
source position and expansion identity
The provider applies the instructions as a provider-native session, system, or developer instruction layer before the native UI accepts its first user turn. It does not send the instructions as a user message and does not invoke a model.
A provider that cannot establish instructions without a model turn refuses the launch. V1 has no bootstrap-prompt fallback. An explicit, observable bootstrap mode is a separate future feature tracked by issue #514.
Prepared instructions are the current attachment's instruction layer. A relaunch with the same layer resumes the existing provider session and does not append another copy to conversation history.
A relaunch with a different layer reconciles according to provider capability:
- a provider may replace the layer in place only when it can preserve the same
provider-native identity and all provider-native conversation history without
invoking a model, and reports
replaced; and - otherwise the provider refuses with
instructions-refusedbefore detaching ACP ownership or starting a native process.
V1 discards no persistent provider state. There is no third branch in which an
"unused" session shell is deleted and remade: no observation available on this
side distinguishes a session that was never used from one a native UI has been
in for an hour, so no launch path sends a discard. installed, resumed and
replaced are the whole of instructionReconciliation. What this costs is a
refusal where a recreation would have been convenient; what it buys is that no
launch destroys a conversation XMD does not own and cannot see.
An empty cached transcript is not proof that a retained or previously handed-off session has no conversation. Native UI turns are provider-owned and need not be mirrored into ACPX or XMD state. Relaunch therefore never silently keeps a stale layer, discards unobserved native history, substitutes a new provider session for retained continuity, or performs a bootstrap turn. A materialization turn is not a bootstrap turn: it runs only for a conversation this launch just created, carries no authored content, and never runs against a retained one.
The prepared text and filesystem permissions are different capabilities:
- the contextual cwd determines what the V1 native agent can access;
- prepared instructions determine text supplied to the model as instructions;
- neither one implies the other; and
- unreferenced repository files are not injected as text.
Agent.AddDir is not an existing semantic this launch consumes. The ACP Client
specification defines the current contract: no directory-registration component
exists, and every V1 launch carries the explicit empty ordered
additionalDirectories list. A later directory feature is a prerequisite to
launching with another root and must define ordering and access modes before an
adapter can map one. Until then the launcher neither receives nor grants one.
The <Session> that owns the conversation may specify its model and effort
level. Native launch adds no launch-only selector. AgentLaunchRequest.with()
may route another whole Session as it routes instructions or agent; no separate
configuration member travels through middleware.
The final routed Session decides configuration. An authentic configured use is applied and verified before handoff; another authentic use applies its own settings; and a raw Session, name or absence follows the unconfigured launch contract with no configuration read. A copied or foreign value claiming to be configured refuses before the provider prepares anything.
The configured use remains valid only while the provider-installation owner
that issued it is live. The launch provider reads it through the coordinator
delivered directly to that installation; a same-named Context, sibling run,
retained post-teardown value or another loaded Agent copy cannot supply that
owner. Provider teardown invalidates lookup before a later launch can prepare
anything. Finishing a session setup and its registration state do not participate in
launch admission: AgentLaunchRequest remains the launch's one-use identity.
Raw prepared instructions never appear in process arguments or environment variables. A provider uses its session API or an invocation-private file with restrictive permissions and removes any temporary during cleanup.
The retained Claude adapter confirms the backend conversation on response
_meta.agentSessionId before ACP session creation or reattachment succeeds.
This confirmation does not change who allocated the native identity: Claude's
native construction route remains explicitly client-allocated. Metadata presence
never chooses a construction route. A resumed Query confirms the exact retained
identity after loading history; it neither replaces the conversation nor rebuilds
its transcript.
Four identities remain distinct:
logical XMD session key which session was requested
construction route how it was first constructed
provider-native session identity which provider conversation exists
ACPX record/session identity how the ACP client arranges attachment
An identity is chosen in one of two ways, and the prepared record says which.
type IdentityProvenance = "provider-returned" | "client-allocated";provider-returned means the provider created the session and reported what it
is called; client-allocated means XMD chose the identity before the provider
existed and supplied it unchanged. New records always write provenance. A
released record without the member reads only as provider-returned, because
client allocation did not exist in that format — the one compatibility
inference this contract makes, and it infers only the weaker claim. Unknown
provenance refuses.
The identity itself comes from the adapter. What shape a provider-native identity takes and what that provider will accept is knowledge about that provider, so an adapter that names its own sessions allocates one, and the provider decides only whether a freshly allocated candidate wins publication. Allocation happens while coordinator ownership is held. An authored string, a logical XMD session key, an ACP session ID, an ACPX record ID, process output, or a value that merely looks like a UUID never supplies or replaces it.
Where the provider returns the identity, XMD does not infer that an ACP session ID is accepted by a native CLI merely because both values are strings or UUIDs.
What an adapter must prove before it is advertised follows its identity provenance, because the two constructions make different claims.
A provider-returned adapter proves all seven of the following:
- by the time the launch hands over, durable state the native UI can resume exists — either because creation alone materialized it, or because the adapter's declared materialization turn did;
- its returned native ID names that exact state;
- prepared instructions are effective on the first native user turn without a bootstrap model turn in front of them, and a materialization turn that preceded that user turn neither supplied nor consumed them;
- cwd and permissions survive the handoff without being widened;
- the ACP owner can release the session before native attachment;
- the native process can exit without deleting the resumable session; and
- ACP can later reattach to the same session if document execution uses it again.
A client-allocated adapter proves less, because it asks less: no ACP session is created, so there is nothing for ACP and a native process to agree about, and claims 1, 2, 5 and 7 are about a handoff it does not make. It creates the session directly and resumes it by the same name, and what it proves is exactly that:
- the launch that creates the session has its identity allocated by the adapter, inside ownership and before any process exists, and nothing else supplies or replaces it;
- the native process creates that exact conversation from a private
mode-
0600instruction file, with the text in neither argv nor environment; - those prepared instructions are effective on the first native user turn, with no bootstrap model turn in front of them;
- a later independent invocation resumes the same identity and reaches the history the first one made, allocating nothing and never falling back to creating;
- a session left without a conversation turn behaves the same way — the same identity comes back, or the provider refuses that exact identity and XMD fails closed;
- every process the launch started is gone when it ends, and so is the private instruction file and the directory holding it; and
- no path substitutes an identity, converts a construction route, or creates a replacement conversation.
Claim 6 is about what a launch is not allowed to outlive, and it is deliberately
narrow. The construction route and the agent_session_launch records stay:
they are how the next invocation knows which conversation this session is, and
removing them is what claim 4 forbids. A proof that removes them is cleaning up
after itself, which is a different act — see Testing.
Both lists are proven against an installed CLI and neither is proven by inspection. An adapter proves the list its provenance names, and nothing is advertised on the strength of the other one.
For the built-in adapters, the native commands are:
claude --session-id <native-session-id> --system-prompt-file <private-file>
claude --resume <native-session-id>
codex resume <native-session-id>
A conversation continues quietly on the executable the current environment selects. The provider must positively confirm the retained native identity before work that requires it. A missing or different assertion refuses without creating a replacement conversation. Executable version and digest do not decide admission. Existing routes and journal history remain unchanged; normal continuation creates no new version-history record.
Fresh production construction uses the released unbound V1 route forms. Client-native construction retains its native identity, client-allocation provenance, launcher and instruction digest. No current version or digest is persisted for compatibility reporting.
Released records may still carry the binding an earlier release recorded:
interface ExecutableBuildBindingV1 {
readonly schema: "executable-build.v1";
readonly reportedVersion: string;
readonly executableDigest: { readonly algorithm: "sha256"; readonly value: string };
}Released V1/V2/V3 routes and prepared journals remain readable and unchanged. Before incomplete live work, compare the original provider, identity, provenance, launcher, instructions and policy. When both original accounts contain executable bindings, those original bindings must agree. A missing binding alone is not disagreement. No original binding is compared with today's executable for admission. A new phase referring to an existing bound route carries its original binding only where required to preserve that agreement.
Selection comes first. A carried adapter's executable is selected by the host
once — Claude's nonempty CLAUDE_CODE_EXECUTABLE, otherwise claude on the
host PATH; Codex's nonempty CODEX_PATH, otherwise codex on the host PATH;
relative selections against the host execution directory, and a bad explicit
choice with no PATH fallback. The host selector resolves a canonical regular
executable and verifies that it can start; its joined, output-suppressed
--version child is a launchability check, and its version text and exit
status decide nothing. A missing or unlaunchable selection is an availability
failure. A host that makes no selection runs the adapter's declared launcher
name, and a custom native adapter keeps its declared command.
The selected path is live only. It exists only in the operation that selected
it. Native creation and resume replace the adapter command's first argv member
with it, and the matching ACP child receives it through its adapter's variable
— CLAUDE_CODE_EXECUTABLE or CODEX_PATH — in a transient child-process
environment. The integrity-pinned ACPX 0.22.0 source closure supplies the
child-only environment seam. Its local first-turn materialization barrier
remains required independently of that released capability. The path enters no
route, journal, ACPX session option or record, public result, diagnostic,
process.env, or provider partition that outlives its last handle.
A session established before any build was recorded is legacy-unbound. Its route directly supplies the native identity, allocation provenance, instruction digest and launcher, so no historical build is needed for exact attachment or native preflight. It continues under the same selection and confirmation as any other session, and no binding is invented for it.
Native launch and client-native ACP attachment are separate trusted-host choices, and neither is inferred from the other or from an adapter's shape. An adapter may be proven to hand a session to a native UI without being proven to join that conversation afterwards.
claude is advertised for both. Its attachment claim was proven by
packages/acp/src/ClaudeNativeToAcp.test.md: one native turn planted a random
marker, a checked-in marker-free ACP <Prompt> recovered it under the same
identity, and an independent route naming an absent identity refused before a
turn without creating history in its place. That same attachment is how a
client-native session's identity is positively confirmed around a native
handoff; a host that does not advertise it cannot hand such a session over.
Those command shapes are adapter implementation details, not authored document values. A custom ACP agent without a declared native launcher fails with an unsupported-capability error before XMD releases its ACP session.
Knowing a command shape is not the same as being launch-capable. Advertisement
is separate: an adapter becomes launch-capable once XMD's integration with it is
proven by an opt-in proof of the claims its provenance names. Until then
<Session.Launch> refuses that agent before anything of the session moves —
before a provider-returned adapter's ACP session is released, and before a
client-allocated adapter allocates an identity or writes a private file. That is
the failure this contract asks for rather than a hopeful spawn.
claude is advertised. Its client-allocated claims were proven through the
production CLI against Claude Code 2.1.241 on macOS arm64.
codex is advertised for native launch, from the complete provider-returned
proof through the production CLI against codex-cli 0.153.2 on macOS arm64,
with the vendored @agentclientprotocol/codex-acp 1.6.2 snapshot that asserts
the App Server thread on the response _meta.
Recorded CLI, adapter and host versions describe the checks that ran. They are evidence, not an allowlist or a requirement to repeat certification for every release. The existing live documents remain opt-in integration regressions for initial use, original-context continuity and native handoff where supported. Actual protocol capabilities and provider-native identity assertions remain required.
The opt-in proofs may still measure a version explicitly. Their Codex parser
recognizes one canonical codex-cli x.y.z line and nothing else: output that is
bare (codex-cli), malformed, or carries a second line is no answer. The
product word travels with the number because a bare semver from another tool
compares equal to one from this one. Normal work reads no version at all.
Every later native launch, attachment or incomplete launch replay selects the current executable and positively confirms the retained native identity before a native process, a configuration or a turn, quietly: nothing about the executable's version is compared or reported. This is the native launch and attachment contract, and it is the same policy ordinary and held ACP continuation follow; see ACP client. Complete means through to history: the gate closes only when XMD rejoins that same conversation over ACP afterwards and reads the native turn back out of it, because a conversation that cannot be rejoined is not the one this contract says was handed over.
Reaching it costs one model turn, and only Codex owes it. The App Server writes
a thread's rollout at that thread's first turn and codex resume <id> reads
rollouts, so a conversation ACP created and nothing has spoken in is refused by
name. codex-materialization.v1 is the single XMD-owned turn that closes that
gap for a freshly created conversation, and it is not the author-supplied
bootstrap of #514: its bytes are fixed by the adapter, it carries no authored
content, path, identity or environment, it refuses on any tool call, and an
already-resumable conversation receives none. Reading the ACP session id as the
native identity remains exactly the substitution the provider-returned route
exists to refuse.
Given xmd AGENTS.md#Implementor:
- XMD resolves the selector to one exact canonical document target.
- The CLI installs the selected Agent provider and native process launcher.
- Target projection excludes sibling roles.
- XMD expands the target and renders
Session.Launchcontent completely. - File reads, captures, parsing, and deterministic evaluation finish or fail.
Session.Launchtakes the run's foreground-terminal lease. A host with no foreground terminal refuses here — before an agent is resolved, so learning that this invocation cannot launch anything costs no availability probe.- The host flushes what that terminal has pending, so the native UI does not open over half-written output.
- The provider resolves the logical Agent and Session against the contextual cwd, and takes exclusive ownership of that session.
Steps 9 to 12 are where the two provenances part, because they are about a session one of them constructs through ACP and the other does not.
Provider-returned. ACP owns the session first and has to hand it over, and where the adapter owes a materialization turn the identity does not exist until that turn is accepted:
-
The current executable is selected, and the
acp-firstroute is published or adopted — before the provider constructs anything, so the route a later run is held to already exists when there is a session to hold it to. A fresh route is unbound V1; an existing route is never rewritten. An executable that cannot run ends the launch here with nothing durable written about a session. -
The provider creates or resumes the durable provider session through ACPX, applying the prepared instruction layer and contextual cwd configuration. An already-established session has an identity of its own: the provider reopens its exact retained loading target with
expectedAgentSessionIdequal to the retained native assertion, under exclusive ownership and before any configuration or handoff, and spends no turn. A record with no retained assertion, or a live load that is missing or differing, refuses withidentity-unavailable. A fresh session on an adapter that owes a materialization turn does not: creation yields provisional occupancy and asserts no native identity at all. -
XMD commits the prepared launch record before releasing ownership. For an already-existing session it carries the asserted identity and no materialization plan, and no turn is spent. For a fresh one it carries an empty
nativeSessionIdand the exact materialization plan this launch owes, and no executable binding.Once
preparedis durable — and only then — the fixed materialization turn is announced on the reserved terminal and executed. It is retained as an ordinaryagent_promptfirst and asmaterializedsecond, because the prompt says the turn was spent and the phase says the launch may go on. Only the backend's explicit acceptance of that turn promotes the provider record and asserts the native identity. A turn that fails stops the launch here, before any detach and before any native process exists. -
Only after a successful materialization — or immediately, where none was owed — the provider closes or detaches the ACP session and waits for that owner to terminate, and XMD commits
detached.
Client-allocated. Nothing is created through ACP at all, so there is no owner to release — what has to be settled first is which conversation this is:
- The provider reads both durable accounts under ownership and refuses rather than converting: a session ACP already established, or a route that disagrees about the instruction layer or the launcher, ends the launch here.
- A launcher without an advertised confirmation capability — client-native
ACP attachment — refuses with
unsupported-capabilitybefore allocation or handoff; exit status is never substituted for confirmation. The current executable is selected before an identity is made, so one that cannot run ends the launch before anything durable is written. Nothing about its version is read or reported, and a legacy unbound route continues the same way and gains no binding. Whether an identity is needed at all is decided next. An existing compatibleclient-nativeroute already names this conversation, so its retained identity is adopted and nothing is allocated — a second candidate for a conversation that already exists is a value with nowhere to go. That established conversation is positively confirmed now: its exact native identity is loaded over ACP — strictly, withexpectedAgentSessionId, when an ACP record exists; with no record, by exactresumeSessionIdand a required returned assertion — with no configuration or turn, and the ACP close is joined before preparation is retained. Only where no route names it yet does the adapter allocate one, inside ownership and before any process exists; nothing else supplies or replaces it. - A launch that allocated publishes the unbound V1
client-nativeroute create-once, and what it publishes against is authoritative — whoever published first described the session that exists. Four outcomes, and no other:- this launch's own candidate won —
created; - a compatible
client-nativeroute won — its identity is adopted, no replacement is allocated, and the launch isresumedunder it; - an
acp-firstroute won — the session already has an identity of its own, so the launch refuses withidentity-unavailable, converting nothing; - a
client-nativeroute disagreeing about the instruction layer or the launcher won — neither account repairs the other, so the launch refuses the same way. Acreatedorresumedrecord is built from the compatible winning route rather than from this launch's candidate, so the two accounts agree by construction rather than by comparison. A refusal is not: it prepared no identity, so it retains the failure the authoritative winner produced without mirroring that route's identity or provenance — no session id, and the weaker provenance claim, because nobody chose one. It is retained atpreparedand reaches no private file, no detach and no spawn.
- this launch's own candidate won —
- The prepared instructions are written to a private mode-
0600file. Detach still happens as a phase — it is the point after which a spawn may happen — and succeeds trivially, because no ACP session was ever open.
From there both rejoin:
- The provider spawns the native UI as an interactive child with the root terminal inherited — resuming, for a provider-returned adapter, the identity its materialization turn asserted, or the one an already-existing session already had; and for a client-allocated one creating it under the allocated identity from the private file, or resuming it by the same name when the route already named it. No resume reaches this step without a positive assertion of its exact identity from this invocation, and ACP's close is joined first; a close that failed stops the handoff and retains unresolved ownership.
Session.Launchsuspends while the child runs.- The child handles prompts, tools, permission dialogs, rendering, and native transcript persistence directly.
- When the child exits, XMD records its terminal outcome, removes the private file and its directory while ownership is still held, and releases the foreground-terminal lease. A fresh client-allocated creation is confirmed after the child has fully joined and before the launch acknowledges success or releases the coordinator: the allocated identity is loaded over ACP, its returned assertion must equal it, and the ACP close is joined. Exit status is retained as process evidence and never as identity. A failed or absent confirmation fails this launch and never creates again. Cancellation joins the child and propagates; it starts no confirmation during teardown. The route and the retained phases stay: they are what the next invocation resumes from.
- Later Agent work depends on the route again. On an
acp-firstsession it lazily reattaches through ACP to the same provider session. On aclient-nativeroute advertised for attachment,<Session>and<Prompt>follow ACP attachment on a bound route below and join the same provider conversation, bound or legacy unbound. An unavailable attachment capability refuses before a turn and creates no substitute conversation. - Execution continues after
Session.Launchin its enclosing document flow.
An enclosing <Agent> or <Session> resolves by its own contract, before
anything inside it runs, so a document that wraps a launch has already reached
its provider by step 6. That is an ordinary earlier effect: what step 6 stands
in front of is the launch, and no session ownership transfers before it.
XMD spawns and waits; it does not replace itself with exec. Remaining the
parent preserves document cancellation, child-liveness settlement, exit-status
ownership, and continuation after the UI closes.
A <Session> or <Prompt> naming a session a native process constructed runs
this sequence, and every step happens while the coordinator holds the session:
- Resolve the session without creating a runtime or probing availability, so nothing touches the provider session before the route has been read.
- Acquire the same machine coordinator, non-blockingly.
- Read and classify the route.
acp-firstfollows the existing ACP path; a session with no route at all is constructed asacp-firsthere, which is what makes a nested client-native launch refuse afterwards. - An agent this host has not advertised for attachment refuses with
unsupported-capability. A legacy unbound route attaches like a bound one. - Select the current executable. One that cannot run is an availability failure; nothing about its version is read or reported.
- Inspect any retained ACP arrangement without creating one: absence may enter exact resume, because exact resume is the operation being attempted; a record must assert this route's identity and nothing else.
- Select the live runtime for
(resolved agent command, selected environment)and give the selected path only to that runtime's child environment. - Ensure with
resumeSessionIdequal to the route's identity, and withexpectedAgentSessionIdequal to it when an ACP record exists. A first attachment without a record carries no expectation that presupposes one and sends no configuration or turn. - Require the provider's canonical assertion to equal it. Absence or disagreement closes the handle and refuses before a turn; a refused first arrangement is left asserting nothing, so a later exact retry is not blocked.
- Only then return a
Session, or start the subscribed turn.
Runtime partitions are scope-owned. Different selected environments never share an ACP child, a managed handle remembers the partition that created it, and every turn, close, detach, cancellation and stale-handle release goes through that same partition. When a bound partition's last handle closes it is removed and torn down; a later attachment selects again and builds another.
A partition is kept exactly as long as something is standing on it, and two different things can be: a handle nobody has closed, and work that has claimed the runtime and not yet produced one. An ensure in flight is the second kind. Eviction requires both to be zero — a partition removed while either is nonzero is one a concurrent operation rebuilds, which is a second child for a build the first is still talking to.
Electing a partition is one step. Everything that suspends — resolving the directory an Agent runs in among it — happens first, so an operation arriving to a map that already names its partition crosses that suspension too rather than answering from a stale read. What follows does not suspend at all: the map is read, an entry is published already claimed if this is the first work to want one, and the ensure is started. Publishing an entry and claiming it across a suspension would leave it in the map standing on nothing, which a sibling giving up its own claim would evict — and the caller would then hold a runtime the map no longer names while the next operation built a second child for the same build.
That, and what follows, is how items 8, 10 and 14 of the structural checklist are met rather than a further invariant beside them:
- Claimed work that produced no handle releases its claim. The runtime is built before the ensure that would use it, so a rejection would otherwise strand a partition holding a live path for work that never happened. The selected command, adapter command and environment determine the partition. Identical executable bytes selected through different paths can therefore use different partitions. Success transfers the claim into ownership of the handle in one step. A moment where neither count is held is a moment another operation could evict.
- Cancellation observes the ensure it started, and settles it before
quiescence. Starting an ensure is not the same as owning it: the call runs
whether or not anybody is still waiting, so a cancellation is not the end of
the story. The claim and the answer are settled by scope-owned cleanup rather
than by a
catch, which a cancellation does not run at all, and that cleanup is registered before the claim is taken and before the call is made — a cancellation delivered while the call is still on the stack is exactly the case where something is in flight and nobody is left to observe it. A cancelled operation therefore waits for the answer: a rejection releases the claim, and a handle is adopted, closed through the runtime that made it, and only then does the operation acknowledge quiescence. A close that fails there keeps the handle, keeps the partition, withholds quiescence and leaves both for teardown, exactly as a failed close does anywhere else. - Every handle-producing path keeps one account. From the moment ensure returns — on an attachment and on a provider-returned launch alike — the handle belongs to this provider and is bound to its creating runtime, before the identity comparison, before the host is asked to retain the session, and before status is read. Each of those can fail, and a handle only a caller- facing map knows about is one teardown cannot close through the runtime that made it.
- Quiescence consults that account. A handle whose validation failed never became a usable session, so nothing a caller can reach names it — and it is still a live thing this owner started. An operation acknowledges quiescence only when no unreleased handle for the session remains, whether or not it ever became usable.
- A settled close leaves only the session's name behind. What a returned
Sessionvalue still resolves to is session metadata; the handle and the runtime that made it are gone from everything this provider can reach. A runtime carries the transient child environment, and therefore the canonical executable path, so a released session that still named one would be that path outliving the operation it was observed for. The next use of that value re-ensures, which reattaches to whatever holds the session now. - A close that failed released nothing. It does not decrement the partition, evict it, forget the handle, detach the session, or let the operation acknowledge quiescence. The refusal is still raised; what differs is that this scope still has something to answer for, and the handle stays reachable for teardown.
- Teardown attempts every owned close, does the release bookkeeping only after a close settles, and reports what it could not settle rather than claiming that partition finished.
One session has one active owner. Its states are:
ACP-owned -> detaching -> native-UI-owned -> detached -> ACP-owned
The transition to native ownership occurs only after ACP release completes. The provider never runs ACP prompts against a native-owned session. A launch holds the session's ownership until the native child exits.
Ownership is answered by a plain AgentSessionCoordinator the host builds and
passes directly into the provider's dependencies. It is deliberately not a
contextual Api: ownership is a security decision, and one document middleware
could replace is not one. Its key is natural rather than authored:
provider = acpx
agent = the resolved agent command
sessionKey = the resolved xmd:v1 session key
A conversation a trusted host holds open is the one qualification. Its key and its construction route keep the provider and resolved command of the history's initial configuration record, with the session key its Prompt records name, for as long as the conversation lasts; the command that executes it, and the executable selected for it, are today's (acp-client-spec.md §Sessions: ownership, routes and attachment). One logical conversation therefore keeps one owner when its adapter command changes, an earlier owner of the original tuple still refuses a changed-command contender, and a tombstone on that tuple still requires recovery. The coordinator interface, the ownership record and force recovery are unchanged. Every other session and launch uses the natural key above.
Every operation that could act on an advertised session enters it first — establishing the session, subscribing a prompt stream, attaching to a session a native process constructed, launching, and resuming an incomplete launch. Coverage follows the agent's capability, not the operation, and not which mechanism constructed the session. Resolving an agent and placing a session own nothing, because there is no session yet to own. An agent no adapter is advertised for keeps ordinary ACP behavior on every host.
Acquisition never waits. A native UI may stay open for hours, and a caller that
queued would hold the reader's terminal while offering no way to reach the owner
it waits for. A contending launch retains session-busy and performs no ACP
ensure, detach, or spawn; session and prompt work raises the corresponding typed
failure instead of manufacturing a launch record.
The body of an acquisition receives a one-use quiesced() acknowledgement. What
it acknowledges is not "I finished" but "nothing I started can still touch this
session" — so a provider acknowledges it exactly when it no longer holds a
usable handle for that session. A handoff whose detach failed, or a session
prepared and never handed over, does not acknowledge, and the durable record
stays active.
An active record is a recovery tombstone. A crash releases the kernel lock but
not the record, and nothing observable afterwards distinguishes a session whose
owner died mid-turn from one it left cleanly — so the next owner receives
session-recovery-required rather than inferring safety from a pid, an elapsed
time, an empty transcript, or the lock being free. Explicit operator recovery
accepts this uncertainty without representing it as quiescence.
The Deno and compiled hosts combine three things a single one of which would not
be enough: a process-local occupancy table, one non-blocking advisory lock, and
an ownership record atomically replaced and durably flushed — active before any
provider work, idle only after quiesced() and before unlock. They live in a
machine-wide namespace, because two processes resolving different roots would
each hold "the" session:
~/.acpx/xmd-native-sessions/v1/
leases/<sha256-of-canonical-key>.lease
ownership/<same-digest>.json
routes/<same-digest>.json
Directories are 0700 and files 0600; lease sidecars are never unlinked. The
record has the single current shape described below. Missing or extra members
refuse rather than read partially; ownership has no format discriminator.
It holds no instructions, credential, cwd, executable path, argv, environment,
transcript, or temporary path — the digest is the only name in the namespace.
Node and Bun build no coordinator. Neither runtime exposes a cross-process
advisory lock, and neither emulates one: a pid, heartbeat, or stale-file timeout
calls a paused process dead and admits two owners. So every advertised
session, prompt, launch and incomplete replay refuses there with
unsupported-capability, before contacting an agent, while read-only resolution
and non-advertised ACP work are unaffected. An advertised agent whose adapter
carries an executable binding also requires a route store; a host without one
refuses before any provider effect, whichever side names the session. No executable
observer is needed. An adapter that carries no binding keeps its ordinary
behavior without those dependencies.
xmd session ownership --key-digest D --json
xmd session ownership --provider P --agent-command A --session-key K --json
xmd session recover --key-digest D --expect R --force --jsonD and R are lowercase SHA-256 digests. The triple form hashes the exact
provider, already resolved configured agent command and logical session key;
it never resolves an alias or contacts an agent. Inspection reads at most 64KiB
of one exact record, decodes strict UTF-8 and validates the complete schema and
key. Its revision hashes the exact bytes, including whitespace and newline.
It creates no directory or lease, probes no lock and makes no liveness assertion.
Recovery requires the digest form, the inspected byte revision and explicit
--force. Under the shared nonblocking lock it rereads the record. Busy, missing,
invalid, idle and stale-expectation records refuse. Only an active record with
matching bytes can become idle/forced. The persistent lease inode is never
removed. A forced release neither cancels a live owner nor sends, resends,
initializes, closes or kills provider work. It changes no route, session identity,
build binding, journal or prior outcome.
Ownership has one current unversioned shape with exactly keyDigest, state,
ownerKind, operationId, release and lastForcedRecovery. Active requires
release none; idle requires quiesced or forced. The latest-force member is
null before any force. A force requires a non-null object containing only a
fresh UUID recoveryId, abandonedOwnerKind, abandonedOperationId, the matched
expectedRevision, backendQuiescenceProved:false and
interruptedOutcome:"unknown". A forced idle record retains the abandoned owner
in its outer fields. Ordinary subsequent ownership preserves this object,
writes its own active owner with release none, and writes idle/quiesced only
on genuine acknowledgement. Later force replaces the latest summary.
The prerelease persistence policy amends this shape in place. There is no ownership schema discriminator, historical-format reader, migration or upgrade. Missing fields, extra fields and obsolete version-tagged records refuse unchanged.
All valued options accept separate or --name=value spelling. Mixing digest
and triple, missing or empty values, duplicate or unknown options, positional
extras and values on --force or --json refuse. Inspection accepts no force or
expectation; recovery accepts no triple. There is no configurable root, path,
listing, history, provider selection or plugin option. session --help,
session ownership --help and session recover --help exit0 without capability
access. Node and Bun refuse inspection and recovery as unsupported.
Success exits0. Refusal, grammar and persistence failures exit1 with safe stderr.
JSON mode emits one closed object and newline: inspection uses
agent-session-ownership-inspection with digest, recordRevision and record;
force uses agent-session-force-recovery with digest, previousRecordRevision,
recordRevision, recoveryId, release forced, backendQuiescenceProved false,
interruptedOutcome unknown and providerRequestSent false. Errors use
agent-session-ownership-error, code and safe message, a validated digest
when available, and applied unknown only for publication uncertainty. Human
output states the same distinction between forced release and proven quiescence.
Publication exclusively creates a fresh UUID staging file, writes it whole, syncs and closes it, atomically replaces the record, then syncs the directory before success. Pending I/O is joined before releasing resources or occupancy. Before rename, cancellation retains the active record and removes only its own staging file. A rename already started settles while locked, and a successful late replacement is directory-synced and retained. Failures after replacement may leave publication UNKNOWN; neither rollback nor automatic repeat is allowed. A new inspection observes current state and cannot prove that an earlier command completed. Another operator action compares the current bytes explicitly.
Ownership and construction answer different questions, and this contract keeps them apart:
construction route: how this logical session was first constructed
session coordinator: who may act on it now
The coordinator remains the one live owner and owns crash behavior. A route grants no right to ensure, prompt, detach, spawn or accept history. It says only which kind of thing this session is, so a later operation cannot quietly treat a conversation that already exists as one it may name.
Three schemas are readable: released V1, bound client-native V2 and bound ACP-first V3. The exact V1 record is:
type AgentSessionRouteV1 =
| {
schema: "session-route.v1";
route: "acp-first";
provider: string;
agent: string;
sessionKey: string;
}
| {
schema: "session-route.v1";
route: "client-native";
provider: string;
agent: string;
sessionKey: string;
nativeSessionId: string;
identityProvenance: "client-allocated";
instructionsDigest: string;
launcher: string;
};V2 exists only for client-native, and adds the one fact V1 never had. Earlier
releases published it; fresh construction no longer does, and a V2 record is
read exactly and never rewritten:
interface AgentSessionRouteV2 {
schema: "session-route.v2";
route: "client-native";
provider: string;
agent: string;
sessionKey: string;
nativeSessionId: string;
identityProvenance: "client-allocated";
instructionsDigest: string;
launcher: string;
executableBinding: ExecutableBuildBindingV1;
}ACP-first construction an earlier release bound to a build is V3, and only V3; fresh construction publishes the unbound V1 form instead:
interface AgentSessionRouteV3 {
schema: "session-route.v3";
route: "acp-first";
provider: string;
agent: string;
sessionKey: string;
executableBinding: ExecutableBuildBindingV1;
}It carries the binding and nothing more. The other members of V2 describe an identity XMD chose and a layer it wrote a file for, and neither is a fact about a session the provider named — so a V3 route says how the session was constructed and which build an earlier release recorded constructing it.
Each bound schema admits only its own construction: a V2 record is
client-native and a V3 record is acp-first, and the two pairings do not
cross. New construction of either kind publishes the unbound V1 form and observes
nothing; V2 and V3 records come only from earlier releases. Serialization
preserves the schema it was given, so nothing here upgrades or downgrades a
route.
Every member of all three schemas is exact. A path, adapter command, environment, argv, instruction text, credential, transcript, process fact or temporary path is not a member, and a record carrying one is refused rather than read partially. A binding beside a V1 record is such a member, which is what keeps a V1 record from being read as a bound one. So are missing, malformed, unknown-schema, moved and natural-key-mismatched records. Only a file that is not there means the session has not been constructed yet.
A V1 route of either kind is legacy-unbound, and is never overwritten,
supplemented or upgraded. A V1 client-native route directly supplies the
native identity, client allocation provenance, instruction digest and launcher,
so it continues through native resume and ACP attachment under the same
selection and positive confirmation as a bound one. A V1 acp-first route has
no native identity itself: its conversation is located by the exact retained
ACP loading target and record placement, and its native assertion comes from
the acknowledged host or history account, or the promoted provider record in
the pre-commit window. Missing both a usable locator and the required native
assertion is a real refusal; the absence of an old version or digest alone is
not. Unknown schemas and corrupt records remain rejected.
The route shares the coordinator's namespace, natural key and digest, so one
session names one lease, one ownership record and one route. The route directory
is 0700 and records are 0600. Publication is durably flushed and atomically
create-if-absent: the loser of a race reads and adopts the winner, and never
overwrites, deletes, converts or partially reads it.
Reconciliation happens while ownership is held, before any provider construction effect:
- a new
session()publishes nothing. It names the session — validating the agent and where the session will live — and constructs nothing, so the first operation that consumes that request is what chooses the route. Asession()on a session that already exists reconciles its route eagerly, as it always has; - the first subscribed prompt on a new session publishes or adopts
acp-firstbefore ACP runtime creation,ensureSession()or a turn, and a turn that fails, is interrupted, or is never accepted by the backend afterwards leaves that route standing: provider state may exist before the caller observed the failure, and preserving the route is what stops that uncertainty from later being reclassified. Anacp-firstroute by itself is not creation; - a launch by an adapter that names its own sessions reads both the route and
existing durable ACPX state; existing state publishes or adopts
acp-first, and otherwise the adapter allocates a candidate and publishesclient-native; - a launch that adopts
acp-firstretainsidentity-unavailableatprepared, before allocation, private-file creation, detach or spawn; - a
session()or subscribed prompt that meets aclient-nativeroute, bound or legacy unbound, follows ACP attachment on a bound route, including advertisement and canonical assertion checks. A refusal there raises the provider's typed error and retains no launch failure, because no launch was asked for.
The resolved agent command is carried from session resolution through the coordinator key, the route key and provider work. It is never resolved a second time inside ownership, because a registry free to answer differently would name a different session than the one this operation prepared.
V1 holds the foreground-terminal lease for the CLI execution. Two launches cannot concurrently own that terminal, even when they name different sessions. Sequential launches are ordinary composition.
Cancellation interrupts the native interactive process, establishes that it can no longer execute or hold the foreground terminal, restores that terminal's state, and runs every provider finalizer. A process that ignores the initial interruption is terminated according to the host process adapter's bounded shutdown policy. The adapter attempts to collect the native exit status, but a runtime-retained defunct PID or a lost exit event is not live process ownership. After a fatal signal was accepted, or the process was already absent, bounded settlement may release the runtime handle without waiting for signal-zero reachability to disappear. XMD never continues the document while the child remains live.
Normal native UI exit completes Session.Launch. An independent nonzero exit or
signal fails it. Cancellation from the parent remains cancellation rather than
being reclassified as an ordinary child failure.
The launch is one durable effect type, agent_session_launch, named from the
expansion identity <Session.Launch> derives. Its records contain preparation
and lifecycle phases rather than the native conversation:
prepared -> [materialization agent_prompt -> materialized]? -> detached -> launched -> exited
launched is live-only and is never retained. The bracketed pair appears only
where the adapter declared a materialization operation and this launch created
the conversation; everywhere else neither the prompt nor the phase exists. They
are two durable operations rather than one because they answer different
questions: the agent_prompt says the turn was spent, and materialized says
the launch may go on. A run that stopped between them replays the first and
rebuilds the second, which is why the prompt is appended first.
Each phase the launch completes is one retained record under that identity, because the preparation has to be retained before anything of the session moves — before ACP ownership is released where ACP holds it, and before a native process exists where the adapter named the session itself. A single record written when the whole launch settles would describe nothing at all for the run that was interrupted between detach and spawn, which is exactly the run that must not create a replacement session.
launched is the live state between the spawn and the child's exit, and is
deliberately not retained: an interrupted native process leaves detached as
the last retained phase, and resuming reattaches the native UI to that same
provider session.
For a session XMD named, the retained phase is what decides the only safe
continuation, because detached is retained before the exit phase is invoked:
preparedonly — the handoff never began, so native creation may still be owed. The replay creates under the same retained identity, from a new private file holding the exact retained instructions. It allocates nothing and publishes no route.detached— a process may already have started under this identity, so the replay resumes and never falls back to creating.- a later independent launch meeting a compatible route — resumes, and allocates nothing at all.
For a session the provider named, the same rule reads against two more durable operations, and the order they are written in is what a replay reads.
A fresh launch selects the current executable and publishes the unbound V1
ACP-first route before the provider constructs anything, so the route a later
run is held to exists before there is a session to hold it to. ACPX then creates
provisional occupancy and asserts no native identity at all: prepared retains
an empty nativeSessionId and the exact materialization plan this launch
owes, and no executable binding. A preparation is not a report of the
conversation's name.
The coordinator retains prepared before the turn starts. It then executes the turn and
retains it as a separate durable agent_prompt — an ordinary prompt record,
because that is what it is, and the sending is what must never be re-run. Only
the backend's explicit acceptance of that turn promotes the provider record and
asserts the native identity. The coordinator then retains materialized, and only after
that detaches ACP ownership and launches the native UI.
An already-established provider-returned session takes none of that path.
Its identity is known, so prepared retains it, carries no materialization
plan, and the launch spends no turn.
preparedwith an owed plan and no retained prompt outcome — ambiguous. The preparation is retained immediately before the turn is sent, so this is a run that reached the sending point and never recorded what happened there. Nothing reachable from the journal separates a turn that was never sent from one the backend accepted and the interrupted run never saw, and sending now, if it is the second, spends a turn in someone's conversation to find out. The replay stops and retainssession-recovery-required. It never sends another turn, and every later replay says the same thing without reconsidering it.- a retained materialization
agent_promptwithoutmaterialized— the turn is already spent and its outcome is on the journal. The replay reconstructs the phase from that record, with no provider work and no second turn. - a retained
materialized, successful or failed — replays as itself. A failed one stays failed; it is not retried. detachedor later — a process may already have started, so the replay resumes and never falls back to creating.- completed — entirely cold. Replay starts no process, spends no turn, contacts no provider, and returns what the run already settled.
The materialization prompt and the authored instructions are separate
throughout. The prompt is the adapter's own fixed bytes, interpolating nothing
and carrying no authored content; the rendered <Session.Launch> body is
retained with the preparation and is what governs the first native user
turn. Neither is ever substituted for the other, and the turn spent here
cannot perform the task the body describes.
A prepared record carries executableBinding exactly when the existing route it
agrees with is bound, whichever side named the session, and it carries the
route's original binding rather than anything about today's executable. A
fresh preparation carries none. A record without it is readable and continued
under the same selection and confirmation as any other, and a refusal that
prepared no identity invents none.
Every incomplete replay requires agreement between its journal and its route on
identity, provenance, instruction digest, launcher and provider before its first
live effect. When both original accounts carry an executable binding, those
bindings must agree exactly; a missing binding alone is not a disagreement, and
no original binding is compared with today's executable. The live executable
is then selected, and the conversation is confirmed positively instead of by
build equality. Neither account repairs or republishes the other: a replay that
found a disagreement has discovered that the session it was going to continue is
not the session it prepared, and retains identity-unavailable without starting
a child. Equal instructions may resume the retained identity; different
instructions retain instructions-refused and replace neither the layer, the
route, the identity, nor any provider state.
Incomplete replay continues at its first remaining live phase under the same rules as a live launch. An established native resume — provider-returned, or client-allocated after a retained detach — is preceded by the same positive confirmation and joined ACP release, even when no configuration was requested. A client-allocated prepared-only replay still owes creation under the retained identity when handoff never began, and confirms after the joined creation. A detached replay resumes only and never creates if confirmation fails. An ambiguous materialization stays recovery-required and sends no turn. Legacy unbound launches follow these same paths. A completed replay reads its journal and nothing else — it performs no selection, observation or live validation and contacts no route store, ACP runtime or process.
A session XMD named takes its instruction layer from one invocation-private
file, mode 0600, passed by path. The text appears in neither argv nor
environment, and the file and its directory are removed on success, ordinary
failure and cancellation alike, while coordinator ownership is still held.
Every private setup or child-creation failure is normalized before it crosses a
public or durable boundary: the retained class is process-creation-failed and
the message is fixed provider-owned text carrying no executable path,
instruction-file path, argv, environment, raw host message, credential or
provider-private state.
The provider does not write these records and cannot reach the thing that does. It offers each phase as live work to the coordinator the Agent package delivered it; the coordinator runs a phase only when the journal has none, retains what comes back under the launching element's Core-issued invocation identity before the next live effect, and cross-checks the preparation against the exact request that was routed — instructions and digest, agent, requested session, cwd, the V1 empty additional-directory list, and permission mode. A record that changed what was asked would make the journal describe a launch nobody authored, so it is refused rather than retained.
That is the coordination boundary. Middleware composed around the Agent Api may observe a launch or refuse one; it cannot author a phase, and a completion it returns settles nothing, because the route ignores returns and the result is derived from the retained records alone.
At minimum the records retain:
document target and component source
logical session key
provider and agent identity
provider-native session identity, empty in a fresh provider-returned preparation
until the materialization turn is accepted
the materialization plan this launch owes, where it owes one
created or resumed
instruction reconciliation outcome
prepared instructions and digest
instruction channel selected by the provider
primary cwd and the empty V1 additional-directory list
the canonical verified Session configuration, on a successful configured
preparation only
permission configuration
launch phase
the materialization turn's outcome, where one was owed: the provider turn
identity, the response, usage and duration, the identity it asserted, and the
failure where it failed
native launcher identity
exit code or signal
Prepared instructions pass through the existing secret-detection gate before persistence. Provider credentials, raw settings, environment, executable path, and unfiltered CLI arguments do not enter the record.
A completed replay restores the terminal outcome and contacts no provider, coordinator, terminal, or process. A partial replay reserves the terminal, acquires session ownership, verifies the retained request against the live one, reuses the recorded native session, and continues at the first incomplete phase. A partial replay whose native process was interrupted reattaches the native UI to that same session; it never creates a replacement or reconstructs state from a transcript.
Those are operation/runtime replay semantics: they define how an execution
behaves when an embedder, a test, or a future retained execution host supplies
the launch's durable history again. They do not create a public continuation
command. Diagnostic persistence remains xmd run --journal, and the ordinary
run command exposes no resume UX; only xmd workflow resume is a current public
CLI continuation mechanism, under the separate constrained workflow profile
that does not provide native launch.
XMD does not journal turns performed inside the native UI. The provider-native session is authoritative for those turns, tool state, summaries, and transcript history. The XMD journal remains authoritative for deterministic preparation, the handoff identity, and whether the launch completed.
The serialized LaunchFailureClass value "directory-authority" stays exactly
as written; retained launch records are parsed against it by exact match.
Preparation failure creates or launches nothing on behalf of
Session.Launch. Provider availability already resolved by an enclosing
Agent remains an ordinary earlier effect.
Failure to configure instructions or the contextual cwd leaves ownership with ACP and does not spawn the native UI. Missing native-launch capability fails before detach. Detach failure also prevents spawn.
Changing instructions on a retained session fails with instructions-refused
whenever the provider cannot replace the layer in place while preserving
identity and history. Nothing is discarded to make room for a layer, and an
empty cached transcript authorizes nothing: a session an enclosing <Session>
placed and a <Prompt> then established is refused by a launch carrying a
different layer, exactly as a session a native UI has been in is. A <Session>
that only placed one has established nothing, so a launch inside it constructs
the session it named rather than meeting one.
A selected executable that is missing, is not a file or cannot be run fails with
executable-binding-refused, the availability class. An executable's version
never causes this refusal, or any notice. The refusal carries no executable
path, raw version output, host error, argv, environment, credential,
instruction text or provider payload.
An attachment that reaches the provider and cannot open the conversation the
route names fails with identity-unavailable: missing provider history, an
adapter that cannot resume by name, a retained provider arrangement asserting
another conversation or none, and a returned identity that differs from the
route's are one answer, and none of them creates a substitute conversation.
A launch that cannot take ownership retains session-busy or
session-recovery-required as its preparation and stops there. Both are
retained rather than raised bare, so a replay resumes from the phase that
actually happened, and both refuse before ACP ensure, detach, or spawn.
If detach succeeds but process creation fails, the durable provider session remains the authoritative retained state. The launch fails and a later replay uses that same identity.
If the native UI mutates its session and then exits unsuccessfully, both facts remain true: the document fails and the provider session retains what happened. XMD neither rolls back provider history nor substitutes its own account of it.
Provider teardown skips a handle already transferred to the native child. It still attempts every unrelated cleanup. After the child exits, the provider marks its old ACP handle stale so later Agent operations must reattach rather than use a connection that predates native ownership.
The existing target grammar is the complete role-selection UX:
xmd AGENTS.md --help
xmd AGENTS.md#Implementor --default-agent claude
xmd AGENTS.md#Implementor --default-agent codexHelp lists static role headings and their first static paragraph without installing an Agent provider or testing native launch support.
The ordinary CLI host requires a terminal for Session.Launch. It refuses a
non-TTY invocation before the launch resolves an agent, so a piped run learns
it cannot launch without probing for an installed CLI first. Test and embedding
hosts can install a controlled launcher that needs no terminal; a host that
installs none — xmd test, document inspection, an embedder — refuses every
launch, which is what keeps help and inspection free of any of this.
<TestAgent> installs a controlled launcher for its own body, because a
scripted agent's native UI does not exist and the terminal a host would hand it
belongs to whoever is running the tests. That is what lets an authored
<Session.Launch> run under xmd test, where the host installs none, and it
means a launch under <TestAgent> never reaches the host's launcher.
Only the Deno and compiled hosts assemble machine-wide agent sessions: a session coordinator and a construction-route store, rooted together, plus the two advertised capability sets this host has proven. Node and Bun keep the same advertised names and assemble none of the answers, so every advertised operation refuses before provider work rather than acting while a native UI may be in the conversation — as Ownership and concurrency describes.
Ordinary xmd run receives the provider view of that assembly. The session
command receives only its separate ownership-administration view. Other commands
receive none, and a host profile whose session capabilities differ from ordinary xmd run
states its capability sets explicitly rather than inheriting the provider
package's. The workflow Agent profile selects both sets empty and installs no
native foreground launcher, so Session.Launch is unsupported there without
weakening the workflow sandbox.
Provider and agent remain runtime bindings. The target and logical session name
remain role and continuity identities. A <Session> may specify exact provider
model and effort IDs; no other Agent component selects them. A document can
explicitly name an Agent where required, but no provider-specific executable or
resume syntax appears in AGENTS.md.
The test-agent stack supplies deterministic provider state. A controlled native launcher records the request, claims a known provider-native session ID, waits on a test-controlled operation, and exits with a selected status. It never starts Claude, Codex, or a model.
Focused tests prove:
- help discovers roles and performs no preparation or launch;
- selecting one role excludes sibling preparation;
- rendered instructions exactly match the selected files and computations;
- no Agent prompt occurs during preparation or launch;
- cwd, the explicit empty additional-directory list, and permission configuration reach the provider exactly;
- a provider without native-launch capability fails before detach;
- ACP release completes before the native child starts;
- the native child receives only the provider-asserted native session ID;
- raw instructions are absent from argv and environment;
- the document remains suspended until controlled child exit;
- cancellation proves the child can no longer execute or hold the terminal before cleanup completes, without treating a defunct PID as live;
- a later Prompt reattaches ACP to the same provider session;
- full replay launches no process;
- partial replay resumes the same incomplete launch identity; and
- concurrent launches cannot share one logical session or foreground terminal; and
- instruction reconciliation installs a layer on a session the launch constructs, resumes an equal one, and refuses a changed one — including on a session a prompt established and never used again, and with no discard on any path; and
- ownership covers session, prompt, launch and incomplete replay under one natural key, contention refuses instead of queueing, a crashed owner leaves a recovery tombstone, and a host with no coordinator refuses before contacting an agent;
- a released build binding is read exactly, an inexact record refuses rather than being read past, and a changed or moved current executable continues the same confirmed conversation quietly;
- new client-native construction selects the executable before it allocates, publishes an unbound V1 route, and retains a preparation that agrees with it, while an existing route continues under today's selection and gains nothing;
- a
<Session>or<Prompt>on a client-native route supplies the route identity as the exact resume identity, delivers the selected path only to the matching child's transient environment, and refuses before a turn on a missing attachment gate, a disagreeing retained arrangement or a returned identity that is not the route's; and - ACP runtimes are partitioned by resolved agent command and selected environment, a handle is closed by the partition that created it, the last close evicts a bound partition, and provider teardown settles what remains;
- claimed runtime work that produced no handle releases its claim, a partition is evicted only with no handles and no work in flight, a handle that came back survives every later refusal bound to its creator whichever path created it, a cancellation waits for an ensure already in flight and closes what it answers with before acknowledging quiescence, and a close that failed releases nothing and withholds quiescence; and
- a canonical version parse accepts exactly one matching line, and refuses zero or several without repeating the output.
The authored half of this is one executable Markdown document,
packages/test-agent/src/NativeSessionLaunch.test.md, run whole. It authors the
launch, the prompt that proves no turn was spent, and the refusal a launch meets
on a session an earlier prompt established, directly — a <Session.Launch> written as <Session.Launch>, not
assembled from a TypeScript string. <Session.Launch> raises a launch failure
as an error segment whose cause carries phase and failureClass, so an
<AssertThrows as="…"> binding can assert which refusal it was rather than the
wording of a message. TypeScript owns what Markdown cannot reach: ACP wire
traffic, the coordinator, locks, files, processes, and the journal.
Adapter contract tests use fake claude and codex executables to verify resume
argument construction and exit propagation. They start real children through the
production launcher, so what they prove is the argument vector a native CLI
receives, the status it propagates back, and that a cancelled launch leaves no
process holding the terminal.
Separate opt-in proofs run the real production command against an installed CLI, and each proves the claims its adapter's provenance names under Provider-native identity — an ACP-created session the native CLI can see for a provider-returned adapter, direct creation and same-identity resume for one that names its own sessions. A provider is not advertised as launch-capable until its own list passes.
Claude's are packages/acp/src/ClaudeNativeLaunch.test.md,
packages/acp/src/ClaudeZeroTurnExit.test.md and
packages/acp/src/ClaudeNativeToAcp.test.md. They are authored documents, run
whole and independently of each other, and what they run is
xmd run AGENTS.md#Implementor --default-agent claude through the built binary
in a byte-for-byte copy of the checked-in role document — never Markdown a test
assembled. The first spends exactly two model turns; the second spends none and
lives apart so that correcting it can never respend them.
The third is the attachment proof, and it spends two of its own: one native turn
that plants a random marker, and one marker-free ACP turn — a checked-in
<Session name="implementer"><Prompt> document, run verbatim from the same
directory — that has to recover it. Equal identities are not the claim: two
accounts agreeing about a UUID say nothing about whether the conversation behind
it is the one the native turn happened in, so the marker exists only in that
first user turn and in the harness's own memory, reaching no instruction file,
argument vector, environment, session key, durable record, executed document or
reported field. Its independent, zero-turn half publishes a bound route naming a
fresh absent identity in a directory of its own and requires
identity-unavailable before a turn: a provider that quietly created empty
history there would make every recovery above unfalsifiable. Both are opt-in and
refuse before starting any provider process without it. TypeScript owns only the
pseudo-terminal, the child lifecycle, the argument vector the CLI received, file
modes, the structured route and journal reads, and exact-path cleanup; the
documents own the schemas, the assertions and everything an operator reads, and
no verdict may carry terminal output, argv, environment, prepared text, the
history marker or a private path.
A proof also removes what it created, and that is the harness's own act rather than anything the product does. Production keeps the construction route and the retained phases — a launch that deleted them would break the continuity claim 4 asserts. A proof reads those exact records for its own natural key, reduces them to filtered evidence, and only then removes those exact paths, together with its temporary project through the provider's own path-scoped purge. It never sweeps the shared coordination namespace and never removes a record it did not create. It also runs the command with an operator's environment rather than its own: a proof nested inside another coding-agent session inherits markers that change what the provider does, and would then be reporting on itself.
The feature is launchAgentSession() and the Session.Launch component; the
opaque launch request its public Agent route carries and the invocation-owned
coordinator its installed provider receives; the agent_session_launch durable
records with their replay and secret scanning; the host-owned session
coordinator and its crash-conservative ownership record; an invocation-owned
native-launch capability in the ACPX provider;
provider-native identity that is either asserted by the provider or allocated by
the adapter before the provider exists, retained explicitly and never inferred;
a strict create-once construction route beside the coordinator's own records,
in a released unbound form and a bound one, of which fresh construction writes
the unbound form; ACP attachment to a
client-native session under its exact retained identity, through runtime
partitions keyed by agent command and selected environment;
an inherited foreground-terminal interactive child with cancellation and
bounded reaping;
and the controlled TestAgent fixture that proves all of it without starting a
model.
The following capabilities remain outside V1 and fail closed rather than degrading:
- Only
claudeandcodexare advertised, and separately for each capability.claudeis client-allocated and is advertised for both native launch and client-native attachment; its proofs ran the applicable claims under Provider-native identity against Claude Code 2.1.241 on macOS arm64.codexis provider-returned and is advertised for native launch only, on the frozen tuple named under Provider-native identity. Handing the session to a native UI does not on its own satisfy that advertisement: the native-launch gate forcodexis the complete provider-returned proof, which requires that XMD rejoins the same conversation through ACP afterwards and reads the native turn back out of its history, so continuity is part of the claim being made and not a separate one. Its absence from client-native attachment says something else entirely: that capability is joining a conversation a native client allocated, andcodexnever has one, because its route is ACP-first and the identity is the adapter's own answer to XMD. A launch naming an unadvertised agent is refused withunsupported-capabilitybefore anything of the session moves, and so is an attachment naming an agent advertised only for native launch. Agent.AddDiris unbuilt, so a launch declares no additional roots. The retained request says so explicitly — an empty ordered list — rather than omitting the fact, and no adapter maps a root it was never given. The ACP Client specification is the prerequisite owner for a future ordering and access-mode contract.- A final configured launch is verified before the handoff.
<Session>says which model and effort level its conversation runs under;<Agent>,<Prompt>and<Session.Launch>have no such prop. Where the provider returns the identity, the settings are applied and verified after the exact session is ensured and before any materialization turn, detach record or native process, and the successful preparation retains one canonicalconfiguration. A launch that could not apply them refuses withconfiguration-refusedand retains no configuration. The Agent package issued the frozen session use that carried both the exact provider Session that finished its setup and these settings; the provider retains no desired-settings association, and a rebuilt use authorizes nothing. Middleware may route another whole Session, and the preparation describes only the final route that actually succeeded. - A route that creates its session in its own interface refuses a final
configured launch. There is no moment between a native UI creating a
conversation and a person typing in it, so a final configured launch on a client-allocated adapter
refuses with
unsupported-capabilitybefore a route is published, an identity allocated, a private instruction file written, or anything detached or spawned. An unconfigured launch on either route is unchanged and reads no configuration at all. Middleware that routes a raw Session or no Session has selected that unchanged unconfigured path. - An incomplete configured launch reapplies what it retained. At its own first live phase — the detach for a launch that never handed over, the spawn for one that did — it reconciles its route and build, reattaches by the exact retained identity, puts the retained configuration back into force, and relinquishes ACP again without authoring a second detach. That reattachment, and a configured launch's owed materialization turn, state whether their configuration names a model exactly as any other attaching call does (ACP client §A configured conversation that reconnects).
- Released launch model members never become configuration. A non-empty
requestedModelor top-level observationalmodelstring is validated and discarded while reading an older preparation; a malformed value refuses the record. New records write neither member, and an incomplete older record does no configuration work because one was present. Canonicalconfigurationbeside either released member is ambiguous and refuses. - Executable history is never rebound. A released route keeps any binding it recorded. A later executable continues the same confirmed conversation quietly; nothing rewrites the route or the provider's history to claim the current executable made it.
Additional provider adapters land independently against the same core contract.
An adapter that cannot prove instruction injection before the first user turn
stays unsupported rather than weakening Session.Launch semantics.
Native UI event mirroring, XMD-rendered interactive chat, simultaneous root
foreground sessions, automatic nested AGENTS.md
discovery, bootstrap model turns, and workflow role scheduling are outside this
contract.
Implementation review checks these frozen invariants:
- Only explicitly rendered
Session.Launchcontent crosses as instructions. - Launch performs no model turn beyond an adapter's declared materialization turn, which runs at most once, only for a conversation the launch just created, and only with that adapter's fixed prompt.
- Provider-native identity is asserted, never inferred.
- ACP and the native UI never concurrently own one session.
- XMD remains the supervising parent and the document stays suspended.
- Cancellation establishes that the native child can no longer execute or own the terminal before document continuation or teardown completion; a lost runtime exit event or defunct PID does not extend live ownership.
- Completed replay launches nothing; incomplete replay uses the same retained provider session.
- Native conversation history remains provider-owned and is never reconstructed from XMD output.
- Raw prepared context does not appear in process arguments or environment.
- Unsupported providers fail before ownership transfer.
- Native launch never widens the admitted filesystem permissions.
- A changed instruction layer never discards persistent provider state: it is replaced in place with identity and history preserved, or refused before handoff.
- Public launch routing is request-only: no return value, copy, superseded parent, foreign request, or repeated delegation authors a phase, and the coordinator reaches the installed provider directly.
- Every operation that can act on an advertised session takes ownership under one natural key first, contention refuses rather than queues, and an owner that did not prove it stopped leaves the session owned until an explicit, matching operator force records release with quiescence unproved.
- A session is constructed once, by one mechanism, and its create-once route says which. Routes never convert, and the loser of a race adopts the winner rather than replacing it.
- A session XMD named is created by the native process under an identity the adapter allocated inside ownership, from a private mode-0600 file whose text reaches neither argv nor environment.
- Private setup and child-creation failures are normalized before they cross a public or durable boundary.
- Every create, resume, attachment and incomplete replay uses the executable the current environment selects and requires the provider's positive assertion of the exact retained native identity before a configuration, a turn or a native handoff — or, for a fresh client-allocated creation, after the child joins and before success. Nothing about the executable's version or digest is compared, reported, admitted or refused; exit status never confirms identity.
- The canonical executable path is live only: it enters no route, journal, retained provider state, public result, diagnostic or global environment, and no partition that outlives its last handle.
- Attachment supplies the route's exact identity as the resume identity, and the provider's canonical assertion must equal it before the first turn.
- Native-launch advertisement and client-native attachment advertisement are separate trusted-host choices, and neither is inferred from the other.
- A released V1 route and a legacy journal remain readable and are never rewritten; they continue through attachment and incomplete replay under the same selection and confirmation, and missing historical build evidence alone refuses nothing.
- A failed acquisition retains no partition and no live path; a partition is evicted only when it holds no handle and no work in flight; every handle-producing path enters one ownership account bound to its creator the moment its handle exists; a cancellation observes and settles an ensure it already started before quiescence; quiescence is answered from that account; and a close that failed releases nothing and acknowledges none. Items 18 and 22 are the #891 amendment: tested versions are evidence, and a session continues quietly on the current executable under positive identity confirmation.
Item 12 is the 2026-08-20 architecture amendment. ACPX fixes systemPrompt at
session creation, while native turns are not authoritative in its cached
transcript. The amendment prevents transcript absence from authorizing loss of
provider-owned history or substitution of durable session identity — which is
why V1 removed the discard branch entirely rather than restricting it.