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 author, I want native Agent sessions in different
terminal panes to remain interactive at the same time, so a terminal grid can
host independent Implementor, Planner, Architect, or reviewer sessions without
weakening their existing continuity and ownership guarantees.
This is the native Agent integration Story under #717. It composes the
provider-neutral pane authority from #730 with the native launch contract from #517. It does not implement tmux or advertise another Agent provider.
Contract
At the root, <Session.Launch> keeps its current behavior: it takes the
document execution's foreground-terminal lease and hands the inherited terminal
to one native UI. Inside a paired <Terminal>, core installs a pane-scoped
native launcher that closes over that pane's private claim and readiness latch. <Session.Launch> uses the launcher already in scope; it receives no pane prop,
token, identifier, or mode, and its public launch request and durable result do
not change.
The pane launcher validates the exact claim through the host terminal authority,
reserves only that pane, flushes that pane, and starts the provider's exact
native launch request there. Launches in distinct panes may own their terminals
concurrently. A second live launch in the same pane refuses. Sequential launches
in one pane are admitted only after the previous child, its observable
descendants and process-group members, and every other holder of that pane
terminal are gone.
Pane ownership and Agent-session ownership remain independent. The existing
session coordinator keeps the natural provider, Agent, and logical-session key.
Two panes naming one logical session still contend without waiting; one pane's
terminal claim cannot ensure, create, resume, detach, prompt, attach to, or
otherwise authorize an Agent session. Distinct sessions may be owned
concurrently.
The launch acknowledges pane readiness only from the native child's successful
runtime spawn event and before waiting for exit. Session preparation, route
publication, private instruction-file creation, ACP detach, PID allocation, and
first output are not readiness. A failed spawn leaves any already-completed
durable launch phases intact and participates in the grid's hidden startup
teardown.
After attachment, a native UI's independent nonzero exit fails its pane flow and
does not cancel siblings. Reader close cancels a still-live launch through the
ordinary launch path, awaits native child teardown and Agent-session quiescence,
and does not turn that cancellation into another pane failure. Parent
cancellation remains cancellation.
All existing #517 rules remain true: prepared instructions are not a Prompt or
transcript, ACP and the native UI never own one session concurrently,
construction routes remain create-once, executable binding and provider-native
identity remain exact, and completed replay launches nothing. An incomplete
launch inside a pane preserves its existing prepared/detached identity and
never substitutes another conversation.
Acceptance
A checked-in executable Markdown journey uses a controlled provider to start
at least two distinct native Agent sessions in different panes before the grid
attaches; both remain concurrently interactive.
A root launch still takes the root foreground lease. A grid and root launch
cannot overlap, while two pane launches in distinct panes do not contend for
terminal ownership.
Two overlapping launches in one pane refuse. A sequential launch is admitted
only after the prior pane terminal is proven quiescent.
Two panes naming one logical Agent session still contend through the existing
non-waiting coordinator. Distinct sessions acquire distinct ownership without
any pane-derived key or authority.
The pane readiness latch is acknowledged only by the runtime spawn event. A
launch failure before spawn prevents grid attachment without rolling back
earlier durable Agent preparation.
Exact argv, cwd, environment, provider-native identity, construction route,
instruction layer, executable binding, and durable launch phases are the same
values the root launch would use; no provider layout identity enters them.
One pane's native exit becomes only that pane's status. Grid close cancels
live launches, awaits native process teardown and session quiescence, and lets
the document continue only afterwards.
TestAgent proves the journey without starting Claude, Codex, or a model. The
grid adds no native-launch advertisement, and an unadvertised Agent still
refuses before session ownership moves.
This Story owns TG5 and the Agent-session and native-launch portions of TG11,
plus native-session-launch checklist items 24–27. It reuses #730's lifecycle and
does not duplicate its generic provider, shell, or replay tests.
Focused evidence
Extend the existing native-launch layers and add one authored grid journey:
deno task test packages/core/tests/agent-session-launch.test.ts
deno task test packages/runtime/tests/native-launcher.test.ts
deno task test packages/test-agent/tests/native-launch.test.ts
deno task test packages/test-agent/tests/terminal-grid-native-launch.test.ts
The authored journey belongs beside the TestAgent native-session launch
documents and uses controlled start, exit, contention, cancellation, and
quiescence signals. No real Agent CLI is delivery evidence for this Story.
No tmux process topology, default-shell provider, new Agent advertisement,
model selection, additional working directory, transcript capture, or root
concurrent launch behavior is added here.
Verification stack
This Story is the fourth layer of #717's linear verification stack.
Story
As an executable-document author, I want native Agent sessions in different
terminal panes to remain interactive at the same time, so a terminal grid can
host independent Implementor, Planner, Architect, or reviewer sessions without
weakening their existing continuity and ownership guarantees.
This is the native Agent integration Story under #717. It composes the
provider-neutral pane authority from #730 with the native launch contract from
#517. It does not implement tmux or advertise another Agent provider.
Contract
At the root,
<Session.Launch>keeps its current behavior: it takes thedocument execution's foreground-terminal lease and hands the inherited terminal
to one native UI. Inside a paired
<Terminal>, core installs a pane-scopednative launcher that closes over that pane's private claim and readiness latch.
<Session.Launch>uses the launcher already in scope; it receives no pane prop,token, identifier, or mode, and its public launch request and durable result do
not change.
The pane launcher validates the exact claim through the host terminal authority,
reserves only that pane, flushes that pane, and starts the provider's exact
native launch request there. Launches in distinct panes may own their terminals
concurrently. A second live launch in the same pane refuses. Sequential launches
in one pane are admitted only after the previous child, its observable
descendants and process-group members, and every other holder of that pane
terminal are gone.
Pane ownership and Agent-session ownership remain independent. The existing
session coordinator keeps the natural provider, Agent, and logical-session key.
Two panes naming one logical session still contend without waiting; one pane's
terminal claim cannot ensure, create, resume, detach, prompt, attach to, or
otherwise authorize an Agent session. Distinct sessions may be owned
concurrently.
The launch acknowledges pane readiness only from the native child's successful
runtime spawn event and before waiting for exit. Session preparation, route
publication, private instruction-file creation, ACP detach, PID allocation, and
first output are not readiness. A failed spawn leaves any already-completed
durable launch phases intact and participates in the grid's hidden startup
teardown.
After attachment, a native UI's independent nonzero exit fails its pane flow and
does not cancel siblings. Reader close cancels a still-live launch through the
ordinary launch path, awaits native child teardown and Agent-session quiescence,
and does not turn that cancellation into another pane failure. Parent
cancellation remains cancellation.
All existing #517 rules remain true: prepared instructions are not a Prompt or
transcript, ACP and the native UI never own one session concurrently,
construction routes remain create-once, executable binding and provider-native
identity remain exact, and completed replay launches nothing. An incomplete
launch inside a pane preserves its existing
prepared/detachedidentity andnever substitutes another conversation.
Acceptance
at least two distinct native Agent sessions in different panes before the grid
attaches; both remain concurrently interactive.
cannot overlap, while two pane launches in distinct panes do not contend for
terminal ownership.
only after the prior pane terminal is proven quiescent.
non-waiting coordinator. Distinct sessions acquire distinct ownership without
any pane-derived key or authority.
launch failure before spawn prevents grid attachment without rolling back
earlier durable Agent preparation.
instruction layer, executable binding, and durable launch phases are the same
values the root launch would use; no provider layout identity enters them.
live launches, awaits native process teardown and session quiescence, and lets
the document continue only afterwards.
launcher. Partial replay of a launch retains the existing Launch a deterministically prepared Agent session in its native UI #517 identity and
reconciliation behavior.
grid adds no native-launch advertisement, and an unadvertised Agent still
refuses before session ownership moves.
This Story owns TG5 and the Agent-session and native-launch portions of TG11,
plus native-session-launch checklist items 24–27. It reuses #730's lifecycle and
does not duplicate its generic provider, shell, or replay tests.
Focused evidence
Extend the existing native-launch layers and add one authored grid journey:
The authored journey belongs beside the TestAgent native-session launch
documents and uses controlled start, exit, contention, cancellation, and
quiescence signals. No real Agent CLI is delivery evidence for this Story.
Dependencies and exclusions
durability, and the controlled terminal provider.
specs/native-agent-session-launch-spec.md§ Terminal-grid composition.parallel.
model selection, additional working directory, transcript capture, or root
concurrent launch behavior is added here.
Verification stack
This Story is the fourth layer of #717's linear verification stack.
open the implementation PR against Execute concurrent terminal panes through a replaceable provider #730's implementation branch.
branches from that revision.
expand this Story's native-launch scope.
feature verification.