@osolmaz/pi-workflows 0.15.3 → 0.16.1

package/docs/live-replay-protocol.md

@@ -1,175 +1,117 @@
-# 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.
+
+## Envelope
 
-A snapshot contains one bounded run view:
+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`. It contains the active run view first. When no run is active, it keeps the most recent terminal run while its terminal workflow message is pending or its first model turn is open, and then for 60 seconds after that turn ends. The same response contains an ordered byte-bounded window of all nonterminal workflow messages and open sent messages needed for recovery, their complete count, and the next eligible pending message only for the active coordinator epoch.
 
-```json
-{
-  "type": "run_page",
-  "runId": "run-1",
-  "revision": 43,
-  "kind": "session_events",
-  "cursor": 20000,
-  "start": 19872,
-  "total": 48620,
-  "items": [ … ]
-}
-```
+The Pi extension assembles the complete run revision and workflow-message content before it updates the widget or coordinator. After every host connection, it reports the active branch before it sends a workflow message or reports a model turn. The report can name only message IDs from the complete session-view window. The extension always uses the exact run ID from that view. It does not select the latest run separately. An idle session does not create empty commands.
+
+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.
+
+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.
 
-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.
+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.
 
-## Messages
+## Subscriptions and reconnection
 
-Client to server:
+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.
 
-| 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 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 active coordinator epoch. It does not infer that an open model turn ended.
 
-Server to client:
+## Origin-session activity
 
-| 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.      |
+The Pi extension uses `workflowTurn.report` to record `started` and `ended` for the exact workflow message, workflow turn, run, and origin session. There is no refresh, activity lease, heartbeat, or sequence counter. A started turn keeps the host-produced display status `running` until the matching end is accepted. A stale end cannot clear a newer turn.
 
-The run list contains `presentationRevision`, `manifest`, `live`, and `possiblyInterrupted`. It contains no payload bodies.
+The host accepts a start only for an open sent workflow message in that origin session. A step message is open while its interaction remains pending and its run is not paused. A terminal or follow-up message is open until its first turn ends. Decisions and notifications never open model turns. Turn binding does not inspect branch membership because documented `agent_start` has no message payload; branch reporting owns entry adoption and branch-specific re-presentation.
 
-## Several clients
+If the workflow message or session view is still loading, the extension buffers the matching start and end and reports them in order after the message is confirmed `sent`. Activity changes display only. It does not grant workflow authority, renew a run claim, or settle an interaction. Host startup does not close an open Pi turn. Only a later idle-session active-branch report can close a proved-lost turn.
 
-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,13 @@ 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.
+Each live view keeps the host's `display` value separate from the durable workflow `state`. The run browser, current-run status, timeline, and latest graph use `display` directly. During an origin-session model turn, the latest graph presents the durable `waitingOn` node as running. Replay continues to use durable state and recorded history. `piw` does not calculate another live status.
 
-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.
+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.
+
+Large values use host content references. `piw` fetches workflow definitions, graph history, and complete host display reasons before it publishes the related live view. It fetches other large details when the user opens them. It verifies the byte count and SHA-256 digest before it 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 +28,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 +211,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
@@ -145,9 +147,11 @@ provisional. A new supervised worker loads the workflow and runs its `validate`
 function before the host accepts the submission. A validation error leaves the
 same request pending and returns the error to the model. Closing Pi leaves that
 request pending; reopening the same session adopts the existing session entry
-or presents it once. Notifications use the durable session outbox. A root
-`presentationPrompt` creates a durable terminal turn only after completion is
-committed. A controller child without an origin session can use a supervised
+or presents it once. Step prompts, protected decisions, notifications, terminal
+results, and follow-ups use the host-owned `workflow_messages` table and one
+extension sender. Initial, reminder, and resumed prompts are the same step-message
+kind with different display reasons. A terminal workflow message becomes eligible only after
+the terminal outcome is committed. A controller child without an origin session can use a supervised
 headless `pi --mode rpc` child for structured agent steps.
 
 Pause stops the worker and parks at the last durable boundary. Resume takes a
@@ -193,17 +197,24 @@ 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,
+without submitting, the host increments the request's unproductive-turn counter
+and can create at most two step messages with reason `reminder`. The next
+unproductive turn fails the step. The timeout remains active during each
+reported model turn, and cancellation remains active throughout. For assistant-message output, the engine appends a normal-response contract,
 waits for `agent_settled`, rejects empty, failed, aborted, or tool-only results,
 and never suppresses the visible text. Timeout and cancellation abort either
 form's active Pi turn.
 
 `timeoutMs` can be a finite positive number, `null`, or a function of the normal
 node context that returns either value. Omit it to use the 15-minute engine
-default. Set it to `null` to disable only the wall-clock deadline; cancellation,
+default. The limit counts active node execution. For an origin-session agent
+node, it counts reported model-turn time from an active connected Pi session.
+It excludes message delivery, waiting, paused time, disconnects, and host downtime. Set it to `null` to disable only this deadline; cancellation,
 parking, claim loss, shutdown, and the node's abort signal still work. A timeout
 function can use prepared outputs to select a policy for this run. It has 30
 seconds to return. Computed timeout functions are runtime code, so definition
@@ -368,7 +379,7 @@ humanDecision({
 });
 ```
 
