@osolmaz/pi-workflows 0.15.2 → 0.16.0

package/docs/live-replay-protocol.md

@@ -1,175 +1,113 @@
-# Live replay protocol
+# Live client protocol
 
-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`.
+Pi Workflows uses one live client protocol for the Pi extension, the TypeScript CLI, local `piw`, and remote `piw` through the loopback relay.
 
-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.
+The protocol ID is `pi-workflows.client.v1`. Its schema is [`protocol/client.v1.schema.json`](../protocol/client.v1.schema.json). TypeScript and Rust use the same valid and invalid fixture corpus.
 
-## Framing
+The host is the only process that reads or writes the active SQLite database. A client protocol or package-version mismatch does not mean that SQLite state is incompatible. The client stops and asks for matching `pi-workflows` and `piw` packages.
 
-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.
+## Transports
 
-```json
-{ "type": "hello", "protocol": "pi-workflows.replay.v1" }
+The local transport is a user-only Unix socket on Unix systems:
+
+```text
+~/.pi/agent/workflows/host/host.sock
 ```
 
-## Bounded run view
+On Windows, the same client uses the package-derived `\\.\pipe\pi-workflows-<state-directory-hash>` named pipe. Local `piw`, `piw serve`, and the TypeScript client derive the same endpoint from the workflow state directory. A foreground TypeScript cold start keeps its retry wait referenced until the detached host becomes ready or the start deadline expires. Only background reconnect timers are unreferenced.
+
+Each message is one canonical JSON object followed by a newline. TypeScript and Rust use the same ECMAScript number formatting and UTF-16 object-key order, including for arbitrary workflow JSON. A message can be at most 1 MiB. Unknown envelope fields, non-canonical JSON, and invalid framing close only the offending connection. If socket backpressure delays a client write, connection close, socket error, or request cancellation ends the wait instead of leaving the request pending.
+
+`piw serve` provides the remote transport at `/ws`. It binds to loopback only. Each WebSocket connection has one matching host-socket connection, and their lifecycles are coupled. The relay forwards one canonical JSON object per text frame. It does not read SQLite, translate views, multiplex clients, or retain state.
+
+Remote clients use an SSH tunnel to reach the loopback relay.
 
-A snapshot contains one bounded run view:
+## Envelope
+
+The protocol has four message types:
+
+- `hello` identifies the protocol connection and package version.
+- `request` carries one operation, request ID, client ID, idempotency key, optional run ID and revision, and payload.
+- `response` settles one request with an outcome, optional revision, receipt, or safe error.
+- `event` carries a revisioned run list, run snapshot, run patch, run page, session snapshot, or unavailable condition.
+
+The host sends `hello` first:
 
 ```json
 {
-  "presentationRevision": 42,
-  "graphRevision": 17,
-  "manifest": { … },
-  "workflow": { … },
-  "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": { … },
-    "entryPage": {
-      "presentationRevision": 42,
-      "start": 768,
-      "total": 1000,
-      "items": [ … ]
-    },
-    "eventPage": {
-      "presentationRevision": 42,
-      "start": 768,
-      "total": 1000,
-      "items": [ … ]
-    },
-    "capture": { … }
-  },
-  "settingsScopes": [ … ],
-  "followUpQueue": { … },
-  "live": true,
-  "possiblyInterrupted": false
+  "connectionId": "connection-1",
+  "packageVersion": "0.15.3",
+  "schema": "pi-workflows.client.v1",
+  "type": "hello"
 }
 ```
 
-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.
+A request uses a stable request ID and idempotency key:
 
 ```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 }
-      ]
-    }
-  ]
+  "clientId": "client-1",
+  "idempotencyKey": "status-1",
+  "operation": "host.status",
+  "payload": {},
+  "requestId": "request-1",
+  "schema": "pi-workflows.client.v1",
+  "type": "request"
 }
 ```
 
-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.
+The closed outcomes are `accepted`, `adopted`, `rejected`, `conflict`, `notFound`, `claimLost`, and `unavailable`.
 
-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.
+## Run and session views
 
