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.

Example

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

The command-line projection provides the same view without authoring a document:

xmd tail claude:provider-native-session-id

It renders the existing conversation and follows complete new events 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 discover, normalize, or follow them. Issue #774 established that passive read-only observation is viable while generic message delivery through an independently interactive tmux pane is not safe.

The POC is disposable evidence under packages/terminal-tmux/poc; it is not a production session viewer and exports no product capability.

Contract

<Session.Tail> is the read-only counterpart to <Session.Launch>. Both can occupy a <Pane> and expose the same normalized conversation view. Their authority differs:

• Session.Launch owns the interactive session behavior its Agent provider grants.
• Session.Tail observes an independently owned provider-native session.
• Disposing a launch settles work it owns. Disposing a tail only stops observation.
• A tailed session cannot prompt, cancel, answer permissions, acquire Agent-session ownership, or tear down the external agent.

The surrounding <Agent name> selects the provider adapter. The session prop names the exact provider-native session identity; XMD does not infer identity from a filename, current directory, newest timestamp, process, or terminal contents. An absent, ambiguous, mismatched, truncated, rotated, or unsupported source refuses or reports the observer unavailable 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.

Provider-specific session discovery and record normalization are executable Markdown adapters over a small native observation substrate. The native substrate owns filesystem enumeration, read-only opening, complete-record framing, partial writes, cursoring, replacement and truncation detection, cancellation, and following. The adapter owns provider paths, schema recognition, event classification, and normalization into immutable user, assistant, tool, status, and error events. Provider logic uses TypeScript evaluation only for pure parsing and classification; it invokes no shell.

The initial supported adapters are Claude Code and Codex. Unknown record variants remain visible as an unsupported-shape condition rather than being silently treated as a completed message.

xmd tail is a CLI projection of the same component and renderer, not a second observer implementation. It can open any exact session supported by an installed adapter, whether or not XMD created it.

This is live host observation under xmd run. It adds no Workflow component, durable effect, journal record, replay behavior, or provider-session authority. A restarted viewer resumes from its own retained cursor only when the exact file identity and complete-record frontier still agree; it never claims that the external agent itself is retained by XMD.

Acceptance

• Claude and Codex fixtures open by exact provider-native identity, render their complete normalized history, and follow appended complete records.
• Two sessions from one working directory remain distinct and never cross-deliver events.
• A partial final record is withheld until complete, then emitted exactly once.
• Restart from a cursor emits neither duplicates nor skipped complete records.
• File ambiguity, identity mismatch, truncation, replacement, unsupported schema, and malformed records fail closed without selecting a nearby session.
• Cancellation closes every watcher and file handle and leaves the provider-owned file byte-identical.
• A tailed session exposes no prompt, cancellation, permission, lifecycle, or ownership operation.
• The Claude and Codex adapters execute as Markdown documents over one provider-neutral observation substrate.
• xmd tail and <Session.Tail> produce the same normalized events and rendering.
• Sanitized fixtures contain no real conversation, credential, machine path, or account identity.
• A negative control that attempts to write a provider file or infer identity from filename recency is refused by the supported boundary.

Evidence

Promote only the read-only observer findings from #774 into production-focused component, adapter, and CLI tests. The deterministic suite covers discovery, identity, normalization, partial records, concurrent sessions, restart, truncation, rotation, unsupported shapes, cancellation, and byte-identical provider files. No ordinary test launches a real coding agent or spends a model turn.

Relationships

• Test black-box REPL messaging through xmd run terminal panes #774 supplies the VIEW_ONLY feasibility evidence.
• Make executable document grids use <Grid> and <Pane> #781 supplies the provider-neutral <Grid> and <Pane> surface used for grid presentation.
• 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.
• The retained REPL Story consumes this normalized view but owns interaction separately.

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.
• Adding live host observation to Workflow.
• Building the multi-session REPL or XMD-owned multiplexer.