@osolmaz/pi-workflows 0.14.0 → 0.15.1

package/docs/live-replay-protocol.md

@@ -1,146 +1,175 @@
 # Live replay protocol
 
-The Rust viewer (`tui/`) can watch runs in two ways: by reading SQLite runs
-directly from the filesystem (the default, in-process) or by connecting to a
-`piw serve` WebSocket server. Both paths produce the same semantic state; the
-protocol below is the network form of that state. Protocol id:
-`pi-workflows.replay.v1`.
-
-The server is a reader like any other: it only consumes SQLite runs (see
-[SQLITE_STATE.md](SQLITE_STATE.md)) and never writes them. The protocol has no
-authentication, so the server only accepts loopback bind addresses and refuses
-to start on anything else; workflow state contains private data, and remote viewing
-goes through an SSH tunnel. Handshakes that
-carry an `Origin` header are rejected: browsers always send one, and a web
-page must not be able to read workflow state by opening a WebSocket to localhost.
-
-## Transport and framing
-
-A single WebSocket endpoint (`/ws`). Every message is one JSON object with a
-`type` field. Unknown message types and unknown fields must be ignored by both
-sides. The server sends `hello` on connect; a client that does not recognize
-the protocol id must disconnect.
+The Rust viewer (`tui/`) can read SQLite directly or connect to `piw serve`. Both modes use the same bounded viewer projection. The protocol ID is `pi-workflows.replay.v1`.
+
+The server reads SQLite and never writes it. It accepts loopback addresses only. Remote use goes through an SSH tunnel. The server rejects WebSocket handshakes with an `Origin` header so a web page cannot read workflow state from localhost.
+
+## Framing
+
+The endpoint is `/ws`. Each message is one JSON object with a `type` field. Unknown message types and fields are ignored. The server sends `hello` first. A client disconnects when it does not support the protocol ID.
 
 ```json
 { "type": "hello", "protocol": "pi-workflows.replay.v1" }
 ```
 
-## Run views
+## Bounded run view
 
-The unit of synchronization is the **run view**, the semantic state of one
-run:
+A snapshot contains one bounded run view:
 
 ```json
 {
+  "presentationRevision": 42,
+  "graphRevision": 17,
   "manifest": { … },
   "workflow": { … },
-  "state": { … },
-  "events": [ … ],
+  "graphScene": {
+    "ranks": [ … ],
+    "edges": [ … ],
+    "segments": [ … ],
+    "rankOfNode": { … }
+  },
+  "graphSteps": [ … ],
+  "takenTransitions": [ "prepare->run" ],
+  "stepStart": 768,
+  "stepTotal": 1000,
+  "state": {
+    "steps": [ … ]
+  },
+  "tracePage": {
+    "presentationRevision": 42,
+    "start": 768,
+    "total": 1000,
+    "items": [ … ]
+  },
   "session": {
+    "presentationRevision": 42,
     "binding": { … },
-    "entries": [ … ],
-    "events": [ … ],
-    "eventsMalformed": false,
-    "eventsTornTail": false,
+    "entryPage": {
+      "presentationRevision": 42,
+      "start": 768,
+      "total": 1000,
+      "items": [ … ]
+    },
+    "eventPage": {
+      "presentationRevision": 42,
+      "start": 768,
+      "total": 1000,
+      "items": [ … ]
+    },
     "capture": { … }
   },
+  "settingsScopes": [ … ],
+  "followUpQueue": { … },
   "live": true,
   "possiblyInterrupted": false
 }
 ```
 
