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

The complete #717 implementation exists on the unmerged agent/issue-717-terminal-packages stack. Its structure, provider lifecycle, pane-native launch, tmux provider, package extraction, and focused evidence have been reviewed. The current stack head beneath PR #764 is a73b2d6d53cdaaac286044c69590f9f07eb9083d.

That stack still exposes the rejected <Terminal.Grid>/<Terminal> syntax and @executablemd/terminal package names. Because none of it has merged or shipped, #781 replaces those names before delivery and preserves no compatibility aliases. No #717 layer merges until the repaired Grid/Pane 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 display labels supplied by the document, may include role and current issue, may repeat, and do not identify panes. A pane's structural identity is its authored ordinal.

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 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 owns the execution's foreground experience. Its panes start concurrently through a replaceable provider and receive independent pane claims. The provider prepares the complete hidden composite 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 composite, restores the root terminal, and only then 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
   • Implemented on the unmerged stack.
   • 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
   • Implemented on the unmerged stack after Describe terminal grids as executable document structure #729.
   • Owns provider-neutral authority, concurrency, lifecycle, durability, replay, and controlled-provider evidence.
3. Launch native Agent sessions in independent terminal panes #731 — Launch native Agent sessions in independent terminal panes
   • Implemented on the unmerged stack after Execute concurrent terminal panes through a replaceable provider #730.
   • Owns pane-scoped native launch, 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
   • Implemented on the unmerged stack after Launch native Agent sessions in independent terminal panes #731 for delivery verification.
   • Owns tmux host assembly, 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>
   • Starts from the accepted Quest: Add interactive grids to executable documents #717 package-stack head after Open terminal grids with tmux in foreground runs #732.
   • Replaces the public syntax, domain names, packages, imports, documentation, diagnostics, and tests while preserving all accepted behavior.

#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 replaceable provider routing	#730
Runtime-spawn readiness, atomic startup and authored-order failure	#730
Independent settlement and complete close, cancellation and provider-failure teardown	#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.