🔗 Let XMD name a coding-agent session, and hand it to the native process

architecture.md

@@ -86,6 +86,8 @@ Existing documents and code get aligned to this section retroactively.
 | launch request | the frozen, one-use value public launch middleware routes. It carries the facts of one launch and `with()`, and nothing that can settle one. Identity is object identity: a rebuilt look-alike describes the same ask and authorizes none of it |
 | provider authority | what core delivers to the provider factory it installs, as an argument that factory closes over. It validates the routed request, runs each absent phase once, cross-checks and retains what comes back, and derives the result. There is no reader for one, no context holding one, and no request member carrying one |
 | session coordinator | the host-built capability that answers who owns one logical agent session right now, across processes. It is passed directly into the provider that needs it and is deliberately not contextual: a decision document middleware could replace is not one. Acquisition never waits |
+| construction route | how one logical agent session was first constructed — through ACP, or under an identity XMD chose — as strict create-once durable state beside the coordinator's own records. It answers a different question from ownership and grants no right to act: the coordinator remains the single live authority. A route never converts, and a session ACP already established is recorded as ACP-first rather than reclassified |
+| identity provenance | who chose a provider-native session identity: the provider returned it, or the client allocated it before the provider existed. Retained rather than inferred, because after the fact both are just a string in the record. A released record written before the distinction existed reads as provider-returned, which is the only compatibility inference |
 | quiescence | the one-use acknowledgement an ownership body gives. It does not mean "I finished" — it means nothing this owner started can still act on the session, which is why a handoff that could not release its handle never gives it |
 | recovery tombstone | an ownership record left active because its owner never proved it stopped. A crash releases the kernel lock and not this, and no pid, elapsed time, released lock or empty transcript clears it |
 | provider partition | one complete, independently owned agent-provider state — runtime, store, managed sessions, queues, coordinator, teardown — selected by the one installed factory at each dispatch. Production is the single-partition case of the same path; holding a partition grants work, never permission |
@@ -2709,7 +2711,7 @@ Status is measured against main.
 | `exec as="name"` | binds one command's settled outcome — exit status, stdout and stderr — as an ordinary mutable binding; the block displays neither channel, renders nothing, and a nonzero status raises nothing. Only the built-in exec terminal and the built-in `timeout` may compose one, authorized by factory identity rather than by registered name, and asked for through a capability-backed request public middleware composes around but cannot issue, claim twice or answer | built on the #447 stack |
 | testing harness (`<Execution>`) | runs another document as a real root under a production host profile, authorized by canonical `<Test>` alone: declarations installed before the root import, child output displayed progressively and collected only when asked, journal retention selected independently of observation, and the outcome published by the invocation's own terminal through a request public middleware composes around but cannot answer | built on the #454 stack for `host="run"`; the workflow profile and `<WorkflowRun>` are unbuilt, and a host that offers no workflow profile refuses them |
 | `Config` run deadline / exec default / Fetch default | three independently owned contextual timeouts, absent unless configured, each read by exactly one consumer | built on main |
-| native session launch (`<Session.Launch>` / `Agent.launch()`) | prepares one durable coding-agent session from the rendered body of `<Session.Launch>` and hands the provider's native UI the terminal for that exact session, then continues the document after it exits. The body renders completely first and only what it rendered crosses as the instruction layer; the launch performs no model turn; the run's one foreground-terminal lease is taken before an agent is resolved, so a host with no terminal refuses without probing for an installed CLI; the ACPX provider installs the layer at session creation, refuses an agent whose native launcher is not advertised or that asserts no provider-native identity, releases ACP ownership before the spawn, and marks its handle stale so a later `<Prompt>` reattaches. Phases are retained as `agent_session_launch` records under one expansion identity — `prepared` before ownership is released, then `detached`, then `exited` — so a completed replay launches nothing and an interrupted one resumes the retained identity instead of creating a replacement session. The public route carries an opaque one-use launch request and answers nothing; authority to run and retain a phase is delivered to the installed provider directly, so neither a returned completion nor a rebuilt request authors a launch. Every operation that can act on an advertised provider-returned session takes exclusive ownership under one natural key first, through a coordinator the host built and passed in; contention refuses instead of queueing, an owner that never proved it stopped leaves a recovery tombstone, and a host that can build none refuses before contacting an agent. No launch path discards persistent provider state | built on the #517 stack; no real adapter is advertised, `Agent.AddDir` is unbuilt, and both fail closed |
+| native session launch (`<Session.Launch>` / `Agent.launch()`) | prepares one durable coding-agent session from the rendered body of `<Session.Launch>` and hands the provider's native UI the terminal for that exact session, then continues the document after it exits. The body renders completely first and only what it rendered crosses as the instruction layer; the launch performs no model turn; the run's one foreground-terminal lease is taken before an agent is resolved, so a host with no terminal refuses without probing for an installed CLI. A session is constructed once, by one of two mechanisms, and its create-once construction route says which. Where the provider returns the identity, the ACPX provider creates the session, installs the layer at creation, releases ACP ownership before the spawn, and marks its handle stale so a later `<Prompt>` reattaches. Where the adapter names its own sessions, it allocates the identity inside ownership before any process exists, the native process creates the session under that name from a private mode-0600 instruction file, and ACP creates nothing — the instruction text reaches neither argv nor environment, and the file is removed on success, failure and cancellation alike while ownership is still held. Neither route converts into the other: an eager `<Session>` publishes ACP-first before it establishes anything and keeps that account even if establishing fails, a launch meeting it refuses before an identity exists, and a `<Session>` or `<Prompt>` meeting a client-allocated route raises the provider's own route error rather than manufacturing a launch failure. Phases are retained as `agent_session_launch` records under one expansion identity — `prepared` before ownership is released, then `detached`, then `exited` — so a completed replay launches nothing, a replay holding only `prepared` proves the handoff never began and may still create under the retained identity, and one holding `detached` resumes and never falls back. The public route carries an opaque one-use launch request and answers nothing; authority to run and retain a phase is delivered to the installed provider directly, so neither a returned completion nor a rebuilt request authors a launch. Every operation that can act on an advertised session takes exclusive ownership under one natural key first, through a coordinator the host built and passed in; contention refuses instead of queueing, and an owner that never proved it stopped leaves a recovery tombstone. A host that cannot say who owns a session refuses every advertised operation, and one that cannot say how a session was constructed additionally refuses an agent that names its own — before any provider effect. Every private setup or child-creation failure is normalized to `process-creation-failed` with fixed provider-owned text, carrying no path, argv, environment or host message. No launch path discards persistent provider state | built on the #517 stack, extended by the #519 stack; Deno and the compiled binary assemble the host, Node and Bun refuse, no real adapter is advertised until #520's gate passes, `Agent.AddDir` is unbuilt, and ACP attachment to a client-allocated session is deferred with #517 |
 | `<Fetch>` | performs one XMD-mediated HTTP read through contextual `API.Fetch`, admitting the whole request before transport, and retains the normalized request and the detached response as one `fetch` durable observation; capture decides whether a status is data or a failure, and the trusted host's destination ceiling sits below the component | built on the #456 stack; a generated fragment may name the pinned identity only for a request the trusted host stated exactly, on the #369 stack |
 | `API.Files` | routes every document filesystem operation to the installed provider, with no host default and structural failure data | built on the #227 stack |
 | host Files provider / `useHostFiles()` | resolves document paths in the caller's filesystem, containing them while the host namespace is stable; installed by all four CLI entrypoints | built on the #227 stack |

packages/acp/mod.ts

@@ -28,7 +28,12 @@ export {
  knownNativeAdapters,
  nativeAdapterFor,
 } from "./src/native-launch.ts";
