@osolmaz/pi-workflows 0.1.0 → 0.3.0

package/docs/plans/replayable-run-bundles-implementation-plan.md

@@ -0,0 +1,65 @@
+# Replayable run bundles — implementation plan
+
+Goal: make every workflow run bundle self-contained for replay, as specified
+in [run-bundles.md](../run-bundles.md). This is a hard cutover: one format,
+no readers for the previous layout, no compatibility code.
+
+## Steps
+
+1. **Spec** — rewrite `docs/run-bundles.md`: trace-first write discipline,
+   `traceSeq` in `state.json`, content-addressed `artifacts/`, `session/`
+   with binding + verbatim Pi entries, explicit `conversation` entry ranges
+   on agent steps, event payload catalog. Review the data model with
+   Schemator. _(done)_
+2. **Types** — `ArtifactRef`/`ArtifactValue`, `ConversationRange`,
+   `WorkflowSessionBinding`, `WorkflowSessionEntryRecord`; `schema` +
+   `traceSeq` on `WorkflowRunState`; `promptText` renamed to `prompt`;
+   optional `session`/`artifacts` manifest paths. _(done)_
+3. **Artifacts** — `src/workflows/artifacts.ts`: threshold-based string
+   externalization with `$escaped` collision handling, dedupe by content
+   hash, resolve/decode helpers. _(done)_
+4. **Store** — trace append before projection writes, `traceSeq` stamping,
+   value encoding at the documented positions, session writers sharing the
+   trace sequence, 0700/0600 modes. _(done)_
+5. **Engine** — outputs/receipts/conversation in terminal node events,
+   `input` in `run_started`, `finalOutput` in terminal run events, shared
+   store option. _(done)_
+6. **Recorder** — `src/extension/recorder.ts` copies session entries into
+   the bundle via documented read APIs; executor mark/range hooks attach
+   `conversation` to accepted submissions; extension wires recording to
+   `message_end`/`agent_settled` and flushes before accepting a submission.
+   _(done)_
+7. **Fixtures** — deterministic layout + render golden files under
+   `fixtures/layout/`, generated from the TypeScript reference and pinned by
+   a parity test, consumed by the Rust port. _(done)_
+
+## Schemator review adjudication
+
+The data model was challenged field-by-field with Schemator (Codex review
+strategy). Outcomes:
+
+- **Accepted** — `WorkflowRunState.currentNodeType` removed: written but
+  never read; every consumer derives the type of `currentNode` from the
+  definition snapshot.
+- **Rejected** — `statusDetail` (live-UX label read by the widget and both
+  viewers), `paused` (orthogonal to `status`: a pause request holding at a
+  boundary while status stays `running`), `waitingOn` (well-specified:
+  checkpoint node id), `updatedAt` (cheap liveness signal for list views that
+  read only `state.json`), `durationMs` (engine-measured, not a timestamp
+  subtraction), `workflowPath` (provenance with a real re-run use case),
+  `piSessionFile` (documented provenance, explicitly never read for replay).
+- **Rejected** — renaming trace/session `at` to `occurredAt`: `at` is the
+  event-envelope convention used throughout the trace format; the `…At`
+  suffix rule applies to document fields, and the deviation is deliberate.
+- **Rejected** — `ArtifactRef.bytes` (lets viewers show sizes and verify
+  truncation without stat-ing every artifact) and
+  `WorkflowSessionBinding.boundAt` (binding.json stays self-describing
+  without consulting the trace).
+
+## Non-goals
+
+- Reading bundles written before this change.
+- Normalizing Pi session entries (they are recorded verbatim; Pi owns the
+  shape).
+- Capturing conversations for runs driven by non-conversation executors
+  (headless tests); `session/` is simply absent.

package/docs/plans/session-event-replay-implementation-plan.md

