Story
As a person coordinating several coding agents, I want one retained XMD REPL to select a role, send it a message, and show the resulting conversation, so I can supervise multiple sessions without moving between unrelated native interfaces.
Common path
An executable document declares Architect and Implementor sessions with their role and current issue. The REPL lists both. The user selects Implementor and sends a message. XMD queues that prompt for the Implementor's ACP session, renders its streamed reply and tool activity, and leaves the Architect independently usable.
Closing and reopening the same REPL session restores its selected roles, conversation views, queued work, and completed actions without sending a prompt twice.
Current gap
XMD can drive one Agent session through ACP and can launch native coding-agent interfaces. ACP activity is not reflected reliably in an already-open provider-native TUI, and #774 established that pasting into a black-box tmux pane cannot close the race between provider state and terminal input.
ACP clients with rich conversation views exist, but an independent client cannot passively attach to XMD's live ACP transport. XMD therefore needs to project the event stream from the ACP connection it already owns.
Contract
The REPL is an ordinary retained XMD session, not a separate workflow engine. Its state follows one-directional data flow:
user or provider event → action → immutable store state → viewer
│
└→ authorized ACP effect
Actions are the only way state changes. Each role has immutable state containing its authored role and issue, exact logical and provider-native session identity, connection and turn state, queued and completed messages, normalized conversation events, permission requests, failures, and the viewer's cursor.
ACP is the sole interaction boundary. One XMD-owned ACP connection and queue owns each interactive Agent session. A viewer never opens a competing ACP client, and no prompt is delivered through tmux, stdio injection, provider files, hooks, or a native TUI.
The REPL execution is the queue. It serializes prompts for one session, permits distinct sessions to work concurrently, and records the transition from queued through admitted, active, and settled. Cancellation and permission answers route through the same owning ACP session. An action whose outcome is uncertain is never silently retried.
Every viewer subscribes to the retained store fed by XMD's ACP updates. Several projections may display the same session without acquiring session authority. <Session.Tail> may supply read-only history for an independently owned or provider-native session, but file observations never authorize a prompt, cancellation, permission decision, completion, or ownership transition.
Restart restores the REPL's durable action history and session bindings. Completed actions do not execute again. An incomplete ACP action resumes only through the retained session identity and the adapter's supported continuation contract; it never allocates a replacement conversation or rewrites identity to make progress. Provider, protocol, capability, host, or identity disagreement remains fail-closed.
The REPL may render in an ordinary terminal, a <Pane>, or another UI. Presentation does not own the ACP connection or session queue.
StarFX may inform or implement the action/store mechanics, but this Story depends on the one-directional contract rather than on that library.
Acceptance
- One retained REPL controls at least two distinct Agent sessions and switches between their complete conversation views.
- Messages to one role enter only that role's ACP queue; distinct roles can run concurrently without cross-delivery.
- Back-to-back messages to one role execute in order with at most one active prompt.
- ACP updates, tool activity, plans, permission requests, completion, cancellation, and failures become immutable store actions and render in every subscribed viewer.
- Closing and reopening the REPL restores the same session identities, selected role, conversation state, queued work, and completed outcomes without duplicate prompts or events.
- An interrupted or uncertain prompt is surfaced explicitly and is not automatically sent again.
- A second viewer observes the same retained state without opening another ACP connection.
- A tailed read-only session refuses interaction even if its records resemble an interactive session.
- Provider, protocol, capability, host, ownership, or identity mismatch refuses without allocating a substitute session or changing retained state.
- Deterministic agents prove queueing, concurrency, restart, permission, cancellation, failure, and duplicate suppression. Explicitly authorized real-provider journeys remain separate and bounded.
Relationships
Out of scope
- Delivering prompts through a tmux pane or native coding-agent TUI.
- Making ACP messages appear inside a provider-native UI.
- Treating provider session files as control authority.
- Choosing a UI toolkit or StarFX as a mandatory public dependency.
- Adding the terminal presentation to Workflow.
Story
As a person coordinating several coding agents, I want one retained XMD REPL to select a role, send it a message, and show the resulting conversation, so I can supervise multiple sessions without moving between unrelated native interfaces.
Common path
An executable document declares Architect and Implementor sessions with their role and current issue. The REPL lists both. The user selects Implementor and sends a message. XMD queues that prompt for the Implementor's ACP session, renders its streamed reply and tool activity, and leaves the Architect independently usable.
Closing and reopening the same REPL session restores its selected roles, conversation views, queued work, and completed actions without sending a prompt twice.
Current gap
XMD can drive one Agent session through ACP and can launch native coding-agent interfaces. ACP activity is not reflected reliably in an already-open provider-native TUI, and #774 established that pasting into a black-box tmux pane cannot close the race between provider state and terminal input.
ACP clients with rich conversation views exist, but an independent client cannot passively attach to XMD's live ACP transport. XMD therefore needs to project the event stream from the ACP connection it already owns.
Contract
The REPL is an ordinary retained XMD session, not a separate workflow engine. Its state follows one-directional data flow:
Actions are the only way state changes. Each role has immutable state containing its authored role and issue, exact logical and provider-native session identity, connection and turn state, queued and completed messages, normalized conversation events, permission requests, failures, and the viewer's cursor.
ACP is the sole interaction boundary. One XMD-owned ACP connection and queue owns each interactive Agent session. A viewer never opens a competing ACP client, and no prompt is delivered through tmux, stdio injection, provider files, hooks, or a native TUI.
The REPL execution is the queue. It serializes prompts for one session, permits distinct sessions to work concurrently, and records the transition from queued through admitted, active, and settled. Cancellation and permission answers route through the same owning ACP session. An action whose outcome is uncertain is never silently retried.
Every viewer subscribes to the retained store fed by XMD's ACP updates. Several projections may display the same session without acquiring session authority.
<Session.Tail>may supply read-only history for an independently owned or provider-native session, but file observations never authorize a prompt, cancellation, permission decision, completion, or ownership transition.Restart restores the REPL's durable action history and session bindings. Completed actions do not execute again. An incomplete ACP action resumes only through the retained session identity and the adapter's supported continuation contract; it never allocates a replacement conversation or rewrites identity to make progress. Provider, protocol, capability, host, or identity disagreement remains fail-closed.
The REPL may render in an ordinary terminal, a
<Pane>, or another UI. Presentation does not own the ACP connection or session queue.StarFX may inform or implement the action/store mechanics, but this Story depends on the one-directional contract rather than on that library.
Acceptance
Relationships
<Session.Tail>andxmd tail#782 for the normalized read-only session view and provider-native observation.<Session.Launch>and ACP.Out of scope