View coding-agent sessions with `<Session.Tail>` and `xmd tail`

[taras]

Story

As a person working with coding agents, I want to open an existing session and follow its conversation through XMD, so I can inspect active and historical work without hooks, plugins, or the agent's native terminal UI.

Examples

Open an existing XMD logical session:

<Session.Tail session="implementor" />

Open an exact provider-native session:

<Agent name="claude">
  <Session.Tail nativeSession="provider-native-session-id" />
</Agent>

The command-line projection opens the provider-native form without authoring a document:

xmd tail claude:provider-native-session-id

It reconstructs the complete conversation, opens at its newest entry, and follows complete new entries until the reader closes it. It never sends a prompt or changes the provider session.

Current gap

Claude Code and Codex retain native conversations in provider-owned files, but XMD has no supported way to open, normalize, and follow them. #774 established that passive read-only observation is viable while generic message delivery through an independently interactive tmux pane is not safe.

The evidence under packages/terminal-tmux/poc remains disposable. It exports no production observer or viewer.

Contract

<Session.Tail> is a blocking, read-only session view. It can run as its own document or command and may occupy a <Pane>. It is not part of the initial linear REPL interaction path.

The session and nativeSession props are mutually exclusive:

• session resolves an existing XMD logical session to its exact retained provider-native identity. It does not create, adopt, resume, or acquire the session.
• nativeSession names an exact provider-native identity under the surrounding <Agent>. It creates no XMD route, ownership record, or interaction authority.

XMD never infers either identity from a filename, current directory, newest timestamp, process, terminal contents, or neighboring route. An absent, ambiguous, mismatched, replaced, truncated, or unsupported source refuses without substituting another session.

The viewer reads provider-owned files and never writes them. It installs no hooks, plugins, MCP tools, startup scripts, or prompts that ask the agent to report itself. Terminal pixels and process-idle state are not conversation evidence.

On every invocation, Tail resolves the exact file, reads complete records through a stable frontier, normalizes them into a disposable in-memory projection, renders the complete conversation, and then follows appended complete records. A partial final record is withheld until complete. Tail retains no cursor, projection, watcher, file handle, viewport, or other state after exit; reopening reconstructs the view from the provider file.

Provider-specific discovery and record normalization are executable Markdown adapters over a small native observation substrate. The substrate owns read-only enumeration and opening, complete-record framing, partial writes, file identity, append following, truncation and replacement detection, cancellation, and cleanup. Each adapter owns provider paths, schema recognition, identity checks, classification, and conversion to the provider-neutral entries defined by #800. Provider parsing invokes no shell.

A safely framed but unknown record becomes an unknown entry rather than disappearing. A schema that cannot establish safe framing or identity refuses.

The full-screen viewer uses #800's Markdown components and Bombshell presentation. It starts at the newest entry. While positioned at the bottom it follows new entries automatically. Scrolling upward suspends visual follow but not file ingestion, reports unread entries, and End returns to the latest entry and resumes follow. The complete conversation remains available for scrolling while only the visible viewport is presented.

xmd tail is an interactive TTY command only. A non-TTY invocation refuses; the first release adds no stream, JSON, once, or alternate UI mode. The command and component share one observer and renderer.

This is live host observation under xmd run. It adds no Workflow component, durable effect, journal record, replay behavior, provider-session authority, or persistent viewer process.

Acceptance

• Claude and Codex fixtures open by exact provider-native identity, render their complete normalized history, start at the newest entry, and follow appended complete records.
• An existing XMD logical session resolves to the exact retained native identity without creating, adopting, resuming, or acquiring it.
• Supplying both target props, neither prop, or a missing logical route refuses before provider-file observation.
• Two sessions from one working directory remain distinct and never cross-deliver entries.
• A partial final record is withheld until complete, then emitted exactly once.
• Reopening reads the exact source from its beginning and reconstructs the same complete conversation without a retained Tail cursor.
• Scrolling upward suspends follow while ingestion continues, unread state advances, and End resumes at the latest entry without loss.
• File ambiguity, identity mismatch, truncation, replacement, unsupported schema, and malformed framing fail closed without selecting a nearby session.
• A safely framed unknown record remains visible as an unknown entry.
• Cancellation closes every watcher and file handle and leaves the provider-owned file byte-identical.
• Tail exposes no prompt, cancellation, permission, lifecycle, ownership, or session-creation operation.
• Repository-local Markdown components change presentation without receiving raw provider records.
• xmd tail refuses non-TTY use, and its interactive behavior matches <Session.Tail>.
• The controlled fixture journey passes through source and deno compile entrypoints.
• Sanitized fixtures contain no real conversation, credential, machine path, or account identity.
• Negative controls that attempt to write a provider file, infer identity from recency, retain a cursor across invocations, or turn a Tail target into an interactive session are refused.

Evidence

Promote only the VIEW_ONLY observation findings from #774. Deterministic tests cover exact discovery, logical-route resolution, identity, normalization, complete-record framing, concurrent sessions, reopen, truncation, replacement, unsupported shapes, viewport following, cancellation, byte-identical provider files, and compiled execution. Ordinary tests launch no coding agent and spend no model turn.

Relationships

• Test black-box REPL messaging through xmd run terminal panes #774 supplies the VIEW_ONLY feasibility evidence.
• Depends on Render Agent session entries with Markdown components #800 for normalized entries and interactive Markdown presentation; its observation substrate can be developed in parallel with Test incremental Agent session rendering with Markdown components #799 and Render Agent session entries with Markdown components #800.
• Make executable document grids use <Grid> and <Pane> #781 supplies the provider-neutral <Grid> and <Pane> surface for optional pane presentation.
• Run and reopen a linear multi-Agent XMD REPL #783 consumes the same presentation contract but receives live entries from ACP and does not depend on Tail.
• Make Claude native-to-ACP continuation preserve the exact conversation #770 governs native Claude-to-ACP continuation identity and does not authorize this read-only observer.

Out of scope

• Sending input through tmux or another native TUI.
• Treating a session file as interaction, completion, permission, or lifecycle authority.
• Modifying provider files or installing provider extensions.
• A persistent Tail process or durable Tail cursor.
• Non-interactive stream or machine-readable output.
• Tail execution as part of the first REPL experience.
• Workflow integration, the multi-session REPL, or an XMD-owned multiplexer.