Run a Plan and follow its Agent sessions in the REPL

[taras]

Story

As a person running XMD interactively, I want to run a real Plan and follow all
of its Agent conversations in the REPL, so I can understand live work, answer
permissions and reviews, and reopen the durable result without leaving the
execution that owns it.

Common path

Run xmd repl with the same Agent provider, default-agent and permission options
that xmd run accepts. Submit:

<Evaluate allow={["write"]}>
  <Plan>
    Create an XMD program that asks me for a project name and a one-sentence
    description. Preview the README it will create and ask for confirmation.
    If I approve, write README.md and report that it was created. If I
    decline, stop without writing anything.
  </Plan>
</Evaluate>

The Sessions surface shows the Plan conversation while it is queued, streaming
and complete. The returned Plan appears at its invocation and its generated XMD
executes inline. Plan review supports feedback and approval. The generated
program asks for the README inputs, presents the complete preview, and writes
only after approval.

A second deterministic journey opens planner, reviewer and implementer
conversations together. The default Sessions view shows every turn in durable
prompt order. Choosing a session filters the view with
?session=<session-key>; removing that query returns to all messages.

The contract below preserves the behavior accepted from version 5 of the
Product Owner's XMD REPL Terminal Interface. The animation is supplementary
evidence, not an implementation or persistence format.

Current gap

Issue #848 delivered one production REPL entry, deterministic Elicit, History
inspection and cold reconstruction. Its Sessions surface is intentionally
empty. xmd repl accepts no Agent options, installs no provider, observes no
live Prompt stream and cannot present the Plan review or generated README forms.

The ordinary run stack cannot simply be reused unchanged: its interactive
permission policy starts readline on the same terminal the REPL owns, and its
foreground launcher may hand that terminal to a provider-native UI.

Contract

Command and configuration

xmd repl accepts its optional location plus:

--agent-provider <provider>
--default-agent [agent]
--approve-all
--approve-reads
--deny-all

approve-reads is the default and the permission flags are mutually exclusive.
Invalid configuration refuses before the terminal, retained history, adapter or
provider is acquired. A document with no Agent work starts no adapter.

The REPL installs the selected provider and Agent components without the
ordinary readline permission prompt or foreground launcher. <Session.Launch>
remains unavailable.

Sessions and turns

With no session query, every Agent turn appears in one chronological stream
ordered by its durable Prompt sequence. session=<session-key> filters that
stream to the provider conversation the key identifies. An unknown key refuses
the location.

A live Prompt creates one queued turn. Provider start, text deltas and terminal
state update that same turn. These updates never change the filter, route,
selected scope, inspected marker or focus. A live text delta is neither
transcript output nor a durable event.

The ordinary agent_prompt append replaces the live overlay and is the only
source for historical and cold Agent turns. A historical prefix before that
append contains no partial response. A cold reopen shows completed, failed and
cancelled retained turns without contacting the provider or pretending a live
stream survived.

Plan and forms

The completed Plan response appears at its invocation and, when it is XMD, is
admitted through the existing <Evaluate> path and evaluated inline.

This Story supports only the forms exercised by the packaged Plan and generated
README program: object text fields, enum decisions, conditionally required
feedback, validation feedback and read-only Markdown or code preview. An
unsupported schema refuses before showing a partial form and identifies the
unsupported keyword and path.

Plan review shows the complete Plan and available decisions, never a future
execution result. The fixed History footer stays reachable while any review,
ordinary Elicit or permission drawer is open, and focus returns to the invoking
location when it closes.

Permissions

A permission request is visible on its owning Agent turn but does not open a
drawer or steal focus by itself. Activating it opens a focus-trapped drawer above
the fixed History footer with every choice the provider offered. Duration is
explicit, including that an “always” choice is scoped to this Agent session.

Only the owning turn waits. Other sessions continue. Choosing one option returns
one outcome to the exact request. Escape, interruption and session teardown
deny or cancel it once and cannot leave the provider waiting. Historical
permission requests are visible but never actionable.

Responsive behavior

Wide composition presents the coordinated panes. Narrow composition mounts only
the routed outlet, active contextual drawer or band, and fixed History footer.
Hidden panes contribute no focus, input, frame demand or rendering. The
canonical location appears once.

Architecture boundaries