@@ -0,0 +1,494 @@
+# Session event replay implementation plan
+
+## Objective
+
+Add live assistant streaming and deterministic temporal replay to PIW using the
+journal defined in
+[session-event-journal.md](../session-event-journal.md).
+
+A completed implementation records the documented Pi event stream in each
+session-bound run bundle, shows it while the run is active, and replays the same
+history later. The workflow trace and final Pi entries keep their existing
+roles.
+
+## Boundaries
+
+- Use only documented Pi extension hooks.
+- Do not modify Pi source, Pi session state, global Pi session files, provider
+  requests, or provider response protocols.
+- Keep `trace.ndjson`, `entries.ndjson`, and `events.ndjson` as separate
+  contracts.
+- Store normalized semantic events. Never persist Pi's cumulative `partial`,
+  terminal `message`, or terminal `error` snapshots from
+  `AssistantMessageEvent`.
+- Preserve every normalized assistant event and timestamp. Filesystem and
+  WebSocket batching must not merge event records.
+- Keep capture failures separate from workflow failures.
+- Keep `src/workflows` independent of Pi and both viewer layers.
+- Preserve TypeScript and Rust reducer behavior through shared fixtures.
+- Keep boxed node dimensions fixed while temporal events change their status or
+  metadata. Live updates must never reflow the graph.
+- Replace the session-bound bundle contract in place. Do not add a legacy
+  reader, dual writer, migration, or fallback path.
+- Keep bundle permissions, artifact containment, terminal sanitization, and
+  loopback-only remote viewing unchanged.
+
+## Contract decisions
+
+The durable history is split by authority:
+
+- `trace.ndjson` records workflow transitions.
+- `session/entries.ndjson` records final Pi session entries.
+- `session/events.ndjson` records temporal session behavior.
+- `session/capture.json` reports whether temporal capture completed.
+
+The viewer orders temporal events by `seq`. The `at` timestamp controls replay
+speed and never changes event order. Final Pi entries replace provisional
+message reconstructions after explicit `entryId` linkage.
+
+Version 1 records each `tool_execution_update` occurrence and timestamp but
+omits Pi's arbitrary cumulative `partialResult`. Tool start arguments and the
+final tool result are retained. This keeps tool timing without quadratic
+storage.
+
+## Schema review
+
+Schemator accepted the session-event envelope without changes in one iteration.
+A second review simplified `capture.json` over three iterations. The final
+capture projection omits `runId` because the bundle supplies it. It also omits
+start, update, and finish timestamps that readers can derive from the journal
+and run state. Capture failures keep the durable `failedAt`, `code`, and
+`message` fields. The retained event and entry counts let readers check the
+append-only files without trusting a malformed tail.
+
+## Implementation order
+
+Work should land in the order below. Each stage has an exit criterion so a
+partially completed branch remains reviewable.
+
+### Persisted types
+
+Add the persisted contracts to `src/workflows/types.ts`:
+
+- `WorkflowSessionEventRecord`
+- the event type union and payload types
+- `WorkflowSessionCapture`
+- capture status and failure types
+
+Add schema constants and fixed paths in `src/workflows/store.ts`:
+
+```text
+session/events.ndjson
+session/capture.json
+pi-workflows.session-event.v1
+pi-workflows.session-capture.v1
+```
+
+Keep event payloads in camelCase. Validate required correlation ids when the
+store receives a normalized record. The store must not import Pi event types.
+
+Exit criterion: TypeScript tests can serialize valid persisted shapes and
+reject invalid ones without loading the extension.
+
+### Session event writer
+
+Add a dedicated event append path to `WorkflowRunStore`. It must use its own
+per-run sequence and append chain so high-rate event writes cannot queue ahead
+of workflow-state persistence.
+
+The store API should accept fully stamped ordered batches. It checks the next
+expected `seq` inside the event append chain and writes one JSON line per
+record. A batch uses one `appendFile` call while preserving separate records.
+
+Add atomic `writeSessionCapture()` support. Create the recording projection
+before the first event. At terminal capture, count complete event and entry
+lines and write `complete` or `failed` with the durable counts.
+
+After an append error, stop that run's event writer. Do not append after a torn
+line. Preserve the first failure and let workflow persistence continue.
+
+Exit criterion: store tests cover sequence assignment, concurrent batches,
+torn writes, append failure, atomic capture replacement, final counts, and no
+writes after terminal capture.
+
+### Bounded recorder queue
+
+Extend `SessionRecorder` with a memory queue in front of the store batch API.
+The recorder assigns the next `seq`, captures `at`, and fixes correlation ids
+before enqueueing each event. The `message_update` and `tool_execution_update`
+paths then schedule a flush without awaiting filesystem work.
+
+Use initial limits that are easy to test:
+
+- Flush after 25 ms, 256 records, or 256 KiB, whichever comes first.
+- Stop capture at 8,192 queued records or 16 MiB of queued JSON.
+- Reject a normalized event larger than 1 MiB.
+
+These are implementation safety limits. Measure the synthetic stress test
+before changing them. Reaching a limit marks capture as failed and stops
+temporal recording. Silent dropping is forbidden.
+
+The writer keeps each event record intact. It may write many lines together,
+but it must not combine adjacent text or thinking deltas.
+
+`SessionRecorder.finish()` must wait for an active Pi turn through `turn_end`,
+then stop accepting events, flush the queue, drain entry recording, write
+terminal capture status, and return. `SessionRecorder.stop()` handles session
+shutdown and marks an active turn as interrupted. The engine's existing
+`onRunFinishing` hook must await `finish()` before it writes the terminal
+workflow event.
+
+Exit criterion: a 10,000-event synthetic stream keeps queue use bounded,
+preserves all records below the limit, and does not block an unrelated workflow
+snapshot behind the event append chain.
+
+### Pi event normalization
+
+Add a Pi-facing module under `src/extension`, separate from the pure store
+contracts. It maps these documented hooks:
+
+| Pi hook                 | Journal event             |
+| ----------------------- | ------------------------- |
+| `turn_start`            | `turn_started`            |
+| `turn_end`              | `turn_finished`           |
+| `message_start`         | `message_started`         |
+| `message_update`        | `assistant_event`         |
+| `message_end`           | `message_finished`        |
+| `tool_execution_start`  | `tool_execution_started`  |
+| `tool_execution_update` | `tool_execution_updated`  |
+| `tool_execution_end`    | `tool_execution_finished` |
+
+The normalizer must exhaustively switch over the installed
+`AssistantMessageEvent` union. Tests must fail when a new Pi event variant is
+not handled.
+
+For assistant events:
+
+- Drop every `partial` field.
+- Drop the cumulative `message` field from `done`.
+- Drop the cumulative `error` object from `error`.
+- Retain delta strings, block indexes, block-end content, final tool-call
+  objects, and stop reasons.
+
+For tool updates, record the event with an empty payload. For tool finish,
+encode the final public-hook result with the existing artifact rules.
+
+Exit criterion: normalization tests cover every Pi event variant and assert
+that serialized records contain none of the omitted cumulative fields.
+
+### Ownership and correlation
+
+Teach the recorder which agent attempt owns the conversation before the
+executor delivers a prompt. Generate run-local turn and message ids as their
+start hooks arrive.
+
+Maintain maps for:
+
+- Active attempt to turn.
+- Turn to messages.
+- Assistant message to generated tool calls.
+- `toolCallId` to the owner captured at tool start.
+
+Each end event uses the owner saved at its matching start. It must not read the
+workflow's current node again. This prevents a late event from moving to the
+next attempt.
+
+Pi persists a message entry after `message_end` handlers return. Buffer that
+receipt and later events until the next synchronized boundary hook or workflow
+tool execution can record the branch entry. Then release the buffered records
+in original hook order. Write `message_finished` with `settled: true` and
+`entryId` only when the exact stable message identity matches a durable entry.
+Use `settled: false` for an aborted or otherwise unrecorded message. Do not
+match messages by text, timestamp, or position during replay.
+
+Exit criterion: tests advance the workflow between start and finish hooks and
+confirm that every late event retains its original `nodeId` and `attemptId`.
+
+### Extension wiring and failure policy
+
+Register the new handlers next to the existing session recorder handlers in
+`src/extension/index.ts`. Keep event handler setup and teardown scoped to the
+active workflow run.
+
+High-rate update handlers enqueue synchronously. Boundary handlers may await a
+flush when they need causal ordering or entry linkage. Capture errors are
+caught, recorded in `capture.json`, and surfaced to the viewer. They must not
+reject an agent turn, fail a tool, or change workflow status.
+
+Session shutdown and workflow cancellation must stop the writer idempotently.
+No timer, pending promise, or file handle may survive recorder shutdown.
+
+Exit criterion: hook tests cover normal completion, abort, cancellation,
+session shutdown, duplicate stop calls, write failure, and a workflow that
+completes successfully after capture fails.
+
+### Bundle readers
+
+Extend both bundle readers with `session/events.ndjson` and
+`session/capture.json`.
+
+For TypeScript, update the standalone viewer's bundle model and loader. For
+Rust, add serde types under `tui/src/bundle`, a third `NdjsonTailer`, and capture
+status loading.
+
+Readers must distinguish:
+
+- Capture currently recording.
+- Verified complete capture.
+- Explicitly failed capture.
+- Missing or invalid capture.
+- Sequence gaps or count mismatches.
+- A torn final line during recording.
+
+Missing files in a session-bound bundle are an invalid or incomplete capture.
+They are not treated as an old format with an alternate read path.
+
+Exit criterion: TypeScript and Rust reader tests produce the same integrity
+result for valid and invalid bundles, including failed capture and torn tails.
+
+### Deterministic reducer
+
+Implement a pure temporal reducer in TypeScript and Rust. Its input is the
+settled entry list plus session events through a selected sequence. Its output
+contains visible settled entries, active messages and content blocks, active or
+finished tools, and integrity diagnostics.
+
+The reducer follows these rules:
+
+- Process by `seq` only.
+- Append text and thinking deltas by `messageId` and `contentIndex`. Apply the
+  same addressing to tool-call deltas.
+- Use block-end content to check the folded block.
+- Switch to the verbatim Pi entry after a settled `message_finished`.
+- Keep unsealed messages visible as partial output.
+- Retain unknown event sequence positions while ignoring their payloads.
+- Let settled entries win when a reconciliation check fails.
+
+Create shared JSON fixtures under `fixtures/session-events/`. Generate expected
+states with the TypeScript implementation and consume the same fixtures from
+Rust. Include every event type and every documented failure mode.
+
+Use an in-memory timestamp index and reducer checkpoints for seeking. Start
+with one checkpoint every 256 events. Checkpoints are viewer cache data and
+must never be written into the run bundle.
+
+Exit criterion: all shared fixtures produce the same visible state and
+integrity diagnostics in TypeScript and Rust at every recorded replay point.
+
+### PIW live and replay views
+
+Update the conversation pane to render reducer output. Live mode shows active
+text, thinking, tool-call construction, and tool execution as events arrive.
+Once a message settles, the pane renders the verbatim Pi entry.
+
+Extend replay position with a temporal cursor while keeping workflow-step
+selection intact. The replay clock schedules events from `at`, orders them by
+`seq`, and applies the existing 1x, 2x, 5x, and 10x speed choices. Timestamp
+ties remain deterministic because sequence order wins.
+
+Follow mode stays attached to the newest temporal event. Manual scrolling or
+seeking detaches it, and the existing live controls reattach it. Capture
+failure or unverified capture must remain visible in the status area and Info
+inspector.
+
+Temporal state also fills the stable full node cards defined in
+[piw-viewer-experience-implementation-plan.md](piw-viewer-experience-implementation-plan.md).
+A node card reserves slots for its status symbol and label plus its exact id
+and type. Separate slots hold start, branch, or terminal markers and every
+branch label. Attempt metadata and timing remain visible beside the short detail
+or outcome. Every node in the graph uses one canonical outer width
+and height chosen before layout. Blank padding fills unused slots. Streaming
+and timer ticks may change card contents. Replay and terminal settlement may do
+the same without changing node bounds or edge routes.
+
+The boxed card must show all of those fields without ellipses. Long immutable
+text wraps during initial measurement, which increases the canonical size for
+every node. Narrow terminals pan over the fixed graph. Unbounded prompts and
+outputs remain in the inspector, along with error text and tool payloads.
+
+Exit criterion: a manual run visibly streams text and thinking, shows tool
+lifecycle changes, can seek into an unfinished message, and reaches the same
+final conversation as `entries.ndjson`. Its node cards keep identical bounds at
+every temporal cursor while their status and timing fields update.
+
+### Live transport
+
+Extend the run view in `docs/live-replay-protocol.md` and the Rust protocol
+types:
+
+```json
+"session": {
+  "binding": {},
+  "entries": [],
+  "events": [],
+  "capture": {}
+}
+```
+
+Tail event growth and send it through the existing `append` patch operation at
+`/session/events`. Replace capture state at `/session/capture`.
+
+Collect pending event records for up to 50 ms before producing one run patch.
+Do not merge event records. The run revision advances once per patch batch, so
+a token burst does not create one network revision per token.
+
+Snapshots contain the complete event history and current capture status.
+Reconnection, revision-gap recovery, and same-revision snapshot replacement use
+the existing resubscription path.
+
+Exit criterion: burst tests show bounded revision growth, exact event order,
+and a byte-for-byte equivalent run view after snapshot plus patches or a fresh
+resnapshot.
+
+### Documentation and format replacement
+
+When code and tests pass, fold the target contract into
+`docs/run-bundles.md` and remove the target-status note from
+`docs/session-event-journal.md`. Update `docs/live-replay-protocol.md`,
+`docs/tui-viewer.md`, `docs/development.md`, and the README where users need new
+commands or controls.
+
+Keep `pi-workflows.run-bundle.v1` and `pi-workflows.replay.v1` as directed by
+the repository's in-place replacement policy. Add the two new file schema ids.
+Do not document or retain an old session layout.
+
+Exit criterion: the documentation describes only the implemented contract and
+all examples validate against real produced bundles.
+
+## Tests
+
+### Storage and normalization
+
+- Every `AssistantMessageEvent` variant maps to the documented payload.
+- No persisted record contains `partial`, terminal `message`, terminal `error`,
+  or tool `partialResult`.
+- Stored bytes grow linearly for generated text of increasing length.
+- Batch boundaries do not change event count, sequence, ids, or timestamps.
+- Queue overflow and oversized events fail capture without failing the run.
+- A failed append leaves at most one torn final line and prevents later event
+  appends.
+- Terminal capture counts match valid lines on disk.
+
+### Correlation and lifecycle
+
+- Turn and message ids remain stable through late events, as do tool ownership
+  and workflow attempt ids.
+- A settled message links to the exact recorded Pi entry.
+- An aborted message remains unsealed and replayable.
+- Recorder shutdown drains once and rejects later enqueue attempts.
+- The terminal workflow event is physically later than terminal capture status.
+- Bundle files remain unchanged after terminal workflow state.
+
+### Reducer parity
+
+- Text and thinking blocks fold correctly at each delta.
+- Tool-call arguments fold before tool execution starts.
+- Tool updates advance timing without copying cumulative output.
+- Final entries replace provisional messages only at their explicit seal.
+- Timestamp ties and backward timestamps preserve sequence order.
+- Unknown events do not change known state.
+- Reconciliation mismatches produce diagnostics while final entries remain
+  authoritative.
+
+### Node-card stability
+
+- Every boxed node uses the same graph-wide outer width and height.
+- Node bounds and edge routes remain unchanged at every temporal cursor.
+- Symbols for every status from queued through cancelled use their documented
+  slots and text labels.
+- Start and terminal symbols remain visible beside runtime status data, as does
+  the branch count.
+- Full node ids and types render without ellipses. Every branch label remains
+  visible. Attempt counts and timing fields remain visible, as do short details.
+- Long card text expands the initial canonical dimensions and pads every shorter
+  card instead of causing later layout changes.
+
+### Local and remote viewing
+
+- Local tailing buffers a torn final event line.
+- Append patches preserve every event under a high-rate burst.
+- Revision gaps force a complete snapshot. Partial recovery is forbidden.
+- Reconnect restores event and capture subscriptions.
+- A fresh same-revision snapshot replaces stale cached events.
+- Capture failure, missing capture, and interruption have distinct labels.
+- Seeking never exposes events or entries later than the selected cursor.
+
+### End-to-end coverage
+
+Extend the mock OpenAI-compatible E2E server to emit text and thinking chunks
+plus a tool-call stream. Run a real Pi process with the extension, then assert that:
+
+- The bundle contains the expected temporal files.
+- Capture finishes as `complete`.
+- Normalized journal events match the streamed order.
+- Finalized entries match the reducer's final state.
+- The Rust viewer can replay an intermediate chunk.
+- No files outside the temporary test directory change.
+
+Add a second E2E failure case with an injected event-writer error. The workflow
+must still finish, and PIW must show failed capture.
+
+## Operational checks
+
+Before calling the feature production-ready, measure a synthetic stream with at
+least 100,000 small assistant events. Record total bytes, peak queued bytes,
+append batch count, elapsed writer time, and workflow snapshot latency while the
+stream runs.
+
+This safety check does not select between competing designs. The design passes
+when memory stays within the configured queue bound, stored size is
+linear in delta bytes, no event is lost below the bound, and workflow snapshots
+remain responsive. If the initial constants fail, change the smallest relevant
+limit or batch size and rerun the same workload.
+
+## Repository checks
+
+Run focused TypeScript and Rust tests after each stage. Before finishing the
+complete implementation, run:
+
+```bash
+npm run check
+npm run test:e2e
+npx slophammer-ts@latest dry .
+npx slophammer-ts@latest check . --only ts.dependency-boundaries-required
+```
+
+Also run the Rust checks directly while iterating on `tui/`:
+
+```bash
+cargo fmt --check --manifest-path tui/Cargo.toml
+cargo clippy --manifest-path tui/Cargo.toml --all-targets -- -D warnings
+cargo test --manifest-path tui/Cargo.toml
+```
+
+## Contract impact
+
+Session state remains unchanged. The extension reads Pi's normal session
+entries and public event payloads but does not append, edit, or remove Pi
+entries.
+
+The run bundle gains `session/events.ndjson` and `session/capture.json`. No
+other persistent store changes. Pi internals and provider protocols remain
+unchanged.
+
+The public Pi API surface is limited to `turn_start`, `turn_end`,
+`message_start`, `message_update`, `message_end`, `tool_execution_start`,
+`tool_execution_update`, and `tool_execution_end`, plus the documented
+read-only session manager getters already used by `SessionRecorder`.
+
+## Completion criteria
+
+The work is complete when:
+
+1. Every session-bound run writes the specified journal and capture status.
+2. High-rate hooks never await disk and cannot grow memory without a bound.
+3. Capture failure is explicit and never changes workflow success or failure.
+4. Local and remote PIW views show the same live temporal state.
+5. Replay can seek to any event and deterministically reconstruct that point.
+6. Final reducer state reconciles with the verbatim Pi entries.
+7. TypeScript and Rust pass the same temporal fixtures.
+8. Terminal bundles never change after the terminal workflow event.
+9. Full boxed nodes show the documented ACPX-style fields and symbols while
+   keeping identical bounds across live updates and replay.
+10. The full repository and E2E checks pass.
+11. The implemented docs contain no legacy session format or fallback path.

