@osolmaz/pi-workflows 0.1.0 → 0.3.0

package/docs/session-event-journal.md

@@ -0,0 +1,470 @@
+# Session event journal specification
+
+This document defines the target format for temporal Pi session history in a
+workflow run bundle. The journal records the order and timing of turns,
+messages, assistant output, and tool execution while a workflow runs.
+
+The format extends the authoritative bundle contract in
+[run-bundles.md](run-bundles.md).
+
+## Bundle structure
+
+A session-bound run contains these files:
+
+```text
+<run-id>/
+├── manifest.json
+├── workflow.json
+├── state.json
+├── trace.ndjson
+├── session/
+│   ├── binding.json
+│   ├── entries.ndjson
+│   ├── events.ndjson
+│   └── capture.json
+└── artifacts/
+```
+
+`events.ndjson` is an append-only journal. `capture.json` is an atomic status
+file that says whether the journal is complete.
+
+## History ownership
+
+Each persisted file answers a different question.
+
+| File                     | Question                                                   | Authority                                               |
+| ------------------------ | ---------------------------------------------------------- | ------------------------------------------------------- |
+| `trace.ndjson`           | What did the workflow engine do?                           | Workflow transitions and outputs                        |
+| `session/entries.ndjson` | What settled in the Pi conversation?                       | Final Pi session entries                                |
+| `session/events.ndjson`  | What happened over time while the conversation was active? | Timing for turns, messages, assistant output, and tools |
+| `session/capture.json`   | Is the temporal history complete?                          | Capture status and final counts                         |
+
+A reader must not rebuild final conversation content from session events after
+a matching entry has settled. The Pi entry is the final content. Session events
+preserve how that content appeared and preserve partial work that never settled.
+
+The three NDJSON journals keep independent sequence spaces. A sequence number
+from one file cannot be compared with a sequence number from another file.
+Explicit ids provide cross-file linkage.
+
+## Minimal journal
+
+A journal with one assistant text block can contain these lines:
+
+```json
+{"seq":1,"at":"2026-07-30T10:00:00.010Z","nodeId":"review","attemptId":"a1","turnId":"t1","type":"turn_started","payload":{"turnIndex":0}}
+{"seq":2,"at":"2026-07-30T10:00:00.020Z","nodeId":"review","attemptId":"a1","turnId":"t1","messageId":"m1","type":"message_started","payload":{"role":"assistant"}}
+{"seq":3,"at":"2026-07-30T10:00:00.100Z","nodeId":"review","attemptId":"a1","turnId":"t1","messageId":"m1","type":"assistant_event","payload":{"type":"text_start","contentIndex":0}}
+{"seq":4,"at":"2026-07-30T10:00:00.140Z","nodeId":"review","attemptId":"a1","turnId":"t1","messageId":"m1","type":"assistant_event","payload":{"type":"text_delta","contentIndex":0,"delta":"Looks good."}}
+{"seq":5,"at":"2026-07-30T10:00:00.150Z","nodeId":"review","attemptId":"a1","turnId":"t1","messageId":"m1","type":"assistant_event","payload":{"type":"text_end","contentIndex":0,"content":"Looks good."}}
+{"seq":6,"at":"2026-07-30T10:00:00.170Z","nodeId":"review","attemptId":"a1","turnId":"t1","messageId":"m1","type":"message_finished","payload":{"role":"assistant","settled":true,"entryId":"e1"}}
+{"seq":7,"at":"2026-07-30T10:00:00.180Z","nodeId":"review","attemptId":"a1","turnId":"t1","type":"turn_finished","payload":{"turnIndex":0,"messageId":"m1","toolCallIds":[]}}
+```
+
+The matching final Pi entry remains in `session/entries.ndjson`:
+
+```json
+{
+  "seq": 2,
+  "at": "2026-07-30T10:00:00.165Z",
+  "entry": {
+    "type": "message",
+    "id": "e1",
+    "parentId": "e0",
+    "timestamp": "2026-07-30T10:00:00.160Z",
+    "message": { "role": "assistant", "content": [{ "type": "text", "text": "Looks good." }] }
+  }
+}
+```
+
+## Event record
+
+Each line in `events.ndjson` has schema
+`pi-workflows.session-event.v1`:
+
+```ts
+type WorkflowSessionEventRecord = {
+  seq: number;
+  at: string;
+  nodeId: string;
+  attemptId: string;
+  turnId?: string;
+  messageId?: string;
+  toolCallId?: string;
+  type:
+    | "turn_started"
+    | "turn_finished"
+    | "message_started"
+    | "assistant_event"
+    | "message_finished"
+    | "tool_execution_started"
+    | "tool_execution_updated"
+    | "tool_execution_finished";
+  payload: Record<string, unknown>;
+};
+```
+
+### Fields
+
+| Field        | Required | Type             | Meaning                                       |
+| ------------ | -------- | ---------------- | --------------------------------------------- |
+| `seq`        | Yes      | positive integer | Position in `events.ndjson`, starting at 1    |
+| `at`         | Yes      | ISO 8601 string  | Time when the extension received the Pi event |
+| `nodeId`     | Yes      | string           | Workflow node that owned the event            |
+| `attemptId`  | Yes      | string           | Workflow attempt that owned the event         |
+| `turnId`     | By event | string           | Run-local turn id                             |
+| `messageId`  | By event | string           | Run-local message id                          |
+| `toolCallId` | By event | string           | Pi tool-call id                               |
+| `type`       | Yes      | string           | Normalized event type                         |
+| `payload`    | Yes      | object           | Fields specific to the event type             |
+
+`seq` must increase by exactly 1. Physical line order must match `seq` order.
+The writer must capture `at` before any asynchronous file work. Readers order
+events by `seq`. They use `at` only for playback timing.
+
+Every record has `nodeId` and `attemptId`. The recorder takes ownership from
+the active agent-step contract when the turn, message, or tool execution
+starts. That ownership remains fixed until the matching end event, even if the
+workflow moves to another node.
+
+The ids under `turnId` and `messageId` are generated by the recorder. They are
+unique within one run and have no meaning outside that run. Readers must use
+them and `toolCallId` directly. Timing is never used to infer relationships.
+
+## Event catalog
+
+The journal records normalized events from Pi's documented extension hooks.
+The payloads below are the complete version 1 contract. Unknown payload fields
+must be ignored.
+
+### `turn_started`
+
+Source hook: `turn_start`.
+
+Required ids: `turnId`.
+
+```json
+{ "turnIndex": 0 }
+```
+
+`turnIndex` is copied from Pi. The local `turnId` remains the journal identity.
+
+### `turn_finished`
+
+Source hook: `turn_end`.
+
+Required ids: `turnId`.
+
+```json
+{ "turnIndex": 0, "messageId": "m1", "toolCallIds": ["call_1"] }
+```
+
+The payload contains references instead of copying the final message and tool
+results. Final message content belongs in `entries.ndjson`, and final tool
+results belong to `tool_execution_finished` and the settled Pi entries.
+
+### `message_started`
+
+Source hook: `message_start`.
+
+Required ids: `turnId`, `messageId`.
+
+```json
+{ "role": "assistant" }
+```
+
+`role` is the Pi message role observed at start.
+
+### `assistant_event`
+
+Source hook: `message_update`.
+
+Required ids: `turnId`, `messageId`.
+
+The payload contains one normalized `AssistantMessageEvent`. The allowed shapes
+are:
+
+```ts
+type NormalizedAssistantEvent =
+  | { type: "start" }
+  | { type: "text_start"; contentIndex: number }
+  | { type: "text_delta"; contentIndex: number; delta: string }
+  | { type: "text_end"; contentIndex: number; content: string }
+  | { type: "thinking_start"; contentIndex: number }
+  | { type: "thinking_delta"; contentIndex: number; delta: string }
+  | { type: "thinking_end"; contentIndex: number; content: string }
+  | { type: "toolcall_start"; contentIndex: number }
+  | { type: "toolcall_delta"; contentIndex: number; delta: string }
+  | { type: "toolcall_end"; contentIndex: number; toolCall: unknown }
+  | { type: "done"; reason: "stop" | "length" | "toolUse" }
+  | { type: "error"; reason: "aborted" | "error" };
+```
+
+The recorder must discard Pi's cumulative `partial` field. It must also discard
+the cumulative `message` or `error` object on stream-terminal events. Persisting
+those snapshots once per chunk would make storage grow with every repeated
+prefix. Delta fields preserve the generated content without that duplication.
+
+The `content` on text and thinking end events and the final `toolCall` object
+are retained once. Readers may compare them with the folded deltas and report a
+mismatch. A mismatch does not replace the matching final Pi entry.
+
+The event writer must preserve every normalized assistant event. It may batch
+several records into one filesystem append, but it must not merge adjacent
+deltas or change their timestamps.
+
+### `message_finished`
+
+Source hook: `message_end`.
+
+Required ids: `turnId`, `messageId`.
+
+Settled message:
+
+```json
+{ "role": "assistant", "settled": true, "entryId": "e1" }
+```
+
+Message without a recorded Pi entry:
+
+```json
+{ "role": "assistant", "settled": false }
+```
+
+`entryId` is required when `settled` is true and forbidden when it is false.
+The recorder must obtain the id while it records the corresponding branch
+entry. Readers must not guess this link from message content or timestamps.
+
+### `tool_execution_started`
+
+Source hook: `tool_execution_start`.
+
+Required ids: `turnId`, `messageId`, `toolCallId`.
+
+```json
+{ "toolName": "read", "args": { "path": "README.md" } }
+```
+
+The tool-call owner is fixed at this event. Later update and finish events with
+the same `toolCallId` keep that owner.
+
+### `tool_execution_updated`
+
+Source hook: `tool_execution_update`.
+
+Required ids: `turnId`, `messageId`, `toolCallId`.
+
+```json
+{}
+```
+
+Version 1 records each update's occurrence and timestamp. Pi exposes
+`partialResult` as an arbitrary cumulative value. The recorder omits it to
+avoid repeatedly storing growing prefixes. The final result remains available
+on `tool_execution_finished` and in the Pi session entries.
+
+### `tool_execution_finished`
+
+Source hook: `tool_execution_end`.
+
+Required ids: `turnId`, `messageId`, `toolCallId`.
+
+```json
+{ "toolName": "read", "isError": false, "result": { "content": [] } }
+```
+
+`result` is the final public-hook result. Large string leaves use the bundle's
+existing artifact encoding. Readers must resolve those references through the
+same containment and size checks used for other bundle values.
+
+## Capture status
+
+`session/capture.json` uses schema `pi-workflows.session-capture.v1`. The
+recorder creates it before the first session event and replaces it atomically.
+
+```json
+{
+  "schema": "pi-workflows.session-capture.v1",
+  "eventSchema": "pi-workflows.session-event.v1",
+  "status": "complete",
+  "eventCount": 47,
+  "entryCount": 6,
+  "lastEventSeq": 47
+}
+```
+
+| Field          | Required    | Type                 | Meaning                                      |
+| -------------- | ----------- | -------------------- | -------------------------------------------- |
+| `schema`       | Yes         | string               | Must equal `pi-workflows.session-capture.v1` |
+| `eventSchema`  | Yes         | string               | Must equal `pi-workflows.session-event.v1`   |
+| `status`       | Yes         | string               | `recording`, `complete`, or `failed`         |
+| `eventCount`   | Yes         | non-negative integer | Number of complete event records on disk     |
+| `entryCount`   | Yes         | non-negative integer | Number of complete entry records on disk     |
+| `lastEventSeq` | Yes         | non-negative integer | Last durable event sequence, or 0            |
+| `failure`      | Failed only | object               | First capture failure                        |
+
+A failed status has this shape:
+
+```json
+{
+  "schema": "pi-workflows.session-capture.v1",
+  "eventSchema": "pi-workflows.session-event.v1",
+  "status": "failed",
+  "eventCount": 31,
+  "entryCount": 4,
+  "lastEventSeq": 31,
+  "failure": {
+    "failedAt": "2026-07-30T10:00:01.900Z",
+    "code": "event_write_failed",
+    "message": "could not append session event batch"
+  }
+}
+```
+
+Status meanings:
+
+- `recording` means the run may append more events or entries. Its counts are
+  lower bounds from the last atomic projection and may lag the files.
+- `complete` means all observed events were written, both session writers were
+  drained, and the counts match the durable files.
+- `failed` means the temporal history may be incomplete. Workflow execution
+  continues, and settled entries may still be usable.
+
+The first capture failure is retained. After an event append fails, the event
+writer must stop appending so a torn line remains at the file tail. The final
+status counts only complete lines. If `capture.json` is missing, invalid, still
+`recording` after a terminal workflow state, or inconsistent with the journal,
+the viewer must report unverified capture instead of treating the journal as
+empty or complete.
+
+## Write lifecycle
+
+The recorder follows this order:
+
+1. Bind the run to the Pi conversation.
+2. Create `capture.json` with status `recording`.
+3. Accept documented Pi events while an agent attempt owns the conversation.
+4. Stamp correlation ids and sequence in each hook, then record the receipt time.
+5. Queue normalized records in memory and return immediately from high-rate
+   update hooks.
+6. Append queued records in ordered batches on a dedicated writer.
+7. At `message_end`, buffer that receipt and later events until a subsequent
+   synchronized hook exposes the durable Pi entry, then attach its exact id
+   without changing event order or receipt timestamps.
+8. When the workflow requests terminal persistence during an active Pi turn,
+   keep capture routed through that turn's final tool, message, and `turn_end`
+   hooks.
+9. Stop accepting events and drain the event and entry writers.
+10. Write terminal `capture.json` atomically.
+11. Allow the engine to append its terminal workflow event.
+
+This order keeps the bundle immutable once the terminal workflow event exists.
+Waiting for the active turn is bounded at 30 seconds. If the turn does not
+finish, capture stops as failed so it cannot hold workflow persistence
+indefinitely. A capture failure must never fail the workflow.
+
+The queue must have tested byte and record limits. Reaching either limit marks
+capture as failed and stops temporal capture. Silent event dropping is
+forbidden.
+
+## Torn writes and validation
+
+Each event is one UTF-8 JSON object followed by `\n`. A reader may ignore an
+incomplete final line while capture is `recording`. Any malformed line before
+the tail is corruption.
+
+A reader validates these rules:
+
+- Required fields have the documented types.
+- `seq` starts at 1 and has no duplicates or gaps.
+- Correlation ids required by the event type are present.
+- Every finish event refers to a matching start event.
+- `message_finished.entryId` exists in `entries.ndjson` when `settled` is true.
+- `capture.json` counts match complete journal lines at terminal status.
+- No session file changes after terminal workflow state.
+
+Unknown event types and unknown payload fields are ignored. The reader still
+advances past their sequence numbers. An unsupported `eventSchema` makes the
+temporal journal unavailable. The reader must not guess another shape.
+
+## Deterministic reduction
+
+Live display and replay must use the same reducer. The reducer processes events
+in `seq` order and keeps run-local state for turns, messages, content blocks,
+and tools.
+
+Text and thinking deltas append to their content blocks. Tool-call deltas use
+the same `messageId` and `contentIndex` addressing. Tool lifecycle events update the tool identified
+by `toolCallId`. A settled message switches to the matching verbatim Pi entry at
+`message_finished`. An unsealed message remains a partial reconstruction.
+
+Replay uses `at` to schedule events at 1x or another selected speed. Ordering
+always comes from `seq`. Seeking may use in-memory checkpoints and a timestamp
+index, but those are derived viewer data and do not belong in the run bundle.
+
+The TypeScript and Rust reducers must pass the same fixtures. Fixtures cover
+normal completion, thinking, tool calls, interleaved tool updates, aborts,
+missing final entries, unknown events, timestamp ties, and capture failure.
+
+## Live transport
+
+The live replay protocol adds the journal and status to the existing run view:
+
+```json
+{
+  "session": {
+    "binding": { "schema": "pi-workflows.session-binding.v1" },
+    "entries": [],
+    "events": [],
+    "capture": { "schema": "pi-workflows.session-capture.v1" }
+  }
+}
+```
+
+The server tails `events.ndjson` like the existing trace and entry files.
+Journal growth uses an `append` patch at `/session/events`. Capture changes use
+a `replace` patch at `/session/capture`.
+
+The server batches pending append records into one patch for a short interval.
+It must preserve every event record and its sequence. This batching limits
+revision growth without changing the durable history. Reconnection always
+starts with a fresh snapshot, followed by later patches.
+
+## Privacy and trust
+
+Session events can contain prompts, generated text, thinking, tool arguments,
+tool results, file paths, and command output. Bundle permissions remain `0700`
+for directories and `0600` for files. Remote viewing remains loopback-only and
+uses the existing SSH tunnel workflow.
+
+Readers must treat all strings and nested values as untrusted. Terminal output
+is sanitized before drawing. Artifact paths must stay inside the manifest's
+artifact directory.
+
+## Versioning
+
+This change replaces the session-bound `pi-workflows.run-bundle.v1` contract in
+place. A session-bound bundle must contain both `events.ndjson` and
+`capture.json` after the implementation lands. Missing files are reported as
+an invalid or incomplete capture. There is no legacy read path.
+
+The new files use `pi-workflows.session-event.v1` and
+`pi-workflows.session-capture.v1`. Breaking either shape requires changing its
+schema identifier. New event types and optional payload fields may be added
+within version 1 because readers ignore unknown values.
+
+The network view grows within `pi-workflows.replay.v1`. Its existing unknown
+field rule makes `session.events` and `session.capture` additive protocol
+fields. No dual writer, migration, or fallback reader is part of this change.
+
+## Contract impact
+
+The extension uses only Pi's documented `turn_start`, `turn_end`,
+`message_start`, `message_update`, `message_end`, `tool_execution_start`,
+`tool_execution_update`, and `tool_execution_end` hooks.
+
+Pi session state is unchanged. Normal Pi behavior still creates its own session
+entries, and the extension only reads those entries for bundling and linkage.
+Pi internals, provider protocols, and global Pi session files are unchanged.
+The only new persistent data is `session/events.ndjson` and
+`session/capture.json` inside the private workflow run bundle.

