Skip to content

Launch native Agent sessions in independent terminal panes #731

Description

@taras

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 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.
  • Completed grid replay contacts no Agent provider, coordinator, or native
    launcher. Partial replay of a launch retains the existing Launch a deterministically prepared Agent session in its native UI #517 identity and
    reconciliation behavior.
  • 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.

Dependencies and exclusions

Verification stack

This Story is the fourth 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