Story
As an XMD user running several coding agents in terminal panes, I want one retained REPL to send a message to a selected role and show that role's reply, while each coding-agent TUI remains an unmodified black box.
Example journey
An executable Markdown document launches an Architect and an Implementor in an xmd run terminal grid. Their role and current issue come from the document's props.
From the REPL, the user sends a message to the Implementor. The message waits while that pane is busy, enters the pane only after its terminal state converges on readiness, and is pasted as literal terminal input. XMD observes acceptance and the reply from the coding agent's own session file, updates the Implementor's immutable state, and renders the conversation in the REPL.
Stopping and reopening the REPL restores each role's state, queued work, and observer position without repeating a message or response.
Current gap
The terminal grid can run native coding-agent interfaces, but XMD has no black-box channel for coordinating them from one REPL. ACP is the reliable interface for sessions XMD drives through ACP, but an ACP exchange is not reflected in an already-open native TUI. Using ACP as a hidden side channel would therefore make the visible pane and the controlling conversation disagree.
Passive observation has passed a feasibility check:
- Claude Code 2.1.263 writes distinct, identity-bearing session files for concurrent native sessions in one working directory. A live follower observed complete appended records and restarted without duplicates.
- Codex CLI 0.153.4 maps its thread identity to one rollout file. Sequential native and ACP continuation appended to that file, and a follower restarted without duplicates.
- Neither experiment installed hooks or plugins, required agent cooperation, wrote provider session files, or inferred completion from terminal pixels.
The unproven boundary is input. A tmux pane accepts terminal bytes, but XMD does not yet know whether generic terminal-state convergence can identify a safe input point often enough to provide useful messaging without corrupting an active turn or the user's own input.
POC contract
This is a finite evaluation, not the production REPL.
The POC treats each coding agent as a black box:
- no hooks, plugins, injected commands, startup scripts, or behavior the agent must invoke;
- no writes to provider-owned session or transcript files;
- no ACP call used to deliver a message to a native tmux pane;
- no parsing of terminal output as authoritative conversation history; and
- no provider-specific prompt text used as the readiness signal.
tmux is an xmd run facility only. The POC adds no Workflow capability, effect, journal record, replay rule, or workflow syntax.
One Flux-style store holds immutable state for the REPL and every role. Actions are the only way state changes. The REPL, terminal-delivery worker, and passive session-file observers dispatch actions; side effects do not mutate role state directly. StarFX may be evaluated as an implementation aid, but adopting that library is not part of the result.
Each role state distinguishes at least:
- its authored role and current issue;
- its native session identity and observer cursor;
- terminal readiness as unknown, converging, ready, busy, or unavailable;
- queued, admitted, delivered, observed, completed, refused, and uncertain messages; and
- normalized user and assistant conversation events.
A pane admits at most one REPL message at a time. Delivery uses a literal tmux paste mechanism so argv syntax, shell metacharacters, Unicode, and multiline content are not interpreted by a shell. A timeout may bound a failed experiment, but elapsed time is never success evidence.
The provider session file is the authority for message acceptance and completion. Terminal convergence only authorizes an attempt to deliver input. If readiness is ambiguous, the pane changes, the user is typing, the agent remains busy, or the session identity cannot be mapped exactly, the message stays queued or becomes explicitly uncertain; the POC never reports it as delivered by assumption.
The REPL itself has a retained XMD session identity. Restart restores its store snapshot or action history and resumes each observer from a durable cursor. Completed actions do not execute again, and a delivery whose outcome cannot be established is not silently retried.
Evaluation
Use deterministic fake panes and synthetic append-only session files for the failure matrix. Then run one explicitly authorized, bounded live journey for Claude and one for Codex. The live journey records the exact product version and authorized model-turn count and never runs in ordinary CI.
Exercise:
- an idle pane receiving one literal message;
- a busy pane retaining a queued message until observable completion;
- two roles receiving distinct messages without cross-delivery;
- back-to-back messages to one role with only one in flight;
- multiline, Unicode, and shell-significant message bytes;
- REPL restart before delivery, during observation, and after completion;
- a partial session-file record followed by completion;
- manual terminal activity during convergence;
- pane exit or replacement before delivery; and
- session-file ambiguity, rotation, truncation, or an unsupported record shape.
Every successful live delivery carries a harmless unique marker. The exact user event observed in the provider session file must contain that marker, and a later complete assistant event must belong to the same native session. Screen contents alone satisfy no claim.
Record convergence attempts, admitted deliveries, refusals, uncertain outcomes, time to confirmed acceptance, time to completion, duplicates, wrong-pane deliveries, and any delivery admitted while the pane was actually busy.
Decision
The POC passes when both supported agents complete the bounded journey with:
- zero duplicate or wrong-pane deliveries;
- zero messages admitted during a known busy or manually active state;
- exact message bytes observed under the intended native session identity;
- completion observed without screen scraping; and
- restart restoring queued and completed state without re-execution or duplicate events.
A pass authorizes planning a production retained REPL and action store. It does not make the POC implementation production code.
If passive observation remains reliable but terminal convergence admits an unsafe or wrong delivery, tmux panes remain view-only for coordinated work and reliable REPL interaction stays ACP-only.
If a provider session cannot be mapped and followed without ambiguity, that provider is excluded from the observer until a separate contract resolves it. The POC does not compensate with hooks, plugins, transcript writes, or screen-derived conversation state.
Relationships
Out of scope
- Shipping the production multi-agent REPL.
- Adding terminal components to Workflow.
- Making ACP activity appear inside a native coding-agent TUI.
- Modifying Claude Code, Codex, or their session files.
- Hooks, plugins, MCP tools, or prompts that ask an agent to report its own state.
- Treating terminal convergence as conversation or completion evidence.
- Choosing StarFX as a production dependency.
Story
As an XMD user running several coding agents in terminal panes, I want one retained REPL to send a message to a selected role and show that role's reply, while each coding-agent TUI remains an unmodified black box.
Example journey
An executable Markdown document launches an Architect and an Implementor in an
xmd runterminal grid. Their role and current issue come from the document's props.From the REPL, the user sends a message to the Implementor. The message waits while that pane is busy, enters the pane only after its terminal state converges on readiness, and is pasted as literal terminal input. XMD observes acceptance and the reply from the coding agent's own session file, updates the Implementor's immutable state, and renders the conversation in the REPL.
Stopping and reopening the REPL restores each role's state, queued work, and observer position without repeating a message or response.
Current gap
The terminal grid can run native coding-agent interfaces, but XMD has no black-box channel for coordinating them from one REPL. ACP is the reliable interface for sessions XMD drives through ACP, but an ACP exchange is not reflected in an already-open native TUI. Using ACP as a hidden side channel would therefore make the visible pane and the controlling conversation disagree.
Passive observation has passed a feasibility check:
The unproven boundary is input. A tmux pane accepts terminal bytes, but XMD does not yet know whether generic terminal-state convergence can identify a safe input point often enough to provide useful messaging without corrupting an active turn or the user's own input.
POC contract
This is a finite evaluation, not the production REPL.
The POC treats each coding agent as a black box:
tmux is an
xmd runfacility only. The POC adds no Workflow capability, effect, journal record, replay rule, or workflow syntax.One Flux-style store holds immutable state for the REPL and every role. Actions are the only way state changes. The REPL, terminal-delivery worker, and passive session-file observers dispatch actions; side effects do not mutate role state directly. StarFX may be evaluated as an implementation aid, but adopting that library is not part of the result.
Each role state distinguishes at least:
A pane admits at most one REPL message at a time. Delivery uses a literal tmux paste mechanism so argv syntax, shell metacharacters, Unicode, and multiline content are not interpreted by a shell. A timeout may bound a failed experiment, but elapsed time is never success evidence.
The provider session file is the authority for message acceptance and completion. Terminal convergence only authorizes an attempt to deliver input. If readiness is ambiguous, the pane changes, the user is typing, the agent remains busy, or the session identity cannot be mapped exactly, the message stays queued or becomes explicitly uncertain; the POC never reports it as delivered by assumption.
The REPL itself has a retained XMD session identity. Restart restores its store snapshot or action history and resumes each observer from a durable cursor. Completed actions do not execute again, and a delivery whose outcome cannot be established is not silently retried.
Evaluation
Use deterministic fake panes and synthetic append-only session files for the failure matrix. Then run one explicitly authorized, bounded live journey for Claude and one for Codex. The live journey records the exact product version and authorized model-turn count and never runs in ordinary CI.
Exercise:
Every successful live delivery carries a harmless unique marker. The exact user event observed in the provider session file must contain that marker, and a later complete assistant event must belong to the same native session. Screen contents alone satisfy no claim.
Record convergence attempts, admitted deliveries, refusals, uncertain outcomes, time to confirmed acceptance, time to completion, duplicates, wrong-pane deliveries, and any delivery admitted while the pane was actually busy.
Decision
The POC passes when both supported agents complete the bounded journey with:
A pass authorizes planning a production retained REPL and action store. It does not make the POC implementation production code.
If passive observation remains reliable but terminal convergence admits an unsafe or wrong delivery, tmux panes remain view-only for coordinated work and reliable REPL interaction stays ACP-only.
If a provider session cannot be mapped and followed without ambiguity, that provider is excluded from the observer until a separate contract resolves it. The POC does not compensate with hooks, plugins, transcript writes, or screen-derived conversation state.
Relationships
Out of scope