• The existing Journal remains the only durable execution record; no Agent UI
  sidecar, snapshot or new record family is added.
• agent_prompt records project into frozen ReplModel session and turn values.
  Routing, layout, components and rendering never read Journal records.
• An agent_prompt may retain a closed permission audit containing safe display
  fields, offered choices and the outcome. It never retains rawInput, a
  callback, waiter or provider object; older records remain valid.
• The REPL observes live turns by wrapping the existing Agent.prompt() stream
  with execution-scoped middleware. <Prompt> remains the sole subscriber and
  owner of provider cancellation. No new public Agent API is introduced.
• The REPL answers interactive permissions through middleware around the
  existing Agent.requestPermission() operation. The REPL session owns the
  pending request; the renderer does not.
• Live observation cannot delay, cancel or alter the provider result. Renderer
  absence drops visual wakes, not Agent events or ownership.
• One application commit replaces a terminal live overlay with its matching
  durable Prompt. Concurrent or identical turns cannot be matched by response
  text, display label or completion order.

Acceptance

• The real packaged Plan streams in the Sessions surface, returns its XMD at the
  Plan invocation and completes the generated README review and approved write
  through the existing runtime.
• Request changes without feedback remains open with validation; valid feedback
  resumes the same conversation. Approve and Decline have distinct observable
  outcomes.
• Three concurrent named sessions show queued, active and complete turns in one
  unfiltered chronology. Selecting one adds session=<key> and filters only the
  messages; background activity changes no route, filter, scope, marker or
  focus.
• Keyboard and pointer activation of the same session or permission control
  produce the same action and outcome.
• A non-read permission request waits only its turn, exposes every provider
  choice with explicit scope, and settles exactly once on choice, Escape,
  interruption and teardown. After Prompt publication the safe request and
  outcome remain visible but inert; rawInput is absent. No readline reader
  exists.
• A marker before durable Prompt publication shows no partial turn. A marker at
  or after publication and a cold reopen show the retained prompt, terminal
  state and final or partial result while making zero provider calls.
• Invalid Agent configuration refuses before host acquisition. A document with
  no Agent work acquires no adapter. <Session.Launch> refuses without taking
  the terminal.
• Renderer failure or terminal loss cannot orphan a provider turn or permission
  wait; already appended Journal truth remains reconstructible and the terminal
  is restored once.
• Wide and narrow terminal journeys preserve the accepted composition, focus
  and History behavior. Narrow Sessions views show the canonical location once.

Negative controls fail if deltas become transcript rows or durable events, the
latest activity selects itself, a historical permission can answer, a cold
reopen fabricates a live turn, the ordinary readline policy is installed, a
partial form mounts, or one live completion replaces another turn's durable
row.

Evidence

Use two deterministic product journeys: the exact Plan/README source above and
a separate three-session document. Drive them through the real XMD execution,
Agent stream, durable Journal, canonical location, mounted Freedom tree,
renderer and terminal host. Compare the accumulated live view with a fresh
projection from the same Journal and location.

Keep focused evidence portable across Deno, Node and Bun except for explicitly
named pseudo-terminal cases. The Planner derives exact test files and feedback
slices from the architect handoff.

Relationships

• Child of Quest: Run, inspect, and resume XMD execution in the REPL #827 and successor to delivered Run and reconstruct one XMD entry in the REPL #848.
• Begins from merged production commit
  8adc10429578a14d0c09ba322d77ca3831f87fcd or a later main.
• Uses the installed <Plan>, <Session>, <Prompt>, <Evaluate> and
  <Elicit> behavior and the existing Agent and permission operations.
• xmd tail remains an independent read-only product and supplies no REPL truth.

Out of scope

• A second submitted entry, entry catalog or concurrent entry queue.
• Fork from here or inherited Agent-session semantics.
• Renaming, deleting, importing or otherwise managing sessions.
• Native <Session.Launch> terminal handoff or provider-TUI mirroring.
• Provider session files as REPL truth.
• A general JSON Schema form toolkit, public terminal component package,
  snapshots or another REPL journal record family.
• Adding the interactive REPL to Workflow.

[taras]

Architect handoff: run a Plan and follow its Agent sessions in the REPL

Verdict

PASS — ready for planning.

The reviewed production base is 8adc10429578a14d0c09ba322d77ca3831f87fcd,
merged by PR #853. It delivers the one-entry REPL from issue #848. The next
Story extends that production implementation; it does not promote code from the
discarded POCs.

The Product Owner accepted version 5 of XMD REPL Terminal Interface as the
observable interaction reference. This handoff records its lasting behavior so
the Story does not depend on a file in Downloads. The mockup is authoritative
for behavior, not React, fixture shapes, pixel sizes or component structure.

Outcome

Run the packaged <Plan> inside xmd repl, follow its Agent conversation while
it is queued and streaming, review the returned Plan, then execute the generated
README program through the existing inline <Evaluate> path. The same REPL also
shows several concurrent Agent sessions without letting background work steer
the person's route, filter, focus or historical inspection.

This Story closes the largest product gap after #848. It does not add a second
submitted entry, forks, session management, native Agent terminal handoff or a
general JSON Schema form framework.

Accepted product interface

Command

xmd repl accepts its existing optional location and the Agent options already
established by xmd run:

--agent-provider <provider>
--default-agent [agent]
--approve-all
--approve-reads
--deny-all

approve-reads remains the default. The permission flags are mutually
exclusive. An unknown provider, malformed location or invalid option
combination refuses before the terminal, retained history, adapter or provider
is acquired. A document that uses no Agent starts no adapter.

The REPL installs the configured Agent provider and components but never the
foreground launcher. <Session.Launch> remains unavailable because this Story
does not hand the full-screen terminal to a provider-native UI.

Sessions surface and location

With no session filter, the Sessions surface shows every Prompt turn in durable
prompt sequence, interleaving conversations into one chronological stream. A
session selector filters that stream to one conversation. It does not navigate
to a different path.

The canonical location carries the filter as:

?session=<session-key>

or as another query member beside at, inspect and draft. An absent
session means all conversations. The value is the provider's retained
sessionKey, percent-encoded by the existing route codec. An unknown session
key is an unresolved location, not an empty view.

Receiving the first or a later Agent event never changes the route. The normal
Sessions view stays unfiltered until the person chooses a session.

Queued, started, delta and terminal updates preserve the selected session,
selected execution scope, inspected marker and exact Freedom focus. Choosing
another session is a semantic action at the application root.

Agent turns

A live Prompt appears immediately as one queued turn. Provider started moves
that same turn to active and supplies its actual agent and session. Each
text_delta extends the same response. A terminal event marks it completed,
failed or cancelled without creating transcript rows for the individual
deltas.

Live deltas are process-local presentation state. They are not Document Output,
not fabricated durable events and not written to a UI sidecar. The ordinary
agent_prompt durable result replaces the live overlay after publication. Only
that record makes the Prompt part of historical or cold reconstruction.

A historical prefix before the agent_prompt append shows no partial turn. A
prefix at or after the append shows the retained prompt, terminal status and
complete or partial final text. Cold reopen shows only retained records. It
never presents queued, responding, a live cursor or a reconnecting fiction, and
it contacts no provider.

The completed Plan response remains visible at the Plan invocation. When it is
XMD, the existing <Evaluate> admission displays and evaluates it inline; it is
not appended as unrelated transcript output.

Permissions

A non-read Agent tool request first appears as an inline fact on its owning turn.
Activating it opens one focus-trapped contextual drawer above the fixed History
footer. The drawer presents the exact provider choices and makes the duration
explicit, including that an “always” choice lasts for this Agent session rather
than becoming a machine-wide rule.

The request suspends only its owning Agent turn. Other sessions and ordinary
Effection work continue. The drawer does not open itself, change the session
filter or steal focus merely because the request arrived. Choosing an option
returns one PermissionOutcome to the exact request. Escape, interruption and
session teardown settle it through the defined denial or cancellation outcome;
none may leave the provider waiting.

Historical permission requests are readable facts and have no actionable
control. The REPL never starts readline and never gives two readers the same
terminal.

Bounded Elicit support

This Story implements the forms exercised by the real packaged Plan and its
generated README program:

• object forms with text fields;
• an enum decision;
• conditionally required feedback;
• validation feedback; and
• read-only Markdown or code preview.

Plan review shows the entire returned Plan and the decisions available at that
moment. It never previews a future execution result. The generated program asks
for project name and one-sentence description, previews the README it would
write, and asks for Approve or Decline.