-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 host produces `pi-workflows.run-view.v1` from one consistent database read. The view contains the bounded workflow state, graph, trace, session projection, page cursors, presentation revision, and one `display` object. A terminal display includes the stored failure reason, not only its machine error code. A reason above the shared 16 KiB inline-content threshold uses a small `reason` notice and a digest-bound `reasonContent` reference. This keeps the run list below the 1 MiB frame limit and keeps the complete diagnostic available.
 
-The database retains 256 presentation revisions per run. The server does not replay an unbounded patch backlog.
+The closed display statuses are:
 
-## Pages
+- `queued`
+- `running`
+- `waiting`
+- `paused`
+- `completed`
+- `failed`
+- `timed_out`
+- `cancelled`
+- `ambiguous`
 
-A client asks for a page with `fetch_page`:
+Only the host computes this status. A parked queue is not a pause. `paused` requires the durable pause flag. An exact live worker or origin-session turn is `running`. An effect being applied by that live worker is still `running`; only a durable `ambiguous` effect that needs operator action is `ambiguous`. `unavailable` is a client connection condition, not a run status.
 
-```json
-{
-  "type": "fetch_page",
-  "runId": "run-1",
-  "kind": "session_events",
-  "cursor": 20000
-}
-```
+The run list uses the same display object. The host sends it as revision-bound `pi-workflows.run-list-page.v1` pages. Each page reads only lightweight run status and source facts. It does not load input, launch options, steps, trace, or session history. TypeScript and Rust clients collect all pages for one revision before they replace the visible list. If the revision changes, they discard the partial list and start from the next subscription event.
 
-`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`:
+An origin-session subscription returns `pi-workflows.session-view.v1`, which contains the current active run view, an ordered byte-bounded window of pending interaction records, their complete count, and read-only notification and turn availability in one read. A session with no active reservation returns no run, even when that session has older terminal runs. The Pi extension assembles the active run's complete step history and hydrates its definition and referenced values before it updates the widget or delivery coordinator. It sends a durable claim command only when the matching availability fact is true. After a turn claim, it reads the claimed run by its exact run ID. It does not use the latest run in the session. An idle session does not create empty claim or status commands.
 
-```json
-{
-  "type": "run_page",
-  "runId": "run-1",
-  "revision": 43,
-  "kind": "session_events",
-  "cursor": 20000,
-  "start": 19872,
-  "total": 48620,
-  "items": [ … ]
-}
-```
+A snapshot page contains at most 256 items and also has a byte budget. `view.page` returns another byte-bounded window that contains the requested cursor. Page responses use `pi-workflows.run-page.v1` and echo the requested cursor and run-view revision. A client applies a page only when both still match its current request and snapshot. A step-centered trace request selects the exact stored attempt first and uses its node only when that attempt has no trace event. Large workflow topology has bounded node, edge, graph-step, and transition projections plus durable content references for the complete original definition and complete graph history. TypeScript clients assemble every run-history page for that revision and hydrate the complete definition and all referenced content before they emit a complete non-interactive view or update the Pi widget. TypeScript and Rust use the same verified content loader for complete graph steps and transitions. Rust also requests, verifies, and decodes the complete referenced definition before it builds the graph layout. A session-event page also carries the replay checkpoint for the exact sequence before its first item, so reducing the page does not lose earlier active messages or tool calls. The checkpoint can itself be a durable content reference. TypeScript hydrates it with the run view, and Rust requests and resolves it before replay.
 
-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.
+The host counts histories first and reads only the selected SQLite ranges. An unchanged subscription uses a lightweight revision check and reuses its prior view. It does not rebuild complete histories every 250 milliseconds.
 
-## Messages
+Large prompt, output, event, settings, follow-up, and update values use a content reference instead of making a protocol frame exceed 1 MiB. `view.content` returns the referenced UTF-8 content in verified chunks. The reference includes its media type, byte count, SHA-256 digest, and an opaque marker for host-created references. The host saves generated view content directly under its exact run ID, content digest, and media type before it advertises the reference. It does not share media metadata with general state blobs. A request for another run or media representation is unavailable. Memory-cache eviction therefore cannot make an advertised aggregate unavailable. Run pruning removes the durable content. Clients reassemble all chunks and verify the bytes against both the content response and the advertised reference before display. Opaque content is restored as user data without interpreting nested objects as host references. Other cursors and content references keep the complete logical history and result available.
 
-Client to server:
+## Subscriptions and reconnection
 