-The waiting run stores a versioned request and asks every channel configured for the logical audience. The structured `subject` remains machine data. Channels receive only the normalized `presentation`, title, choices, input prompts, and any deadline policy. The first valid verified human answer wins. When `onTimeout` is present and no human answer wins before the saved deadline, the host takes a control claim on the waiting parent and atomically applies the validated response with `timeout` provenance, closes the interaction, and reserves the continuation. This policy can continue without a configured channel. A continuation preserves the original workflow input and exposes the resolved response as the checkpoint output. `humanDecisionEdge()` provides exhaustive routing for the choices. Existing `body` requests remain a legacy compatibility form and use deterministic readable formatting.
+The waiting run stores a versioned request and asks every channel configured for the logical audience. The structured `subject` remains machine data. Channels receive only the normalized `presentation`, title, choices, input prompts, and any deadline policy. The first valid verified human answer wins. When `onTimeout` is present and no human answer wins before the saved deadline, the host takes a control claim on the waiting parent and atomically applies the validated response with `timeout` provenance, closes the interaction, and reserves the continuation. This policy can continue without a configured channel. A continuation preserves the original workflow input and exposes the resolved response as the checkpoint output. `humanDecisionEdge()` provides exhaustive routing for the choices. The removed `body` request form is invalid under the alpha hard cut.
 
 The model-facing workflow tool cannot answer a protected human decision. The origin Pi session displays the request without starting a model turn. A person uses `/workflow answer` to send the answer through the host-owned path. Ordinary checkpoints can also use the model-facing `answer` action.
 
