You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
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.
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.Launchintegration and theproduction 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.Launchnorinstalls 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
exact row-major layout from Describe terminal grids as executable document structure #729 and begins all authored pane operations
concurrently.
contextual changes, checked failures,
Break, andReturnfrom siblings andenclosing control flow.
the grid and a surrounding capture receive no pane display or terminal bytes.
rejected by a crossed test, and a child that spawns then immediately exits is
both ready and settled.
a partial grid. All acquired pane work and finalizers settle, and simultaneous
failures select the first authored ordinal.
final status remains visible until reader close.
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.
claims do not contend. A claim from another grid, ordinal, provider generation,
or completed invocation authorizes nothing.
absence refuses before pane start or shell execution.
completed pane statuses, continues incomplete durable children, and refuses a
changed layout before provider contact.
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:
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
architecture.md§ Interactive terminal grids andspecs/executable-mdx-spec.md§6.21 and Tier TG.Session.Launchbehavior, Agent coordinator change, tmux command, realterminal multiplexer, or new Agent advertisement is implemented here.
Verification stack
This Story is the third layer of #717's linear verification stack.
97be06321cbdf08d84ef53dbefb88407f54326fe,the reviewed head of PR ✨ Describe terminal grids as executable document structure (#729) #733.
agent/issue-729-terminal-grid, notmain.branches from that revision.
feature verification.