Story
As a person running several coding-agent sessions, I want XMD to present their panes itself, so I can view and interact with the whole grid without installing or configuring an external terminal multiplexer.
Example
The authored document remains provider-neutral:
<Grid columns={2}>
<Pane title="Architect · #783">
<Session.Tail session="architect-session" />
</Pane>
<Pane title="Implementor · #783">
<Session.Launch session="implementor">...</Session.Launch>
</Pane>
</Grid>
The same document that tmux presents can be presented by XMD without changing its grid, panes, titles, roles, issues, or content.
Current gap
The first #717 provider uses tmux. That is useful for configuring and arranging terminal work today, but it leaves presentation, input focus, and cell rendering in an external process. It also cannot make an ACP conversation appear in a provider-native coding-agent TUI.
The Grid/Pane contract is provider-neutral, so replacing tmux should be a provider implementation rather than a new document language.
Contract
XMD supplies a first-party provider for the @executablemd/grid contract. It owns the visible composite, cell layout, focus, input routing, resizing, titles, and teardown. No tmux command, socket, server, configuration, or process participates.
The provider presents the same static authored row-major layout and the same pane lifecycle as the tmux provider. Role and current issue remain ordinary document props used to derive pane titles; they do not become provider identity.
A pane may render a normalized Agent conversation, the retained REPL, ordinary document output, or an interactive terminal capability required by a native process or default shell. The provider routes input according to the content's authority:
- REPL and ACP-backed session input goes through the REPL's owning ACP queue.
- A native interactive process receives input through its owned PTY.
<Session.Tail> is read-only and accepts no conversational input.
- Changing focus grants no Agent-session or durable authority.
The multiplexer is presentation. It observes the XMD-owned retained store and ACP event stream but does not own either. Several cells may show one session without opening competing ACP connections.
Startup remains atomic: the visible grid appears only after every required cell endpoint is ready. Cells settle independently and preserve visible final status until the reader closes the grid. Close stops new input, completes every cell and provider finalizer, restores the enclosing terminal, and only then lets the document continue.
The provider is available to xmd run only. It adds no Workflow component, effect, journal record, replay authority, or remote-host assumption. A host chooses an installed grid provider; the document does not name tmux or the XMD multiplexer.
Tmux remains a valid alternative provider. Provider choice changes presentation, not document meaning, session identity, retained history, interaction authority, or teardown guarantees.
Acceptance
- One document runs unchanged with the tmux provider and the XMD provider and produces the same grid structure, titles, pane identities, and lifecycle outcomes.
- The XMD provider renders at least two live Agent conversation cells plus the retained REPL without opening duplicate ACP connections.
- Role and current-issue prop changes produce the exact pane titles without changing pane or Agent identity.
- Keyboard focus routes input only to the selected cell and never turns a read-only tailed session into an interactive one.
- ACP prompts enter only the owning session queue; native PTY input enters only the selected native pane.
- Resize and relayout preserve authored row-major order and session identity.
- Partial startup presents no grid; post-attach cell failure remains contained until close.
- Reader close, parent cancellation, terminal loss, provider failure, and cell finalizer failure retain the accepted Grid/Pane precedence and complete teardown.
- No tmux executable or configuration is required or observed by the XMD provider.
- Node, Bun, Deno, compiled-host, and non-terminal availability are stated explicitly and unsupported hosts refuse before cell work begins.
- Controlled evidence uses signals rather than elapsed time and includes wrong-cell input and duplicate-ACP-connection negative controls.
Relationships
Out of scope
- Adding grids or live host observation to Workflow.
- Synchronizing a provider-native TUI with an ACP conversation.
- Using provider session files to authorize interaction.
- Remote collaborative presentation or browser hosting unless separately specified.
Story
As a person running several coding-agent sessions, I want XMD to present their panes itself, so I can view and interact with the whole grid without installing or configuring an external terminal multiplexer.
Example
The authored document remains provider-neutral:
The same document that tmux presents can be presented by XMD without changing its grid, panes, titles, roles, issues, or content.
Current gap
The first #717 provider uses tmux. That is useful for configuring and arranging terminal work today, but it leaves presentation, input focus, and cell rendering in an external process. It also cannot make an ACP conversation appear in a provider-native coding-agent TUI.
The Grid/Pane contract is provider-neutral, so replacing tmux should be a provider implementation rather than a new document language.
Contract
XMD supplies a first-party provider for the
@executablemd/gridcontract. It owns the visible composite, cell layout, focus, input routing, resizing, titles, and teardown. No tmux command, socket, server, configuration, or process participates.The provider presents the same static authored row-major layout and the same pane lifecycle as the tmux provider. Role and current issue remain ordinary document props used to derive pane titles; they do not become provider identity.
A pane may render a normalized Agent conversation, the retained REPL, ordinary document output, or an interactive terminal capability required by a native process or default shell. The provider routes input according to the content's authority:
<Session.Tail>is read-only and accepts no conversational input.The multiplexer is presentation. It observes the XMD-owned retained store and ACP event stream but does not own either. Several cells may show one session without opening competing ACP connections.
Startup remains atomic: the visible grid appears only after every required cell endpoint is ready. Cells settle independently and preserve visible final status until the reader closes the grid. Close stops new input, completes every cell and provider finalizer, restores the enclosing terminal, and only then lets the document continue.
The provider is available to
xmd runonly. It adds no Workflow component, effect, journal record, replay authority, or remote-host assumption. A host chooses an installed grid provider; the document does not name tmux or the XMD multiplexer.Tmux remains a valid alternative provider. Provider choice changes presentation, not document meaning, session identity, retained history, interaction authority, or teardown guarantees.
Acceptance
Relationships
<Grid>and<Pane>#781 for the stable<Grid>and<Pane>provider contract.<Session.Tail>andxmd tail#782 for read-only session cells.Out of scope