-- `manifest`, `workflow`, `state`, `events`, and every `session` field are
-  semantic projections from SQLite. `workflow` is the definition snapshot,
-  top-level `events` are workflow events, `session.entries` are settled Pi
-  entries, `session.events` are normalized temporal events, and
-  `session.capture` is capture integrity. `session` is `null` until a binding
-  exists.
-- `live` is true while the run status is non-terminal. `possiblyInterrupted`
-  is a reader-side diagnostic based on current ownership and update time.
-- Values are resolved from content-addressed SQLite blobs.
+Each step, trace, session-entry, and session-event page contains at most 256 rows. `graphSteps` contains at most one latest attempt per node at the replay cursor. `takenTransitions` contains distinct transitions up to that cursor. `graphScene` is the retained language-neutral rank and route plan shared by Rust and TypeScript.
+
+A snapshot does not contain complete trace or session history. A replay jump fetches the page that contains the requested zero-based cursor.
+
+## Revisions and target patches
+
+Each viewer-visible SQLite transaction advances the run presentation revision and commits ordered target patches with the same transaction. The server reads those patches. It does not build complete old and new run views to compare them.
+
+```json
+{
+  "type": "run_patch",
+  "runId": "run-1",
+  "revision": 43,
+  "targets": [
+    {
+      "targetType": "conversation",
+      "targetKey": "entries:tail",
+      "patch": [
+        { "op": "replace", "path": "/presentationRevision", "value": 43 },
+        { "op": "remove", "path": "/items/0" },
+        { "op": "append", "path": "/items", "value": [ { "seq": 1001, … } ] },
+        { "op": "replace", "path": "/start", "value": 745 },
+        { "op": "replace", "path": "/total", "value": 1001 }
+      ]
+    }
+  ]
+}
+```
+
+The patch set supports `add`, `replace`, `remove`, and `append`. `append` adds each value to the target array in order. Sliding tail pages keep 256 rows by removing old leading rows when necessary. Session-event pages stay aligned to 256-event checkpoint boundaries. They append inside one block and request the next page when a write crosses a boundary.
+
+A patch targets one bounded document or page. A client applies a tail patch only when it holds that tail page. Older loaded pages stay valid because committed history is immutable. A target that needs a fresh bounded projection causes a snapshot. This still avoids complete-run reads and complete-run JSON comparison.
+
+Revisions must arrive in order. Duplicate state is harmless because a client ignores an old revision. A wrong run, malformed patch, missing path, stale page, future revision, or gap cannot replace the last good view. A gap or a cursor older than retained patches causes a bounded snapshot.
+
+The database retains 256 presentation revisions per run. The server does not replay an unbounded patch backlog.
 
-Because the full trace and session history are part of the view, replay
-scrubbing is a pure client-side operation; rewinding never requires the
-server. Clients order session events by `seq` and use `at` only for playback
-timing.
+## Pages
 
-## Snapshot, then patches
+A client asks for a page with `fetch_page`:
+
+```json
+{
+  "type": "fetch_page",
+  "runId": "run-1",
+  "kind": "session_events",
+  "cursor": 20000
+}
+```
 
-State synchronization follows a snapshot-then-patch model. After a client
-subscribes to a run, the server sends one `run_snapshot`, then a stream of
-`run_patch` messages:
+`kind` is one of `steps`, `trace`, `trace_at_step`, `session_entries`, `session_events`, `settings`, `follow_ups`, or `updates`. `trace_at_step` uses a step index as its cursor and returns the trace page around that step's timestamp. The server answers with `run_page`:
 
 ```json
-{ "type": "run_snapshot", "runId": "…", "revision": 3, "view": { … } }
-{ "type": "run_patch", "runId": "…", "revision": 4, "patch": [
-  { "op": "append", "path": "/events", "value": [ { "seq": 18, … } ] },
-  { "op": "replace", "path": "/state", "value": { … } }
-] }
+{
+  "type": "run_page",
+  "runId": "run-1",
+  "revision": 43,
+  "kind": "session_events",
+  "cursor": 20000,
+  "start": 19872,
+  "total": 48620,
+  "items": [ … ]
+}
 ```
 
-- `revision` increases by exactly 1 per patch. A client that observes a gap
-  must resubscribe and take a fresh snapshot.
-- `patch` is JSON Patch (RFC 6902) plus one extension op: `append`, whose
-  `value` is an array of items appended to the array at `path`. Semantically
-  `append` equals a sequence of `add` ops at `/-`; it exists so that the
-  common case (trace and session growth) stays compact and readable.
-- Session growth uses `append` at `/session/entries` and `/session/events`.
-  Capture changes use `replace` at `/session/capture`. Changes to the derived
-  tail diagnostics use `replace` at `/session/eventsMalformed` and
-  `/session/eventsTornTail`.
-- The server waits 50 ms after a filesystem notification before refreshing,
-  so one token burst normally becomes one revision. Batch boundaries never
-  merge or alter event records.
-- Patches are computed against the previous view revision; applying them in
-  order reproduces the server's view exactly.
+Page reads use bounded ranges. The response echoes the requested `cursor` and carries the presentation revision read in the same SQLite snapshot as its rows. A client ignores an older response when a newer cursor is pending. A step page also returns `graphCursor`, `graphSteps`, and `takenTransitions` for that exact replay point, even when the selected step was already in the prior page. A historical session-event page can return `replayCheckpoint`. The checkpoint contains only active message and tool state at the page boundary. The writer stores it at each 256-event boundary, so a page jump reads one checkpoint blob instead of predecessor event rows. It lets the client continue the temporal reducer without loading predecessor event pages. The client also requests the related entry page. Settings, follow-up, and current-update pages keep the Info inspector complete without loading every record. A page request does not change the shared watched-run projection or another client's cursor.
 
 ## Messages
 
 Client to server:
 