-export type { NativeAdapter } from "./src/native-launch.ts";
+export { allocatesIdentity } from "./src/native-launch.ts";
+export type {
+ ClientAllocatedAdapter,
+ NativeAdapter,
+ ProviderReturnedAdapter,
+} from "./src/native-launch.ts";
 
 export {
  AcpxPartitionError,
@@ -37,3 +42,19 @@ export {
 } from "./src/provider.ts";
 export type { AcpxPartitionSelector } from "./src/provider.ts";
 export type { AcpxProvider, ProbeCapableRuntime } from "./src/provider.ts";
+
+// The construction route: how a logical session was first constructed, kept
+// strictly and create-once beside the coordinator's own records. It is not an
+// Agent Api, a component, or a source of launch authority — the coordinator
+// remains the single live authority.
+export {
+ AgentSessionRouteError,
+ createDenoSessionRouteStore,
+ createMemorySessionRouteStore,
+ hasDenoSessionRouteStore,
+ parseAgentSessionRoute,
+ routeKey,
+ routeNamesKey,
+ serializeAgentSessionRoute,
+} from "./src/session-route.ts";
+export type { AgentSessionRouteStore, AgentSessionRouteV1 } from "./src/session-route.ts";

packages/acp/src/native-launch.ts

@@ -16,22 +16,78 @@
  * Until then `<Session.Launch>` refuses that agent before releasing its ACP
  * session, which is the failure the contract asks for rather than a hopeful
  * spawn.
+ *
+ * Adapters differ in one structural way, and it is discriminated rather than
+ * inferred: who chooses the provider-native session identity. A
+ * `provider-returned` adapter can only resume a session something else created
+ * and named. A `client-allocated` adapter names the session first and hands
+ * that name to the native process, which is what lets a launch construct a
+ * conversation instead of merely reattaching to one.
  */
 
-export interface NativeAdapter {
+import { randomUUID } from "node:crypto";
+import type { IdentityProvenance } from "@executablemd/core";
+
+interface AdapterCommands {
  /** Stable adapter identity — `claude`, `codex`. Never an executable path. */
  launcher: string;
+ /** Who chooses this adapter's native session identity. */
+ identity: IdentityProvenance;
  /** The argv that resumes this exact provider-native session. */
  resume(nativeSessionId: string): string[];
 }
 
+/**
+ * An adapter whose native UI is handed the session it is to create.
+ *
+ * `allocate` is the adapter's because the identity is that provider's dialect:
+ * what shape one takes and what the provider will accept is knowledge about
+ * the provider, not about launching in general. The provider decides whether a
+ * freshly allocated candidate wins publication; it does not decide what one
+ * looks like.
+ *
+ * The instruction layer crosses as a file path and never as text, so nothing
+ * here takes the instructions themselves.
+ */
+export interface ClientAllocatedAdapter extends AdapterCommands {
+ identity: "client-allocated";
+ /** A fresh provider-native session identity. */
+ allocate(): string;
+ /** The argv that creates a session under `id` with that instruction layer. */
+ create(nativeSessionId: string, instructionFile: string): string[];
+}
+
+export interface ProviderReturnedAdapter extends AdapterCommands {
+ identity: "provider-returned";
+}
+
+export type NativeAdapter = ProviderReturnedAdapter | ClientAllocatedAdapter;
+
+/** Whether this adapter names its own sessions. */
+export function allocatesIdentity(adapter: NativeAdapter): adapter is ClientAllocatedAdapter {
+ return adapter.identity === "client-allocated";
+}
+
 const ADAPTERS: Readonly<Record<string, NativeAdapter>> = {
  claude: {
  launcher: "claude",
+ // XMD names the session before Claude exists, so the native process is
+ // told which conversation to make rather than reporting one afterwards.
+ identity: "client-allocated",
+ // Claude takes a UUID it has never seen and makes it the session's name.
+ allocate: () => randomUUID(),
+ create: (nativeSessionId, instructionFile) => [
+ "claude",
+ "--session-id",
+ nativeSessionId,
+ "--system-prompt-file",
+ instructionFile,
+ ],
  resume: (nativeSessionId) => ["claude", "--resume", nativeSessionId],
  },
  codex: {
  launcher: "codex",
+ identity: "provider-returned",
  resume: (nativeSessionId) => ["codex", "resume", nativeSessionId],
  },
 };

architecture.md

@@ -86,6 +86,8 @@ Existing documents and code get aligned to this section retroactively.
 | launch request | the frozen, one-use value public launch middleware routes. It carries the facts of one launch and `with()`, and nothing that can settle one. Identity is object identity: a rebuilt look-alike describes the same ask and authorizes none of it |
 | provider authority | what core delivers to the provider factory it installs, as an argument that factory closes over. It validates the routed request, runs each absent phase once, cross-checks and retains what comes back, and derives the result. There is no reader for one, no context holding one, and no request member carrying one |
 | session coordinator | the host-built capability that answers who owns one logical agent session right now, across processes. It is passed directly into the provider that needs it and is deliberately not contextual: a decision document middleware could replace is not one. Acquisition never waits |
+| construction route | how one logical agent session was first constructed — through ACP, or under an identity XMD chose — as strict create-once durable state beside the coordinator's own records. It answers a different question from ownership and grants no right to act: the coordinator remains the single live authority. A route never converts, and a session ACP already established is recorded as ACP-first rather than reclassified |
+| identity provenance | who chose a provider-native session identity: the provider returned it, or the client allocated it before the provider existed. Retained rather than inferred, because after the fact both are just a string in the record. A released record written before the distinction existed reads as provider-returned, which is the only compatibility inference |
 | quiescence | the one-use acknowledgement an ownership body gives. It does not mean "I finished" — it means nothing this owner started can still act on the session, which is why a handoff that could not release its handle never gives it |
 | recovery tombstone | an ownership record left active because its owner never proved it stopped. A crash releases the kernel lock and not this, and no pid, elapsed time, released lock or empty transcript clears it |
 | provider partition | one complete, independently owned agent-provider state — runtime, store, managed sessions, queues, coordinator, teardown — selected by the one installed factory at each dispatch. Production is the single-partition case of the same path; holding a partition grants work, never permission |
@@ -2709,7 +2711,7 @@ Status is measured against main.
 | `exec as="name"` | binds one command's settled outcome — exit status, stdout and stderr — as an ordinary mutable binding; the block displays neither channel, renders nothing, and a nonzero status raises nothing. Only the built-in exec terminal and the built-in `timeout` may compose one, authorized by factory identity rather than by registered name, and asked for through a capability-backed request public middleware composes around but cannot issue, claim twice or answer | built on the #447 stack |
 | testing harness (`<Execution>`) | runs another document as a real root under a production host profile, authorized by canonical `<Test>` alone: declarations installed before the root import, child output displayed progressively and collected only when asked, journal retention selected independently of observation, and the outcome published by the invocation's own terminal through a request public middleware composes around but cannot answer | built on the #454 stack for `host="run"`; the workflow profile and `<WorkflowRun>` are unbuilt, and a host that offers no workflow profile refuses them |
 | `Config` run deadline / exec default / Fetch default | three independently owned contextual timeouts, absent unless configured, each read by exactly one consumer | built on main |
-| native session launch (`<Session.Launch>` / `Agent.launch()`) | prepares one durable coding-agent session from the rendered body of `<Session.Launch>` and hands the provider's native UI the terminal for that exact session, then continues the document after it exits. The body renders completely first and only what it rendered crosses as the instruction layer; the launch performs no model turn; the run's one foreground-terminal lease is taken before an agent is resolved, so a host with no terminal refuses without probing for an installed CLI; the ACPX provider installs the layer at session creation, refuses an agent whose native launcher is not advertised or that asserts no provider-native identity, releases ACP ownership before the spawn, and marks its handle stale so a later `<Prompt>` reattaches. Phases are retained as `agent_session_launch` records under one expansion identity — `prepared` before ownership is released, then `detached`, then `exited` — so a completed replay launches nothing and an interrupted one resumes the retained identity instead of creating a replacement session. The public route carries an opaque one-use launch request and answers nothing; authority to run and retain a phase is delivered to the installed provider directly, so neither a returned completion nor a rebuilt request authors a launch. Every operation that can act on an advertised provider-returned session takes exclusive ownership under one natural key first, through a coordinator the host built and passed in; contention refuses instead of queueing, an owner that never proved it stopped leaves a recovery tombstone, and a host that can build none refuses before contacting an agent. No launch path discards persistent provider state | built on the #517 stack; no real adapter is advertised, `Agent.AddDir` is unbuilt, and both fail closed |
+| native session launch (`<Session.Launch>` / `Agent.launch()`) | prepares one durable coding-agent session from the rendered body of `<Session.Launch>` and hands the provider's native UI the terminal for that exact session, then continues the document after it exits. The body renders completely first and only what it rendered crosses as the instruction layer; the launch performs no model turn; the run's one foreground-terminal lease is taken before an agent is resolved, so a host with no terminal refuses without probing for an installed CLI. A session is constructed once, by one of two mechanisms, and its create-once construction route says which. Where the provider returns the identity, the ACPX provider creates the session, installs the layer at creation, releases ACP ownership before the spawn, and marks its handle stale so a later `<Prompt>` reattaches. Where the adapter names its own sessions, it allocates the identity inside ownership before any process exists, the native process creates the session under that name from a private mode-0600 instruction file, and ACP creates nothing — the instruction text reaches neither argv nor environment, and the file is removed on success, failure and cancellation alike while ownership is still held. Neither route converts into the other: an eager `<Session>` publishes ACP-first before it establishes anything and keeps that account even if establishing fails, a launch meeting it refuses before an identity exists, and a `<Session>` or `<Prompt>` meeting a client-allocated route raises the provider's own route error rather than manufacturing a launch failure. Phases are retained as `agent_session_launch` records under one expansion identity — `prepared` before ownership is released, then `detached`, then `exited` — so a completed replay launches nothing, a replay holding only `prepared` proves the handoff never began and may still create under the retained identity, and one holding `detached` resumes and never falls back. The public route carries an opaque one-use launch request and answers nothing; authority to run and retain a phase is delivered to the installed provider directly, so neither a returned completion nor a rebuilt request authors a launch. Every operation that can act on an advertised session takes exclusive ownership under one natural key first, through a coordinator the host built and passed in; contention refuses instead of queueing, and an owner that never proved it stopped leaves a recovery tombstone. A host that cannot say who owns a session refuses every advertised operation, and one that cannot say how a session was constructed additionally refuses an agent that names its own — before any provider effect. Every private setup or child-creation failure is normalized to `process-creation-failed` with fixed provider-owned text, carrying no path, argv, environment or host message. No launch path discards persistent provider state | built on the #517 stack, extended by the #519 stack; Deno and the compiled binary assemble the host, Node and Bun refuse, no real adapter is advertised until #520's gate passes, `Agent.AddDir` is unbuilt, and ACP attachment to a client-allocated session is deferred with #517 |
 | `<Fetch>` | performs one XMD-mediated HTTP read through contextual `API.Fetch`, admitting the whole request before transport, and retains the normalized request and the detached response as one `fetch` durable observation; capture decides whether a status is data or a failure, and the trusted host's destination ceiling sits below the component | built on the #456 stack; a generated fragment may name the pinned identity only for a request the trusted host stated exactly, on the #369 stack |
 | `API.Files` | routes every document filesystem operation to the installed provider, with no host default and structural failure data | built on the #227 stack |
 | host Files provider / `useHostFiles()` | resolves document paths in the caller's filesystem, containing them while the host namespace is stable; installed by all four CLI entrypoints | built on the #227 stack |

packages/acp/mod.ts

@@ -28,7 +28,12 @@ export {
  knownNativeAdapters,
  nativeAdapterFor,
 } from "./src/native-launch.ts";
-export type { NativeAdapter } from "./src/native-launch.ts";
+export { allocatesIdentity } from "./src/native-launch.ts";
+export type {
+ ClientAllocatedAdapter,
+ NativeAdapter,
+ ProviderReturnedAdapter,
+} from "./src/native-launch.ts";
 
 export {
  AcpxPartitionError,
@@ -37,3 +42,19 @@ export {
 } from "./src/provider.ts";
 export type { AcpxPartitionSelector } from "./src/provider.ts";
 export type { AcpxProvider, ProbeCapableRuntime } from "./src/provider.ts";
+
+// The construction route: how a logical session was first constructed, kept
+// strictly and create-once beside the coordinator's own records. It is not an
+// Agent Api, a component, or a source of launch authority — the coordinator
+// remains the single live authority.
+export {
+ AgentSessionRouteError,
+ createDenoSessionRouteStore,
+ createMemorySessionRouteStore,
+ hasDenoSessionRouteStore,
+ parseAgentSessionRoute,
+ routeKey,
+ routeNamesKey,
+ serializeAgentSessionRoute,
+} from "./src/session-route.ts";
+export type { AgentSessionRouteStore, AgentSessionRouteV1 } from "./src/session-route.ts";

packages/acp/src/native-launch.ts

@@ -16,22 +16,78 @@
  * Until then `<Session.Launch>` refuses that agent before releasing its ACP
  * session, which is the failure the contract asks for rather than a hopeful
  * spawn.
+ *
+ * Adapters differ in one structural way, and it is discriminated rather than
+ * inferred: who chooses the provider-native session identity. A
+ * `provider-returned` adapter can only resume a session something else created
+ * and named. A `client-allocated` adapter names the session first and hands
+ * that name to the native process, which is what lets a launch construct a
+ * conversation instead of merely reattaching to one.
  */
 
-export interface NativeAdapter {
+import { randomUUID } from "node:crypto";
+import type { IdentityProvenance } from "@executablemd/core";
+
+interface AdapterCommands {
  /** Stable adapter identity — `claude`, `codex`. Never an executable path. */
  launcher: string;
+ /** Who chooses this adapter's native session identity. */
+ identity: IdentityProvenance;
  /** The argv that resumes this exact provider-native session. */
  resume(nativeSessionId: string): string[];
 }
 
+/**
+ * An adapter whose native UI is handed the session it is to create.
+ *
+ * `allocate` is the adapter's because the identity is that provider's dialect:
+ * what shape one takes and what the provider will accept is knowledge about
+ * the provider, not about launching in general. The provider decides whether a
+ * freshly allocated candidate wins publication; it does not decide what one
+ * looks like.
+ *
+ * The instruction layer crosses as a file path and never as text, so nothing
+ * here takes the instructions themselves.
+ */
+export interface ClientAllocatedAdapter extends AdapterCommands {
+ identity: "client-allocated";
+ /** A fresh provider-native session identity. */
+ allocate(): string;
+ /** The argv that creates a session under `id` with that instruction layer. */
+ create(nativeSessionId: string, instructionFile: string): string[];
+}
+
+export interface ProviderReturnedAdapter extends AdapterCommands {
+ identity: "provider-returned";
+}
+
+export type NativeAdapter = ProviderReturnedAdapter | ClientAllocatedAdapter;
+
+/** Whether this adapter names its own sessions. */
+export function allocatesIdentity(adapter: NativeAdapter): adapter is ClientAllocatedAdapter {
+ return adapter.identity === "client-allocated";
+}
+
 const ADAPTERS: Readonly<Record<string, NativeAdapter>> = {
  claude: {
  launcher: "claude",
+ // XMD names the session before Claude exists, so the native process is
+ // told which conversation to make rather than reporting one afterwards.
+ identity: "client-allocated",
+ // Claude takes a UUID it has never seen and makes it the session's name.
+ allocate: () => randomUUID(),
+ create: (nativeSessionId, instructionFile) => [
+ "claude",
+ "--session-id",
+ nativeSessionId,
+ "--system-prompt-file",
+ instructionFile,
+ ],
  resume: (nativeSessionId) => ["claude", "--resume", nativeSessionId],
  },
  codex: {
  launcher: "codex",
+ identity: "provider-returned",
  resume: (nativeSessionId) => ["codex", "resume", nativeSessionId],
  },
 };

architecture.md

@@ -86,6 +86,8 @@ Existing documents and code get aligned to this section retroactively.
 | launch request | the frozen, one-use value public launch middleware routes. It carries the facts of one launch and `with()`, and nothing that can settle one. Identity is object identity: a rebuilt look-alike describes the same ask and authorizes none of it |
 | provider authority | what core delivers to the provider factory it installs, as an argument that factory closes over. It validates the routed request, runs each absent phase once, cross-checks and retains what comes back, and derives the result. There is no reader for one, no context holding one, and no request member carrying one |
 | session coordinator | the host-built capability that answers who owns one logical agent session right now, across processes. It is passed directly into the provider that needs it and is deliberately not contextual: a decision document middleware could replace is not one. Acquisition never waits |
+| construction route | how one logical agent session was first constructed — through ACP, or under an identity XMD chose — as strict create-once durable state beside the coordinator's own records. It answers a different question from ownership and grants no right to act: the coordinator remains the single live authority. A route never converts, and a session ACP already established is recorded as ACP-first rather than reclassified |
+| identity provenance | who chose a provider-native session identity: the provider returned it, or the client allocated it before the provider existed. Retained rather than inferred, because after the fact both are just a string in the record. A released record written before the distinction existed reads as provider-returned, which is the only compatibility inference |
 | quiescence | the one-use acknowledgement an ownership body gives. It does not mean "I finished" — it means nothing this owner started can still act on the session, which is why a handoff that could not release its handle never gives it |
 | recovery tombstone | an ownership record left active because its owner never proved it stopped. A crash releases the kernel lock and not this, and no pid, elapsed time, released lock or empty transcript clears it |
 | provider partition | one complete, independently owned agent-provider state — runtime, store, managed sessions, queues, coordinator, teardown — selected by the one installed factory at each dispatch. Production is the single-partition case of the same path; holding a partition grants work, never permission |
@@ -2709,7 +2711,7 @@ Status is measured against main.
 | `exec as="name"` | binds one command's settled outcome — exit status, stdout and stderr — as an ordinary mutable binding; the block displays neither channel, renders nothing, and a nonzero status raises nothing. Only the built-in exec terminal and the built-in `timeout` may compose one, authorized by factory identity rather than by registered name, and asked for through a capability-backed request public middleware composes around but cannot issue, claim twice or answer | built on the #447 stack |
 | testing harness (`<Execution>`) | runs another document as a real root under a production host profile, authorized by canonical `<Test>` alone: declarations installed before the root import, child output displayed progressively and collected only when asked, journal retention selected independently of observation, and the outcome published by the invocation's own terminal through a request public middleware composes around but cannot answer | built on the #454 stack for `host="run"`; the workflow profile and `<WorkflowRun>` are unbuilt, and a host that offers no workflow profile refuses them |
 | `Config` run deadline / exec default / Fetch default | three independently owned contextual timeouts, absent unless configured, each read by exactly one consumer | built on main |
-| native session launch (`<Session.Launch>` / `Agent.launch()`) | prepares one durable coding-agent session from the rendered body of `<Session.Launch>` and hands the provider's native UI the terminal for that exact session, then continues the document after it exits. The body renders completely first and only what it rendered crosses as the instruction layer; the launch performs no model turn; the run's one foreground-terminal lease is taken before an agent is resolved, so a host with no terminal refuses without probing for an installed CLI; the ACPX provider installs the layer at session creation, refuses an agent whose native launcher is not advertised or that asserts no provider-native identity, releases ACP ownership before the spawn, and marks its handle stale so a later `<Prompt>` reattaches. Phases are retained as `agent_session_launch` records under one expansion identity — `prepared` before ownership is released, then `detached`, then `exited` — so a completed replay launches nothing and an interrupted one resumes the retained identity instead of creating a replacement session. The public route carries an opaque one-use launch request and answers nothing; authority to run and retain a phase is delivered to the installed provider directly, so neither a returned completion nor a rebuilt request authors a launch. Every operation that can act on an advertised provider-returned session takes exclusive ownership under one natural key first, through a coordinator the host built and passed in; contention refuses instead of queueing, an owner that never proved it stopped leaves a recovery tombstone, and a host that can build none refuses before contacting an agent. No launch path discards persistent provider state | built on the #517 stack; no real adapter is advertised, `Agent.AddDir` is unbuilt, and both fail closed |
+| native session launch (`<Session.Launch>` / `Agent.launch()`) | prepares one durable coding-agent session from the rendered body of `<Session.Launch>` and hands the provider's native UI the terminal for that exact session, then continues the document after it exits. The body renders completely first and only what it rendered crosses as the instruction layer; the launch performs no model turn; the run's one foreground-terminal lease is taken before an agent is resolved, so a host with no terminal refuses without probing for an installed CLI. A session is constructed once, by one of two mechanisms, and its create-once construction route says which. Where the provider returns the identity, the ACPX provider creates the session, installs the layer at creation, releases ACP ownership before the spawn, and marks its handle stale so a later `<Prompt>` reattaches. Where the adapter names its own sessions, it allocates the identity inside ownership before any process exists, the native process creates the session under that name from a private mode-0600 instruction file, and ACP creates nothing — the instruction text reaches neither argv nor environment, and the file is removed on success, failure and cancellation alike while ownership is still held. Neither route converts into the other: an eager `<Session>` publishes ACP-first before it establishes anything and keeps that account even if establishing fails, a launch meeting it refuses before an identity exists, and a `<Session>` or `<Prompt>` meeting a client-allocated route raises the provider's own route error rather than manufacturing a launch failure. Phases are retained as `agent_session_launch` records under one expansion identity — `prepared` before ownership is released, then `detached`, then `exited` — so a completed replay launches nothing, a replay holding only `prepared` proves the handoff never began and may still create under the retained identity, and one holding `detached` resumes and never falls back. The public route carries an opaque one-use launch request and answers nothing; authority to run and retain a phase is delivered to the installed provider directly, so neither a returned completion nor a rebuilt request authors a launch. Every operation that can act on an advertised session takes exclusive ownership under one natural key first, through a coordinator the host built and passed in; contention refuses instead of queueing, and an owner that never proved it stopped leaves a recovery tombstone. A host that cannot say who owns a session refuses every advertised operation, and one that cannot say how a session was constructed additionally refuses an agent that names its own — before any provider effect. Every private setup or child-creation failure is normalized to `process-creation-failed` with fixed provider-owned text, carrying no path, argv, environment or host message. No launch path discards persistent provider state | built on the #517 stack, extended by the #519 stack; Deno and the compiled binary assemble the host, Node and Bun refuse, no real adapter is advertised until #520's gate passes, `Agent.AddDir` is unbuilt, and ACP attachment to a client-allocated session is deferred with #517 |
 | `<Fetch>` | performs one XMD-mediated HTTP read through contextual `API.Fetch`, admitting the whole request before transport, and retains the normalized request and the detached response as one `fetch` durable observation; capture decides whether a status is data or a failure, and the trusted host's destination ceiling sits below the component | built on the #456 stack; a generated fragment may name the pinned identity only for a request the trusted host stated exactly, on the #369 stack |
 | `API.Files` | routes every document filesystem operation to the installed provider, with no host default and structural failure data | built on the #227 stack |
 | host Files provider / `useHostFiles()` | resolves document paths in the caller's filesystem, containing them while the host namespace is stable; installed by all four CLI entrypoints | built on the #227 stack |

packages/acp/mod.ts

@@ -28,7 +28,12 @@ export {
  knownNativeAdapters,
  nativeAdapterFor,
 } from "./src/native-launch.ts";
-export type { NativeAdapter } from "./src/native-launch.ts";
+export { allocatesIdentity } from "./src/native-launch.ts";
+export type {
+ ClientAllocatedAdapter,
+ NativeAdapter,
+ ProviderReturnedAdapter,
+} from "./src/native-launch.ts";
 
 export {
  AcpxPartitionError,
@@ -37,3 +42,19 @@ export {
 } from "./src/provider.ts";
 export type { AcpxPartitionSelector } from "./src/provider.ts";
 export type { AcpxProvider, ProbeCapableRuntime } from "./src/provider.ts";
+
+// The construction route: how a logical session was first constructed, kept
+// strictly and create-once beside the coordinator's own records. It is not an
+// Agent Api, a component, or a source of launch authority — the coordinator
+// remains the single live authority.
+export {
+ AgentSessionRouteError,
+ createDenoSessionRouteStore,
+ createMemorySessionRouteStore,
+ hasDenoSessionRouteStore,
+ parseAgentSessionRoute,
+ routeKey,
+ routeNamesKey,
+ serializeAgentSessionRoute,
+} from "./src/session-route.ts";
+export type { AgentSessionRouteStore, AgentSessionRouteV1 } from "./src/session-route.ts";

packages/acp/src/native-launch.ts

@@ -16,22 +16,78 @@
  * Until then `<Session.Launch>` refuses that agent before releasing its ACP
  * session, which is the failure the contract asks for rather than a hopeful
  * spawn.
+ *
+ * Adapters differ in one structural way, and it is discriminated rather than
+ * inferred: who chooses the provider-native session identity. A
+ * `provider-returned` adapter can only resume a session something else created
+ * and named. A `client-allocated` adapter names the session first and hands
+ * that name to the native process, which is what lets a launch construct a
+ * conversation instead of merely reattaching to one.
  */
 
-export interface NativeAdapter {
+import { randomUUID } from "node:crypto";
+import type { IdentityProvenance } from "@executablemd/core";
+
+interface AdapterCommands {
  /** Stable adapter identity — `claude`, `codex`. Never an executable path. */
  launcher: string;
+ /** Who chooses this adapter's native session identity. */
+ identity: IdentityProvenance;
  /** The argv that resumes this exact provider-native session. */
  resume(nativeSessionId: string): string[];
 }
 
+/**
+ * An adapter whose native UI is handed the session it is to create.
+ *
+ * `allocate` is the adapter's because the identity is that provider's dialect:
+ * what shape one takes and what the provider will accept is knowledge about
+ * the provider, not about launching in general. The provider decides whether a
+ * freshly allocated candidate wins publication; it does not decide what one
+ * looks like.
+ *
+ * The instruction layer crosses as a file path and never as text, so nothing
+ * here takes the instructions themselves.
+ */
+export interface ClientAllocatedAdapter extends AdapterCommands {
+ identity: "client-allocated";
+ /** A fresh provider-native session identity. */
+ allocate(): string;
+ /** The argv that creates a session under `id` with that instruction layer. */
+ create(nativeSessionId: string, instructionFile: string): string[];
+}
+
+export interface ProviderReturnedAdapter extends AdapterCommands {
+ identity: "provider-returned";
+}
+
+export type NativeAdapter = ProviderReturnedAdapter | ClientAllocatedAdapter;
+
+/** Whether this adapter names its own sessions. */
+export function allocatesIdentity(adapter: NativeAdapter): adapter is ClientAllocatedAdapter {
+ return adapter.identity === "client-allocated";
+}
+
 const ADAPTERS: Readonly<Record<string, NativeAdapter>> = {
  claude: {
  launcher: "claude",
+ // XMD names the session before Claude exists, so the native process is
+ // told which conversation to make rather than reporting one afterwards.
+ identity: "client-allocated",
+ // Claude takes a UUID it has never seen and makes it the session's name.
+ allocate: () => randomUUID(),
+ create: (nativeSessionId, instructionFile) => [
+ "claude",
+ "--session-id",
+ nativeSessionId,
+ "--system-prompt-file",
+ instructionFile,
+ ],
  resume: (nativeSessionId) => ["claude", "--resume", nativeSessionId],
  },
  codex: {
  launcher: "codex",
+ identity: "provider-returned",
  resume: (nativeSessionId) => ["codex", "resume", nativeSessionId],
  },
 };

architecture.md

@@ -86,6 +86,8 @@ Existing documents and code get aligned to this section retroactively.
 | launch request | the frozen, one-use value public launch middleware routes. It carries the facts of one launch and `with()`, and nothing that can settle one. Identity is object identity: a rebuilt look-alike describes the same ask and authorizes none of it |
 | provider authority | what core delivers to the provider factory it installs, as an argument that factory closes over. It validates the routed request, runs each absent phase once, cross-checks and retains what comes back, and derives the result. There is no reader for one, no context holding one, and no request member carrying one |
 | session coordinator | the host-built capability that answers who owns one logical agent session right now, across processes. It is passed directly into the provider that needs it and is deliberately not contextual: a decision document middleware could replace is not one. Acquisition never waits |
+| construction route | how one logical agent session was first constructed — through ACP, or under an identity XMD chose — as strict create-once durable state beside the coordinator's own records. It answers a different question from ownership and grants no right to act: the coordinator remains the single live authority. A route never converts, and a session ACP already established is recorded as ACP-first rather than reclassified |
+| identity provenance | who chose a provider-native session identity: the provider returned it, or the client allocated it before the provider existed. Retained rather than inferred, because after the fact both are just a string in the record. A released record written before the distinction existed reads as provider-returned, which is the only compatibility inference |
 | quiescence | the one-use acknowledgement an ownership body gives. It does not mean "I finished" — it means nothing this owner started can still act on the session, which is why a handoff that could not release its handle never gives it |
 | recovery tombstone | an ownership record left active because its owner never proved it stopped. A crash releases the kernel lock and not this, and no pid, elapsed time, released lock or empty transcript clears it |
 | provider partition | one complete, independently owned agent-provider state — runtime, store, managed sessions, queues, coordinator, teardown — selected by the one installed factory at each dispatch. Production is the single-partition case of the same path; holding a partition grants work, never permission |
@@ -2709,7 +2711,7 @@ Status is measured against main.
 | `exec as="name"` | binds one command's settled outcome — exit status, stdout and stderr — as an ordinary mutable binding; the block displays neither channel, renders nothing, and a nonzero status raises nothing. Only the built-in exec terminal and the built-in `timeout` may compose one, authorized by factory identity rather than by registered name, and asked for through a capability-backed request public middleware composes around but cannot issue, claim twice or answer | built on the #447 stack |
 | testing harness (`<Execution>`) | runs another document as a real root under a production host profile, authorized by canonical `<Test>` alone: declarations installed before the root import, child output displayed progressively and collected only when asked, journal retention selected independently of observation, and the outcome published by the invocation's own terminal through a request public middleware composes around but cannot answer | built on the #454 stack for `host="run"`; the workflow profile and `<WorkflowRun>` are unbuilt, and a host that offers no workflow profile refuses them |
 | `Config` run deadline / exec default / Fetch default | three independently owned contextual timeouts, absent unless configured, each read by exactly one consumer | built on main |
-| native session launch (`<Session.Launch>` / `Agent.launch()`) | prepares one durable coding-agent session from the rendered body of `<Session.Launch>` and hands the provider's native UI the terminal for that exact session, then continues the document after it exits. The body renders completely first and only what it rendered crosses as the instruction layer; the launch performs no model turn; the run's one foreground-terminal lease is taken before an agent is resolved, so a host with no terminal refuses without probing for an installed CLI; the ACPX provider installs the layer at session creation, refuses an agent whose native launcher is not advertised or that asserts no provider-native identity, releases ACP ownership before the spawn, and marks its handle stale so a later `<Prompt>` reattaches. Phases are retained as `agent_session_launch` records under one expansion identity — `prepared` before ownership is released, then `detached`, then `exited` — so a completed replay launches nothing and an interrupted one resumes the retained identity instead of creating a replacement session. The public route carries an opaque one-use launch request and answers nothing; authority to run and retain a phase is delivered to the installed provider directly, so neither a returned completion nor a rebuilt request authors a launch. Every operation that can act on an advertised provider-returned session takes exclusive ownership under one natural key first, through a coordinator the host built and passed in; contention refuses instead of queueing, an owner that never proved it stopped leaves a recovery tombstone, and a host that can build none refuses before contacting an agent. No launch path discards persistent provider state | built on the #517 stack; no real adapter is advertised, `Agent.AddDir` is unbuilt, and both fail closed |
+| native session launch (`<Session.Launch>` / `Agent.launch()`) | prepares one durable coding-agent session from the rendered body of `<Session.Launch>` and hands the provider's native UI the terminal for that exact session, then continues the document after it exits. The body renders completely first and only what it rendered crosses as the instruction layer; the launch performs no model turn; the run's one foreground-terminal lease is taken before an agent is resolved, so a host with no terminal refuses without probing for an installed CLI. A session is constructed once, by one of two mechanisms, and its create-once construction route says which. Where the provider returns the identity, the ACPX provider creates the session, installs the layer at creation, releases ACP ownership before the spawn, and marks its handle stale so a later `<Prompt>` reattaches. Where the adapter names its own sessions, it allocates the identity inside ownership before any process exists, the native process creates the session under that name from a private mode-0600 instruction file, and ACP creates nothing — the instruction text reaches neither argv nor environment, and the file is removed on success, failure and cancellation alike while ownership is still held. Neither route converts into the other: an eager `<Session>` publishes ACP-first before it establishes anything and keeps that account even if establishing fails, a launch meeting it refuses before an identity exists, and a `<Session>` or `<Prompt>` meeting a client-allocated route raises the provider's own route error rather than manufacturing a launch failure. Phases are retained as `agent_session_launch` records under one expansion identity — `prepared` before ownership is released, then `detached`, then `exited` — so a completed replay launches nothing, a replay holding only `prepared` proves the handoff never began and may still create under the retained identity, and one holding `detached` resumes and never falls back. The public route carries an opaque one-use launch request and answers nothing; authority to run and retain a phase is delivered to the installed provider directly, so neither a returned completion nor a rebuilt request authors a launch. Every operation that can act on an advertised session takes exclusive ownership under one natural key first, through a coordinator the host built and passed in; contention refuses instead of queueing, and an owner that never proved it stopped leaves a recovery tombstone. A host that cannot say who owns a session refuses every advertised operation, and one that cannot say how a session was constructed additionally refuses an agent that names its own — before any provider effect. Every private setup or child-creation failure is normalized to `process-creation-failed` with fixed provider-owned text, carrying no path, argv, environment or host message. No launch path discards persistent provider state | built on the #517 stack, extended by the #519 stack; Deno and the compiled binary assemble the host, Node and Bun refuse, no real adapter is advertised until #520's gate passes, `Agent.AddDir` is unbuilt, and ACP attachment to a client-allocated session is deferred with #517 |
 | `<Fetch>` | performs one XMD-mediated HTTP read through contextual `API.Fetch`, admitting the whole request before transport, and retains the normalized request and the detached response as one `fetch` durable observation; capture decides whether a status is data or a failure, and the trusted host's destination ceiling sits below the component | built on the #456 stack; a generated fragment may name the pinned identity only for a request the trusted host stated exactly, on the #369 stack |
 | `API.Files` | routes every document filesystem operation to the installed provider, with no host default and structural failure data | built on the #227 stack |
 | host Files provider / `useHostFiles()` | resolves document paths in the caller's filesystem, containing them while the host namespace is stable; installed by all four CLI entrypoints | built on the #227 stack |

packages/acp/mod.ts

@@ -28,7 +28,12 @@ export {
  knownNativeAdapters,
  nativeAdapterFor,
 } from "./src/native-launch.ts";
-export type { NativeAdapter } from "./src/native-launch.ts";
+export { allocatesIdentity } from "./src/native-launch.ts";
+export type {
+ ClientAllocatedAdapter,
+ NativeAdapter,
+ ProviderReturnedAdapter,
+} from "./src/native-launch.ts";
 
 export {
  AcpxPartitionError,
@@ -37,3 +42,19 @@ export {
 } from "./src/provider.ts";
 export type { AcpxPartitionSelector } from "./src/provider.ts";
 export type { AcpxProvider, ProbeCapableRuntime } from "./src/provider.ts";
+
+// The construction route: how a logical session was first constructed, kept
+// strictly and create-once beside the coordinator's own records. It is not an
+// Agent Api, a component, or a source of launch authority — the coordinator
+// remains the single live authority.
+export {
+ AgentSessionRouteError,
+ createDenoSessionRouteStore,
+ createMemorySessionRouteStore,
+ hasDenoSessionRouteStore,
+ parseAgentSessionRoute,
+ routeKey,
+ routeNamesKey,
+ serializeAgentSessionRoute,
+} from "./src/session-route.ts";
+export type { AgentSessionRouteStore, AgentSessionRouteV1 } from "./src/session-route.ts";

packages/acp/src/native-launch.ts

@@ -16,22 +16,78 @@
  * Until then `<Session.Launch>` refuses that agent before releasing its ACP
  * session, which is the failure the contract asks for rather than a hopeful
  * spawn.
+ *
+ * Adapters differ in one structural way, and it is discriminated rather than
+ * inferred: who chooses the provider-native session identity. A
+ * `provider-returned` adapter can only resume a session something else created
+ * and named. A `client-allocated` adapter names the session first and hands
+ * that name to the native process, which is what lets a launch construct a
+ * conversation instead of merely reattaching to one.
  */
 
-export interface NativeAdapter {
+import { randomUUID } from "node:crypto";
+import type { IdentityProvenance } from "@executablemd/core";
+
+interface AdapterCommands {
  /** Stable adapter identity — `claude`, `codex`. Never an executable path. */
  launcher: string;
+ /** Who chooses this adapter's native session identity. */
+ identity: IdentityProvenance;
  /** The argv that resumes this exact provider-native session. */
  resume(nativeSessionId: string): string[];
 }
 
+/**
+ * An adapter whose native UI is handed the session it is to create.
+ *
+ * `allocate` is the adapter's because the identity is that provider's dialect:
+ * what shape one takes and what the provider will accept is knowledge about
+ * the provider, not about launching in general. The provider decides whether a
+ * freshly allocated candidate wins publication; it does not decide what one
+ * looks like.
+ *
+ * The instruction layer crosses as a file path and never as text, so nothing
+ * here takes the instructions themselves.
+ */
+export interface ClientAllocatedAdapter extends AdapterCommands {
+ identity: "client-allocated";
+ /** A fresh provider-native session identity. */
+ allocate(): string;
+ /** The argv that creates a session under `id` with that instruction layer. */
+ create(nativeSessionId: string, instructionFile: string): string[];
+}
+
+export interface ProviderReturnedAdapter extends AdapterCommands {
+ identity: "provider-returned";
+}
+
+export type NativeAdapter = ProviderReturnedAdapter | ClientAllocatedAdapter;
+
+/** Whether this adapter names its own sessions. */
+export function allocatesIdentity(adapter: NativeAdapter): adapter is ClientAllocatedAdapter {
+ return adapter.identity === "client-allocated";
+}
+
 const ADAPTERS: Readonly<Record<string, NativeAdapter>> = {
  claude: {
  launcher: "claude",
+ // XMD names the session before Claude exists, so the native process is
+ // told which conversation to make rather than reporting one afterwards.
+ identity: "client-allocated",
+ // Claude takes a UUID it has never seen and makes it the session's name.
+ allocate: () => randomUUID(),
+ create: (nativeSessionId, instructionFile) => [
+ "claude",
+ "--session-id",
+ nativeSessionId,
+ "--system-prompt-file",
+ instructionFile,
+ ],
  resume: (nativeSessionId) => ["claude", "--resume", nativeSessionId],
  },
  codex: {
  launcher: "codex",
+ identity: "provider-returned",
  resume: (nativeSessionId) => ["codex", "resume", nativeSessionId],
  },
 };

architecture.md

@@ -86,6 +86,8 @@ Existing documents and code get aligned to this section retroactively.
 | launch request | the frozen, one-use value public launch middleware routes. It carries the facts of one launch and `with()`, and nothing that can settle one. Identity is object identity: a rebuilt look-alike describes the same ask and authorizes none of it |
 | provider authority | what core delivers to the provider factory it installs, as an argument that factory closes over. It validates the routed request, runs each absent phase once, cross-checks and retains what comes back, and derives the result. There is no reader for one, no context holding one, and no request member carrying one |
 | session coordinator | the host-built capability that answers who owns one logical agent session right now, across processes. It is passed directly into the provider that needs it and is deliberately not contextual: a decision document middleware could replace is not one. Acquisition never waits |
+| construction route | how one logical agent session was first constructed — through ACP, or under an identity XMD chose — as strict create-once durable state beside the coordinator's own records. It answers a different question from ownership and grants no right to act: the coordinator remains the single live authority. A route never converts, and a session ACP already established is recorded as ACP-first rather than reclassified |
+| identity provenance | who chose a provider-native session identity: the provider returned it, or the client allocated it before the provider existed. Retained rather than inferred, because after the fact both are just a string in the record. A released record written before the distinction existed reads as provider-returned, which is the only compatibility inference |
 | quiescence | the one-use acknowledgement an ownership body gives. It does not mean "I finished" — it means nothing this owner started can still act on the session, which is why a handoff that could not release its handle never gives it |
 | recovery tombstone | an ownership record left active because its owner never proved it stopped. A crash releases the kernel lock and not this, and no pid, elapsed time, released lock or empty transcript clears it |
 | provider partition | one complete, independently owned agent-provider state — runtime, store, managed sessions, queues, coordinator, teardown — selected by the one installed factory at each dispatch. Production is the single-partition case of the same path; holding a partition grants work, never permission |
@@ -2709,7 +2711,7 @@ Status is measured against main.
 | `exec as="name"` | binds one command's settled outcome — exit status, stdout and stderr — as an ordinary mutable binding; the block displays neither channel, renders nothing, and a nonzero status raises nothing. Only the built-in exec terminal and the built-in `timeout` may compose one, authorized by factory identity rather than by registered name, and asked for through a capability-backed request public middleware composes around but cannot issue, claim twice or answer | built on the #447 stack |
 | testing harness (`<Execution>`) | runs another document as a real root under a production host profile, authorized by canonical `<Test>` alone: declarations installed before the root import, child output displayed progressively and collected only when asked, journal retention selected independently of observation, and the outcome published by the invocation's own terminal through a request public middleware composes around but cannot answer | built on the #454 stack for `host="run"`; the workflow profile and `<WorkflowRun>` are unbuilt, and a host that offers no workflow profile refuses them |
 | `Config` run deadline / exec default / Fetch default | three independently owned contextual timeouts, absent unless configured, each read by exactly one consumer | built on main |
-| native session launch (`<Session.Launch>` / `Agent.launch()`) | prepares one durable coding-agent session from the rendered body of `<Session.Launch>` and hands the provider's native UI the terminal for that exact session, then continues the document after it exits. The body renders completely first and only what it rendered crosses as the instruction layer; the launch performs no model turn; the run's one foreground-terminal lease is taken before an agent is resolved, so a host with no terminal refuses without probing for an installed CLI; the ACPX provider installs the layer at session creation, refuses an agent whose native launcher is not advertised or that asserts no provider-native identity, releases ACP ownership before the spawn, and marks its handle stale so a later `<Prompt>` reattaches. Phases are retained as `agent_session_launch` records under one expansion identity — `prepared` before ownership is released, then `detached`, then `exited` — so a completed replay launches nothing and an interrupted one resumes the retained identity instead of creating a replacement session. The public route carries an opaque one-use launch request and answers nothing; authority to run and retain a phase is delivered to the installed provider directly, so neither a returned completion nor a rebuilt request authors a launch. Every operation that can act on an advertised provider-returned session takes exclusive ownership under one natural key first, through a coordinator the host built and passed in; contention refuses instead of queueing, an owner that never proved it stopped leaves a recovery tombstone, and a host that can build none refuses before contacting an agent. No launch path discards persistent provider state | built on the #517 stack; no real adapter is advertised, `Agent.AddDir` is unbuilt, and both fail closed |
+| native session launch (`<Session.Launch>` / `Agent.launch()`) | prepares one durable coding-agent session from the rendered body of `<Session.Launch>` and hands the provider's native UI the terminal for that exact session, then continues the document after it exits. The body renders completely first and only what it rendered crosses as the instruction layer; the launch performs no model turn; the run's one foreground-terminal lease is taken before an agent is resolved, so a host with no terminal refuses without probing for an installed CLI. A session is constructed once, by one of two mechanisms, and its create-once construction route says which. Where the provider returns the identity, the ACPX provider creates the session, installs the layer at creation, releases ACP ownership before the spawn, and marks its handle stale so a later `<Prompt>` reattaches. Where the adapter names its own sessions, it allocates the identity inside ownership before any process exists, the native process creates the session under that name from a private mode-0600 instruction file, and ACP creates nothing — the instruction text reaches neither argv nor environment, and the file is removed on success, failure and cancellation alike while ownership is still held. Neither route converts into the other: an eager `<Session>` publishes ACP-first before it establishes anything and keeps that account even if establishing fails, a launch meeting it refuses before an identity exists, and a `<Session>` or `<Prompt>` meeting a client-allocated route raises the provider's own route error rather than manufacturing a launch failure. Phases are retained as `agent_session_launch` records under one expansion identity — `prepared` before ownership is released, then `detached`, then `exited` — so a completed replay launches nothing, a replay holding only `prepared` proves the handoff never began and may still create under the retained identity, and one holding `detached` resumes and never falls back. The public route carries an opaque one-use launch request and answers nothing; authority to run and retain a phase is delivered to the installed provider directly, so neither a returned completion nor a rebuilt request authors a launch. Every operation that can act on an advertised session takes exclusive ownership under one natural key first, through a coordinator the host built and passed in; contention refuses instead of queueing, and an owner that never proved it stopped leaves a recovery tombstone. A host that cannot say who owns a session refuses every advertised operation, and one that cannot say how a session was constructed additionally refuses an agent that names its own — before any provider effect. Every private setup or child-creation failure is normalized to `process-creation-failed` with fixed provider-owned text, carrying no path, argv, environment or host message. No launch path discards persistent provider state | built on the #517 stack, extended by the #519 stack; Deno and the compiled binary assemble the host, Node and Bun refuse, no real adapter is advertised until #520's gate passes, `Agent.AddDir` is unbuilt, and ACP attachment to a client-allocated session is deferred with #517 |
 | `<Fetch>` | performs one XMD-mediated HTTP read through contextual `API.Fetch`, admitting the whole request before transport, and retains the normalized request and the detached response as one `fetch` durable observation; capture decides whether a status is data or a failure, and the trusted host's destination ceiling sits below the component | built on the #456 stack; a generated fragment may name the pinned identity only for a request the trusted host stated exactly, on the #369 stack |
 | `API.Files` | routes every document filesystem operation to the installed provider, with no host default and structural failure data | built on the #227 stack |
 | host Files provider / `useHostFiles()` | resolves document paths in the caller's filesystem, containing them while the host namespace is stable; installed by all four CLI entrypoints | built on the #227 stack |

packages/acp/mod.ts

@@ -28,7 +28,12 @@ export {
  knownNativeAdapters,
  nativeAdapterFor,
 } from "./src/native-launch.ts";
-export type { NativeAdapter } from "./src/native-launch.ts";
+export { allocatesIdentity } from "./src/native-launch.ts";
+export type {
+ ClientAllocatedAdapter,
+ NativeAdapter,
+ ProviderReturnedAdapter,
+} from "./src/native-launch.ts";
 
 export {
  AcpxPartitionError,
@@ -37,3 +42,19 @@ export {
 } from "./src/provider.ts";
 export type { AcpxPartitionSelector } from "./src/provider.ts";
 export type { AcpxProvider, ProbeCapableRuntime } from "./src/provider.ts";
+
+// The construction route: how a logical session was first constructed, kept
+// strictly and create-once beside the coordinator's own records. It is not an
+// Agent Api, a component, or a source of launch authority — the coordinator
+// remains the single live authority.
+export {
+ AgentSessionRouteError,
+ createDenoSessionRouteStore,
+ createMemorySessionRouteStore,
+ hasDenoSessionRouteStore,
+ parseAgentSessionRoute,
+ routeKey,
+ routeNamesKey,
+ serializeAgentSessionRoute,
+} from "./src/session-route.ts";
+export type { AgentSessionRouteStore, AgentSessionRouteV1 } from "./src/session-route.ts";

packages/acp/src/native-launch.ts

@@ -16,22 +16,78 @@
  * Until then `<Session.Launch>` refuses that agent before releasing its ACP
  * session, which is the failure the contract asks for rather than a hopeful
  * spawn.
+ *
+ * Adapters differ in one structural way, and it is discriminated rather than
+ * inferred: who chooses the provider-native session identity. A
+ * `provider-returned` adapter can only resume a session something else created
+ * and named. A `client-allocated` adapter names the session first and hands
+ * that name to the native process, which is what lets a launch construct a
+ * conversation instead of merely reattaching to one.
  */
 
-export interface NativeAdapter {
+import { randomUUID } from "node:crypto";
+import type { IdentityProvenance } from "@executablemd/core";
+
+interface AdapterCommands {
  /** Stable adapter identity — `claude`, `codex`. Never an executable path. */
  launcher: string;
+ /** Who chooses this adapter's native session identity. */
+ identity: IdentityProvenance;
  /** The argv that resumes this exact provider-native session. */
  resume(nativeSessionId: string): string[];
 }
 
+/**
+ * An adapter whose native UI is handed the session it is to create.
+ *
+ * `allocate` is the adapter's because the identity is that provider's dialect:
+ * what shape one takes and what the provider will accept is knowledge about
+ * the provider, not about launching in general. The provider decides whether a
+ * freshly allocated candidate wins publication; it does not decide what one
+ * looks like.
+ *
+ * The instruction layer crosses as a file path and never as text, so nothing
+ * here takes the instructions themselves.
+ */
+export interface ClientAllocatedAdapter extends AdapterCommands {
+ identity: "client-allocated";
+ /** A fresh provider-native session identity. */
+ allocate(): string;
+ /** The argv that creates a session under `id` with that instruction layer. */
+ create(nativeSessionId: string, instructionFile: string): string[];
+}
+
+export interface ProviderReturnedAdapter extends AdapterCommands {
+ identity: "provider-returned";
+}
+
+export type NativeAdapter = ProviderReturnedAdapter | ClientAllocatedAdapter;
+
+/** Whether this adapter names its own sessions. */
+export function allocatesIdentity(adapter: NativeAdapter): adapter is ClientAllocatedAdapter {
+ return adapter.identity === "client-allocated";
+}
+
 const ADAPTERS: Readonly<Record<string, NativeAdapter>> = {
  claude: {
  launcher: "claude",
+ // XMD names the session before Claude exists, so the native process is
+ // told which conversation to make rather than reporting one afterwards.
+ identity: "client-allocated",
+ // Claude takes a UUID it has never seen and makes it the session's name.
+ allocate: () => randomUUID(),
+ create: (nativeSessionId, instructionFile) => [
+ "claude",
+ "--session-id",
+ nativeSessionId,
+ "--system-prompt-file",
+ instructionFile,
+ ],
  resume: (nativeSessionId) => ["claude", "--resume", nativeSessionId],
  },
  codex: {
  launcher: "codex",
+ identity: "provider-returned",
  resume: (nativeSessionId) => ["codex", "resume", nativeSessionId],
  },
 };

architecture.md

@@ -86,6 +86,8 @@ Existing documents and code get aligned to this section retroactively.
 | launch request | the frozen, one-use value public launch middleware routes. It carries the facts of one launch and `with()`, and nothing that can settle one. Identity is object identity: a rebuilt look-alike describes the same ask and authorizes none of it |
 | provider authority | what core delivers to the provider factory it installs, as an argument that factory closes over. It validates the routed request, runs each absent phase once, cross-checks and retains what comes back, and derives the result. There is no reader for one, no context holding one, and no request member carrying one |
 | session coordinator | the host-built capability that answers who owns one logical agent session right now, across processes. It is passed directly into the provider that needs it and is deliberately not contextual: a decision document middleware could replace is not one. Acquisition never waits |
+| construction route | how one logical agent session was first constructed — through ACP, or under an identity XMD chose — as strict create-once durable state beside the coordinator's own records. It answers a different question from ownership and grants no right to act: the coordinator remains the single live authority. A route never converts, and a session ACP already established is recorded as ACP-first rather than reclassified |
+| identity provenance | who chose a provider-native session identity: the provider returned it, or the client allocated it before the provider existed. Retained rather than inferred, because after the fact both are just a string in the record. A released record written before the distinction existed reads as provider-returned, which is the only compatibility inference |
 | quiescence | the one-use acknowledgement an ownership body gives. It does not mean "I finished" — it means nothing this owner started can still act on the session, which is why a handoff that could not release its handle never gives it |
 | recovery tombstone | an ownership record left active because its owner never proved it stopped. A crash releases the kernel lock and not this, and no pid, elapsed time, released lock or empty transcript clears it |
 | provider partition | one complete, independently owned agent-provider state — runtime, store, managed sessions, queues, coordinator, teardown — selected by the one installed factory at each dispatch. Production is the single-partition case of the same path; holding a partition grants work, never permission |
@@ -2709,7 +2711,7 @@ Status is measured against main.
 | `exec as="name"` | binds one command's settled outcome — exit status, stdout and stderr — as an ordinary mutable binding; the block displays neither channel, renders nothing, and a nonzero status raises nothing. Only the built-in exec terminal and the built-in `timeout` may compose one, authorized by factory identity rather than by registered name, and asked for through a capability-backed request public middleware composes around but cannot issue, claim twice or answer | built on the #447 stack |
 | testing harness (`<Execution>`) | runs another document as a real root under a production host profile, authorized by canonical `<Test>` alone: declarations installed before the root import, child output displayed progressively and collected only when asked, journal retention selected independently of observation, and the outcome published by the invocation's own terminal through a request public middleware composes around but cannot answer | built on the #454 stack for `host="run"`; the workflow profile and `<WorkflowRun>` are unbuilt, and a host that offers no workflow profile refuses them |
 | `Config` run deadline / exec default / Fetch default | three independently owned contextual timeouts, absent unless configured, each read by exactly one consumer | built on main |
-| native session launch (`<Session.Launch>` / `Agent.launch()`) | prepares one durable coding-agent session from the rendered body of `<Session.Launch>` and hands the provider's native UI the terminal for that exact session, then continues the document after it exits. The body renders completely first and only what it rendered crosses as the instruction layer; the launch performs no model turn; the run's one foreground-terminal lease is taken before an agent is resolved, so a host with no terminal refuses without probing for an installed CLI; the ACPX provider installs the layer at session creation, refuses an agent whose native launcher is not advertised or that asserts no provider-native identity, releases ACP ownership before the spawn, and marks its handle stale so a later `<Prompt>` reattaches. Phases are retained as `agent_session_launch` records under one expansion identity — `prepared` before ownership is released, then `detached`, then `exited` — so a completed replay launches nothing and an interrupted one resumes the retained identity instead of creating a replacement session. The public route carries an opaque one-use launch request and answers nothing; authority to run and retain a phase is delivered to the installed provider directly, so neither a returned completion nor a rebuilt request authors a launch. Every operation that can act on an advertised provider-returned session takes exclusive ownership under one natural key first, through a coordinator the host built and passed in; contention refuses instead of queueing, an owner that never proved it stopped leaves a recovery tombstone, and a host that can build none refuses before contacting an agent. No launch path discards persistent provider state | built on the #517 stack; no real adapter is advertised, `Agent.AddDir` is unbuilt, and both fail closed |
+| native session launch (`<Session.Launch>` / `Agent.launch()`) | prepares one durable coding-agent session from the rendered body of `<Session.Launch>` and hands the provider's native UI the terminal for that exact session, then continues the document after it exits. The body renders completely first and only what it rendered crosses as the instruction layer; the launch performs no model turn; the run's one foreground-terminal lease is taken before an agent is resolved, so a host with no terminal refuses without probing for an installed CLI. A session is constructed once, by one of two mechanisms, and its create-once construction route says which. Where the provider returns the identity, the ACPX provider creates the session, installs the layer at creation, releases ACP ownership before the spawn, and marks its handle stale so a later `<Prompt>` reattaches. Where the adapter names its own sessions, it allocates the identity inside ownership before any process exists, the native process creates the session under that name from a private mode-0600 instruction file, and ACP creates nothing — the instruction text reaches neither argv nor environment, and the file is removed on success, failure and cancellation alike while ownership is still held. Neither route converts into the other: an eager `<Session>` publishes ACP-first before it establishes anything and keeps that account even if establishing fails, a launch meeting it refuses before an identity exists, and a `<Session>` or `<Prompt>` meeting a client-allocated route raises the provider's own route error rather than manufacturing a launch failure. Phases are retained as `agent_session_launch` records under one expansion identity — `prepared` before ownership is released, then `detached`, then `exited` — so a completed replay launches nothing, a replay holding only `prepared` proves the handoff never began and may still create under the retained identity, and one holding `detached` resumes and never falls back. The public route carries an opaque one-use launch request and answers nothing; authority to run and retain a phase is delivered to the installed provider directly, so neither a returned completion nor a rebuilt request authors a launch. Every operation that can act on an advertised session takes exclusive ownership under one natural key first, through a coordinator the host built and passed in; contention refuses instead of queueing, and an owner that never proved it stopped leaves a recovery tombstone. A host that cannot say who owns a session refuses every advertised operation, and one that cannot say how a session was constructed additionally refuses an agent that names its own — before any provider effect. Every private setup or child-creation failure is normalized to `process-creation-failed` with fixed provider-owned text, carrying no path, argv, environment or host message. No launch path discards persistent provider state | built on the #517 stack, extended by the #519 stack; Deno and the compiled binary assemble the host, Node and Bun refuse, no real adapter is advertised until #520's gate passes, `Agent.AddDir` is unbuilt, and ACP attachment to a client-allocated session is deferred with #517 |
 | `<Fetch>` | performs one XMD-mediated HTTP read through contextual `API.Fetch`, admitting the whole request before transport, and retains the normalized request and the detached response as one `fetch` durable observation; capture decides whether a status is data or a failure, and the trusted host's destination ceiling sits below the component | built on the #456 stack; a generated fragment may name the pinned identity only for a request the trusted host stated exactly, on the #369 stack |
 | `API.Files` | routes every document filesystem operation to the installed provider, with no host default and structural failure data | built on the #227 stack |
 | host Files provider / `useHostFiles()` | resolves document paths in the caller's filesystem, containing them while the host namespace is stable; installed by all four CLI entrypoints | built on the #227 stack |

packages/acp/mod.ts

@@ -28,7 +28,12 @@ export {
  knownNativeAdapters,
  nativeAdapterFor,
 } from "./src/native-launch.ts";
-export type { NativeAdapter } from "./src/native-launch.ts";
+export { allocatesIdentity } from "./src/native-launch.ts";
+export type {
+ ClientAllocatedAdapter,
+ NativeAdapter,
+ ProviderReturnedAdapter,
+} from "./src/native-launch.ts";
 
 export {
  AcpxPartitionError,
@@ -37,3 +42,19 @@ export {
 } from "./src/provider.ts";
 export type { AcpxPartitionSelector } from "./src/provider.ts";
 export type { AcpxProvider, ProbeCapableRuntime } from "./src/provider.ts";
+
+// The construction route: how a logical session was first constructed, kept
+// strictly and create-once beside the coordinator's own records. It is not an
+// Agent Api, a component, or a source of launch authority — the coordinator
+// remains the single live authority.
+export {
+ AgentSessionRouteError,
+ createDenoSessionRouteStore,
+ createMemorySessionRouteStore,
+ hasDenoSessionRouteStore,
+ parseAgentSessionRoute,
+ routeKey,
+ routeNamesKey,
+ serializeAgentSessionRoute,
+} from "./src/session-route.ts";
+export type { AgentSessionRouteStore, AgentSessionRouteV1 } from "./src/session-route.ts";

packages/acp/src/native-launch.ts

@@ -16,22 +16,78 @@
  * Until then `<Session.Launch>` refuses that agent before releasing its ACP
  * session, which is the failure the contract asks for rather than a hopeful
  * spawn.
+ *
+ * Adapters differ in one structural way, and it is discriminated rather than
+ * inferred: who chooses the provider-native session identity. A
+ * `provider-returned` adapter can only resume a session something else created
+ * and named. A `client-allocated` adapter names the session first and hands
+ * that name to the native process, which is what lets a launch construct a
+ * conversation instead of merely reattaching to one.
  */
 
-export interface NativeAdapter {
+import { randomUUID } from "node:crypto";
+import type { IdentityProvenance } from "@executablemd/core";
+
+interface AdapterCommands {
  /** Stable adapter identity — `claude`, `codex`. Never an executable path. */
  launcher: string;
+ /** Who chooses this adapter's native session identity. */
+ identity: IdentityProvenance;
  /** The argv that resumes this exact provider-native session. */
  resume(nativeSessionId: string): string[];
 }
 
+/**
+ * An adapter whose native UI is handed the session it is to create.
+ *
+ * `allocate` is the adapter's because the identity is that provider's dialect:
+ * what shape one takes and what the provider will accept is knowledge about
+ * the provider, not about launching in general. The provider decides whether a
+ * freshly allocated candidate wins publication; it does not decide what one
+ * looks like.
+ *
+ * The instruction layer crosses as a file path and never as text, so nothing
+ * here takes the instructions themselves.
+ */
+export interface ClientAllocatedAdapter extends AdapterCommands {
+ identity: "client-allocated";
+ /** A fresh provider-native session identity. */
+ allocate(): string;
+ /** The argv that creates a session under `id` with that instruction layer. */
+ create(nativeSessionId: string, instructionFile: string): string[];
+}
+
+export interface ProviderReturnedAdapter extends AdapterCommands {
+ identity: "provider-returned";
+}
+
+export type NativeAdapter = ProviderReturnedAdapter | ClientAllocatedAdapter;
+
+/** Whether this adapter names its own sessions. */
+export function allocatesIdentity(adapter: NativeAdapter): adapter is ClientAllocatedAdapter {
+ return adapter.identity === "client-allocated";
+}
+
 const ADAPTERS: Readonly<Record<string, NativeAdapter>> = {
  claude: {
  launcher: "claude",
+ // XMD names the session before Claude exists, so the native process is
+ // told which conversation to make rather than reporting one afterwards.
+ identity: "client-allocated",
+ // Claude takes a UUID it has never seen and makes it the session's name.
+ allocate: () => randomUUID(),
+ create: (nativeSessionId, instructionFile) => [
+ "claude",
+ "--session-id",
+ nativeSessionId,
+ "--system-prompt-file",
+ instructionFile,
+ ],
  resume: (nativeSessionId) => ["claude", "--resume", nativeSessionId],
  },
  codex: {
  launcher: "codex",
+ identity: "provider-returned",
  resume: (nativeSessionId) => ["codex", "resume", nativeSessionId],
  },
 };

architecture.md

@@ -86,6 +86,8 @@ Existing documents and code get aligned to this section retroactively.
 | launch request | the frozen, one-use value public launch middleware routes. It carries the facts of one launch and `with()`, and nothing that can settle one. Identity is object identity: a rebuilt look-alike describes the same ask and authorizes none of it |
 | provider authority | what core delivers to the provider factory it installs, as an argument that factory closes over. It validates the routed request, runs each absent phase once, cross-checks and retains what comes back, and derives the result. There is no reader for one, no context holding one, and no request member carrying one |
 | session coordinator | the host-built capability that answers who owns one logical agent session right now, across processes. It is passed directly into the provider that needs it and is deliberately not contextual: a decision document middleware could replace is not one. Acquisition never waits |
+| construction route | how one logical agent session was first constructed — through ACP, or under an identity XMD chose — as strict create-once durable state beside the coordinator's own records. It answers a different question from ownership and grants no right to act: the coordinator remains the single live authority. A route never converts, and a session ACP already established is recorded as ACP-first rather than reclassified |
+| identity provenance | who chose a provider-native session identity: the provider returned it, or the client allocated it before the provider existed. Retained rather than inferred, because after the fact both are just a string in the record. A released record written before the distinction existed reads as provider-returned, which is the only compatibility inference |
 | quiescence | the one-use acknowledgement an ownership body gives. It does not mean "I finished" — it means nothing this owner started can still act on the session, which is why a handoff that could not release its handle never gives it |
 | recovery tombstone | an ownership record left active because its owner never proved it stopped. A crash releases the kernel lock and not this, and no pid, elapsed time, released lock or empty transcript clears it |
 | provider partition | one complete, independently owned agent-provider state — runtime, store, managed sessions, queues, coordinator, teardown — selected by the one installed factory at each dispatch. Production is the single-partition case of the same path; holding a partition grants work, never permission |
@@ -2709,7 +2711,7 @@ Status is measured against main.
 | `exec as="name"` | binds one command's settled outcome — exit status, stdout and stderr — as an ordinary mutable binding; the block displays neither channel, renders nothing, and a nonzero status raises nothing. Only the built-in exec terminal and the built-in `timeout` may compose one, authorized by factory identity rather than by registered name, and asked for through a capability-backed request public middleware composes around but cannot issue, claim twice or answer | built on the #447 stack |
 | testing harness (`<Execution>`) | runs another document as a real root under a production host profile, authorized by canonical `<Test>` alone: declarations installed before the root import, child output displayed progressively and collected only when asked, journal retention selected independently of observation, and the outcome published by the invocation's own terminal through a request public middleware composes around but cannot answer | built on the #454 stack for `host="run"`; the workflow profile and `<WorkflowRun>` are unbuilt, and a host that offers no workflow profile refuses them |
 | `Config` run deadline / exec default / Fetch default | three independently owned contextual timeouts, absent unless configured, each read by exactly one consumer | built on main |
-| native session launch (`<Session.Launch>` / `Agent.launch()`) | prepares one durable coding-agent session from the rendered body of `<Session.Launch>` and hands the provider's native UI the terminal for that exact session, then continues the document after it exits. The body renders completely first and only what it rendered crosses as the instruction layer; the launch performs no model turn; the run's one foreground-terminal lease is taken before an agent is resolved, so a host with no terminal refuses without probing for an installed CLI; the ACPX provider installs the layer at session creation, refuses an agent whose native launcher is not advertised or that asserts no provider-native identity, releases ACP ownership before the spawn, and marks its handle stale so a later `<Prompt>` reattaches. Phases are retained as `agent_session_launch` records under one expansion identity — `prepared` before ownership is released, then `detached`, then `exited` — so a completed replay launches nothing and an interrupted one resumes the retained identity instead of creating a replacement session. The public route carries an opaque one-use launch request and answers nothing; authority to run and retain a phase is delivered to the installed provider directly, so neither a returned completion nor a rebuilt request authors a launch. Every operation that can act on an advertised provider-returned session takes exclusive ownership under one natural key first, through a coordinator the host built and passed in; contention refuses instead of queueing, an owner that never proved it stopped leaves a recovery tombstone, and a host that can build none refuses before contacting an agent. No launch path discards persistent provider state | built on the #517 stack; no real adapter is advertised, `Agent.AddDir` is unbuilt, and both fail closed |
+| native session launch (`<Session.Launch>` / `Agent.launch()`) | prepares one durable coding-agent session from the rendered body of `<Session.Launch>` and hands the provider's native UI the terminal for that exact session, then continues the document after it exits. The body renders completely first and only what it rendered crosses as the instruction layer; the launch performs no model turn; the run's one foreground-terminal lease is taken before an agent is resolved, so a host with no terminal refuses without probing for an installed CLI. A session is constructed once, by one of two mechanisms, and its create-once construction route says which. Where the provider returns the identity, the ACPX provider creates the session, installs the layer at creation, releases ACP ownership before the spawn, and marks its handle stale so a later `<Prompt>` reattaches. Where the adapter names its own sessions, it allocates the identity inside ownership before any process exists, the native process creates the session under that name from a private mode-0600 instruction file, and ACP creates nothing — the instruction text reaches neither argv nor environment, and the file is removed on success, failure and cancellation alike while ownership is still held. Neither route converts into the other: an eager `<Session>` publishes ACP-first before it establishes anything and keeps that account even if establishing fails, a launch meeting it refuses before an identity exists, and a `<Session>` or `<Prompt>` meeting a client-allocated route raises the provider's own route error rather than manufacturing a launch failure. Phases are retained as `agent_session_launch` records under one expansion identity — `prepared` before ownership is released, then `detached`, then `exited` — so a completed replay launches nothing, a replay holding only `prepared` proves the handoff never began and may still create under the retained identity, and one holding `detached` resumes and never falls back. The public route carries an opaque one-use launch request and answers nothing; authority to run and retain a phase is delivered to the installed provider directly, so neither a returned completion nor a rebuilt request authors a launch. Every operation that can act on an advertised session takes exclusive ownership under one natural key first, through a coordinator the host built and passed in; contention refuses instead of queueing, and an owner that never proved it stopped leaves a recovery tombstone. A host that cannot say who owns a session refuses every advertised operation, and one that cannot say how a session was constructed additionally refuses an agent that names its own — before any provider effect. Every private setup or child-creation failure is normalized to `process-creation-failed` with fixed provider-owned text, carrying no path, argv, environment or host message. No launch path discards persistent provider state | built on the #517 stack, extended by the #519 stack; Deno and the compiled binary assemble the host, Node and Bun refuse, no real adapter is advertised until #520's gate passes, `Agent.AddDir` is unbuilt, and ACP attachment to a client-allocated session is deferred with #517 |
 | `<Fetch>` | performs one XMD-mediated HTTP read through contextual `API.Fetch`, admitting the whole request before transport, and retains the normalized request and the detached response as one `fetch` durable observation; capture decides whether a status is data or a failure, and the trusted host's destination ceiling sits below the component | built on the #456 stack; a generated fragment may name the pinned identity only for a request the trusted host stated exactly, on the #369 stack |
 | `API.Files` | routes every document filesystem operation to the installed provider, with no host default and structural failure data | built on the #227 stack |
 | host Files provider / `useHostFiles()` | resolves document paths in the caller's filesystem, containing them while the host namespace is stable; installed by all four CLI entrypoints | built on the #227 stack |

packages/acp/mod.ts

@@ -28,7 +28,12 @@ export {
  knownNativeAdapters,
  nativeAdapterFor,
 } from "./src/native-launch.ts";
-export type { NativeAdapter } from "./src/native-launch.ts";
+export { allocatesIdentity } from "./src/native-launch.ts";
+export type {
+ ClientAllocatedAdapter,
+ NativeAdapter,
+ ProviderReturnedAdapter,
+} from "./src/native-launch.ts";
 
 export {
  AcpxPartitionError,
@@ -37,3 +42,19 @@ export {
 } from "./src/provider.ts";
 export type { AcpxPartitionSelector } from "./src/provider.ts";
 export type { AcpxProvider, ProbeCapableRuntime } from "./src/provider.ts";
+
+// The construction route: how a logical session was first constructed, kept
+// strictly and create-once beside the coordinator's own records. It is not an
+// Agent Api, a component, or a source of launch authority — the coordinator
+// remains the single live authority.
+export {
+ AgentSessionRouteError,
+ createDenoSessionRouteStore,
+ createMemorySessionRouteStore,
+ hasDenoSessionRouteStore,
+ parseAgentSessionRoute,
+ routeKey,
+ routeNamesKey,
+ serializeAgentSessionRoute,
+} from "./src/session-route.ts";
+export type { AgentSessionRouteStore, AgentSessionRouteV1 } from "./src/session-route.ts";

packages/acp/src/native-launch.ts

@@ -16,22 +16,78 @@
  * Until then `<Session.Launch>` refuses that agent before releasing its ACP
  * session, which is the failure the contract asks for rather than a hopeful
  * spawn.
+ *
+ * Adapters differ in one structural way, and it is discriminated rather than
+ * inferred: who chooses the provider-native session identity. A
+ * `provider-returned` adapter can only resume a session something else created
+ * and named. A `client-allocated` adapter names the session first and hands
+ * that name to the native process, which is what lets a launch construct a
+ * conversation instead of merely reattaching to one.
  */
 
-export interface NativeAdapter {
+import { randomUUID } from "node:crypto";
+import type { IdentityProvenance } from "@executablemd/core";
+
+interface AdapterCommands {
  /** Stable adapter identity — `claude`, `codex`. Never an executable path. */
  launcher: string;
+ /** Who chooses this adapter's native session identity. */
+ identity: IdentityProvenance;
  /** The argv that resumes this exact provider-native session. */
  resume(nativeSessionId: string): string[];
 }
 
+/**
+ * An adapter whose native UI is handed the session it is to create.
+ *
+ * `allocate` is the adapter's because the identity is that provider's dialect:
+ * what shape one takes and what the provider will accept is knowledge about
+ * the provider, not about launching in general. The provider decides whether a
+ * freshly allocated candidate wins publication; it does not decide what one
+ * looks like.
+ *
+ * The instruction layer crosses as a file path and never as text, so nothing
+ * here takes the instructions themselves.
+ */
+export interface ClientAllocatedAdapter extends AdapterCommands {
+ identity: "client-allocated";
+ /** A fresh provider-native session identity. */
+ allocate(): string;
+ /** The argv that creates a session under `id` with that instruction layer. */
+ create(nativeSessionId: string, instructionFile: string): string[];
+}
+
+export interface ProviderReturnedAdapter extends AdapterCommands {
+ identity: "provider-returned";
+}
+
+export type NativeAdapter = ProviderReturnedAdapter | ClientAllocatedAdapter;
+
+/** Whether this adapter names its own sessions. */
+export function allocatesIdentity(adapter: NativeAdapter): adapter is ClientAllocatedAdapter {
+ return adapter.identity === "client-allocated";
+}
+
 const ADAPTERS: Readonly<Record<string, NativeAdapter>> = {
  claude: {
  launcher: "claude",
+ // XMD names the session before Claude exists, so the native process is
+ // told which conversation to make rather than reporting one afterwards.
+ identity: "client-allocated",
+ // Claude takes a UUID it has never seen and makes it the session's name.
+ allocate: () => randomUUID(),
+ create: (nativeSessionId, instructionFile) => [
+ "claude",
+ "--session-id",
+ nativeSessionId,
+ "--system-prompt-file",
+ instructionFile,
+ ],
  resume: (nativeSessionId) => ["claude", "--resume", nativeSessionId],
  },
  codex: {
  launcher: "codex",
+ identity: "provider-returned",
  resume: (nativeSessionId) => ["codex", "resume", nativeSessionId],
  },
 };

architecture.md

@@ -86,6 +86,8 @@ Existing documents and code get aligned to this section retroactively.
 | launch request | the frozen, one-use value public launch middleware routes. It carries the facts of one launch and `with()`, and nothing that can settle one. Identity is object identity: a rebuilt look-alike describes the same ask and authorizes none of it |
 | provider authority | what core delivers to the provider factory it installs, as an argument that factory closes over. It validates the routed request, runs each absent phase once, cross-checks and retains what comes back, and derives the result. There is no reader for one, no context holding one, and no request member carrying one |
 | session coordinator | the host-built capability that answers who owns one logical agent session right now, across processes. It is passed directly into the provider that needs it and is deliberately not contextual: a decision document middleware could replace is not one. Acquisition never waits |
+| construction route | how one logical agent session was first constructed — through ACP, or under an identity XMD chose — as strict create-once durable state beside the coordinator's own records. It answers a different question from ownership and grants no right to act: the coordinator remains the single live authority. A route never converts, and a session ACP already established is recorded as ACP-first rather than reclassified |
+| identity provenance | who chose a provider-native session identity: the provider returned it, or the client allocated it before the provider existed. Retained rather than inferred, because after the fact both are just a string in the record. A released record written before the distinction existed reads as provider-returned, which is the only compatibility inference |
 | quiescence | the one-use acknowledgement an ownership body gives. It does not mean "I finished" — it means nothing this owner started can still act on the session, which is why a handoff that could not release its handle never gives it |
 | recovery tombstone | an ownership record left active because its owner never proved it stopped. A crash releases the kernel lock and not this, and no pid, elapsed time, released lock or empty transcript clears it |
 | provider partition | one complete, independently owned agent-provider state — runtime, store, managed sessions, queues, coordinator, teardown — selected by the one installed factory at each dispatch. Production is the single-partition case of the same path; holding a partition grants work, never permission |
@@ -2709,7 +2711,7 @@ Status is measured against main.
 | `exec as="name"` | binds one command's settled outcome — exit status, stdout and stderr — as an ordinary mutable binding; the block displays neither channel, renders nothing, and a nonzero status raises nothing. Only the built-in exec terminal and the built-in `timeout` may compose one, authorized by factory identity rather than by registered name, and asked for through a capability-backed request public middleware composes around but cannot issue, claim twice or answer | built on the #447 stack |
 | testing harness (`<Execution>`) | runs another document as a real root under a production host profile, authorized by canonical `<Test>` alone: declarations installed before the root import, child output displayed progressively and collected only when asked, journal retention selected independently of observation, and the outcome published by the invocation's own terminal through a request public middleware composes around but cannot answer | built on the #454 stack for `host="run"`; the workflow profile and `<WorkflowRun>` are unbuilt, and a host that offers no workflow profile refuses them |
 | `Config` run deadline / exec default / Fetch default | three independently owned contextual timeouts, absent unless configured, each read by exactly one consumer | built on main |
-| native session launch (`<Session.Launch>` / `Agent.launch()`) | prepares one durable coding-agent session from the rendered body of `<Session.Launch>` and hands the provider's native UI the terminal for that exact session, then continues the document after it exits. The body renders completely first and only what it rendered crosses as the instruction layer; the launch performs no model turn; the run's one foreground-terminal lease is taken before an agent is resolved, so a host with no terminal refuses without probing for an installed CLI; the ACPX provider installs the layer at session creation, refuses an agent whose native launcher is not advertised or that asserts no provider-native identity, releases ACP ownership before the spawn, and marks its handle stale so a later `<Prompt>` reattaches. Phases are retained as `agent_session_launch` records under one expansion identity — `prepared` before ownership is released, then `detached`, then `exited` — so a completed replay launches nothing and an interrupted one resumes the retained identity instead of creating a replacement session. The public route carries an opaque one-use launch request and answers nothing; authority to run and retain a phase is delivered to the installed provider directly, so neither a returned completion nor a rebuilt request authors a launch. Every operation that can act on an advertised provider-returned session takes exclusive ownership under one natural key first, through a coordinator the host built and passed in; contention refuses instead of queueing, an owner that never proved it stopped leaves a recovery tombstone, and a host that can build none refuses before contacting an agent. No launch path discards persistent provider state | built on the #517 stack; no real adapter is advertised, `Agent.AddDir` is unbuilt, and both fail closed |
+| native session launch (`<Session.Launch>` / `Agent.launch()`) | prepares one durable coding-agent session from the rendered body of `<Session.Launch>` and hands the provider's native UI the terminal for that exact session, then continues the document after it exits. The body renders completely first and only what it rendered crosses as the instruction layer; the launch performs no model turn; the run's one foreground-terminal lease is taken before an agent is resolved, so a host with no terminal refuses without probing for an installed CLI. A session is constructed once, by one of two mechanisms, and its create-once construction route says which. Where the provider returns the identity, the ACPX provider creates the session, installs the layer at creation, releases ACP ownership before the spawn, and marks its handle stale so a later `<Prompt>` reattaches. Where the adapter names its own sessions, it allocates the identity inside ownership before any process exists, the native process creates the session under that name from a private mode-0600 instruction file, and ACP creates nothing — the instruction text reaches neither argv nor environment, and the file is removed on success, failure and cancellation alike while ownership is still held. Neither route converts into the other: an eager `<Session>` publishes ACP-first before it establishes anything and keeps that account even if establishing fails, a launch meeting it refuses before an identity exists, and a `<Session>` or `<Prompt>` meeting a client-allocated route raises the provider's own route error rather than manufacturing a launch failure. Phases are retained as `agent_session_launch` records under one expansion identity — `prepared` before ownership is released, then `detached`, then `exited` — so a completed replay launches nothing, a replay holding only `prepared` proves the handoff never began and may still create under the retained identity, and one holding `detached` resumes and never falls back. The public route carries an opaque one-use launch request and answers nothing; authority to run and retain a phase is delivered to the installed provider directly, so neither a returned completion nor a rebuilt request authors a launch. Every operation that can act on an advertised session takes exclusive ownership under one natural key first, through a coordinator the host built and passed in; contention refuses instead of queueing, and an owner that never proved it stopped leaves a recovery tombstone. A host that cannot say who owns a session refuses every advertised operation, and one that cannot say how a session was constructed additionally refuses an agent that names its own — before any provider effect. Every private setup or child-creation failure is normalized to `process-creation-failed` with fixed provider-owned text, carrying no path, argv, environment or host message. No launch path discards persistent provider state | built on the #517 stack, extended by the #519 stack; Deno and the compiled binary assemble the host, Node and Bun refuse, no real adapter is advertised until #520's gate passes, `Agent.AddDir` is unbuilt, and ACP attachment to a client-allocated session is deferred with #517 |
 | `<Fetch>` | performs one XMD-mediated HTTP read through contextual `API.Fetch`, admitting the whole request before transport, and retains the normalized request and the detached response as one `fetch` durable observation; capture decides whether a status is data or a failure, and the trusted host's destination ceiling sits below the component | built on the #456 stack; a generated fragment may name the pinned identity only for a request the trusted host stated exactly, on the #369 stack |
 | `API.Files` | routes every document filesystem operation to the installed provider, with no host default and structural failure data | built on the #227 stack |
 | host Files provider / `useHostFiles()` | resolves document paths in the caller's filesystem, containing them while the host namespace is stable; installed by all four CLI entrypoints | built on the #227 stack |

packages/acp/mod.ts

@@ -28,7 +28,12 @@ export {
  knownNativeAdapters,
  nativeAdapterFor,
 } from "./src/native-launch.ts";
-export type { NativeAdapter } from "./src/native-launch.ts";
+export { allocatesIdentity } from "./src/native-launch.ts";
+export type {
+ ClientAllocatedAdapter,
+ NativeAdapter,
+ ProviderReturnedAdapter,
+} from "./src/native-launch.ts";
 
 export {
  AcpxPartitionError,
@@ -37,3 +42,19 @@ export {
 } from "./src/provider.ts";
 export type { AcpxPartitionSelector } from "./src/provider.ts";
 export type { AcpxProvider, ProbeCapableRuntime } from "./src/provider.ts";
+
+// The construction route: how a logical session was first constructed, kept
+// strictly and create-once beside the coordinator's own records. It is not an
+// Agent Api, a component, or a source of launch authority — the coordinator
+// remains the single live authority.
+export {
+ AgentSessionRouteError,
+ createDenoSessionRouteStore,
+ createMemorySessionRouteStore,
+ hasDenoSessionRouteStore,
+ parseAgentSessionRoute,
+ routeKey,
+ routeNamesKey,
+ serializeAgentSessionRoute,
+} from "./src/session-route.ts";
+export type { AgentSessionRouteStore, AgentSessionRouteV1 } from "./src/session-route.ts";

packages/acp/src/native-launch.ts

@@ -16,22 +16,78 @@
  * Until then `<Session.Launch>` refuses that agent before releasing its ACP
  * session, which is the failure the contract asks for rather than a hopeful
  * spawn.
+ *
+ * Adapters differ in one structural way, and it is discriminated rather than
+ * inferred: who chooses the provider-native session identity. A
+ * `provider-returned` adapter can only resume a session something else created
+ * and named. A `client-allocated` adapter names the session first and hands
+ * that name to the native process, which is what lets a launch construct a
+ * conversation instead of merely reattaching to one.
  */
 
-export interface NativeAdapter {
+import { randomUUID } from "node:crypto";
+import type { IdentityProvenance } from "@executablemd/core";
+
+interface AdapterCommands {
  /** Stable adapter identity — `claude`, `codex`. Never an executable path. */
  launcher: string;
+ /** Who chooses this adapter's native session identity. */
+ identity: IdentityProvenance;
  /** The argv that resumes this exact provider-native session. */
  resume(nativeSessionId: string): string[];
 }
 
+/**
+ * An adapter whose native UI is handed the session it is to create.
+ *
+ * `allocate` is the adapter's because the identity is that provider's dialect:
+ * what shape one takes and what the provider will accept is knowledge about
+ * the provider, not about launching in general. The provider decides whether a
+ * freshly allocated candidate wins publication; it does not decide what one
+ * looks like.
+ *
+ * The instruction layer crosses as a file path and never as text, so nothing
+ * here takes the instructions themselves.
+ */
+export interface ClientAllocatedAdapter extends AdapterCommands {
+ identity: "client-allocated";
+ /** A fresh provider-native session identity. */
+ allocate(): string;
+ /** The argv that creates a session under `id` with that instruction layer. */
+ create(nativeSessionId: string, instructionFile: string): string[];
+}
+
+export interface ProviderReturnedAdapter extends AdapterCommands {
+ identity: "provider-returned";
+}
+
+export type NativeAdapter = ProviderReturnedAdapter | ClientAllocatedAdapter;
+
+/** Whether this adapter names its own sessions. */
+export function allocatesIdentity(adapter: NativeAdapter): adapter is ClientAllocatedAdapter {
+ return adapter.identity === "client-allocated";
+}
+
 const ADAPTERS: Readonly<Record<string, NativeAdapter>> = {
  claude: {
  launcher: "claude",
+ // XMD names the session before Claude exists, so the native process is
+ // told which conversation to make rather than reporting one afterwards.
+ identity: "client-allocated",
+ // Claude takes a UUID it has never seen and makes it the session's name.
+ allocate: () => randomUUID(),
+ create: (nativeSessionId, instructionFile) => [
+ "claude",
+ "--session-id",
+ nativeSessionId,
+ "--system-prompt-file",
+ instructionFile,
+ ],
  resume: (nativeSessionId) => ["claude", "--resume", nativeSessionId],
  },
  codex: {
  launcher: "codex",
+ identity: "provider-returned",
  resume: (nativeSessionId) => ["codex", "resume", nativeSessionId],
  },
 };