Quest: Add interactive grids to executable documents

[taras]

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 ✨ Execute concurrent terminal panes through a replaceable provider (#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

Quest outcome	Owning Story and evidence
Static public structure, exact forms and row-major layout	#729, renamed and made canonical by #781
Catalog and validation perform no terminal, shell, tmux, or Agent work	#729 and #781
Concurrent isolated pane execution through one scope-owned replaceable-provider lifecycle	#730
Atomic current-and-newer state observation and serialized revision coalescing	#730, TG20 and TG23
Pre-show and pre-terminal-transfer convergence	#730 and #731, TG23
Independent provider-failure observation and complete teardown during convergence	#730 and #732, TG24
Runtime-spawn readiness, atomic startup and authored-order failure	#730
Provider-neutral durability, completed replay, partial replay and divergence	#730
Concurrent native sessions without weakening logical-session ownership	#731
Deno/compiled tmux presentation and Node/Bun fail-closed behavior	#732
Canonical <Grid>/<Pane> syntax and grid/grid-tmux package boundaries, with no old compatibility surface	#781
Terminal-holder observation remains replaceable host infrastructure rather than layout identity	#732 and #781

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.

[taras]

Architect decision from #726 / PR #727: adopt the persistent tmux pane-worker topology. Each pane has one persistent initial worker; exact argv/cwd/environment and display/lifecycle messages use authenticated invocation-private IPC; the worker creates the interactive child with inherited stdio and reports readiness only from the runtime spawn event. The provider applies explicit layout plus swap-pane, uses separate visible and no-output control clients, attaches only after the all-pane barrier, and treats root-terminal SIGHUP as structured cancellation. Pane workers use Effection run(), not main(), so SIGINT remains terminal job control rather than worker exit 130.

The lifecycle contract is narrowed to the facts the macOS host can establish. Teardown proves 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 remains. A descendant that already created a new session, closed the terminal, and lost its parent has severed all observable links and is outside that claim. The Story and its Acceptance section now state this boundary.

One proof correction remains on #726 before implementation planning treats sequential reuse as established: the pane worker must perform its terminal-holder sweep before clearing the active launch and reporting exited, not only during final worker shutdown. PR #727 currently permits an escaped terminal holder from the prior launch to overlap a later child in the same pane. The topology decision stands; #726 remains open for that crossed negative path.

[taras]

Architect readiness update: the remaining pane-reuse proof condition is satisfied at PR #727 head 80770ea3 / evidence 650510b5; #726 is closed with PASS.

The worker now completes escalation and its terminal-holder sweep before clearing the pane or reporting exited, and the crossed regression proves an escaped holder cannot overlap the next child. The persistent pane-worker topology, spawn-event readiness, explicit row-major layout, atomic attach, distinct close signals, and bounded macOS teardown contract are decision-complete for implementation planning.

The measured sweep cost is an implementation concern, not a contract change: median handoff was 616 / 814 / 1500 ms at 2 / 4 / 8 panes, while relaunch after exited remained about 2 ms. The architecture keeps holder enumeration behind the host process adapter so it can be optimized without weakening pane quiescence.

#717 is architecture-ready. This is not an implementation or merge-readiness verdict; the production feature and its controlled non-tmux contract suite remain unbuilt.

[taras]

The Quest now uses one linear delivery stack so the complete feature can be
verified at a single top revision before any layer merges:

1. 🏗️ Define interactive terminal grid architecture (#717) #734 — architecture contract, base main, head
   architect/717-terminal-grid-contract at 736b909d.
2. ✨ Describe terminal grids as executable document structure (#729) #733 / Describe terminal grids as executable document structure #729 — authored structure, base the architecture branch, head
   agent/issue-729-terminal-grid at 97be0632.
3. Execute concurrent terminal panes through a replaceable provider #730 — provider-neutral execution, based on ✨ Describe terminal grids as executable document structure (#729) #733's exact head.
4. Launch native Agent sessions in independent terminal panes #731 — native Agent sessions, based on Execute concurrent terminal panes through a replaceable provider #730's accepted head.
5. Open terminal grids with tmux in foreground runs #732 — tmux foreground provider, based on Launch native Agent sessions in independent terminal panes #731's accepted head.

The product dependency remains #729 → #730 → {#731, #732}. The delivery
stack linearizes #731 before #732 only so #732's final PR head contains both
consumers and can serve as the end-to-end verification target. This does not
move native-launch work into #732 or tmux work into #731.

No layer merges until that exact final head passes the complete feature
verification. After acceptance, merge bottom-up from #734 so each focused PR
retargets cleanly onto its predecessor.

[taras]

Product contract amendment

The Product Owner has rejected Terminal as the public identity of the grid and its cells. Because the complete stack is unmerged, no compatibility surface is preserved.

#781 now owns the final #717 amendment:

• <Terminal.Grid> → <Grid>
• <Terminal> → <Pane>
• @executablemd/terminal → @executablemd/grid
• @executablemd/terminal-tmux → @executablemd/grid-tmux

The persistent worker, terminal capability, native launch, layout, durability, replay, cancellation, and teardown contracts remain intact. Terminal terminology remains only for actual PTY, foreground-terminal, process-observation, and interactive-child behavior.

The exact implementation base for planning is the accepted #717 stack head a73b2d6d53cdaaac286044c69590f9f07eb9083d. No existing #717 layer merges until #781 is accepted. The descriptions of #729–#732 remain unchanged because they are active implementation contracts for the slices already built; #781 replaces their unshipped public surface at the top.

PR #764 retains its sole #755 Codex-certification purpose. It is rebased onto the repaired #717 head after #781 rather than absorbing the Grid/Pane amendment.