package/docs/tui-viewer.md

@@ -0,0 +1,218 @@
+# Rust TUI viewer (piw)
+
+`tui/` contains `piw`, a Rust terminal viewer for workflow runs. It renders
+the same graph as the bundled TypeScript viewer, pinned by the golden fixtures
+under `fixtures/layout/`, and adds live following, replay, detailed inspection,
+a recorded Pi conversation, themes, and remote viewing.
+
+## Install
+
+The crates.io package uses the project name and installs the shorter `piw`
+command:
+
+```bash
+cargo install pi-workflows
+```
+
+## Modes
+
+- `piw` browses the local runs directory (`PI_WORKFLOWS_RUNS_DIR` or
+  `~/.pi/agent/workflows/runs`).
+- `piw <runId|runDir>` opens one run. A bare run id resolves inside the default
+  runs directory.
+- `piw serve [--runs-dir <dir>] [--bind 127.0.0.1:9377]` exposes the runs
+  directory over the [live replay protocol](live-replay-protocol.md). Only
+  loopback addresses are accepted; use an SSH tunnel for remote viewing.
+- `piw --connect ws://…` reads from another `piw serve` process.
+- `piw --theme <name>` selects a theme for this invocation.
+- `piw --list-themes` prints the built-in theme names.
+
+Direct filesystem mode and connected mode use the same semantic run view.
+The protocol is the network form of that view.
+
+## Layout
+
+The normal layout contains a run browser, graph, inspector, and two-line replay
+timeline. Short terminals use a compact one-line transport. Terminals below 100
+columns start with the run browser collapsed to a status rail; `b` toggles it.
+Drag the run browser's right border to resize it. Drag the inspector's top
+border to resize the bottom panel. PIW saves both sizes in its viewer config and
+clamps them when the terminal is smaller. A directly opened single run hides
+the browser.
+
+- **Run browser:** every bundle, newest first, with status, title, elapsed time,
+  and a `?` marker for a possibly interrupted run.
+- **Graph:** the complete workflow definition using the same layered layout as
+  the TypeScript renderer. Full bordered cards are the default. Every card in
+  one graph has the same width and height, fixed before layout. The exact step
+  id is centered in a header above a horizontal divider. Structured body rows
+  pair a type badge with status (`●` agent, `ƒ` compute, `⚙` action, `◆`
+  checkpoint), then attempts (`↻`) with elapsed time (`◷`). Branch labels use
+  `◇`; the final reserved row carries a short detail while unbounded content
+  stays in the inspector. The outer border and header divider share the node's
+  state color on the graph background. The body background starts inside that
+  border, while the header interior uses a separate panel surface. Type badges
+  keep their semantic colors. Updates fill reserved rows without moving nodes
+  or edges.
+  Narrow terminals pan over the fixed graph. Compact line nodes remain
+  available with `z`. Start `▶` and terminal `■` markers sit outside the card.
+  Branch labels remain on edges and loops use a right-hand gutter.
+- **Inspector:** Steps, Trace, Conversation, and Info tabs. Each tab is a
+  bracketed symbol button with a full-label mouse target; the selected tab uses
+  the accent surface. Steps can expand to full prompt, output, timestamps,
+  error, and action receipt fields. Trace can
+  show the selected attempt, the replay-visible prefix, or the full run, with
+  expandable JSON payloads. Conversation shows live text, thinking, tool-call
+  construction, and tool execution, then switches settled messages to the
+  verbatim Pi entry. Raw records remain expandable. Info shows run metadata,
+  final output, capture status, counts, and integrity diagnostics.
+- **Timeline:** run status, elapsed time, replay track, playhead, position,
+  playback controls, and speed. Every playback action uses the same bracketed
+  symbol-button style as the inspector and theme actions. The controls accept
+  full-label mouse clicks; the track supports click and drag seeking.
+
+## State presentation
+
+The graph distinguishes these states:
+
+- queued;
+- running;
+- replay focus;
+- completed;
+- failed;
+- timed out;
+- waiting; and
+- cancelled.
+
+A live running node uses a blue heavy border and `◐`. A selected historical
+step uses a mauve heavy border and `◆`, so replay never looks live. Timed-out
+nodes use `×` and a separate color. Type color is independent of state: agent
+is green, compute is blue, action is yellow, and checkpoint is mauve. The graph
+title distinguishes `(live)`,
+`(latest)`, and `(replay)` and also reports paused, reconnecting, disconnected,
+and failed or invalid capture states.
+
+## Themes
+
+Catppuccin Mocha is the default. The whole frame uses the theme: application,
+panels, graph canvas, node surfaces, selected rows, borders, states,
+conversation roles, and timeline. Boxed nodes use a surface color different
+from the graph canvas.
+
+Press `,` to open the theme picker. Moving through the list previews a theme
+immediately. Enter applies and saves it; Escape restores the exact original
+palette. Mouse selection is supported.
+
+Built-in themes are:
+
+- Catppuccin Mocha and Latte;
+- terminal palette;
+- Tokyo Night and Day;
+- Dracula;
+- Nord;
+- Gruvbox Dark and Light;
+- One Dark and Light;
+- Solarized Dark and Light;
+- Kanagawa and Lotus;
+- Rosé Pine and Dawn; and
+- Vesper.
+
+Theme configuration is loaded from `PIW_CONFIG_PATH`, then
+`$XDG_CONFIG_HOME/piw/config.toml`, then `~/.config/piw/config.toml`:
+
+```toml
+[theme]
+name = "catppuccin"
+auto_switch = false
+dark_name = "catppuccin"
+light_name = "catppuccin-latte"
+
+[theme.custom]
+# canvas_bg = "#1e1e2e"
+# node_bg = "#313244"
+# accent = "#89b4fa"
+
+[ui]
+# sidebar_width = 34
+# inspector_height = 16
+```
+
+`PIW_THEME` overrides the config file and `--theme` overrides both. Custom
+colors accept `#rrggbb`, `#rgb`, `rgb(r,g,b)`, named terminal colors, and
+`reset`. Invalid fields are reported without discarding valid fields.
+
+When `auto_switch` is enabled, `PIW_THEME_APPEARANCE=dark|light` or the host's
+`COLORFGBG` value selects `dark_name` or `light_name` at startup. A manual
+selection in the picker disables automatic switching.
+
+## Replay semantics
+
+A session-bound run uses the temporal session event journal as its replay
+track. `-1` means before capture and `None` means latest/live. Each event cursor
+folds text, thinking, tool calls, and tool execution through that event's
+sequence. PIW keeps a workflow-step selection beside the temporal cursor so
+the graph, trace, and attempt inspectors stay aligned. Runs without session
+events retain step-based replay.
+
+Playback uses event timestamps at 1x, 2x, 5x, or 10x and breaks timestamp ties
+by event sequence. Step-only runs use the 700 ms base interval. Seeking
+backward detaches from live. Active runs show a Live button that rejoins the
+latest event and enables graph follow. Finished runs omit that button; End
+jumps to their latest event. A viewer already at latest follows newly appended
+events. A detached viewer stays at its chosen position. Rewinding
+never changes graph geometry because card size and layout depend only on the
+persisted definition snapshot.
+
+Graph follow is on by default and is shown as `FOLLOW` in the graph title. It
+centers the running node, the waiting checkpoint, or the selected replay step,
+including nodes at the graph edges and graphs smaller than the viewport. `f`
+toggles follow. Keyboard or mouse panning turns it off; `f`, `0`, or returning
+to the latest position turns it back on.
+
+The conversation folds `session/events.ndjson` through the temporal cursor.
+Unsealed messages stay visible as partial output. A settled `message_finished`
+with `entryId` switches that message to the matching verbatim record from
+`session/entries.ndjson`. Capture failures, sequence gaps, count mismatches,
+and reconciliation diagnostics remain visible. Conversation auto-follow stays
+at the bottom until the user moves to an older message and returns with End.
+
+## Remote behavior
+
+The client reconnects automatically with bounded backoff. It restores the run
+listing and selected-run subscription after the server returns. Cached content
+stays visible but is labeled reconnecting or disconnected, never current.
+Revision gaps still force a fresh snapshot.
+
+Expanded remote prompt and output fields fetch artifact content on demand.
+The client caches bounded responses while the server enforces bundle path,
+symlink, and 4 MiB limits.
+
+## Interaction
+
+- Replay: `[`/`]` previous/next, Space play/pause, Home or `g` to start, End
+  to jump to latest, and `{`/`}` to change speed. Active runs also show Live;
+  `G` and `L` are its keyboard shortcuts.
+- Focus: Tab cycles Runs → Graph → Inspector. Click the full `[symbol Tab]`
+  buttons, or use `t` or `1`–`4`, to change inspector tabs.
+- Graph: arrows or `hjkl` pan, `0` resets, `f` toggles centered follow, and
+  `z`, `+`, or `-` switches boxed/compact density. Clicking a node selects its
+  latest visible attempt. Dragging inside the graph pans.
+- Browser: `b` expands or collapses it. Up/Down or `j`/`k` selects a run. Drag
+  its right border to resize it.
+- Inspector: Enter expands the selected step, trace payload, or conversation
+  entry. In Trace, `v` changes scope. Page Up/Down scrolls long content. Drag
+  its top border to resize the bottom panel.
+- Theme: `,` opens the picker; arrows or `j`/`k` preview. Click `[✓ Apply]` or
+  `[× Cancel]`; Enter and Escape remain the keyboard equivalents.
+- `q` or Ctrl-C quits.
+
+## TypeScript renderer parity
+
+The Rust and TypeScript renderers must reproduce the same plain graph and
+layout fixtures under `fixtures/layout/`. Theme backgrounds and ratatui styles
+are Rust-only and do not change plain fixture output. Any node text or geometry
+change must be made in both renderers and committed with regenerated fixtures:
+
+```bash
+npm run fixtures
+```