-| 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`. |
+A client keeps one persistent connection and records its desired run-list, run, and origin-session subscriptions. A request to watch a run that does not exist returns `notFound` and does not install a subscription. TypeScript and Rust clients show that response instead of waiting for a snapshot. Explicit `piw <runId>` mode keeps that run selected even when the run list contains a newer run. After reconnection, the client sends accepted subscriptions again with its run revision. The host sends a bounded snapshot when the client needs one. The protocol also supports retained revision patches. Unsubscribing sends the subscription ID to the host for every subscription kind, so no unused snapshot work remains on a live connection.
 
-Server to client:
+A slow or disconnected client cannot stop the host, another client, claim renewal, or workflow execution. The host waits for socket drain before it publishes another snapshot to that connection. Polling coalesces while the connection is blocked, so the socket buffer cannot grow by one snapshot on every poll. When a connection closes, the host removes its subscriptions and exact origin-session activity immediately.
 
-| 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.      |
+## Origin-session activity
 
-The run list contains `presentationRevision`, `manifest`, `live`, and `possiblyInterrupted`. It contains no payload bodies.
+The Pi extension reports `started`, `refresh`, and `settled` activity for the exact session, run, interaction request, delivery, and Pi session entry. Reports use a monotonic sequence. The first report on each protocol connection is `started`; only later reports on that same connection use `refresh`. Refresh happens before the connection-scoped lease expires.
 
-## Several clients
+The host accepts activity only when its session, run, request, deterministic `interaction:<request-id>` delivery ID, and presented Pi session entry match the durable presented interaction. Activity entries are keyed by connection and request, so another caller-supplied delivery label cannot create a duplicate overlay. Activity changes display only. It does not grant authority, renew a workflow claim, settle a step, or change durable pause state. A disconnect or expired activity lease removes the overlay.
 
-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.
+## Commands and uncertain results
 
-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.
+Durable commands use stable idempotency keys. The Pi extension routes each state-changing command through the durable client request path. If the connection closes after the host commits but before the response arrives, the client reconnects with a new request ID and adopts the stored result. A retry with the same durable identity and payload adopts the stored receipt. Reusing that identity with another payload is a conflict. The request ID identifies one transport attempt and is not part of the durable request fingerprint. A retry after a local abort uses a new request ID and keeps the durable idempotency and submission IDs, so a late response from the aborted attempt cannot settle the retry.
 
-## Reconnection
+An `interaction.submit` response stays open while the supervised workflow child validates the value. The response settles only after the durable result is accepted, adopted, or rejected. A tool abort stops waiting immediately but does not undo an accepted host command. A later retry adopts the durable outcome. The host waits on the stored submission ID returned by adoption, not a different ID from the retry attempt. Clients do not poll SQLite.
 
-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.
+The protocol does not claim exactly-once behavior for an external system that cannot prove it. An uncertain non-idempotent effect becomes ambiguous and requires explicit recovery.
 
-## SQLite consistency
+## Maintenance
 
-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.
+Active `state.status`, `state.verify`, `state.backup`, and `state.prune` requests run in the host against its existing database connection. The CLI uses one stable client identity and creates a fresh idempotency key for each backup or applied prune invocation. If that invocation loses its connection, the client reconnects once with a new request ID and the same invocation key, so the host adopts the exact in-flight or stored result. A later user invocation gets a new key and does not reuse a stale success or rejection. The host keeps an in-flight maintenance command alive after a client disconnect, stores its accepted or rejected receipt before it responds, and adopts the exact retry instead of running the operation again. Host shutdown waits for in-flight maintenance receipts. `state.status` returns the database file size and safe counts for resources, runs, controllers, decisions, settings scopes, pending interactions, pending follow-ups, active leases, and unsettled effects.
 
-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.
+Only `pi-workflows state verify <inactive-backup>` opens SQLite outside the host. It uses a query-only TypeScript connection and rejects the active database, including another path to the same file.

package/docs/tui-viewer.md

@@ -9,11 +9,11 @@ a recorded Pi conversation, themes, and remote viewing.
 
 The viewer uses the [incremental and virtualized viewer design](plans/2026-08-28-piw-incremental-viewer-plan.md).
 
-The run browser reads small metadata rows. It does not load trace, step, session, settings, or follow-up payloads. The local viewer checks SQLite `data_version` on its timer. When the value is unchanged, the timer does not scan runs or read payloads.
+The run browser subscribes to small host-owned metadata views. It does not load trace, step, session, settings, or follow-up payloads. The host publishes a new bounded view only when its content changes.
 
-The selected run contains bounded pages. Step, trace, session-entry, and session-event pages contain at most 256 rows. Replay can jump to any position. The viewer loads the page that contains that position and keeps only the current windows. A compact graph projection keeps the latest attempt for each node and the taken transitions up to the replay point.
+The selected run contains bounded pages. Step, trace, session-entry, session-event, settings, follow-up, and update pages have both a row limit and a byte budget. Replay can jump to any position. The viewer loads the page that contains that position and keeps only the current windows. A session-event page includes the replay checkpoint immediately before its first event. A compact graph projection keeps the latest attempt for each node and the taken transitions up to the replay point.
 
-Local page reads run outside input and drawing through one overwrite-only request slot. A newer selection replaces pending work. A failed first read leaves the run browser usable. A failed refresh keeps the last good view and marks it stale.
+Large values use host content references. `piw` fetches them in bounded chunks when the user opens the related detail, verifies the byte count and SHA-256 digest, and then shows the complete text or JSON value. Page and content requests run outside input and drawing through the shared client protocol. A newer page selection replaces the previous request, including when the user returns to an earlier page. A failed first read leaves the run browser usable. A failed refresh keeps the last good view and marks it stale.
 
 ## Install
 
@@ -26,17 +26,15 @@ cargo install pi-workflows
 
 ## Modes
 
-- `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` connects to the local package-owned workflow host. If the socket is absent, it runs the installed `pi-workflows host start` command.
+- `piw <runId>` opens one host-owned run view.
+- `piw <runId> --once` waits for that run, renders one complete 120 × 40 plain-text frame, and exits. It returns a nonzero status for host, protocol, missing-run, or snapshot-timeout failures.
+- `piw serve [--bind 127.0.0.1:9377]` relays each WebSocket connection to one host socket over the [live client 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 database mode and connected mode use the same semantic run view.
-The protocol is the network form of that view.
+Local and remote modes use the same semantic run view and the same protocol. `piw` has no SQLite mode or database schema copy.
 
 ## Herdr
 
@@ -211,11 +209,9 @@ listing and selected-run subscription after the server returns. Cached content
 stays visible but is labeled reconnecting or disconnected, never current.
 Revision gaps force a bounded snapshot.
 
-`piw serve` keeps one loaded projection and one graph scene for each watched run. The first watcher loads it. Later watchers reuse it. The last unwatch or disconnect releases it. Clients keep separate revision and page cursors, so one client's replay jump does not move another client. A lagged client gets a bounded snapshot instead of an unbounded patch backlog.
+`piw serve` is a frame relay. It keeps no run projection or client activity after either side closes. Clients keep separate revision and page cursors, so one client's replay jump does not move another client. A lagged client gets a bounded snapshot instead of an unbounded patch backlog.
 
-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.
+The host resolves expanded prompt and output fields from durable content. Local and remote snapshots carry the same bounded semantic view and do not expose a database path.
 
 ## Interaction
 

package/docs/workflows.md

@@ -126,6 +126,8 @@ pi-workflows host run
 `host run` stays attached. The other commands start, inspect, or stop the
 on-demand process. No command installs an operating-system service.
 
+The extension, CLI, and `piw` use the same version-1 client protocol over a Unix socket or Windows named pipe. The host sends byte-bounded run-list and run-view pages. Clients collect a complete run list for one revision and reject stale run pages whose cursor or revision no longer matches. The host reads only the selected history ranges and reuses an unchanged subscribed view after a lightweight revision check. It waits for a slow socket to drain and removes every subscription when its client unsubscribes. Large values stay available through verified content chunks. Host-generated aggregate values are saved and linked to the run before the host advertises them.
+
 A worker verifies the root and all mounted source identities before it loads
 workflow modules. It then checks the resolved mounted-source map and executes
 from committed state through a host-backed store. A source mismatch parks the
@@ -193,7 +195,10 @@ For submitted output, the engine appends the existing workflow-tool contract.
 The host checks the durable transport identifiers, stores a `validating`
 submission, and starts a supervised worker. In that worker, the output passes
 through tolerant JSON normalization and then `validate`. The tool reports
-success only after this check accepts the output. Rejected submissions return
+success only after this check accepts the output. If the tool turn is aborted,
+the client stops waiting but does not cancel the durable host command. A retry
+uses a new transport request ID with the same durable submission identity and
+adopts the stored result. Rejected submissions return
 the validation error and can retry in the same step. If the model settles
 without submitting, the durable request stays pending until it receives valid
 output, times out, or is cancelled. For assistant-message output, the engine appends a normal-response contract,
@@ -475,8 +480,18 @@ The model sees one `workflow` tool. Its `action` field supports:
 A direct user request to continue or resume the active workflow maps to
 `resume` immediately. The model does not call `status` instead of `resume` or
 use it as a prerequisite. An already active run adopts the resume request. A
-paused or parked run gets a new claim generation and worker. With no resumable
-run, the host rejects the request.
+paused interaction remains the same durable request and resumes without a
+worker. Other paused or parked work gets a new claim generation and worker.
+With no resumable run, the host rejects the request.
+
+The origin Pi session shows its active run in the workflow widget. `Shift+Up`
+and `Shift+Down` scroll it. If Escape aborts the model turn started by a
+presented workflow interaction, the extension detects the public context abort
+signal and pauses that run through the host. It also accepts Pi's public
+`aborted` stop reason. The matching `agent_end` event must contain the workflow
+prompt, so an unrelated interrupted turn cannot pause old pending work. The
+paused run does not accept updates, submissions, or decision answers until
+`resume`.
 
 `status` reports the durable queue projection. A host command succeeds only
 after its transaction commits. The protocol stores request fingerprints and
@@ -785,3 +800,41 @@ const engine = new WorkflowEngine({
 });
 const { state } = await engine.run(workflow, { task: "..." });
 ```
