Skip to content

Execute concurrent terminal panes through a replaceable provider #730

Description

@taras

Story

As an executable-document host, I want the panes in a terminal grid to execute
concurrently through one replaceable terminal provider, so the document keeps
one lifecycle and replay contract whether the presentation is tmux, a controlled
test surface, or a future native interface.

This is the provider-neutral execution Story under #717. It begins after #729
has frozen the structural language. Native Session.Launch integration and the
production tmux provider are separate consumers of the boundary established
here.

Contract

Core validates the complete resolved layout, takes the document execution's one
foreground-terminal lease, flushes root output, and issues one provider request
for the exact grid expansion. The host supplies a terminal provider and a
non-contextual terminal authority. The stable contextual API routes the request
and permits observation, narrowing, refusal, wrapping, and delegation; no
handler return value can authorize or settle a grid. Only the direct authority
can validate the request, mint one-use pane claims, and acquire or release root
and pane terminal ownership.

The provider prepares the whole composite while it remains hidden. Core creates
one durable child operation per authored pane ordinal and starts those children
concurrently. A paired pane expands its document flow in an isolated binding,
evaluation, checked-failure, and control-flow scope while inheriting the grid
site's providers, configuration, working directory, repository selection, and
bindings. A self-closing pane starts the host-configured default interactive
shell through its pane claim. Pane display reaches that pane only; the grid
renders "", and native terminal bytes are neither captured nor journaled.

Each pane becomes ready only when its first interactive child reports the
runtime's successful spawn event through the private one-use readiness latch in
its pane claim. Endpoint or PID allocation, preparation, first output, or child
settlement without a spawn event is not readiness. The provider attaches the
composite only after every pane is ready. Any provider-preparation or pane-start
failure before that barrier cancels every pane, awaits complete teardown,
discards the hidden composite, restores the root terminal, and reports the first
failure by authored pane order. Effects completed before the failed start remain
durable.

After attachment, pane success and ordinary failure are independent visible
statuses and do not cancel siblings. The composite remains visible after all
panes settle until the reader closes it. Close prevents new launches, cancels
live pane scopes, awaits every child and finalizer, destroys the exact
composite, restores the root terminal, releases its lease, 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. Provider failure
cancels and fails the whole grid. Parent cancellation follows the same complete
teardown and remains cancellation.

The terminal authority and pane claims grant terminal ownership only. They
grant no Agent-session authority. This Story exposes the pane-scoped launch seam
that later integrations consume, but it neither changes Session.Launch nor
installs an Agent provider.

Durability and replay

The grid is one core-owned structured durable region. Its identity contains the
resolved columns and ordered pane forms and titles. Pane child identities derive
from the grid expansion and ordinal, never a title, schedule, or provider
identifier.

The completed record retains the provider-neutral layout, close kind, and
ordered pane outcomes after the ordinary secret gate. Completed replay restores
the exact result without contacting a terminal provider, expanding pane content,
or starting a shell. Partial replay compares the complete layout before provider
work, builds a fresh live composite, restores completed panes as statuses, and
continues incomplete pane children from their own durable histories. An
incomplete self-closing pane starts the current authorized default shell and
claims no terminal-history continuity.

Commands, sockets, paths, process identifiers, layout identifiers, argv,
environment, terminal bytes, and provider topology remain live provider state
and enter no public request result, retained identity, record, or diagnostic.

Acceptance

  • A controlled provider that is not tmux runs one through eight panes using the
    exact row-major layout from Describe terminal grids as executable document structure #729 and begins all authored pane operations
    concurrently.
  • Each pane inherits grid-site state but isolates its own later bindings,
    contextual changes, checked failures, Break, and Return from siblings and
    enclosing control flow.
  • Root output is flushed before preparation; pane output reaches only its pane;
    the grid and a surrounding capture receive no pane display or terminal bytes.
  • Readiness is exactly the runtime child-spawn event. Every earlier candidate is
    rejected by a crossed test, and a child that spawns then immediately exits is
    both ready and settled.
  • Every provider-preparation and pane-start position can fail without attaching
    a partial grid. All acquired pane work and finalizers settle, and simultaneous
    failures select the first authored ordinal.
  • After attach, one pane can succeed or fail while siblings remain live. Its
    final status remains visible until reader close.
  • Reader close, parent cancellation at preparation/readiness/active phases, and
    provider failure each perform complete teardown with the specified result and
    failure precedence. No later document sibling starts while any acquired pane
    or provider resource remains live.
  • One pane claim admits only one interactive operation at a time; distinct pane
    claims do not contend. A claim from another grid, ordinal, provider generation,
    or completed invocation authorizes nothing.
  • The default shell uses live host policy and the pane terminal; provider
    absence refuses before pane start or shell execution.
  • Completed replay performs no provider or pane work. Partial replay restores
    completed pane statuses, continues incomplete durable children, and refuses a
    changed layout before provider contact.
  • Retained and diagnostic data contain only provider-neutral layout and outcome
    facts.

This Story owns TG6–TG10 and TG12–TG17, plus the controlled-provider half of
TG18. TG5 and Agent-session contention in TG11 belong to the native-launch
Story. The tmux half of TG18 belongs to the production-provider Story.

Focused evidence

Add the controlled provider and terminal-authority tests beside the core
structured execution they exercise:

deno task test packages/core/tests/terminal-grid.test.ts
deno task test packages/runtime/tests/terminal-provider.test.ts

The suite uses test-controlled readiness, settlement, close, failure, and
teardown operations. It must prove provider non-observation and teardown
ordering directly rather than infer them from process timing.

Dependencies and exclusions

Verification stack

This Story is the third layer of #717's linear verification stack.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions