Quest: Run, inspect, and resume XMD execution in the REPL

[taras]

Story

As a person running XMD interactively, I want each submission to become an
immutable transcript entry whose execution unfolds inline, so I can understand
live work, coordinate Agent sessions, answer suspended interactions, and inspect
earlier execution without leaving the REPL.

The REPL opens empty with one input. Submitting XMD or invoking a document
appends an entry and opens its execution projection in place. Component entry,
nested work, generated XMD, replacement output, exit, and teardown remain
visible as parts of that entry rather than becoming a mutable editor buffer.

The Product Owner's XMD REPL Terminal Interface animation and keyboard study
are the observable design reference. They demonstrate the empty REPL, immutable
Entry 1, nested Plan execution, concurrent Agent sessions, Elicit drawers, scope
bindings, history inspection, pause, scrub, reconstruction, return to the live
head, continuation, and settled Entry 1. They specify behavior, not a UI library
or component tree. The accepted behavior is preserved in the child Stories so
delivery does not depend on a file outside the repository.

Current state and gap

Issue #848 delivered the production kernel: xmd repl runs one immutable entry,
shows nested execution, bindings, generated XMD and one Elicit, pauses expansion,
inspects retained prefixes, and reconstructs a cold screen from ordinary durable
events plus one canonical location.

Its Sessions surface is intentionally empty. The REPL does not yet install an
Agent provider, show live or retained Prompt turns, present Agent permissions,
or support the bounded Plan and README forms. It still admits only one submitted
entry and implements no fork.

xmd tail in #782 remains a separate read-only product for opening
provider-owned session files. It is neither a prerequisite nor the source of
truth for this REPL.

Product contract

One execution transcript

• The transcript is the primary surface. It is not an editor displaying a
  mutable source document.
• Every submitted entry keeps its exact source immutable.
• An opening component enters a stable scope and acquires that scope's
  resources. Its body executes there. Its output replaces the expression that
  produced it and continues evaluating inline. Its closing boundary exits the
  scope and completes teardown.
• Generated XMD is visible before it is admitted and evaluated at the point that
  produced it.
• Visually collapsing completed work does not erase scope identity, lifecycle,
  durable history, or the ability to reconstruct it.
• The first experience runs one transcript entry at a time, while work inside
  that entry—including several Agent sessions—may proceed concurrently.

Four coordinated surfaces

The REPL presents one coherent state through:

1. a persistent Sessions/Entries sidebar;
2. the central execution transcript;
3. bindings and recorded questions for the selected scope; and
4. a fixed, full-width Execution History footer that controls the whole REPL
   runtime.

An Elicit request suspends its execution and opens the complete validated
interaction in a drawer immediately above the History footer. The footer never
moves or becomes covered. Binding changes appear in the bindings surface, not
as synthetic transcript output.

The Sessions surface normally shows all Agent turns together in durable prompt
order. Selecting one conversation filters the messages with
?session=<session-key>; it does not move to a :session path. Background
starts, deltas, permission requests and completions never change that filter,
the selected scope, inspected marker or focus.

Agent turns show what the Agent received and returned. Returned XMD commonly
becomes generated source that the runtime then admits and evaluates inline. A
live delta updates its existing turn and is not transcript output or a durable
event. Several sessions may be queued, active, streaming, failed or complete at
once.

An Agent permission request remains on its owning turn until activated. Its
focus-trapped drawer presents the provider's choices and makes their Agent-
session duration explicit. It suspends only that turn; historical requests are
visible but never actionable.

Durable reconstruction and time

The append-only execution Journal is sufficient to reconstruct every retained
REPL surface: transcript, open and closed scopes, completed Agent turns,
selected-scope bindings, answered Elicit state, permission audit and history
position. Live Agent deltas and pending permission waits remain process-local
and never masquerade as retained truth.

Execution History presents selected semantic checkpoints rather than every
internal record. Entry boundaries are major checkpoints; important execution
events are minor checkpoints; long waits may be visually compressed. The
recorded timeline grows as execution advances because future duration is
unknown.

While running, the playhead follows the live expansion position. Pausing stops
XMD expansion while ordinary Effection work and durable recording may continue.
Selecting and inspecting an earlier checkpoint is a separate, read-only mode: it
reconstructs the recorded state without mutating it, resuming it, answering an
Elicit or permission request, or redirecting live execution. The person can
return to the paused expansion position and then continue from there.

A historical prefix before an agent_prompt append contains no partial Agent
turn. At and after the append it contains the terminal Prompt and its safe
permission audit. Cold reconstruction contacts no provider and never fabricates
queued, streaming or reconnecting state.

The mockup exposes Fork from here, but the durable meaning, admissible
checkpoints, side-effect treatment, and session ownership of a fork remain a
separate Product Owner decision.

Focus and constrained terminals

Keyboard focus follows a deterministic order derived from visible, enabled
targets. Background execution never steals it. A contextual drawer moves focus
to its first meaningful control, keeps the fixed History footer reachable, and
returns focus to the transcript location that requested it. Scrubbing changes
history selection, not focus. When reconstruction removes the focused target,
focus moves to a stable visible owner.

The 2560×1440 mockup is a design reference, not a minimum terminal size. Wide
composition mounts the coordinated panes. Narrow composition mounts only its
routed outlet, active contextual drawer or band, and fixed footer. Hidden panes
have no mounted branch, focus target, input path, frame demand or render output.

Failure and ownership

Live runtime work, durable Journal truth, reconstructed projections and terminal
rendering have distinct ownership. Rendering does not own execution, Agent
sessions, Elicit requests, bindings or Journal state. Historical projections can
be discarded and rebuilt without changing the live runtime.

Failure, cancellation, terminal loss and reader close retain already recorded
truth, expose partial generated XMD and terminal Agent results honestly, stop
admitting new work where required, join owned effects and resources, settle
pending permission waits, and restore the enclosing terminal before the REPL
settles. A presentation failure cannot silently leave execution running without
an observable owner.

Product verification

• A fresh run shows no transcript entries, sessions, or bindings and places
  focus in the input while keeping Execution History reachable.
• Submitting the reference Evaluate/Plan program freezes its source as Entry 1,
  opens document and component scopes, and shows nested progress inline.
• The Plan's returned XMD visibly replaces the Plan expression and then executes
  in the surrounding document scope; appending it as unrelated output fails.
• Concurrent planner, reviewer and implementer updates appear in one Sessions
  chronology without moving transcript focus or changing a chosen filter.
• Choosing a session writes session=<key> and filters only its messages;
  removing it restores all messages.
• The Plan review and generated README forms present every required field,
  conditional validation, decision and read-only preview. Unsupported schema
  breadth refuses before a partial form appears.
• A permission request waits only its owning Agent turn, opens only when
  activated, exposes every provider choice with explicit duration, and settles
  exactly once. No second terminal reader exists.
• Pausing at the live expansion position, scrubbing to representative
  checkpoints, and entering inspection reconstructs transcript, scopes,
  retained sessions, bindings and drawer state together. Inspection performs no
  live action.
• A marker before Prompt publication shows no partial text. A marker at or after
  publication and a cold reopen show the retained terminal turn and safe
  permission audit with no provider call.
• Returning to the paused position restores the exact paused projection;
  continuing advances that live execution rather than the inspected historical
  point.
• Settling an entry preserves its rendered result and Agent turns, releases its
  resources, and makes the input ready for the next entry.
• Failure, cancellation, partial generated XMD, renderer failure, terminal loss,
  permission teardown and replay divergence have signal-controlled evidence
  that distinguishes retained truth from uncommitted or live-only state.
• The same journeys remain usable under the supported constrained-terminal
  profiles. Merely shrinking the reference canvas is insufficient evidence.

Child map

The evidence stories ran first and produced disposable implementations. The
production Stories begin again from main and reimplement only accepted
contracts.

1. Render the REPL interaction study in a real terminal #838 — Render the REPL interaction study in a real terminal — completed
   experiment — retained the renderer, responsive-composition and terminal-
   lifecycle findings.
2. Navigate every REPL surface with deterministic keyboard focus #839 — Navigate every REPL surface with deterministic keyboard focus —
   completed experiment — retained canonical location, routing, focus and
   byte-driven input contracts.
3. Compose the REPL interface from reusable terminal components #840 — Compose the REPL interface from reusable terminal components —
   completed experiment — retained the private keyed component,
   reconciliation and router model.
4. Pause XMD expansion in one REPL execution without cancelling it #841 — Pause one REPL execution subtree without cancelling it — completed
   experiment — retained REPL-owned middleware that pauses XMD expansion while
   Effection and durable recording continue.
5. Rebuild any REPL view from its journal and URL #842 — Rebuild any REPL view from its journal and URL — completed
   experiment — retained Journal-and-URL reconstruction, discardable hydration,
   replay and self-contained fork findings.
6. Run and reconstruct one XMD entry in the REPL #848 — Run and reconstruct one XMD entry in the REPL — delivered by PR
   ✨ Slice E of #848: run and reconstruct one XMD entry in a REPL #853 — production kernel for one deterministic entry, Elicit, History and
   cold reconstruction.
7. Run spawned document work concurrently with <All> #855 — Run spawned document work concurrently with <All> — open next
   Story — follows Run a Plan and follow its Agent sessions in the REPL #854's accepted projection slice and adds the authored,
   durable concurrency boundary its remaining Agent-session work requires.
8. Run a Plan and follow its Agent sessions in the REPL #854 — Run a Plan and follow its Agent sessions in the REPL — active
   Story — its projection slice is accepted; its concurrent runtime and TUI
   journey continue after Run spawned document work concurrently with <All> #855 lands.

Later production Stories own Entry 2 and an entry catalog, fork semantics,
session management and any broader presentation or form capability. None beyond
#855 is a prerequisite for #854.

Relationships

• 🔥 Withdraw the unimplemented terminal-grid surface (#717) #824 and DEC-016 withdraw the unimplemented terminal-grid and tmux
  architecture. This Quest does not restore it.
• View coding-agent sessions with <Session.Tail> and xmd tail #782 remains independent read-only session-file Tail work and may share a
  projection only if the accepted architecture makes that useful.
• Root Claude and Codex native launch support remains independent of the REPL.
• Prior POCs remain historical evidence. Their disposable implementations are
  not production foundations.

Out of scope

• Restoring <Grid>, <Pane>, tmux orchestration, or a general terminal
  multiplexer.
• Synchronizing an ACP conversation into an independently open provider-native
  TUI.
• Using terminal pixels or provider session files as truth for REPL interaction.
• Choosing a public UI abstraction, package extraction or persistence library
  before a Story requires one.
• Adding the interactive REPL to Workflow.

[taras]

Experiment phase complete

All five evidence stories are complete and conclude that the REPL architecture is viable. Their disposable implementations are closed without merging:

• Render the REPL interaction study in a real terminal #838 retains @bomb.sh/tty as the renderer boundary, with explicit terminal lifecycle, resize, animation and narrow-layout revisions.
• Navigate every REPL surface with deterministic keyboard focus #839 retains one canonical URL for location and one mounted Freedom tree for focus, traversal, input ownership and branch lifetime.
• Compose the REPL interface from reusable terminal components #840 retains the small framework-independent router and keyed component/reconciliation model.
• Pause XMD expansion in one REPL execution without cancelling it #841 retains REPL-owned middleware that pauses XMD expansion while Effection and durable recording continue normally.
• Rebuild any REPL view from its journal and URL #842 retains Journal-and-URL reconstruction, a discardable StarFX cache, restart replay distinct from Continue, secret re-prompting and atomic self-contained forks.

The convergence is one ownership model: the Journal owns durable execution truth; the URL owns semantic location; live Effection scopes own continuations and expansion-pause state; the mounted component tree owns presentation lifetime, focus and input; and caches or historical projections may be discarded and rebuilt.

Draft PR #844 is the non-merging audit trail. Production begins afresh from main; no POC commit is promoted or cherry-picked. Because its dependency and test additions will not merge, the stack does not consume verify:clean or runner test-weight measurement.

The next child is a production Story, not another Quest. It will deliver the smallest vertical slice already named here: one immutable submitted entry whose deterministic document opens nested scope, publishes a binding, admits generated XMD inline, suspends once for Elicit, settles, and reconstructs selected checkpoints across all four REPL surfaces. Real Agent transport, forks and presentation breadth remain later stories.