-| type             | fields          | meaning                      |
-| ---------------- | --------------- | ---------------------------- |
-| `watch_runs`     | —               | subscribe to the run listing |
-| `watch_run`      | `runId`         | subscribe to one run's view  |
-| `unwatch_run`    | `runId`         | end a run subscription       |
-| `fetch_artifact` | `runId`, `path` | unsupported; returns `error` |
+| Type             | Fields                                                                                                | Meaning                                        |
+| ---------------- | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
+| `watch_runs`     | none                                                                                                  | Subscribe to run-list rows.                    |
+| `watch_run`      | `runId`, optional `revision`, `stepCursor`, `traceCursor`, `sessionEntryCursor`, `sessionEventCursor` | Subscribe or resume one run.                   |
+| `unwatch_run`    | `runId`                                                                                               | End one run subscription.                      |
+| `fetch_page`     | `runId`, `kind`, `cursor`                                                                             | Read one bounded page.                         |
+| `fetch_artifact` | `runId`, `path`                                                                                       | Unsupported for SQLite state; returns `error`. |
 
 Server to client:
 
-| type           | fields                       | meaning                                         |
-| -------------- | ---------------------------- | ----------------------------------------------- |
-| `hello`        | `protocol`                   | sent once on connect                            |
-| `runs`         | `runs`                       | full run listing (summaries), re-sent on change |
-| `run_snapshot` | `runId`, `revision`, `view`  | full view after subscribe                       |
-| `run_patch`    | `runId`, `revision`, `patch` | incremental view update                         |
-| `artifact`     | `runId`, `path`, `content`   | reserved; not sent by SQLite-backed servers     |
-| `error`        | `message`, `runId?`          | request failed                                  |
+| Type           | Fields                                                 | Meaning                                  |
+| -------------- | ------------------------------------------------------ | ---------------------------------------- |
+| `hello`        | `protocol`                                             | Identify the protocol.                   |
+| `runs`         | `runs`                                                 | Send all lightweight run-list rows.      |
+| `run_snapshot` | `runId`, `revision`, `view`                            | Send one bounded run view.               |
+| `run_patch`    | `runId`, `revision`, `targets`                         | Apply direct bounded target patches.     |
+| `run_page`     | `runId`, `revision`, `kind`, `start`, `total`, `items` | Return one bounded page.                 |
+| `artifact`     | `runId`, `path`, `content`                             | Reserved and not sent by SQLite servers. |
+| `error`        | `message`, optional `runId`                            | Report a sanitized request failure.      |
 
-SQLite-backed views contain resolved values. A `fetch_artifact` request returns
-an `error` because there is no artifact directory.
+The run list contains `presentationRevision`, `manifest`, `live`, and `possiblyInterrupted`. It contains no payload bodies.
 
-Run listing summaries are the manifest plus `live` and
-`possiblyInterrupted`:
+## Several clients
 
-```json
-{ "type": "runs", "runs": [ { "manifest": { … }, "live": true, "possiblyInterrupted": false } ] }
-```
+The server keeps one projection and graph scene for each watched run. The first watcher loads it. Later watchers reuse it. The last unwatch or disconnect releases it. Different watched runs load independently.
 
-The run listing is small and changes rarely, so it is always sent whole; only
-run views use patches.
+Each client keeps its own revision and page cursors. Network sends happen outside the shared state lock. A slow client cannot stop another client. If a broadcast receiver falls behind, that client receives a bounded snapshot.
 
 ## Reconnection
 
-The native client treats the run listing and selected run as desired state rather
-than one-shot commands. After a connection closes,
-it keeps the cached run visible with a stale/reconnecting label, retries with
-bounded backoff, sends `watch_runs` after the next valid `hello`, and restores
-the current `watch_run`. A reconnect receives a fresh snapshot before later
-patches.
+The client keeps the run list and selected run as desired state. After a disconnect, it keeps cached content visible with a stale or reconnecting label. It retries with bounded backoff, sends `watch_runs` after the next valid `hello`, and resumes `watch_run` from its revision and page cursors. A retained cursor receives patches. A stale cursor receives a bounded snapshot and requested pages.
+
+## SQLite consistency
 