+
+## Test the installed package
+
+The installed-package end-to-end test packs this repository and installs the
+archive with production dependencies in a temporary consumer project. It then
+starts the repository-pinned base Pi with only that Pi Workflows installation.
+The test checks command isolation, host startup, widget and status changes,
+pause, resume, completion, and `piw <runId> --once` output.
+
+Run the deterministic phase without a model call:
+
+```bash
+npm run test:e2e:live -- --runtime-only
+```
+
+A real-model phase is manual. Supply the exact Pi provider and model as separate
+values. The runner does not select a default or accept model fallback:
+
+```bash
+npm run test:e2e:live -- \
+  --provider openai \
+  --model gpt-5.6-luna
+```
+
+For subscription authentication, use a dedicated Pi profile that has no other
+extensions or resources:
+
+```bash
+npm run test:e2e:live -- \
+  --profile ~/.config/pi-workflows-e2e/openai-codex \
+  --provider openai-codex \
+  --model gpt-5.6-luna
+```
+
+The profile and normal provider environment remain operator-owned. The runner
+does not read, copy, print, or save credentials. It uses one guarded temporary
+root and removes that root after success or failure. Use `--keep` only when you
+need the isolated files for diagnosis.

package/herdr-plugin.toml

@@ -1,6 +1,6 @@
 id = "osolmaz.pi-workflows"
 name = "pi-workflows"
