Quest: Observe and interact with multiple coding-agent sessions

[taras]

Story

As a person coordinating several coding agents, I want one XMD interface to preserve, display, and interact with their sessions, so I can move between roles and issues without losing conversation state or depending on each provider's native UI.

An executable document declares a provider-neutral grid. Each pane can launch an Agent session, follow an independently owned session, or display the retained REPL. Tmux presents that grid first; an XMD-owned provider can present the same document later. Interaction always uses the authority belonging to the session rather than terminal-state inference.

<Grid columns={2}>
  <Pane title="Architect · #784">
    <Agent name="codex">
      <Session.Tail session="existing-session-id" />
    </Agent>
  </Pane>
  <Pane title="Implementor · #784">
    <Agent name="claude">
      <Session.Launch session="implementor">...</Session.Launch>
    </Agent>
  </Pane>
</Grid>

Current gap

The unmerged #717 stack proves concurrent interactive panes and tmux lifecycle, but its public syntax identifies every pane as a terminal. XMD can interact reliably through ACP, yet those messages do not become visible in an already-open provider-native TUI.

Issue #774 tested whether session-file observation plus terminal convergence could bridge that gap without provider cooperation. Passive observation succeeded; generic tmux input remained subject to an uncloseable race between the final provider-file sample and terminal paste. The safe result is VIEW_ONLY: observe provider sessions from their files, but never use that observation to authorize input.

Product contract

Grid and pane are the durable presentation vocabulary. Tmux and a first-party XMD multiplexer implement the same run-only provider contract. A physical terminal remains a capability a pane may require, not the identity of every cell.

<Session.Launch> and <Session.Tail> are interchangeable as pane session sources and differ in authority. Launch owns the interaction and lifecycle its Agent provider grants. Tail observes an independently owned native session and can only stop observing it.

A retained XMD REPL owns interactive ACP sessions and their queues. Every viewer projects the same immutable action store and ACP event stream; a viewer does not open another ACP client. Provider session files supply read-only history and live observation, never prompt, permission, completion, cancellation, identity-allocation, or teardown authority.

Tmux remains useful for document-configured layouts and titles, including role and current issue. It is an xmd run provider, not Workflow behavior. No child in this Quest adds terminal presentation, live provider-file observation, or REPL interaction to Workflow.

Dependency-ordered child map

1. Test black-box REPL messaging through xmd run terminal panes #774 — Test black-box REPL messaging through xmd run terminal panes
   • Implemented on open PR 🔒 Terminal REPL POC (#774) — VIEW_ONLY evidence #779 as disposable evidence.
   • Establishes VIEW_ONLY: passive session-file observation is viable and generic tmux message delivery is not authorized.
2. Make executable document grids use <Grid> and <Pane> #781 — Make executable document grids use <Grid> and <Pane>
   • Final amendment to the unmerged Quest: Add interactive grids to executable documents #717 stack.
   • Replaces the rejected public component and package names while preserving its proven lifecycle.
   • PR ✨ Launch Codex sessions with <Session.Launch> (#755) #764 is rebased after the repaired Quest: Add interactive grids to executable documents #717 head; its Codex certification remains a separate purpose.
3. View coding-agent sessions with <Session.Tail> and xmd tail #782 — View coding-agent sessions with <Session.Tail> and xmd tail
   • Uses Test black-box REPL messaging through xmd run terminal panes #774's passive evidence and Make executable document grids use <Grid> and <Pane> #781's pane surface.
   • Owns exact read-only identity, normalized events, Markdown provider adapters, filesystem following, and the standalone viewer.
4. Interact with multiple Agent sessions through a retained XMD REPL #783 — Interact with multiple Agent sessions through a retained XMD REPL
   • Depends on View coding-agent sessions with <Session.Tail> and xmd tail #782.
   • Owns the immutable action store, ACP queues, restart, permissions, cancellation, and shared viewer projection.
5. Present Agent session grids without an external multiplexer #784 — Present Agent session grids without an external multiplexer
   • Depends on Make executable document grids use <Grid> and <Pane> #781–Interact with multiple Agent sessions through a retained XMD REPL #783.
   • Implements the same Grid/Pane contract without tmux and never becomes session authority.

#774 ──> #782 ──> #783 ──> #784
             ▲                 ▲
#717 ──> #781 ─────────────────┘

Completion

The Quest is complete when:

• <Grid> and <Pane> are the only shipped grid syntax and the old unshipped Terminal names and packages are absent;
• <Session.Tail> and xmd tail open and follow exact supported Claude and Codex sessions read-only;
• one retained REPL controls multiple ACP sessions without duplicate prompts, competing clients, or identity substitution;
• tmux and the XMD-owned provider present the same authored grid contract;
• role and issue titles remain document data;
• every interaction follows ACP or an explicitly owned native PTY, while provider files and terminal convergence remain observation only; and
• focused positive and negative evidence covers identity, concurrent sessions, restart, uncertain work, wrong-cell input, cancellation, and complete provider teardown.

Relationships and boundaries

• Quest: Add interactive grids to executable documents #717 remains the Quest that delivers the reusable Grid/Pane execution and tmux provider foundation.
• Launch Codex sessions with <Session.Launch> #755 and PR ✨ Launch Codex sessions with <Session.Launch> (#755) #764 remain the Codex native-launch certification and are not repurposed by this Quest.
• Make Claude native-to-ACP continuation preserve the exact conversation #770 is required only where a Claude conversation constructed in the native UI must later become ACP-controlled; it does not block read-only tailing or ACP-owned sessions.
• No child writes provider session files, installs hooks or plugins, scrapes terminal pixels for conversation state, or asks an agent to report itself.