-## SQLite semantics behind the protocol
+The server uses a query-only SQLite connection. A writer commits the domain change, presentation revision, and patch records atomically. A reader sees all of that transaction or none of it.
 
-The server polls `state.sqlite` through a query-only connection. Each refresh
-reads a committed run projection, immutable events, session rows, and blob
-values. A transaction is either fully visible or not visible, so a client never
-observes half of a state transition.
+The refresh timer first checks `PRAGMA data_version`. An unchanged value causes no run-index query and no payload read. A changed value refreshes lightweight rows and only the watched projections whose presentation revisions changed.

package/docs/plans/2026-08-27-workflow-terminal-restart-plan.md

@@ -281,6 +281,45 @@ Document:
 
 No workflow definition needs an opt-in or terminal restart step.
 
+### 9. Render deferred terminal turns as compact cards
+
+**Where**
+
+- `src/extension/deferred-turn.ts`
+- `src/extension/index.ts`
+- Deferred-turn renderer unit tests
+- Real-Pi end-to-end tests
+
+**Change**
+
+Register a custom TUI message renderer for the existing `pi-workflows-deferred-turn` message type through Pi's documented `pi.registerMessageRenderer()` API.
+
+Keep the complete existing message content unchanged. The model and session history must still receive the terminal facts, exact input, bounded result, restart history, and instructions. Do not replace that content with a summary, split it into another entry, or hide the deferred fallback with `display: false`.
+
+Add small, bounded presentation fields to the existing message details. The fields cover the workflow name, terminal state or cause, run identity, terminal reason kind, and restart count and limit when available. The renderer must read those fields directly and must not parse the model prompt.
+
+The collapsed card must show a concise workflow summary. It must not show the terminal facts JSON, exact input, result, fingerprint, or full model instructions. The expanded card must show the complete existing content through Pi's standard `expanded` state, consistent with agent-step message cards.
+
+Use standard Pi TUI components and theme colors. Sanitize all workflow-derived display text. Missing or malformed details must produce a safe generic card instead of an exception.
+
+Keep the behavior workflow-agnostic. Ordinary deferred fallbacks, terminal decisions, and restored messages use the same renderer. Presentation messages that already use `display: false` stay unchanged. Headless and RPC behavior stays unchanged. Rendering must not create a duplicate session entry or model turn.
+
+This change uses only `pi.sendMessage()` and `pi.registerMessageRenderer()`. It adds no Pi core or private API use, database table, migration, store, service, controller, daemon, or external resource.
+
+**Verification**
+
+Focused tests must prove that:
+
+- collapsed output shows bounded workflow, state or cause, run, and restart fields
+- collapsed output omits the full prompt, terminal JSON, input, result, and fingerprint
+- expanded output contains the complete model-facing content
+- completed, failed, timed-out, cancelled, launch-failure, and maxSteps states render correctly
+- long or terminal-unsafe fields are safe
+- missing and malformed details do not throw
+- the renderer registers once for `pi-workflows-deferred-turn`
+- restored messages render without creating another entry or turn
+- real Pi still gives the provider the complete prompt while the session record keeps the custom message type and renderer details
+
 ## Contract changes
 
 - The workflow tool gains `restart`.
@@ -293,6 +332,9 @@ No workflow definition needs an opt-in or terminal restart step.
 - Restart lineage uses existing run launch data.
 - No new store, service, controller, or Pi API is added.
 - No original-message provenance contract is added.
+- The existing deferred-turn message details gain small, bounded presentation fields.
+- The existing deferred-turn message content remains complete and unchanged for the model and session history.
+- Interactive Pi renders deferred turns through the public message-renderer API. Headless and RPC delivery do not change.
 
 ## Test plan
 

package/docs/plans/2026-08-28-piw-incremental-viewer-plan.md