-version = "0.15.2"
+version = "0.16.0"
 min_herdr_version = "0.7.0"
 description = "Open the active pi-workflows run in piw from a managed Herdr pane."
 platforms = ["linux", "macos"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osolmaz/pi-workflows",
-  "version": "0.15.2",
+  "version": "0.16.0",
   "description": "Workflow and controller runtime with a live terminal viewer for the pi coding agent",
   "keywords": [
     "pi-package"
@@ -24,6 +24,7 @@
     "examples",
     "docs",
     "schemas",
+    "protocol",
     "plugins/herdr",
     "herdr-plugin.toml",
     "README.md",
@@ -39,6 +40,10 @@
       "types": "./dist/extension/index.d.ts",
       "default": "./dist/extension/index.js"
     },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "default": "./dist/client/index.js"
+    },
     "./controllers": {
       "types": "./dist/controllers/index.d.ts",
       "default": "./dist/controllers/index.js"
@@ -62,11 +67,13 @@
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "test:e2e:live": "node scripts/live-e2e.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
     "better-sqlite3": "^13.0.2",
-    "jiti": "^2.7.0"
+    "jiti": "^2.7.0",
+    "tsx": "^4.23.13"
   },
   "devDependencies": {
     "@earendil-works/pi-ai": "0.84.2",
@@ -77,7 +84,6 @@
     "@vitest/coverage-istanbul": "^4.1.10",
     "oxfmt": "^0.59.0",
     "oxlint": "^1.74.0",
-    "tsx": "^4.23.1",
     "typebox": "^1.3.6",
     "typescript": "^7.0.2",
     "vitest": "^4.1.10"

package/protocol/client.v1.schema.json

@@ -0,0 +1,137 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/osolmaz/pi-workflows/blob/main/protocol/client.v1.schema.json",
+  "title": "Pi Workflows client protocol version 1",
+  "oneOf": [
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schema", "type", "connectionId", "packageVersion"],
+      "properties": {
+        "schema": { "const": "pi-workflows.client.v1" },
+        "type": { "const": "hello" },
+        "connectionId": { "$ref": "#/$defs/opaqueId" },
+        "packageVersion": { "type": "string", "minLength": 1 }
+      }
+    },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schema",
+        "type",
+        "requestId",
+        "clientId",
+        "operation",
+        "idempotencyKey",
+        "payload"
+      ],
+      "properties": {
+        "schema": { "const": "pi-workflows.client.v1" },
+        "type": { "const": "request" },
+        "requestId": { "$ref": "#/$defs/opaqueId" },
+        "clientId": { "$ref": "#/$defs/opaqueId" },
+        "operation": {
+          "enum": [
+            "run.start",
+            "run.pause",
+            "run.resume",
+            "run.cancel",
+            "run.status",
+            "run.list",
+            "checkpoint.answer",
+            "decision.answer",
+            "interaction.submit",
+            "interaction.update",
+            "notification.claim",
+            "notification.deliver",
+            "turn.claim",
+            "turn.resolve",
+            "controller.list",
+            "controller.get",
+            "controller.apply",
+            "controller.reconcile",
+            "controller.delete",
+            "host.status",
+            "host.stop",
+            "view.runs.watch",
+            "view.runs.page",
+            "view.run.get",
+            "view.run.watch",
+            "view.run.unwatch",
+            "view.page",
+            "view.content",
+            "view.session.watch",
+            "activity.report",
+            "state.status",
+            "state.verify",
+            "state.backup",
+            "state.prune"
+          ]
+        },
+        "idempotencyKey": { "$ref": "#/$defs/opaqueId" },
+        "runId": { "$ref": "#/$defs/opaqueId" },
+        "expectedRevision": { "$ref": "#/$defs/revision" },
+        "payload": {}
+      }
+    },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schema", "type", "requestId", "outcome"],
+      "properties": {
+        "schema": { "const": "pi-workflows.client.v1" },
+        "type": { "const": "response" },
+        "requestId": { "$ref": "#/$defs/opaqueId" },
+        "outcome": {
+          "enum": [
+            "accepted",
+            "adopted",
+            "rejected",
+            "conflict",
+            "notFound",
+            "claimLost",
+            "unavailable"
+          ]
+        },
+        "revision": { "$ref": "#/$defs/revision" },
+        "receipt": {},
+        "error": { "type": "string", "minLength": 1 }
+      }
+    },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schema", "type", "subscriptionId", "event", "payload"],
+      "properties": {
+        "schema": { "const": "pi-workflows.client.v1" },
+        "type": { "const": "event" },
+        "subscriptionId": { "$ref": "#/$defs/opaqueId" },
+        "event": {
+          "enum": [
+            "runs",
+            "run_snapshot",
+            "run_patch",
+            "run_page",
+            "session_snapshot",
+            "unavailable"
+          ]
+        },
+        "revision": { "$ref": "#/$defs/revision" },
+        "runId": { "$ref": "#/$defs/opaqueId" },
+        "payload": {}
+      }
+    }
+  ],
+  "$defs": {
+    "opaqueId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256
+    },
+    "revision": {
+      "type": "integer",
+      "minimum": 0
+    }
+  }
+}