Quest: Add interactive grids to executable documents #717

Story

As a repository user, I want an executable document to open several interactive panes in one foreground grid, so I can work with multiple coding-agent sessions, session viewers, and an ordinary repository shell at the same time.

The document declares the grid, panes, titles, and pane content. The host chooses how to present them. Tmux is the first production provider, but no tmux session, window, target, command, key binding, socket, or process identity appears in the authored surface. Another multiplexer implements the same contract without changing the document.

<Grid columns={2}>
  <Pane title="Architect">
    <Agent name="codex">
      <Session.Launch session="architect">
        ...prepared Architect instructions...
      </Session.Launch>
    </Agent>
  </Pane>
  <Pane title="Planner">
    <Agent name="codex">
      <Session.Launch session="planner">
        ...prepared Planner instructions...
      </Session.Launch>
    </Agent>
  </Pane>
  <Pane title="Implementor">
    <Agent name="claude">
      <Session.Launch session="implementor">
        ...prepared Implementor instructions...
      </Session.Launch>
    </Agent>
  </Pane>
  <Pane title="Workspace" />
</Grid>

A production pane launches only an Agent the host has independently advertised under the native-launch proof. Codex advertisement remains #755 and PR #764 rather than this Quest.

Current state

#729 is delivered through merged PR #733. The provider-neutral, native-launch, tmux, package-extraction, and Grid/Pane implementations exist on open stacked branches, but their live provider interface predates the accepted one-directional state and convergence contract. They are not ready to merge unchanged.

Signed architecture commit 69157e4ca3d9272b8ebbcacce50c408dc09c832d, directly atop PR #738 head 08287748fe4d2baaaa823a26ce3d454fd28f35a9, is the repair base. It changes documentation only. #730 is repaired there first; #731 and #732 are then semantically restacked; #781 finally reapplies the accepted Grid/Pane and package rename without weakening the repaired behavior. No remaining #717 layer merges until that integrated head is accepted.

The architecture is recorded in architecture.md, specs/executable-mdx-spec.md, and specs/native-agent-session-launch-spec.md. Closed #726 and PR #727 establish the persistent tmux pane-worker topology and bounded teardown facts. They remain evidence, not product delivery.

Accepted product and lifecycle contract

<Grid> and <Pane> are core-owned structural syntax. A grid has a positive integer column count and one or more statically authored direct panes in row-major order. A paired pane expands isolated document flow; a self-closing pane runs the host's default interactive shell. Titles are non-empty display labels supplied by the document, may include role and current issue, may repeat, and do not identify panes. This delivery exposes no live title mutation.

Grid and pane describe presentation. Terminal remains an internal capability where a PTY, foreground-terminal lease, terminal process observation, native interactive process, or shell requires it. The final neutral package is @executablemd/grid; the tmux provider package is @executablemd/grid-tmux. The rejected component names, package names, implementation paths, exports, and compatibility re-exports do not ship.

One grid is one scope-owned computation. Core supplies inert lazy pane operations and a source-aware journal adapter. The neutral lifecycle owns layout reconciliation, the durable grid and pane tasks, the foreground lease and root-output flush, one private StarFX store, provider resource, reader-close handshake, and complete teardown. Completed replay creates none of those live objects; partial replay starts a fresh live presentation while retaining the established durable identities and outcomes.

Every live state snapshot is immutable and carries a per-grid monotonic revision. A provider subscription atomically receives one current snapshot and then only strictly newer revisions, with no read/subscribe gap. The provider renders through one serialized lane, may coalesce pending full snapshots to the newest revision, and never applies older state after newer state.

Ordinary state presentation remains asynchronous. show() waits until the provider has applied its captured visible revision before attachment. Before a pane transfers its terminal to a native launch or shell, it waits until all causally prior pane output and its launching state have converged. Cancellation during that wait starts no child. Background renderer, subscription, control, or provider failure is observed independently from reader departure, fails the grid, and enters complete teardown.

The provider prepares the complete hidden grid and attaches it only after every required interactive child reaches the runtime spawn event. Failure before that barrier presents no partial grid and tears down all acquired work. After attachment, panes settle independently and retain visible final statuses while siblings remain usable.

Reader close prevents new launches, asks live pane work to close, awaits every child and finalizer, removes the provider grid, restores the root terminal, releases the foreground lease, and only then settles the grid task and lets the document continue. The first failed pane in authored order fails the grid at close; close-induced cancellation is not a pane failure.

Pane presentation ownership never grants Agent-session ownership. Native launches in distinct panes may own their terminals concurrently, while two panes naming one logical Agent session still contend through the unchanged coordinator. Durable launch identity, construction routes, executable admission, replay, provider advertisement, privacy, and no-substitution rules remain those of <Session.Launch>.

