@osolmaz/pi-workflows 0.12.1 → 0.13.0

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

@@ -1,12 +1,12 @@
 # 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,
+in [run-bundles.md](../SQLITE_STATE.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,
+1. **Spec** — rewrite `docs/SQLITE_STATE.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

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

@@ -343,7 +343,7 @@ 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/SQLITE_STATE.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.

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

@@ -30,7 +30,7 @@ way whether they come from the local filesystem or a WebSocket.
 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
+2. **Bundle module** — serde types mirroring `docs/SQLITE_STATE.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.

package/docs/session-event-journal.md

@@ -1,470 +1,99 @@
-# 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.
+# Session event journal
 
-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.
+Pi Workflows records the Pi conversation events associated with a workflow run. The journal supports live viewing, replay, and exact links from workflow steps to settled Pi entries.
 
-### `turn_started`
+All records live in the canonical [SQLite state](SQLITE_STATE.md) database.
 
-Source hook: `turn_start`.
+## Tables
 
-Required ids: `turnId`.
+### `session_segments`
 
-```json
-{ "turnIndex": 0 }
-```
+A segment is one capture owner tenure for one run. It stores:
 
-`turnIndex` is copied from Pi. The local `turnId` remains the journal identity.
+- the run and optional node attempt
+- the Pi session ID
+- the content-addressed binding record
+- recording, complete, or failed status
+- accepted entry and event counts
+- failure details when capture fails
+- start and finish times
 
-### `turn_finished`
+A later owner writes another segment. It does not rewrite the earlier segment.
 
-Source hook: `turn_end`.
+### `session_entries`
 
-Required ids: `turnId`.
+Each row stores one settled Pi session entry with a contiguous sequence, Pi entry ID, recorded time, and blob hash for the verbatim entry JSON.
 
-```json
-{ "turnIndex": 0, "messageId": "m1", "toolCallIds": ["call_1"] }
-```
+### `session_events`
 
-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.
+Each row stores one normalized temporal event with a contiguous sequence and these references when applicable:
 
-### `message_started`
+- node and attempt ID
+- turn ID
+- message ID
+- tool-call ID
+- event payload blob
+- receipt time
 
-Source hook: `message_start`.
+## Event types
 
-Required ids: `turnId`, `messageId`.
+The current event types are:
 
-```json
-{ "role": "assistant" }
-```
+- `turn_started`
+- `turn_finished`
+- `message_started`
+- `assistant_event`
+- `message_finished`
+- `tool_execution_started`
+- `tool_execution_updated`
+- `tool_execution_finished`
 
-`role` is the Pi message role observed at start.
+Unknown future event types remain visible to generic readers.
 
-### `assistant_event`
+## Write rules
 
-Source hook: `message_update`.
+The recorder queues hot-path Pi events in memory and writes bounded batches. One transaction writes the complete batch, updates the segment count, increments the segment resource revision, and appends its audit event.
 
-Required ids: `turnId`, `messageId`.
+The writer checks:
 
-The payload contains one normalized `AssistantMessageEvent`. The allowed shapes
-are:
+- positive contiguous event sequence numbers
+- required event envelope fields
+- the 1 MiB per-event limit
+- current segment state
+- current owner authority when ownership is required
 
-```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" };
-```
+A failed batch writes a failed capture status. Failed and complete capture states are terminal. A later completion call cannot replace a failed capture.
 
-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.
+Workflow execution does not fail because temporal capture failed. The run and the capture report their states separately.
 
-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.
+## Settled entries
 
-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.
+A `message_finished` event can refer to the Pi entry ID that settled the message. Replay first shows temporal deltas, then switches to the verbatim entry when that settled link is available.
 
-### `message_finished`
+Agent workflow steps also store their first and last Pi entry IDs. This makes the conversation slice for each step explicit without changing Pi session data.
 
-Source hook: `message_end`.
+## Read and replay rules
 
-Required ids: `turnId`, `messageId`.
+Readers order events by `event_seq`, not by wall-clock time. The `recorded_at` value controls playback timing only.
 
-Settled message:
+A capture is invalid when:
 
-```json
-{ "role": "assistant", "settled": true, "entryId": "e1" }
-```
+- sequences have a gap
+- required references are missing
+- row counts differ from the segment counters
+- a terminal run still reports recording
+- a settled event refers to an entry that does not exist
 
-Message without a recorded Pi entry:
+The TypeScript and Rust viewers read the same committed rows. They do not repair capture state.
 
-```json
-{ "role": "assistant", "settled": false }
-```
+## Privacy
 
-`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.
+Session entries and events can contain prompts, generated text, thinking, tool arguments, tool results, paths, and command output. The workflow directory uses mode `0700`, and `state.sqlite` uses mode `0600`.
 
-### `tool_execution_started`
+Status output does not expose raw session payloads. Remote replay is loopback-only unless the operator uses an SSH tunnel.
 
-Source hook: `tool_execution_start`.
+## Pi API boundary
 
-Required ids: `turnId`, `messageId`, `toolCallId`.
+The recorder uses Pi's documented `turn_start`, `turn_end`, `message_start`, `message_update`, `message_end`, `tool_execution_start`, `tool_execution_update`, and `tool_execution_end` hooks.
 
-```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.
+It does not change Pi session files, session entry schemas, or Pi internals.

package/docs/tui-viewer.md

@@ -16,18 +16,16 @@ 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
+- `piw` browses `~/.pi/agent/workflows/state.sqlite` through a read-only SQLite connection.
+- `piw <runId>` opens one run from that database.
+- `piw serve [--bind 127.0.0.1:9377]` exposes database-backed run views 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.
+Direct database mode and connected mode use the same semantic run view.
 The protocol is the network form of that view.
 
 ## Herdr
@@ -36,7 +34,7 @@ The npm package contains a native Herdr plugin. Link the installed package with
 `pi-workflows herdr setup`. A workflow running in Pi inside Herdr then shows
 `Ctrl+Shift+R piw` in its widget. When rows are hidden, the call to action shares
 the scroll-controls line. The shortcut and `/piw` command open
-the current bundle directly in a managed Herdr pane. The placement menu supports
+the current run directly in a managed Herdr pane. The placement menu supports
 right, below, left, above, a new tab, and a new workspace.
 
 The integration resolves the calling pane at invocation time and uses returned
@@ -54,7 +52,7 @@ 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,
+- **Run browser:** every run, 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
@@ -184,10 +182,10 @@ 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.
+The conversation folds `session_events` rows 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,
+with `entryId` switches that message to the matching verbatim `session_entries`
+row. 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.
 
@@ -198,9 +196,9 @@ 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.
+Expanded prompt and output fields come from content-addressed SQLite blobs.
+The local reader uses query-only mode. Remote snapshots carry the same bounded
+semantic view and do not expose a filesystem path.
 
 ## Interaction