An unsupported schema refuses before mounting a partial form and names the
unsupported keyword and path. This is not a general JSON Schema form toolkit.

The fixed History footer remains reachable while a Plan review, ordinary Elicit
or permission drawer is open. Closing or answering returns focus to the
invocation that opened it.

Responsive composition

Wide composition mounts the coordinated panes. Narrow composition mounts only
the routed outlet, the active contextual drawer or band, and the fixed History
footer. Hidden panes have no mounted branch, focus target, input middleware,
frame demand or render output.

The canonical location is shown once. In narrow Sessions views it is not
duplicated inside the routed surface.

Accepted architecture

Durable model

The existing durable Journal remains the sole retained execution record.
parsePromptRecord() is the hostile reader for agent_prompt results. The
record gains one optional closed permission-audit list for requests completed
during that turn: tool-call ID, optional title and kind, the offered option IDs,
names and kinds, and the selected option ID or cancellation. It never retains
rawInput, a callback, a waiter or a provider object. Older records with no list
remain valid.

The projector adds frozen session and turn values to ReplModel, grouped by
retained sessionKey and ordered by PromptRecord.sequence. Routing,
components, layout and rendering continue to receive only projected values.

No new record kind, snapshot, sidecar or persisted UI state is introduced.
Request, provider start, deltas and permission waits remain live facts. A
permission becomes historical only as the completed audit retained with its
settled ordinary Prompt record. That Prompt record is the durable boundary.

Live observation uses the existing Agent API

The REPL installs middleware around the existing Agent.prompt() operation at
the execution boundary. The middleware returns a wrapped stream; the <Prompt>
component remains the stream's only subscriber and retains ownership of the
provider turn and its cancellation. The wrapper announces queued state before
delegation and copies started, text_delta and terminal events into the
REPL session's detached live projection while yielding the same events and
terminal value unchanged.

This is a REPL installation, not a new member of AgentApi, a provider callback
or a document-composable observer. It is absent from ordinary runs and full
replay. Removing the renderer does not unsubscribe, cancel, delay or consume the
turn.

The live turn key is process-local and opaque. It is stable only from the
queued announcement through that turn's publication. It is never encoded in a
URL or journal. Publication causes one atomic application reprojection: the
durable Prompt appears and the matching live overlay disappears in the same
committed view. The implementation must demonstrate that concurrent turns and
identical text cannot replace the wrong row; it may not match by label, response
text or completion order.

Observation never waits for a render or frame. It updates the latest immutable
live projection and coalesces a wake-up for the application. If the application
or renderer is absent, the visual update is dropped while the Prompt continues.
An observer defect cannot change the Prompt result, reorder provider events or
keep a cancelled turn alive.

Durable publication stays separate

The existing Journal append remains the event that replaces live state with
retained state. The live terminal event is not retained truth. A publication
failure leaves no durable turn and follows the existing durability failure
path; cold reconstruction never recovers the live overlay.

Permission handling uses the existing Agent API

The REPL installs middleware around the existing
Agent.requestPermission(request) operation. It applies the selected permission
mode and, when a person must decide, sends the exact PermissionRequest to the
REPL session and waits for exactly one PermissionOutcome. The session owns the
pending request and drawer; its teardown settles the wait. The renderer owns
neither.

The Prompt's existing execution scope observes that same operation around the
provider turn, delegates it unchanged, and copies the request's safe display
fields plus the returned outcome into the Prompt record's permission audit. It
uses the existing operation and scope inheritance; it adds no public or
cross-package API. The live REPL handler still receives the complete request,
including rawInput, but that member never crosses the durable boundary.

This replaces the ordinary run stack's readline policy inside the REPL. It does
not add a permission API, weaken the provider's offered choices or expose a
document-level callback.

Ownership flow

Agent.prompt middleware -> detached live turn overlay -> immutable ReplView
ordinary agent_prompt append -> ReplModel reprojection -> historical/cold turn
raw terminal input -> mounted Freedom target -> semantic action -> application
Agent.requestPermission middleware -> session-owned wait -> contextual drawer

The execution owns provider turns and permission waits. The Journal owns
retained Prompt truth. The REPL session owns live overlays and application
wakes. The mounted Freedom tree owns presentation lifetime, focus and input.
The renderer owns only the bytes for one acknowledged frame.

Product verification