package/docs/plans/tui-viewer-implementation-plan.md

@@ -0,0 +1,64 @@
+# Rust TUI viewer — implementation plan
+
+Goal: `piw`, a Rust TUI in `tui/` for live viewing and replaying workflow
+runs, per [tui-viewer.md](../tui-viewer.md) and
+[live-replay-protocol.md](../live-replay-protocol.md).
+
+## Architecture
+
+One crate, library-first with a thin binary:
+
+```
+tui/
+  Cargo.toml            # package "piw"
+  src/
+    main.rs             # CLI (clap): browse / open / serve / connect
+    bundle/             # serde types, bundle reader, NDJSON tailer, runs watcher
+    source/             # RunSource: semantic run views + revisioned patches
+    protocol/           # message types, JSON Patch+ apply/diff, WS server+client
+    layout/             # port of src/render/graph.ts
+    render/             # port of canvas.ts + graph-render.ts (cell canvas, viewport)
+    ui/                 # ratatui app: panes, transport, input, camera
+  tests/                # fixture parity, protocol round-trip, tailer tests
+```
+
+`RunSource` is the seam: the TUI consumes run views + patch streams the same
+way whether they come from the local filesystem or a WebSocket.
+
+## Steps
+
+1. **Scaffold** — Cargo crate (ratatui, crossterm, tokio, tokio-tungstenite,
+   notify, serde, clap), rustfmt/clippy config, CI job alongside the npm
+   checks.
+2. **Bundle module** — serde types mirroring `docs/run-bundles.md`, bundle
+   reader (manifest-first, schema check, skip unknown), incremental NDJSON
+   tailer tolerating torn lines, runs-directory watcher with polling
+   fallback, artifact resolution with path containment.
+3. **Layout port** — `layout/` reproduces `layoutGraph` exactly; parity test
+   deserializes every `fixtures/layout/*.json` and compares ranks, edges,
+   segments, and node ranks.
+4. **Render port** — cell canvas + boxed/line graph renderer; parity test
+   compares ANSI-stripped frames against fixture `frames`.
+5. **Source + protocol** — `RunSource` builds run views, computes revisioned
+   JSON Patch+ diffs, serves them over WebSocket (`piw serve`); client mode
+   applies them. Round-trip test: filesystem view == connected view.
+6. **TUI shell** — runs sidebar, graph pane with camera (follow/overview),
+   inspector tabs, status line; live mode follows patches.
+7. **Replay transport** — seq-based scrubber, play/pause with speed, step
+   keys, detach-on-rewind, jump-to-live; per-position state reconstruction
+   from the event log.
+8. **Conversation pane** — render recorded session entries, progressive
+   reveal by replay position, attempt-slice highlighting via `conversation`
+   ranges, artifact-backed content on demand.
+9. **Polish** — mouse drag/wheel, zoom density levels, keybinding help,
+   terminal snapshot tests.
+
+## Testing
+
+- Golden parity against `fixtures/layout/` (regenerate with `npm run
+fixtures`; update both implementations together).
+- Tailer: torn lines, appends across reads, truncation detection.
+- Protocol: snapshot+patch reconstruction equals direct view; revision gap
+  forces resnapshot.
+- End-to-end: run a workflow via the engine test harness, watch the bundle
+  with the Rust source, assert the final view matches the bundle documents.