@@ -0,0 +1,293 @@
+---
+title: Build the incremental and virtualized piw viewer
+author: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
+date: 2026-08-28
+status: implemented
+---
+
+# Incremental and virtualized piw viewer plan
+
+## Goal
+
+Make `piw` stay fast as workflow history grows.
+
+Pi Workflows will expose one canonical viewer projection for local and remote clients. Every viewer-visible change will advance one run presentation revision and produce a bounded, resumable JSON Patch delta directly from the committed change. Viewers will load small run-list rows, the graph state they need, and bounded pages around the current replay position.
+
+The graph will use bounded adaptive cards. Each card will use space based on its own content. One long name or large switch will not enlarge unrelated cards.
+
+This plan replaces the tactical indexed-worker design. That design would stop loading every run, but it would still poll and rebuild the complete selected run. The selected design removes that remaining scaling limit.
+
+## Current problems
+
+The current local viewer checks SQLite every 300 ms. Its run-list path loads every run in full, and its refresh path then loads every run again. It also reloads terminal runs. The UI performs this work on the same path that handles input and drawing.
+
+A measured database contained 44 runs, 17,812 workflow events, 9,268 session entries, and 48,634 session events. The database was 97 MB. An eight-second all-runs check reached 370 MB peak RSS and used 1.29 CPU seconds. A single-run check reached 37 MB and used 0.04 CPU seconds.
+
+Boxed graph mode also calculates one width and height for the whole graph. A 58-character hierarchical name and a 14-way switch made every card about 62 columns wide and 21 rows high. Most cards contained large empty areas.
+
+## Boundaries
+
+This design keeps SQLite as the canonical durable store. It keeps `piw` as a standalone Rust TUI and keeps the TypeScript graph renderer.
+
+The implementation must not change workflow execution, saved Pi session content, full workflow history, theme behavior, keyboard or mouse meaning, replay meaning, or Pi extension boundaries.
+
+The WebSocket server remains loopback-only. Remote use continues through an SSH tunnel. The design adds no external service, sidecar, cache database, or telemetry system.
+
+The existing JSON Patch operations and `append` extension remain the change format. The implementation changes how patches are created and what they target. It must not rebuild two complete run views to find their differences.
+
+Pi Workflows is in alpha. If the implementation needs a persisted contract change, it will replace the current `v1` contract in place. It will not add a migration shim, compatibility reader, dual read, dual write, feature flag, or `v2` contract. An incompatible database will fail with a clear reset instruction and remain untouched.
+
+The repository source now implements this design. Release work, installation, and adoption of a new `piw` binary remain separate.
+
+## Canonical viewer projection
+
+One projection will serve local and remote viewers. It will have the following read surfaces:
+
+- lightweight rows for the run list;
+- graph state and replay metadata for one run;
+- bounded timeline pages;
+- bounded conversation pages;
+- bounded inspector pages; and
+- ordered JSON Patch deltas after a known run presentation revision.
+
+Run-list rows contain only the fields needed by the browser, such as identity, title, status, timestamps, and interruption state. Building the list must not read run outputs, trace payloads, session entry bodies, or session event bodies.
+
+The local viewer and `piw serve` must use the same projection rules. They may use different transports, but they must agree on revisions, cursors, pages, gaps, and failure recovery.
+
+## Presentation revision
+
+Each run has one authoritative presentation revision. The revision covers every fact that can change the viewer:
+
+- run status and current position;
+- node attempts and completed steps;
+- workflow trace records;
+- session segments, entries, and temporal events;
+- live settings;
+- follow-up queues and items;
+- human decisions;
+- leases and interruption state; and
+- any other field exposed by the canonical viewer projection.
+
+A transaction that changes one of these facts also advances the presentation revision. It creates the corresponding JSON Patch operations from the records changed by that transaction. The database commit makes the domain change, revision, and patch visible together. Patch creation must not read the previous complete run view or compare two complete run documents. A viewer must never observe a revision that does not describe the committed state.
+
+The implementation must audit every durable writer that can change viewer output. A missing writer is a correctness bug because it can leave a viewer stale.
+
+## JSON Patch deltas and cursors
+
+A delta is an ordered list of the existing JSON Patch operations after one presentation revision. The current `add`, `replace`, `remove`, and `append` operations remain available. A client identifies the run and last revision it has applied.
+
+Each patch targets one bounded projection document or one bounded page. It does not target one JSON document containing the complete run history. The envelope identifies the target document, run revision, and page revision or cursor needed to apply it safely.
+
+The active timeline or conversation page can use `append` as new records arrive. An unloaded or evicted page is not rebuilt only to apply a patch. Its revision changes, and the client fetches the current page if it needs that range. Stable IDs and page boundaries prevent paths from depending on array positions outside the loaded page.
+
+The server returns the next available patches when the cursor is valid. If the cursor is missing, invalid, or older than the retained patch window, the server returns a fresh bounded snapshot and the pages needed for the current view.
+
+Applying patches in order must produce the same logical view as reading a fresh projection at the final revision. Duplicate patches must be harmless. A client rejects an out-of-order revision, malformed page, invalid path, or mismatched run ID without changing its current good view.
+
+The canonical database retains bounded patch records or enough authoritative revisioned records to return the same patches without reconstructing full history. The implementation must prove bounded resume behavior and must not depend on an unbounded in-memory backlog.
+
+## Paging and replay
+
+Timeline, conversation, and inspector data use bounded pages. A page identifies its run, presentation revision, content range, and neighboring cursors.
+
+The viewer loads the page that contains the current step, event, or time. It may prefetch a small number of neighboring pages. It evicts pages outside a documented memory window.
+
+A jump to another time loads a page around that point. It does not load the complete timeline or conversation. The viewer may show a short loading state while the page arrives. The amount of data loaded for one jump stays bounded.
+
+Replay order and timing keep their current meaning. The temporal session event sequence remains authoritative. Paging changes how the viewer obtains records, not how it interprets them.
+
+Search and count displays must state whether they cover the complete run or only loaded pages. A complete search must use a bounded database query or a paged server operation. It must not silently search only the cache.
+
+## Multiple clients
+
+`piw serve` keeps one shared projection and cache for each watched run.
+
+The first watcher starts that run's projection. Later watchers reuse it. Each client keeps its own revision cursor, selected replay position, and loaded pages. A database change is projected once and fanned out to every client that watches the run.
+
+The server tracks a watcher count for each run. An unwatch request or client disconnect reduces the count. When the count reaches zero, the server releases the run projection and its pages. Different watched runs load independently. Unwatched runs do not load.
+
+A slow client does not block projection work or delivery to other clients. If it falls behind the retained delta window, it receives a fresh bounded snapshot and the pages for its current position. The server does not keep an unbounded queue for that client.
+
+Duplicate clients watching one run must not duplicate database reconstruction, graph layout, or delta generation.
+
+## Client state and failures
+
+The TUI applies database and network results away from the input and drawing path. Input, mouse handling, and frame drawing must not wait for a complete run read, page query, or graph layout.
+
+The run list stays usable when one run fails to load. An initial failure shows a sanitized error for that run. A refresh failure keeps the last good view and marks it stale.
+
+A revision gap causes a fresh bounded snapshot. A malformed page, invalid cursor, or wrong revision is rejected. The viewer keeps its last good state and requests recovery. Reconnect keeps the current stale label until a valid snapshot or delta stream resumes.
+
+Shutdown cancels pending reads and joins local worker tasks. A disconnected client releases server watcher counts and page references.
+
+## Semantic graph scene
+
+Rust and TypeScript will consume one language-neutral semantic scene contract. The contract contains logical nodes and edges, display text, status, branch meaning, card bounds, edge ports, and stable scene identities.
+
+A card calculates its width and height from its own content and then applies documented minimum and maximum bounds. Long text uses one deterministic overflow rule. The local node name remains visible. Full names, details, and branch cases remain available in the inspector.
+
+Branch meaning stays on edges and in the selected-node inspector. A switch with many cases can summarize its card content, but it must keep every logical branch and full case label in the scene.
+
+One node's label, detail, or branch count cannot change the size of another node. The current graph-wide maximum is removed.
+
+Rust and TypeScript use the same size limits, text-width rules, branch order, overflow markers, ports, and fixture output. Unicode width behavior must be pinned by conformance fixtures.
+
+## Retained layout and virtualization
+
+The viewer keeps a retained logical graph scene between updates. A change updates the affected node or edge and recomputes only the ranks and routes that depend on it.
+
+The renderer materializes viewport-near cards and edges. Off-screen graph items remain in the logical scene, so keyboard navigation, centering, search, and replay can still reach them.
+
+Hit testing uses exact visible bounds. Edge routing uses exact node ports. Panning, following, clipping, and mouse selection use the same scene geometry.
+
+The implementation must define the viewport margin and scene eviction rules. These bounds must be large enough to avoid visible popping during normal movement and small enough to keep memory independent of total graph size.
+
+## Performance contract
+
+The implementation must meet these structural rules:
+
+- idle work does not grow with stored trace or session payload;
+- an unchanged run causes no payload read;
+- building the run list reads no payload bodies;
+- client memory is bounded by run-list rows, watched-run metadata, configured page windows, and viewport-near scene data;
+- two clients watching one run share projection and layout work;
+- a replay jump loads a bounded page; and
+- input handling never waits for full-history reconstruction; and
+- patch creation never reads or compares complete old and new run views.
+
+Benchmarks must report raw query counts, rows and bytes read, delta sizes, page loads, layout work, input-stall latency, CPU time, and peak RSS. They must use generated fixtures with increasing run count, trace size, session size, graph size, and client count.
+
+Timing measurements must use repeated runs and report the median, range, and a high percentile. Query, load, and memory bounds are deterministic gates. Timing is supporting evidence and must include uncertainty.
+
+The measured comparison points are 370 MB peak RSS for the all-runs view and cards of about 62 columns by 21 rows for the large Autoimplement graph. The new design must show that memory and card size no longer grow from unrelated history or unrelated nodes.
+
+## Implementation sequence
+
+### State revision
+
+Update the durable state writer so every viewer-visible transaction advances the run presentation revision and creates its bounded JSON Patch operations directly. Add the authoritative revision and required bounded patch records to the current SQLite schema in place.
+
+Audit run transitions, attempts, steps, trace, session capture, settings, follow-ups, decisions, leases, and interruption changes. Add one mutation test for each writer.
+
+Exit when a fresh projection and directly created JSON Patch operations agree at every revision without a full-view diff.
+
+### Projection reads
+
+Add canonical read operations for run-list rows, graph state, replay metadata, timeline pages, conversation pages, inspector pages, bounded snapshots, and JSON Patch deltas.
+
+Keep payload bodies out of run-list queries. Make page queries use indexed range bounds. Add query-plan tests and row-read counters.
+
+Exit when increasing payload size does not change idle or run-list work.
+
+### Local viewer
+
+Replace full-run polling with revision checks, page requests, and bounded caches. Apply reads outside the input path. Add loading, stale, error, and recovery states.
+
+Keep replay semantics, themes, input, and inspection behavior. Make arbitrary time jumps request the containing page.
+
+Exit when a delayed database read does not delay synthetic keyboard or mouse input.
+
+### Replay protocol
+
+Keep the current JSON Patch protocol and `append` operation. Change the alpha protocol in place so each patch identifies its bounded projection document or page and carries the required presentation revision, page cursor, and recovery data. Keep the current loopback and browser-origin restrictions.
+
+Update the server to share one directly created patch stream per watched run. Update the client to keep independent cursors and page caches. Remove complete run-view transfer, full-view diffing, and unbounded patch history.
+
+Exit when local and connected viewers produce the same logical view at each revision.
+
+### Graph scene
+
+Define the semantic scene and bounded adaptive card rules. Port the same contract to Rust and TypeScript. Replace graph-wide card sizing with node-owned bounds.
+
+Add retained rank and route updates, viewport materialization, exact hit testing, and full inspector detail. Regenerate shared fixtures.
+
+Exit when long names and large switches do not resize unrelated cards and large graphs keep bounded materialized geometry.
+
+### Multi-client recovery
+
+Add shared watched-run caches, watcher counts, independent client cursors, slow-client recovery, disconnect cleanup, and bounded delivery queues.
+
+Exit when many clients can watch one run without duplicate reconstruction and one stalled client cannot delay the others.
+
+### Benchmarks and checks
+
+Add generated scale fixtures for small and large histories, graphs, replay jumps, and client counts. Record raw structural and timing results. Compare them with the current measurements.
+
+Run the full Rust, TypeScript, parity, protocol, end-to-end, and repository checks.
+
+## Tests
+
+Test presentation revision changes for every viewer-visible writer and remains unchanged for unrelated writes.
+
+Test bounded snapshots plus ordered JSON Patch operations against a fresh projection at every revision. Prove that patch creation does not read a complete old or new run view. Cover `add`, `replace`, `remove`, `append`, duplicate, missing, stale, malformed, invalid-path, wrong-page, and wrong-run cases.
+
+Test first-page, next-page, previous-page, arbitrary-time, end-of-run, active-tail, and evicted-page behavior for timeline, conversation, and inspector data.
+
+Test run-list queries with large payload bodies and prove that no payload rows or blobs are read.
+
+Test local and remote parity for current, replayed, reconnecting, stale, and recovered views.
+
+Test several clients watching the same run, different runs, unwatching, disconnecting, falling behind, and reconnecting. Prove that one run is projected once and released after its last watcher leaves.
+
+Test long labels, long local names, Unicode, large fan-out, loops, back edges, mixed card sizes, clipping, panning, following, centering, keyboard navigation, and mouse hit testing.
+
+Test viewport materialization and retained layout with graphs much larger than the terminal. Prove that logical navigation still reaches off-screen nodes.
+
+Test failure handling for database read errors, protocol gaps, invalid cursors, malformed pages, interrupted streams, and shutdown during a read.
+
+Test performance with growing history and client counts. Assert deterministic query, load, page, cache, and materialized-node bounds. Report timing and memory separately.
+
+## Verification
+
+Run:
+
+```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
+npm run fixtures
+npm run check
+npm run test:e2e
+npx slophammer-ts@latest dry .
+npx slophammer-ts@latest check . --only ts.dependency-boundaries-required
+npx -y @simpledoc/simpledoc check
+git diff --check
+```
+
+Use a source-built `piw` in a PTY to verify run selection, replay jumps, box and line modes, panning, mouse selection, reconnect, several clients, and clean exit. Use only generated state for destructive or failure tests.
+
+A read-only check against a real growing database may report aggregate counts, timings, query counts, and memory. It must not print workflow titles, prompts, outputs, session text, actor identifiers, channel references, or credentials. It must not write the database.
+
+## Implementation record
+
+The current alpha schema now stores `viewer_runs` and `viewer_deltas`. A run starts at presentation revision 1. Each viewer-visible write advances that revision in the same SQLite transaction and stores ordered target patches. The store retains 256 revisions. An older or invalid cursor requires a bounded snapshot.
+
+Timeline, step, session-entry, session-event, settings, follow-up, and current-update pages contain at most 256 rows. Session rows have run-wide sequence numbers and indexed `(run_id, run_seq)` reads. Step pages keep full detail for the active replay window and return compact graph state for that exact cursor. A separate graph projection keeps only the latest attempt per node and the distinct taken transitions up to the replay cursor. Run-list reads use metadata and do not open payload blobs.
+
+The local viewer checks `PRAGMA data_version`. An unchanged check does not scan the run list or load payloads. Local page reads use one overwrite-only worker request, so a newer selection replaces pending work. The source keeps the last good view after a read failure and marks it stale. Direct tail patches update a loaded page without another run read.
+
+`piw serve` keeps one bounded projection and one retained graph scene for each watched run. Watchers share that state. Each client keeps its own revision and page cursors. Page requests do not change another client's window. A client that misses retained deltas receives a bounded snapshot and the pages it requests.
+
+Boxed cards use a content width from 20 through 28 cells, which gives an outer width from 24 through 32 cells. A card has a 7-row core and at most 3 branch rows. A larger switch shows the first two branch names and a `+N branches` row. Each rank uses its own tallest card. Exact node bounds control ports, centering, and mouse hits. The viewer retains the graph layout between state changes and materializes only the visible rows and columns for Ratatui. Rust checks every TypeScript fixture byte for byte, including long labels, large fan-out, and Unicode labels.
+
+The generated scale fixture is 98,242,560 bytes and contains 44 runs, 17,820 run events, 9,284 session entries, and 48,620 session events. Five release-mode runs of 1,000 idle checks each loaded one selected window with 723 payload rows. They performed one run-index read, no later payload loads, and used 9,388 KiB peak RSS, or 9.61 MB. Total time was 1,291 through 2,331 microseconds per 1,000 checks. Median checks took 1 through 2 microseconds, p99 checks took 1 through 2 microseconds, and the maximum was 9 through 27 microseconds. Compared with the measured 370 MB baseline, peak memory fell by about 360.39 MB, or 97.4%. This is much larger than the registered 50% memory reduction gate. A separate run of 1,000,000 unchanged checks used 0.63 CPU seconds in user code and 0.65 CPU seconds in system calls. Its p99 check took 2 microseconds. The deterministic structural gate also passed: idle checks performed zero payload reads after the first bounded selected window.
+
+## Rollout
+
+The implementation is one hard replacement. State writers, projection readers, local viewer, replay server, replay client, and protocol must agree before release.
+
+If the new presentation revision or delta records make the existing alpha database incompatible, startup must stop with the standard clear reset instruction. It must not modify or delete the old database.
+
+Release publication and installation of the matching npm and crates.io packages are separate work. Existing installed viewers keep their current behavior until they are replaced.
+
+## Outside dependencies
+
+SQLite remains responsible for committed read consistency. Ratatui and Crossterm remain responsible for terminal drawing and input. Terminal emulators and Unicode cell-width behavior remain outside repository control. Tests and bounds account for them without assuming they will change.
+
+A matching release and installed `piw` binary are required before users receive the fix.
+
+## Completion criteria
+
+The work is complete when one canonical revisioned projection serves local and remote clients, committed changes create bounded JSON Patch operations without full-view diffing, bounded pages support arbitrary replay positions, shared subscriptions handle several clients without duplicate reconstruction, graph work stays near the viewport, and unrelated history or nodes no longer determine memory, input latency, or card size.
+
+All failure, parity, performance, privacy, hard-replacement, and repository checks must pass before release.