Teardown proves the facts the host can observe: no process remains in a pane process group, no process remains descended from a child alive when cancellation began, no process holds a pane terminal, and no provider worker, client, server, or private path remains. A descendant that already created a new session, closed the pane terminal, and lost its parent remains outside the observable macOS boundary; the provider claims no more.

Tmux is an xmd run provider only. The Quest adds no Grid, Pane, terminal, provider, effect, journal, or replay behavior to Workflow.

Dependency-ordered implementation Stories

1. Describe terminal grids as executable document structure #729 — Describe terminal grids as executable document structure
   • Delivered through merged PR ✨ Describe terminal grids as executable document structure (#729) #733.
   • Owns the original structural grammar and inert validation evidence that Make executable document grids use <Grid> and <Pane> #781 renames without weakening.
2. Execute concurrent terminal panes through a replaceable provider #730 — Execute concurrent terminal panes through a replaceable provider
   • PR ♻️ Converge terminal grids on one immutable state (#730) #738 contains the earlier implementation at 08287748; repair it atop architecture SHA 69157e4c.
   • Owns the resource/task lifecycle, private state, provider observation and convergence, durability, replay, close, cancellation, and controlled-provider evidence.
3. Launch native Agent sessions in independent terminal panes #731 — Launch native Agent sessions in independent terminal panes
   • PR ✨ Launch native Agent sessions in independent terminal panes (#731) #741 is implemented against the earlier Execute concurrent terminal panes through a replaceable provider #730 surface and must be semantically restacked after its repair.
   • Owns pane-scoped native launch, pre-transfer convergence, independent terminal and session ownership, readiness, cancellation, and quiescence.
4. Open terminal grids with tmux in foreground runs #732 — Open terminal grids with tmux in foreground runs
   • PR ✨ Open terminal grids with tmux in foreground runs (#732) #747 is implemented against the earlier provider surface and must be semantically restacked after Launch native Agent sessions in independent terminal panes #731.
   • Owns tmux host assembly, the serialized renderer, applied-revision convergence, provider-failure reporting, persistent workers, authenticated IPC, explicit layout, attach, SIGHUP, and bounded teardown.
5. Make executable document grids use <Grid> and <Pane> #781 — Make executable document grids use <Grid> and <Pane>
   • Its prior stacked implementation must be reapplied after the repaired Open terminal grids with tmux in foreground runs #732 head.
   • Replaces public syntax, domain names, packages, imports, documentation, diagnostics, and tests while preserving every repaired lifecycle contract.

#729 → #730 → #731 → #732 → #781

The product boundary still permits #731 and #732 as independent consumers of #730. The linear stack exists so one top revision proves the complete feature before any layer merges.

PR #764 remains #755's Codex certification. After #781 produces the repaired #717 head, #764 is rebased onto it and re-reviewed; Grid/Pane work is not added as a new purpose of that PR.

Acceptance map

The Quest is complete when all five Stories are delivered to main, the old unshipped Terminal grid surface is absent, the governing contracts describe the Grid/Pane implementation, and required delivery checks pass at the final integrated head.

Evidence already accepted

#726 closed with the persistent pane-worker topology accepted at PR #727 evidence commit 650510b5 and reviewed report head 80770ea3. It proves spawn-event readiness, byte-exact private IPC, job control, row-major layout, atomic attach, independent close signals, phase cancellation, sequential reuse after terminal-holder quiescence, and the bounded macOS teardown claim.

The measured lsof -t sweep cost remains an implementation concern rather than a latency contract. Terminal-holder enumeration stays behind the host process adapter so it can be optimized without weakening quiescence.

Related work

• Quest: Observe and interact with multiple coding-agent sessions #785 coordinates session viewing, the retained REPL, and an XMD-owned multiplexer over this Grid/Pane foundation.
• View coding-agent sessions with <Session.Tail> and xmd tail #782 adds the read-only <Session.Tail> content shown by that Quest.
• Test black-box REPL messaging through xmd run terminal panes #774 records why provider session files remain observation and tmux input is not a reliable interaction protocol.

Out of scope

• Advertising an Agent without its independent native-launch proof.
• Provider-specific layout props, key bindings, executable selection, or identities in authored syntax.
• Detach-and-leave-running behavior, remote hosting, or browser streaming.
• Session transcript capture, <Session.Tail>, the retained REPL, or the XMD-owned multiplexer.
• Additional Agent working directories, owned by Add additional working directories to Agent sessions #682.