Quest: Add interactive terminal grids to executable documents

[taras]

Story

As a repository user, I want an executable document to open several interactive
terminals in one foreground grid, so I can work with multiple coding-agent
sessions 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. The first production provider uses tmux, but no tmux
session, window, pane, target, command, key binding, socket, or process identity
appears in the authored surface. Another multiplexer or native interface can
implement the same contract later without changing the document.

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

The example states the layout and role intent. A production pane launches only
an Agent that the host has independently advertised under the existing native
launch proof; this Quest does not advertise Codex or another provider.

Current state

The product implementation is unbuilt. <Session.Launch> currently owns the
root execution's one foreground terminal, so simultaneous native launches
refuse. Ordinary executable blocks are piped and captured and therefore cannot
substitute for independent interactive terminals.

The architecture is settled in architecture.md § Interactive terminal grids,
specs/executable-mdx-spec.md §6.21 and Tier TG, and
specs/native-agent-session-launch-spec.md § Terminal-grid composition. Closed
#726 and PR #727 establish the persistent tmux pane-worker topology and bounded
teardown facts. They are evidence and an accepted architecture decision, not
product implementation or delivery of this Quest.

Accepted product and lifecycle contract

<Terminal.Grid> and <Terminal> are core-owned structural syntax. A grid has
a positive integer column count and one or more statically authored direct
panes, placed in row-major order. A paired pane expands isolated document flow;
a self-closing pane runs the host's default interactive shell. Syntax inspection
and validation remain inert and report the same language on every runtime.

One grid owns the execution's foreground experience. Its panes start
concurrently through a replaceable provider and receive independent terminal
claims. The provider prepares the complete hidden composite and attaches it only
after every pane's 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. The grid remains foreground until the reader
closes or leaves it. Close prevents new launches, cancels live pane scopes,
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 terminal 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 binding, replay, and
provider advertisement remain those of #517.

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 is outside that observable macOS
boundary; the provider does not claim otherwise.

Dependency-ordered implementation Stories

1. Describe terminal grids as executable document structure #729 — Describe terminal grids as executable document structure
   • Owns the core grammar, exact forms and props, structural placement,
     row-major layout, syntax catalog, and inert document validation.
2. Execute concurrent terminal panes through a replaceable provider #730 — Execute concurrent terminal panes through a replaceable provider
   • Depends on Describe terminal grids as executable document structure #729.
   • Owns terminal authority, provider routing, pane scopes and claims,
     concurrency, readiness, atomic attach, default shell, output, settlement,
     teardown, durability, replay, and the controlled non-tmux provider.
3. Launch native Agent sessions in independent terminal panes #731 — Launch native Agent sessions in independent terminal panes
   • Depends on Execute concurrent terminal panes through a replaceable provider #730.
   • Owns the pane-scoped native launcher, independent terminal versus session
     ownership, native readiness, cancellation, quiescence, and controlled Agent
     journey.
4. Open terminal grids with tmux in foreground runs #732 — Open terminal grids with tmux in foreground runs
   • Depends on Execute concurrent terminal panes through a replaceable provider #730.
   • Owns the production tmux provider, Deno and compiled host assembly,
     persistent pane workers, authenticated IPC, explicit layout, visible and
     control clients, SIGHUP, and bounded process and terminal teardown.

#731 and #732 are independent consumers of #730 and may proceed in parallel.
The dependency graph is:

#729 → #730 → #731
 └→ #732

Acceptance map

Quest outcome	Owning Story and evidence
Exact public syntax, static placement and row-major layout	#729; TG1–TG4
Catalog and validation perform no terminal, shell, tmux, or Agent work	#729; TG3
Concurrent isolated pane execution through non-authoritative provider routing and direct terminal authority	#730; TG6–TG7 and controlled-provider TG18
Runtime-spawn readiness, hidden atomic startup and authored-order startup failure	#730; TG8–TG9
Independent visible settlement and complete reader-close, cancellation and provider-failure teardown	#730; TG10 and TG12–TG14
Provider-neutral durability, completed replay, partial replay and divergence	#730; TG15–TG17
Concurrent native sessions in distinct panes without weakening logical-session ownership	#731; TG5, TG11 and native-launch checklist 24–27
Deno/compiled tmux presentation with private workers, exact IPC, explicit layout, close classification and bounded teardown	#732; tmux half of TG18
Node and Bun expose the language and refuse operational use before pane start	#729 for catalog/validation and #732 for host-provider absence
Terminal-holder enumeration preserves quiescence without becoming public policy or a latency promise	#732; host process-adapter contract informed by #726

The Quest is complete when all four Stories are delivered to main, their
focused evidence passes, the terminal-grid portions of the three governing
contracts describe implemented rather than unbuilt behavior, and the resulting
runtime jobs remain covered by the required green aggregate.

Evidence already accepted

#726 closed with the persistent pane-worker topology accepted at PR #727
evidence commit 650510b5 and reviewed head/report 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.

Its measured lsof -t terminal-holder sweep cost is a design constraint owned
by #732. It motivates keeping enumeration behind the host process adapter; it
does not create another POC, define a latency threshold, or permit pane reuse
before the same quiescence fact is established.

Out of scope

• Advertising Codex or another unproven native Agent provider.
• Provider-specific layout props, key bindings, or executable selection.
• Detach-and-leave-running behavior, remote terminal hosting, browser streaming,
  or transcript capture.
• Additional Agent working directories, owned by Add additional working directories to Agent sessions #682.
• A new tmux feasibility proof or a product implementation copied wholesale
  from PR 🔬 Prove persistent tmux pane workers for <Terminal.Grid> (#726) #727.

[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.