1. The real Plan journey

Submit this source:

<Evaluate allow={["write"]}>
  <Plan>
    Create an XMD program that asks me for a project name and a one-sentence
    description. Preview the README it will create and ask for confirmation.
    If I approve, write README.md and report that it was created. If I
    decline, stop without writing anything.
  </Plan>
</Evaluate>

A deterministic Agent streams the Plan. The Sessions surface updates one turn
without adding delta rows to the transcript. The returned XMD replaces the Plan
expression and executes inline. Request changes without feedback stays open
with validation; valid feedback resumes the same conversation. Approval runs
the generated project form and confirmation preview, then writes and reports
the README once.

A fake Plan, a response appended as unrelated output, a form reduced to its
first enum or a preview that includes the future write result fails.

2. Concurrent sessions do not steer the person

A separate deterministic document opens planner, reviewer and implementer
conversations so one is complete, one streams and one is queued in the same
frame. The unfiltered Sessions view interleaves every turn by prompt sequence.
Choosing reviewer adds session=<reviewer-key> and filters the messages.

While focus remains in the transcript, background start, delta, permission and
terminal events preserve route, filter, selected scope, inspected marker and
focus. Removing the query returns to all messages. A latest-activity selector,
completion-order key or background focus move fails.

3. Permission ownership

A non-read request becomes visible on its owning turn without moving focus.
Activation opens the drawer; every offered choice is reachable and visibly
scoped. The selected choice resumes only that turn while another session keeps
streaming. Escape, interruption and teardown each settle the provider wait once.
After the Prompt publishes, inspection and cold reopen show the safe retained
request and outcome without rawInput and without an action. Readline, silent
approval, an actionable historical request, leaked raw input or a provider left
waiting fails.

4. History and cold reconstruction

Inspect a marker before the Prompt record and one at or after settlement. The
earlier view contains no delta or fabricated turn. The later view contains the
ordinary retained Prompt facts. A cold process reconstructs completed, failed
and cancelled turns, performs zero provider calls and leaves the Journal
byte-identical. A sidecar, revived live cursor or partial text before durable
publication fails.

5. Configuration and failure

Help lists the five Agent options and their defaults. Invalid configuration
refuses before host acquisition. A document with no Agent reaches no adapter.
Provider failure, cancellation, terminal loss and renderer failure preserve
already appended records, stop admitting new visual facts where required, join
owned turns and permission waits, and restore the terminal once.

Signal-controlled tests distinguish queued, active, terminal-live, durably
published and cold-reconstructed states. A final screenshot alone is not
sufficient evidence.

Production scope and sequencing

The Planner should preserve these dependency boundaries:

1. Extend the hostile durable projection and route codec with session turns and
   the optional session query.
2. Install the configured provider plus existing prompt and permission
   middleware without the foreground launcher or readline policy.
3. Add the detached live overlay and prove atomic replacement by durable Prompt
   publication.
4. Add the bounded forms required by the packaged Plan and README journey.
5. Compose the Sessions timeline, selector, turn detail and permission drawer
   through the existing keyed tree and responsive layouts.
6. Prove both journeys, historical prefixes, cold reopen, failure and teardown
   through the real terminal path.

Each feedback slice must leave the existing one-entry journey green. Planning
may refine file and commit boundaries but may not ask the Implementor to choose
the product, identity, lifetime, durability or absence semantics above.

Explicit follow-ups

• Entry 2, an entry catalog and concurrent submitted entries.
• Fork from here and inherited Agent-session semantics.
• Rename, delete, import or otherwise manage sessions.
• Native <Session.Launch> terminal handoff.
• Provider-native TUI mirroring or provider session files as REPL truth.
• A general JSON Schema form framework or public terminal component package.
• Snapshot persistence or another REPL record family.

Required durable updates

The implementation updates specs/repl-spec.md, the Agent journaling and
permission sections of specs/acp-client-spec.md, the architecture inventory
and focused product evidence. A reusable architecture rule is added only if the
implementation discovers a rule not already settled by the mounted-tree,
Journal-projection, routing or host-input rules.

Planner handoff

Plan from origin/main at or after 8adc1042. Use this handoff and the new
child Story under Quest #827 as the complete contract. Inspect version 5 of the
mockup only to clarify an animation or layout transition; its behavior is
already recorded here and in the Story.