@@ -475,18 +486,19 @@ 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 interaction remains the same durable request and resumes without a
-worker. Other paused or parked work gets a new claim generation and worker.
+pending interaction on a paused run 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`.
+and `Shift+Down` scroll it. A sent step message is open only while its
+interaction is pending and its run is not paused. Because public `agent_start`
+has no message payload, any model turn that starts in that state is workflow
+work. If Escape ends that turn with Pi's public `aborted` stop reason, one
+turn-end report atomically sets the run pause and cancels the interaction's
+pending step messages. A turn that starts while the run is paused does not bind
+to the workflow. 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
@@ -679,18 +691,16 @@ is pending, the step id is wrong, the attempt id belongs to an earlier attempt
 of the same node (loops revisit node ids, so each attempt gets a fresh id), or
 `validate` throws.
 Acceptance resolves the step and the engine advances. In an interactive Pi
-session, each agent prompt arrives as a `pi-workflows-agent-step` custom message
+session, each agent prompt arrives as a `pi-workflows-step` custom message
 with `triggerTurn: true`. The model receives the complete prompt, while the
 conversation shows a compact workflow and node card. Expanding tool output with
-Ctrl+O shows the exact contract and full prompt. Reminders and resumed prompts
-use the same card and keep the active attempt id.
+Ctrl+O shows the exact contract and full prompt. Step messages with reason `reminder` or `resumed` use the same card and keep the active attempt ID.
 
 Headless RPC execution receives the same complete prompt without TUI metadata.
-Workflow notifications use a separate message type with `triggerTurn: false`,
-so a notification does not start an assistant response. Deferred successor turns
-use an internal turn-intent contract instead of the notification outbox. See
-[WORKFLOW_STEP_MESSAGES.md](WORKFLOW_STEP_MESSAGES.md) for the step-message contract
-and [Deferred workflow turns](DEFERRED_TURNS.md) for the successor-turn contract.
+Workflow notifications use a custom message with `triggerTurn: false`, so a
+notification does not start an assistant response. Step prompts, decisions, notifications, terminal results, and follow-ups use the same saved workflow-message contract and extension coordinator. Initial, reminder, and resumed prompts use the same step kind. See
+[Workflow messages in Pi](WORKFLOW_STEP_MESSAGES.md) and the approved
+[workflow-message restoration plan](2026-09-02-unify-workflow-messages-plan.md).
 
 ## Visible responses
 
@@ -707,7 +717,7 @@ returns its stored receipt.
 
 A headless controller child cannot produce a visible assistant message without
 an approved origin-session binding. Use structured agent output for detached
-work. Terminal run state does not create an extra model turn.
+work. A final continuation-chain outcome creates its own terminal workflow message through the shared coordinator only after the outcome is durable.
 
 ## Runtime behavior
 
@@ -719,8 +729,10 @@ possible. Defaults worth knowing:
   number or context callback. A timed-out node has outcome `timed_out` and can
   be routed with `$result.outcome`. A timed-out agent node also aborts its Pi
   turn, and late output for that attempt is rejected. Interactive runs save the
-  resolved wall-clock deadline before they park. The host enforces that deadline
-  while Pi is closed and after host restart.
+  resolved deadline before they park. The host advances it only during a
+  reported model turn from an active connected origin session. Message delivery,
+  waiting, pauses, disconnects, and host downtime do not consume the limit. This
+  active-time budget survives host restart.
 - `maxSteps` (workflow-level, default 100) bounds loops built from cycles in
   the graph.
 - `/workflow pause` atomically parks the run with `paused: true`, stores the
@@ -795,3 +807,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.3"
+version = "0.16.1"
 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.3",
+  "version": "0.16.1",
   "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/plugins/herdr/viewer.mjs

@@ -12,12 +12,14 @@ if (!/^[A-Za-z0-9]+:p[A-Za-z0-9]+$/u.test(paneId)) {
   fail("HERDR_PANE_ID is missing or invalid.");
 }
 
-const herdr = process.env.HERDR_BIN_PATH ?? "herdr";
+const configuredHerdr = process.env.HERDR_BIN_PATH ?? "herdr";
 const label = `piw · ${runId}`;
-const labeled = spawnSync(herdr, ["pane", "rename", paneId, label], {
-  encoding: "utf8",
-  stdio: ["ignore", "ignore", "pipe"],
-});
+let herdr = configuredHerdr;
+let labeled = renamePane(herdr, paneId, label);
+if (labeled.error?.code === "ENOENT" && herdr !== "herdr") {
+  herdr = "herdr";
+  labeled = renamePane(herdr, paneId, label);
+}
 if (labeled.error) fail(`Could not label the Herdr viewer pane: ${labeled.error.message}`);
 if (labeled.status !== 0) {
   fail(`Could not label the Herdr viewer pane: ${bounded(labeled.stderr) || "unknown error"}`);
@@ -32,6 +34,13 @@ viewer.on("exit", (code, signal) => {
   process.exitCode = signal ? 1 : (code ?? 1);
 });
 
+function renamePane(command, targetPaneId, targetLabel) {
+  return spawnSync(command, ["pane", "rename", targetPaneId, targetLabel], {
+    encoding: "utf8",
+    stdio: ["ignore", "ignore", "pipe"],
+  });
+}
+
 function fail(message) {
   process.stderr.write(`${message}\n`);
   process.exit(1);