@osolmaz/pi-workflows 0.15.2 → 0.16.0

package/docs/2026-09-02-installed-live-e2e-plan.md

@@ -0,0 +1,225 @@
+---
+title: Test installed workflows end to end
+author: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
+date: 2026-09-02
+---
+
+# Test installed workflows end to end
+
+## Goal
+
+Add one black-box test runner that starts base Pi with only the packed Pi Workflows package. The runner will execute a workflow through the package-owned host and check Pi's workflow widget throughout its lifecycle. It will also check the Rust `piw` client. A separate phase can use a real model.
+
+The runner must keep the Pi provider and model as separate exact values. It must work with Pi's built-in providers instead of containing OpenAI-specific model logic.
+
+## Provider boundary
+
+Pi has two distinct OpenAI providers.
+
+- `openai-codex` uses ChatGPT Plus or Pro subscription credentials. Its GPT-5.6 models use the `openai-codex-responses` API against the ChatGPT backend.
+- `openai` uses an OpenAI API key. Its GPT-5.6 models use the `openai-responses` API against `api.openai.com`.
+
+The current base Pi catalog includes `gpt-5.6-luna` under both providers. These are separate provider and model pairs:
+
+```text
+provider=openai-codex model=gpt-5.6-luna
+provider=openai       model=gpt-5.6-luna
+```
+
+The runner will require both `--provider` and `--model` for a real-model run. It will pass them to Pi as separate arguments and then query Pi's RPC state. The selected provider and model id must match the request. The selected API must match that exact pair. The runner will never accept Pi's model fallback.
+
+Any built-in Pi provider can be used when its normal authentication is ready and its selected model can call tools. The runner will not write a `models.json` file or register a custom provider.
+
+## Base Pi and resource isolation
+
+The runner will invoke the `@earendil-works/pi-coding-agent` package entry point directly. It will not invoke the `pi` command found in `PATH`, because that command can be a wrapper that adds personal packages or restart behavior.
+
+The default entry point will come from the repository's pinned Pi dependency. An optional `--pi-entry` argument will allow a pre-release check against another installed base Pi version.
+
+Each run will use:
+
+- one temporary home directory;
+- one temporary project;
+- one temporary session directory;
+- one temporary package installation;
+- either a temporary Pi agent directory or a dedicated user-supplied test profile.
+
+Pi will start with `--no-skills`, `--no-themes`, `--no-prompt-templates`, `--no-context-files`, and `--no-builtin-tools`. The runner must not use `--no-extensions`, because that would also disable Pi Workflows.
+
+After startup, the runner will call RPC `get_commands`. The `workflow`, `controller`, and `piw` commands must come from the packed Pi Workflows package. Any other user or project extension is a failure. Base Pi's own inline commands are allowed.
+
+## Installed package test
+
+The test must use the npm package that would be published, including its file allowlist and production dependencies.
+
+The runner will:
+
+1. Run `npm pack` into the temporary root.
+2. Install that archive into a temporary consumer project with `npm install --omit=dev`.
+3. Find the resulting `@osolmaz/pi-workflows` package directory.
+4. Run base Pi's `install` command against that installed directory.
+5. Start Pi and verify the extension command source paths point into that directory.
+
+Passing the `.tgz` file directly to `pi install` is not valid. Pi treats that file as an extension path. Pointing Pi at an extracted package before its dependencies are installed also fails because `better-sqlite3` is absent. The temporary consumer installation avoids both errors and tests the same dependency layout as a normal npm install.
+
+## Authentication
+
+The runner will let base Pi resolve credentials through Pi's documented authentication rules. It will not read, print, copy, or rewrite credential values.
+
+### Subscription profile
+
+A subscription run will use a dedicated Pi test profile supplied with `--profile`. The operator logs in to that profile once with base Pi. For ChatGPT Plus or Pro, the requested provider is `openai-codex`.
+
+The profile must be dedicated to this smoke test. The runtime resource check will reject unrelated extensions. The run uses a temporary home and temporary workflow state. Its session directory is also temporary even when the profile is reused for OAuth credentials.
+
+### API key
+
+An API-key run can use an ephemeral agent directory. Pi receives the caller's existing environment and resolves the provider's normal variable, such as `OPENAI_API_KEY` for the `openai` provider. The runner will not name, inspect, or log the variable value.
+
+Before a model call, the runner will execute Pi's documented `auth check` command for the exact provider and model. It will stop before the workflow starts when authentication or model resolution fails.
+
+## Runtime workflow
+
+The first workflow does not call a model. It has one delayed compute step and a fixed final output.
+
+The runner will start it through Pi RPC and check the following sequence:
+
+1. The package-owned host starts on demand.
+2. RPC emits `setWidget` and `setStatus` for the `pi-workflows` key with `running` state.
+3. `/workflow pause` is accepted.
+4. The widget and status change to `paused`.
+5. Host status reports one parked run and no active workflow worker.
+6. `/workflow resume` is accepted.
+7. The widget and status return to `running`.
+8. The workflow completes with the fixed output.
+9. RPC clears the widget and status after completion.
+10. No `extension_error` event appears.
+
+This run proves package loading and client-to-host startup. It also proves supervised worker control and the RPC widget contract. The complete check uses no model usage.
+
+## Real-model workflow
+
+The second workflow has one structured agent step. Its prompt asks the selected model to submit one fixed object through the `workflow` tool. Built-in tools stay disabled, so the model sees the workflow tool without file or shell mutation tools.
+
+The runner will check:
+
+- Pi still reports the requested provider and model id, while its API matches that exact pair;
+- one durable workflow step message exists in the origin session;
+- the message has one request id and one current attempt id;
+- one submission is accepted for that attempt;
+- stale or duplicate session delivery does not appear;
+- the workflow completes with the fixed output;
+- the Pi turn settles and no extension error appears.
+
+The result will not claim one upstream API request. Pi or the provider can retry a request. The test proves one accepted workflow submission and one origin-session delivery.
+
+## Headless piw check
+
+The current Rust `piw` command requires a terminal. Add one production command-line option:
+
+```bash
+piw RUN_ID --once
+```
+
+`--once` will connect through the normal Rust client and wait for one complete run view. It will render one frame with the existing `piw` renderer and a Ratatui test backend. It will then print the plain frame and exit. A missing run, connection failure, protocol error, or snapshot timeout will return a nonzero exit code.
+
+The E2E runner will install the candidate Rust binary into the temporary root with `cargo install --path tui --root ... --locked`. It will call `piw RUN_ID --once` while the runtime workflow is active and after completion. The output must contain the exact run id, workflow name, step name, and current status.
+
+This option also gives operators a normal noninteractive way to capture one viewer frame. It is not a test-only protocol.
+
+## Runner interface
+
+Add one command:
+
+```bash
+npm run test:e2e:live -- [options]
+```
+
+Supported forms:
+
+```bash
+npm run test:e2e:live -- --runtime-only
+
+npm run test:e2e:live -- \
+  --profile ~/.config/pi-workflows-e2e/openai-codex \
+  --provider openai-codex \
+  --model gpt-5.6-luna
+
+npm run test:e2e:live -- \
+  --provider openai \
+  --model gpt-5.6-luna
+
+npm run test:e2e:live -- \
+  --profile /path/to/dedicated-profile \
+  --provider anthropic \
+  --model exact-model-id
+```
+
+A real-model run requires explicit provider and model arguments. `--runtime-only` makes no model call. The runner will not choose a default provider, infer a provider from a model name, or change the model after startup.
+
+## Cleanup and failure evidence
+
+The standalone runner will own one temporary root and remove it in a `finally` path. It will:
+
+- close the Pi RPC process;
+- stop the workflow host through the installed client;
+- wait for the host endpoint to disappear;
+- stop child workers started for the smoke workflows;
+- remove the npm consumer installation, sessions, workflow state, and fixture project.
+
+A normal failure will print a small diagnostic summary before cleanup. The summary will identify the failed phase and the software versions. It will also show the exact provider, model name, run id, host status, recent RPC event types, and bounded `piw` output. It will not print credentials, arbitrary environment values, or unrelated session content.
+
+An explicit `--keep` option can preserve the one temporary root for manual debugging. Without that option, failures must not leave stale test directories.
+
+## Automated tests
+
+Add tests for:
+
+- `piw --once` argument handling and one-frame rendering;
+- timeout, missing-run, and host connection failures;
+- packed npm installation with production dependencies;
+- extension source isolation in base Pi;
+- RPC widget and status transitions;
+- pause with no active worker;
+- resume and completion;
+- exact provider and model validation;
+- model fallback rejection;
+- cleanup after success and injected failure;
+- bounded and secret-free diagnostics.
+
+The existing mock-provider E2E suite remains the deterministic origin-session and model-tool gate. CI will run the new installed-package runner in `--runtime-only` mode. Real-provider runs stay manual because provider availability, subscription usage, API cost, and model behavior are external facts.
+
+## Release use
+
+Before a release:
+
+1. Run all repository checks.
+2. Run the installed-package test in `--runtime-only` mode.
+3. Run one real-model check with an explicit provider and model.
+4. Record the exact Pi version, package version, Rust version, provider, model id, API, and run result.
+5. Do not release after fallback, ambiguous delivery, duplicate session delivery, extension error, cleanup failure, or disagreement between Pi, the host, and `piw`.
+
+The GitHub publish jobs will continue to use deterministic checks. They must not receive a personal subscription credential or a broad API key.
+
+## Files
+
+Implementation will update:
+
+- `scripts/live-e2e.mjs`;
+- `test/fixtures/live-e2e/runtime.workflow.ts`;
+- `test/fixtures/live-e2e/model.workflow.ts`;
+- `package.json`;
+- `tui/src/main.rs`;
+- `tui/src/ui/mod.rs`;
+- Rust and TypeScript E2E tests;
+- `docs/workflows.md` and `docs/tui-viewer.md`.
+
+## Contract impact
+
+The runner creates only temporary Pi sessions and workflow state. A reusable subscription test profile is operator-owned and contains its own normal Pi authentication. The script does not change Pi session schemas, Pi internals, private APIs, or another repository.
+
+The implementation uses documented Pi package installation and CLI model selection. It uses `auth check`, RPC state, RPC command discovery, and RPC extension UI events. Workflow state remains behind the existing Pi Workflows client protocol. The only new public interface is `piw RUN_ID --once`.
+
+## Completion criteria
+
+The work is complete when a clean base Pi process loads only the packed Pi Workflows package. The deterministic runtime workflow must pass every widget and lifecycle check, while `piw --once` must agree with Pi and the host. An explicitly selected built-in model must complete the structured agent workflow. Cleanup must leave no process or large temporary directory, and all repository checks must pass.

package/docs/SQLITE_STATE.md

@@ -6,13 +6,13 @@ Pi Workflows stores all live durable state in one database:
 ~/.pi/agent/workflows/state.sqlite
 ```
 
-There is one database for the user installation. Project and run IDs separate data inside it. Workflow targets do not read or write this database.
+There is one database for the user installation. Project and run IDs separate data inside it. The host is the only production process that opens this live database. Workflow targets, extensions, CLI clients, Herdr adapters, and `piw` do not open it. Live clients use `pi-workflows.client.v1`.
 
 ## Viewer projection
 
-The database includes the [incremental and virtualized viewer design](plans/2026-08-28-piw-incremental-viewer-plan.md).
+The database includes the [incremental and virtualized viewer design](plans/2026-08-28-piw-incremental-viewer-plan.md). The host owns this projection and exposes it as the canonical live run view. Local and remote renderers do not recreate it or validate its SQLite tables.
 
-`viewer_runs` stores one presentation revision and retained revision floor for each run. `viewer_deltas` stores ordered target patches by run, presentation revision, and delta index. `viewer_session_checkpoints` stores the bounded active message and tool state at each 256-event boundary. A viewer-visible transaction writes the domain change, advances the presentation revision, and writes its patch blobs before the same commit. Session-event transactions write each reached replay checkpoint in that transaction.
+`viewer_runs` stores one presentation revision and retained revision floor for each run. `viewer_deltas` stores ordered target patches by run, presentation revision, and delta index. `viewer_session_checkpoints` stores the bounded active message and tool state at each 256-event boundary. `run_view_content` stores generated reference bytes under the exact run ID, content digest, and media type. It is separate from general state blobs, and content reads require all three identities. A viewer-visible transaction writes the domain change, advances the presentation revision, and writes its patch blobs before the same commit. Session-event transactions write each reached replay checkpoint in that transaction.
 
 The store retains 256 presentation revisions. A reader with an older cursor must take a bounded snapshot. Patches use `add`, `replace`, `remove`, and `append`. They target small projection documents or pages. Patch creation does not reconstruct and compare complete run views.
 
@@ -60,9 +60,9 @@ The database also uses:
 - directory mode `0700`
 - database and backup mode `0600`
 
-Read-only tools open the same file with SQLite read-only mode and `PRAGMA query_only = ON`.
+The host opens the active database. It verifies the application ID, user version, schema metadata, compiled DDL digest, and exact SQLite schema shape. An incompatible database fails with the standard backup-and-reset instruction. Pi Workflows does not import, reinterpret, or delete that state.
 
-Opening code verifies the application ID, user version, schema metadata, compiled DDL digest, and exact SQLite schema shape. An incompatible database fails with an instruction to clear the incompatible alpha state. Pi Workflows does not import, reinterpret, or delete that state.
+The host completes this verification before it serves any client, and no other production process opens the active database. A maintenance verifier may open an explicit inactive backup with SQLite read-only mode and `PRAGMA query_only = ON`. That offline verification path is not a live client and cannot select the active state database. TypeScript and Rust clients validate the client protocol and package versions, not the SQLite DDL digest.
 
 The normalized run layout is an in-place alpha cutover. It keeps SQLite user version `1` and the current `v1` public record identifiers. A database with the former nested run-snapshot layout is incompatible and must be moved or removed. There is no migration, compatibility reader, dual write, alias, or second schema generation.
 
@@ -111,7 +111,7 @@ The shared records do not replace domain schemas. The following `STRICT` tables
 | Area                | Tables                                                                                                                       |
 | ------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
 | Schema and projects | `schema_meta`, `projects`                                                                                                    |
-| Content             | `blobs`                                                                                                                      |
+| Content             | `blobs`, `run_view_content`                                                                                                  |
 | Shared lifecycle    | `resources`, `leases`, `events`, `workflow_host_state`                                                                       |
 | Host protocol       | `host_commands`, `run_workers`, `worker_messages`, `interactive_requests`, `interactive_submissions`                         |
 | Workflows           | `workflow_definitions`, `runs`, `run_sources`, `run_steps`, `run_bindings`, `run_queue`, `node_attempts`, `workflow_updates` |
@@ -146,7 +146,7 @@ without inserting another visible message.
 
 ## Content-addressed values
 
-`blobs` stores canonical JSON and UTF-8 text as bytes. Its primary key is the 32-byte SHA-256 digest of the bytes.
+`blobs` stores canonical JSON and UTF-8 text as bytes. Its primary key is the 32-byte SHA-256 digest of the bytes. `run_view_content` keeps host-generated large view values reachable for the life of the run, including aggregate outputs that do not exist as one source record. The host creates this link before it sends a content reference. Deleting the run removes the link, and normal blob pruning can then remove unreferenced content.
 
 Insertion verifies the digest, media type, byte length, and exact bytes. Repeated content adopts the existing row. This replaces separate artifact files while keeping outputs, errors, settled Pi entries, and rendered channel text deduplicated. Opening the database never deletes blobs. The explicit prune command removes unreferenced blobs after it deletes safe old run trees.
 
@@ -199,7 +199,7 @@ Reading or finding a row never gives write authority.
 - Control commands have narrow explicit operations, such as requesting cancellation or deletion.
 - Model-originated workflow answers cannot resolve protected human decisions.
 
-The global host is the normal state writer. Its protected stores check ownership and renew the exact live claim in the same transaction as the write. A stale or expired owner cannot renew itself. Pi extensions and mutating CLI commands use the local host protocol. Shared scans, status commands, lists, viewers, and the Rust `piw` program are read-only.
+The global host is the sole live database owner and the normal state writer. Its protected stores check ownership and renew the exact live claim in the same transaction as the write. A stale or expired owner cannot renew itself. Pi extensions, CLI commands, Herdr adapters, and the Rust `piw` program use the versioned client protocol for live reads and controls. They do not open the active database. Only explicit inactive backup verification remains a direct read-only SQLite operation.
 
 ## Competing outcomes
 
@@ -215,7 +215,7 @@ The same rule applies to run terminal outcomes, continuation admission, queue se
 
 ## Read contract
 
-Status is a pure projection of domain rows, immutable facts, current leases, and effect results.
+Durable status is a pure projection of domain rows, immutable facts, current leases, and effect results. The host combines that projection with validated ephemeral origin-session activity to produce one live run view. Ephemeral activity can change display status only. It cannot change durable workflow state or authority. Every renderer consumes the host-produced display status and allowed controls without running another status reducer.
 
 A settings scope uses its resource revision as its public change number. Each accepted patch, current value, and node binding is saved in one transaction. A checkpoint continuation keeps the same settings resources and transfers them to the continuation run.
 
@@ -233,7 +233,7 @@ Read paths do not repair state. Owner reconcilers apply pending effects and writ
 
 All projects use the same file. `projects` stores a stable ID and canonical path. Project-scoped controller and run queries use that key. One global host owns the file for the user installation. Its socket, lock, and exact child-process registry are under `~/.pi/agent/workflows/host/`. A second live host is rejected even when it was started from another project.
 
-SQLite WAL permits concurrent readers while one writer commits. Writers are serialized by SQLite and must keep transactions short. Hashing, model calls, shell work, and external requests happen outside write transactions.
+SQLite WAL keeps bounded projection reads consistent with commits. Writers are serialized by SQLite and must keep transactions short. Hashing, model calls, shell work, and external requests happen outside write transactions. Production clients receive revisioned snapshots, patches, and pages from the host instead of opening concurrent SQLite readers.
 
 This contract is for local storage on one machine. It does not claim distributed consensus or network-filesystem safety.
 
@@ -260,6 +260,8 @@ pi-workflows state prune --before 2026-08-01T00:00:00Z --dry-run
 pi-workflows state prune --before 2026-08-01T00:00:00Z --backup /absolute/path/to/before-prune.sqlite --apply
 ```
 
+These commands send maintenance operations to the host when they target the active database. Only `pi-workflows state verify` with an explicit inactive backup opens SQLite in the command process. It rejects the active database, including another path to the same file.
+
 `status` reports only safe counts, file size, active leases, and unsettled effects.
 It does not print actor IDs, channel references, payloads, or credentials.
 
@@ -267,6 +269,6 @@ It does not print actor IDs, channel references, payloads, or credentials.
 
 ## Alpha cutover
 
-This is a hard cut. Pi Workflows has no normal reader or writer for older live storage. It does not use dual reads, dual writes, aliases, versioned state roots, or automatic import.
+The persisted-state alpha boundary is a hard cut. Pi Workflows has no normal reader or writer for older live storage. It does not use dual reads, dual writes, aliases, versioned state roots, or automatic import. No direct live-state client, replay server reader, or Rust SQLite fallback remains outside the host.
 
 Older state remains untouched. Pi Workflows fails before mutation with this instruction: “Pi Workflows durable state is incompatible. Back up and move state.sqlite with its -wal and -shm files, then start Pi Workflows to create a new state.sqlite database. The incompatible state was not changed.”

package/docs/WORKFLOW_HOST.md

@@ -1,6 +1,6 @@
 # Workflow host
 
-Status: implemented. [Run workflows outside Pi](2026-08-30-out-of-process-workflow-host-plan.md) records the approved implementation plan.
+Status: implemented. The out-of-process host, unified live workflow client, session delivery, widget, Herdr controls, and client-only `piw` viewer are one production path. [Run workflows outside Pi](2026-08-30-out-of-process-workflow-host-plan.md), [restore workflow session delivery and controls](2026-09-01-restore-session-delivery-controls-plan.md), and [unify live workflow clients](2026-09-01-unified-workflow-client-plan.md) record the approved redesigns.
 
 ## Purpose
 
@@ -22,6 +22,8 @@ The host solves two different failures:
 - **Durable boundary:** A committed node or lifecycle transition from which execution can resume.
 - **Interactive request:** A durable agent or assistant-message step that must run in the origin Pi session.
 - **Managed effect:** A side effect reserved and settled through an idempotent durable record.
+- **Live run view:** The host's versioned, bounded projection of one run, including its durable state, current origin-session activity, allowed controls, and page cursors.
+- **Renderer:** A Pi widget, status line, command-line view, Herdr adapter, or `piw` screen that displays or acts on a live run view without deriving workflow state.
 
 ## Boundaries
 
@@ -37,17 +39,20 @@ One host owns the global workflow database for one user installation.
 
 ```text
 Pi extension ─┐
-Pi extension ─┼── local socket ── workflow host ── SQLite
-CLI client ───┘                         │
-                                        ├── run worker A
-                                        ├── run worker B ── headless pi --mode rpc
-                                        ├── controller worker
-                                        └── source resolver
+CLI client ───┼── WorkflowClient v1 ── local socket ── workflow host ── SQLite
+piw ──────────┘                                              │
+                                                             ├── run worker A
+Remote piw ── SSH tunnel ── loopback WebSocket relay ────────┤
+                                                             ├── run worker B ── headless pi --mode rpc
+                                                             ├── controller worker
+                                                             └── source resolver
 ```
 
+The local socket and loopback WebSocket relay carry the same logical client protocol and live run view. The relay reads no state and translates no domain contract. The host is the only production process that opens the live SQLite database. The worker and source-resolver channels are private supervision protocols, not alternate client interfaces.
+
 The host may manage runs from more than one project. Each run keeps its canonical project path and source identity.
 
-The host process performs only bounded protocol handling, short SQLite transactions, timers, queue scheduling, and process supervision. It does not import or execute workflow definitions.
+The host process performs only bounded protocol handling, live-view projection, short SQLite transactions, timers, queue scheduling, and process supervision. It does not import or execute workflow definitions.
 
 A worker loads one workflow source and executes one run generation. It cannot receive a writable `WorkflowRunStore`. It proposes changes to the host over a private child channel. This is an architectural guard against accidental writes. It is not a security sandbox against code running as the same operating-system user.
 
@@ -185,17 +190,20 @@ The child protocol must apply backpressure. A child that exceeds message or outp
 
 The process registry includes a process start identity, not only a PID. The host accepts a worker registration only when the PID is a direct child of that active worker. A reused PID cannot let a new host kill an unrelated process.
 
-## Local client protocol
+## Live client protocol
+
+Every production client uses one versioned `WorkflowClient` protocol. No extension, CLI command, Herdr adapter, or `piw` mode opens the live SQLite database. Clients connect through a user-only local socket. Unix socket mode is `0600`. Other platforms use their equivalent local transport and access control. Remote viewing uses a loopback-only WebSocket relay through an SSH tunnel. The relay carries the same messages and does not read SQLite.
 
-Clients connect through a user-only local socket. Unix socket mode is `0600`. Other platforms use their equivalent local transport and access control.
+The alpha hard cut replaces the existing host request and replay protocols in place with `pi-workflows.client.v1`. It adds no `v2`, compatibility path, fallback reader, or second live protocol. One neutral JSON schema is the wire-contract source for TypeScript and Rust. Shared conformance fixtures must pass in both languages.
 
-Messages use newline-delimited canonical JSON. One message is at most 1 MiB, matching the existing durable event limit. The receiver closes only the offending connection when framing or validation fails.
+Messages use newline-delimited canonical JSON on the local socket and one canonical JSON object per WebSocket message. TypeScript and Rust use the same ECMAScript number formatting and UTF-16 object-key order for canonical JSON. Both parsers reject unknown envelope fields and non-canonical framing. One message is at most 1 MiB, matching the existing durable event limit. The receiver closes only the offending connection when framing or validation fails.
 
-Every request uses this envelope:
+Each message uses one envelope:
 
 ```json
 {
-  "schema": "pi-workflows.host-request.v1",
+  "schema": "pi-workflows.client.v1",
+  "type": "request",
   "requestId": "opaque-id",
   "clientId": "opaque-id",
   "operation": "run.cancel",
@@ -206,55 +214,56 @@ Every request uses this envelope:
 }
 ```
 
-A response uses:
+The `type` is `hello`, `request`, `response`, or `event`. A response repeats the request ID and includes its outcome, revision, receipt, or bounded safe error. An event names its subscription and carries one revisioned run-list snapshot, run-view snapshot, patch, page, origin-session delivery change, or availability change. Valid command outcomes remain `accepted`, `adopted`, `rejected`, `conflict`, `notFound`, `claimLost`, and `unavailable`.
 
-```json
-{
-  "schema": "pi-workflows.host-response.v1",
-  "requestId": "opaque-id",
-  "outcome": "accepted",
-  "revision": 13,
-  "receipt": {}
-}
-```
+The host commits a command receipt before it acknowledges success. The request ID identifies one transport attempt and is excluded from the durable fingerprint. The Pi extension sends state-changing commands through the durable client path. If a connection closes after commit but before response, a retry uses a new request ID with the same client ID, idempotency key, operation, and payload, then adopts the stored receipt. Reusing a request ID or idempotency key with another durable payload returns a conflict. An `interaction.submit` response stays pending while the supervised child validates the value and settles only after the durable outcome is `accepted`, `adopted`, or `rejected`. A reconnect with the same durable identity and payload waits for and returns that same outcome. Clients do not poll SQLite for submission results.
 
-Valid outcomes are:
+View and subscription reads do not create receipts. Reconnection restores desired subscriptions from the last accepted presentation revision. A retained revision receives patches. A stale revision receives a bounded snapshot. A slow subscriber gets at most one socket-buffered snapshot at a time because the host waits for drain and coalesces later polls. A backpressured client write stops waiting when its connection closes, its socket fails, or its request is cancelled. Every explicit client unsubscribe removes the matching host subscription, including run-list and origin-session subscriptions.
 
-- `accepted`
-- `adopted`
-- `rejected`
-- `conflict`
-- `notFound`
-- `claimLost`
-- `unavailable`
-
-The host commits a command receipt before it acknowledges success. Repeating the same request ID and payload returns the stored receipt. Reusing an ID with another payload returns a conflict.
-
-The first command set is:
-
-- `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`
-
-Read operations may use the existing read-only store directly in viewers. Mutating Pi and CLI paths use the host.
+The protocol owns four operation groups:
+
+- run and controller commands, including start, pause, resume, cancel, answers, updates, submissions, reconciliation, and host control;
+- live views, including lightweight run lists, one run snapshot, revision subscriptions, byte-bounded pages, chunked referenced content, and one consistent origin-session response with its active run view, ordered pending delivery records, and read-only delivery availability;
+- origin-session activity reports for the exact workflow delivery being processed by Pi;
+- state maintenance, including status, verification, backup, and prune against the active database. Backup and applied prune use one fresh CLI idempotency key per user invocation. An automatic reconnect retry keeps that key and uses a new request ID. A later invocation gets a new key. The host finishes an in-flight operation after a disconnect, stores its accepted or rejected receipt before response, waits for it during shutdown, and adopts an exact retry.
+
+`notification.claim` and `turn.claim` can create a claim or revalidate the exact retained claim before delivery. Revalidation checks the in-memory client claim and its durable lease without creating another claim.
+
+### Live run view
+
+The host returns one canonical `pi-workflows.run-view.v1` document. It contains the existing bounded workflow projection and page cursors plus a `display` object. The queue field contains display metadata only. It does not repeat the input, launch options, worker affinity, or claim capability; the complete input remains reachable through the state projection. The `display` object contains the effective status, current activity kind, allowed controls, and the stored reason when action is required. A reason above the shared 16 KiB inline-content threshold uses a small `reason` notice and a digest-bound `reasonContent` reference, so one diagnostic cannot exceed the 1 MiB protocol frame while the complete reason remains available. Renderers use this object directly. They must not combine separate queries or infer status from durable rows.
+
+Generated referenced content is stored directly in `run_view_content` under its exact run ID, content digest, and media type. It does not share general state-blob media metadata. A content read must match all three values, so a reference from another run or another media representation is unavailable.
+
+The origin-session response contains this active run view or no active run plus an ordered byte-bounded window of pending delivery records, their complete count, and read-only notification and turn availability for that session. It does not retain an older terminal run after the session reservation ends. The records include the request, delivery, contract, revision, presentation entry, and claim facts required by the shared delivery coordinator. The host returns them from one consistent read. The extension materializes the complete active run revision and hydrates the definition and delivery contracts before it updates the widget or delivery coordinator. It issues a claim command only when the matching availability fact is true. Polling an idle session creates no durable command.
+
+Each history page has both an item limit and an encoded byte budget. Oversized values become digest-bound content references. Large workflow topology uses bounded node, edge, graph-step, and transition projections plus references for the complete original definition and complete graph history. Before the host advertises a generated reference, it stores the bytes under the exact run ID, content digest, and media type in `run_view_content`. It does not share media metadata with general state blobs. Memory-cache eviction cannot make a reference unavailable. `view.content` returns bounded chunks until the client has the complete value. The client verifies the assembled bytes against both the response digest and the digest in the advertised reference. TypeScript clients assemble every run-history page for one revision and hydrate the complete definition, complete graph history, and all referenced content before they emit a complete non-interactive view or update the Pi widget. Rust automatically requests and verifies the complete referenced definition and graph history, decodes the complete values, and then builds its graph layout. Session-event pages include the replay checkpoint immediately before the first event in the page. A large checkpoint is also a referenced value. TypeScript hydrates it with the run view, and Rust requests and resolves it before replay. A step-centered trace page selects the exact stored attempt first and uses the node ID only if that attempt has no trace event. The run list reads only status facts and never loads complete run histories.
+
+The closed `display.status` set is `queued`, `running`, `waiting`, `paused`, `completed`, `failed`, `timed_out`, `cancelled`, and `ambiguous`.
+
+The host computes effective status in this order:
+
+1. A durable ambiguous external effect that requires explicit review is `ambiguous`. An effect that is still applying under a live worker is not ambiguous.
+2. Another durable terminal result keeps its terminal label.
+3. A durable pause is `paused`.
+4. A live supervised worker or an exact active origin-session workflow turn is `running`.
+5. A pending interaction, decision, or presentation with no exact active turn is `waiting`.
+6. Parked resumable work with no pending interaction is `queued`.
+7. Admitted work that has not started is `queued`.
+
+Host connection failure is the client condition `unavailable`, not a `display.status` value. `paused` is never inferred from a parked queue, pending interaction, stale cursor, or missing activity report.
+
+### Origin-session activity
+
+The Pi extension reports `started`, `settled`, and lease refreshes only for the exact workflow delivery that it can identify through documented Pi lifecycle events and its in-memory delivery map. The host requires the deterministic `interaction:<request-id>` delivery identity and keys activity by connection and request, not by an unchecked caller label. The first activity report on each client connection is `started`; only later reports on that connection are refreshes. Each report includes the origin session, run, request, delivery, client connection, and increasing activity sequence. The host validates these facts against the durable pending interactive request and its recorded delivery or presentation entry. Settlement of the presentation claim does not end activity while the model turn continues.
+
+Activity is ephemeral display state. It cannot grant workflow authority, settle a request, change a durable run state, or survive as a claim. A repeated report is idempotent. A stale sequence, replaced delivery, or wrong session is rejected. One shared client constants module defines the refresh period and lease duration. The refresh period is shorter than the lease duration, and the lease duration bounds stale `running` display after client loss. The host clears activity on the matching settled event, client disconnect, or lease expiry. Missing activity falls back to the durable `waiting` view and never creates a false `paused` or `running` state.
+
+### Renderers and controls
+
+The Pi widget, Pi status line, `/piw`, `Ctrl+Shift+R`, Herdr placement adapter, CLI status output, and every local or remote `piw` screen consume the same live run view. The Pi extension subscribes by origin session and materializes the complete step history before it renders the widget. The Herdr adapter receives the exact run target from that view and owns only pane placement and focus. The TypeScript CLI and Rust TUI subscribe by run ID and use protocol pages and referenced content. Explicit `piw <runId>` mode keeps the requested run selected and does not replace it with the newest run-list item. They do not open live SQLite or compile or validate its DDL digest.
+
+Local `piw` may start the host only by executing the installed `pi-workflows host start` command. It does not reimplement host lifecycle. A foreground TypeScript client keeps its cold-start retry timer referenced until the host is ready or the start deadline expires. It uses the package socket on Unix and the same package-derived named pipe as TypeScript on Windows. `piw serve` becomes a loopback WebSocket relay for the same client protocol. It opens one host socket connection for each WebSocket connection and couples their lifecycles one to one. It never multiplexes clients, translates state, or opens the database. A client that cannot start or reach the matching host fails with one clear unavailable or package-version error. It must not fall back to direct SQLite access.
 
 ## Worker protocol
 
@@ -296,7 +305,7 @@ Add only these records if implementation proves the current rows cannot hold the
 
 ### Host commands
 
-`host_commands` stores request ID, client ID, operation, idempotency key, request fingerprint, run ID, accepted revision, outcome, receipt or error hash, and timestamps. The unique request fingerprint prevents one request ID from naming two commands.
+`host_commands` stores request ID, client ID, operation, idempotency key, durable request fingerprint, run ID, accepted revision, outcome, receipt or error hash, and timestamps. The request ID is transport identity and is not part of the fingerprint. The request primary key prevents one request ID from naming two payloads. The client and idempotency-key uniqueness adopts the same durable payload across transport attempts.
 
 ### Interactive requests
 
@@ -316,9 +325,11 @@ Agent and assistant-message steps for an interactive run execute in the origin P
 
 The worker commits the node's resolved wall-clock deadline before it proposes `interaction.requested`. The host commits the request, changes the node attempt to waiting, parks the queue row, releases the claim, and acknowledges the worker. The worker then exits. The host continues to enforce the durable deadline while no worker exists. If the deadline passes, one control claim atomically closes the stale request and schedules a supervised timeout-resume child. The child preserves the same attempt and deadline, records `timed_out`, and follows any `$result.outcome` edge. A run with no timeout recovery edge becomes terminal and releases its session reservation. Restart recovery starts this timeout path before it schedules other work.
 
-The extension finds pending requests during `session_start`, after `agent_settled`, and once per second while the session is open. One shared session-delivery coordinator handles step prompts, protected decisions, notifications, and terminal presentation turns. It waits until Pi is idle and has no pending messages before it claims new work. Because the host claim is asynchronous, it checks those conditions again immediately before the synchronous call to the documented `pi.sendMessage()` API. An unused claim expires and is never sent later. After a claim, the coordinator records the delivery ID in memory before it sends. Polling only checks for delivery evidence while that ID remains queued; it cannot send the message again.
+The extension finds pending requests during `session_start`, after `agent_settled`, and once per second while the session is open. One shared session-delivery coordinator handles step prompts, protected decisions, notifications, and terminal presentation turns. It waits until Pi is idle and has no pending messages before it claims new work. Because the host claim is asynchronous, it checks those conditions again immediately before the synchronous call to the documented `pi.sendMessage()` API. The coordinator remembers the claimed delivery before that final check. If Pi became busy, a later poll can send with that exact claim while its lease remains live. An expired unused claim is discarded. Polling cannot acquire a second claim or send a delivery that is already queued.
+
+The host grants one live presentation claim. The current presenter cannot claim the same request again before that claim expires. A poll that sees any live presentation claim treats it as unavailable, not as a tool failure. When the matching custom message appears in the active Pi branch, the coordinator records its public session entry ID through the host and clears the local queued state. If Pi becomes idle without exposing a matching entry after the confirmation interval, the coordinator reports the delivery as ambiguous and keeps it blocked. A failed durable receipt also keeps the visible message blocked. Neither case can send the message again. The normal `workflow` tool contract then submits updates and results.
 
-The host grants one live presentation claim. The current presenter cannot claim the same request again before that claim expires. When the matching custom message appears in the active Pi branch, the coordinator records its public session entry ID through the host and clears the local queued state. If Pi becomes idle without exposing a matching entry after the confirmation interval, the coordinator reports the delivery as ambiguous and keeps it blocked. It does not infer success or retry. The normal `workflow` tool contract then submits updates and results.
+The extension subscribes to the active origin-session live run view and projects it into Pi's documented widget and status APIs. It never opens SQLite, runs workflow code, or derives a display status. `Shift+Up` and `Shift+Down` scroll the widget. When Herdr is available, the widget also shows `Ctrl+Shift+R piw`, and `/piw` remains the command fallback. Both actions open or focus the exact run from the same view.
 
 A tool update or submission goes to the host. It includes the exact request, node, attempt, expected revision, and tool-call idempotency key. The host first checks this transport contract and records a provisional `validating` submission. It then schedules a supervised workflow child. Only that child loads workflow code and runs the node's `validate` function. The child reports `interaction.accepted` or `interaction.rejected` to the host. The host settles the request only after acceptance. A rejected payload leaves the same request pending and returns the stored actionable error to the model. If the child stops before it reports a result, the host rejects the provisional submission and leaves the request ready for a corrected retry.
 
@@ -340,7 +351,7 @@ The run binding records `interactive` or `headless` execution mode. Viewers show
 
 ## Pause and cancellation
 
-Pause atomically commits `paused = 1`, parks the queue, releases the exact claim, and stores the command receipt. The fenced worker process group then stops. An uncommitted pure node can run again after resume. Resume takes a new generation and starts another worker from the last durable boundary.
+Pause atomically commits `paused = 1`, parks the queue, releases the exact claim, and stores the command receipt. The fenced worker process group then stops. If a Pi model turn ends while the public extension context signal is aborted, or with public stop reason `aborted`, the extension sends this same host pause command only when that `agent_end` event contains the pending interaction's workflow prompt. A parked interaction has no worker or live run claim, so the host marks it paused in place. While paused, updates, submissions, and decision answers are rejected. Resume clears the pause on that same pending interaction; other paused work takes a new generation and starts another worker from the last durable boundary. An uncommitted pure node can run again after resume.
 
 Cancellation against a live worker atomically commits terminal cancellation, cancels pending attempt and interaction state, settles effect recovery state, releases the exact claim, and stores the command receipt. A pending effect becomes cancelled. An applying effect becomes ambiguous because the host cannot prove its external outcome. The host then stops the fenced worker process group. A host crash after the receipt cannot resume the cancelled run or retry the ambiguous effect. If the child does not stop by the deadline, the host kills its process group.
 
@@ -433,7 +444,8 @@ When the installed state has the old digest, fail before mutation with the stand
 - **Session state:** Pi appends normal messages and tool results. Pi Workflows does not edit session files.
 - **Other persistent data:** The workflow SQLite shape changes in place and older alpha state requires reset.
 - **Pi internals:** None.
-- **Public API:** The extension uses documented command registration, tool registration, session lifecycle events, message sending, widgets, status, and session IDs.
+- **Public API:** The extension uses documented command and shortcut registration, tool registration, session lifecycle events, message sending, widgets, status, and session IDs.
+- **Client protocol:** All live clients use `pi-workflows.client.v1`. There is no compatibility transport or direct live-state fallback.
 
 ## Conformance
 
@@ -452,4 +464,9 @@ The implementation conforms when:
 - effects are deduplicated or marked ambiguous;
 - the extension and host run no workflow or controller code in their own event loops;
 - the production package contains no embedded execution fallback;
+- the host is the only production process that opens live SQLite state;
+- the widget, status line, Herdr actions, CLI, and `piw` render the same host-produced status and controls;
+- a busy origin session displays `running` only while its exact workflow turn is active, and `paused` appears only after a durable pause;
+- a TypeScript-created live database is viewable by the matching Rust `piw` through the client protocol without a duplicated SQLite digest;
+- no removed host, replay, or direct SQLite client path remains selectable;
 - real Pi end-to-end tests, repository checks, reviewer checks, and CI pass.

package/docs/WORKFLOW_STEP_MESSAGES.md

@@ -1,6 +1,6 @@
 # Workflow step messages
 
-This specification defines how pi-workflows shows agent-step instructions in an interactive Pi session. The model receives the complete step prompt, while the user sees a small workflow card that can be expanded.
+This specification defines how pi-workflows shows agent-step instructions in an interactive Pi session. The model receives the complete step prompt, while the user sees a small workflow card that can be expanded. [Restore workflow session delivery and controls](2026-09-01-restore-session-delivery-controls-plan.md) records the delivery and session-control repair.
 
 ## Goal
 
@@ -48,11 +48,11 @@ pi.sendMessage(
 
 ## Session delivery
 
-One shared coordinator delivers step prompts, protected decisions, notifications, and final workflow results. It does not claim or send a new message while Pi is busy or another message is pending. It checks these conditions again after the asynchronous host claim and immediately before the synchronous send. If Pi became busy, the unused claim expires and is never sent later. Before it calls `pi.sendMessage()`, the coordinator records the stable delivery ID in a process-local queued map. The one-second poll can then look for the matching session entry, but it cannot send that ID again.
+One shared coordinator delivers step prompts, protected decisions, notifications, and final workflow results. It does not claim or send a new message while Pi is busy or another message is pending. It checks these conditions again after the asynchronous host claim and immediately before the synchronous send. The coordinator remembers the stable delivery ID and exact claim expiry before that final check. If Pi became busy, a later poll can use that same claim while it remains live. Before it sends retained work, it revalidates the exact claim and durable resource through the host, then checks Pi and the lease again. Cancelled, paused, or replaced work is discarded. An expired unused claim is also discarded.
 
-The coordinator clears the queued ID only after it observes the custom message in the active branch and saves the public Pi session entry ID through the workflow host. If Pi becomes idle but does not expose that entry after the confirmation interval, the coordinator reports an ambiguous delivery and keeps it blocked. Reload and restart recovery first search the branch for that stable ID. An existing entry is adopted. A new message is sent only when no entry exists and the host grants a new claim.
+Before the coordinator calls `pi.sendMessage()`, it records the delivery in a process-local queued map. The one-second poll can look for the matching session entry, but it cannot send that ID again. The coordinator clears the queued ID only after it observes the custom message in the active branch and saves the public Pi session entry ID through the workflow host. If Pi does not expose that entry after the confirmation interval, or if saving its receipt fails, the coordinator reports an ambiguous delivery and keeps it blocked.
 
-The host does not grant another live presentation claim to the same extension client. Claim expiry permits recovery by a new claimant; it is not permission for the current process to resend a queued message.
+Reload and restart recovery first search the branch for that stable ID. An existing entry is adopted. A new message is sent only when no entry exists and the host grants a new claim. The host does not grant a second live presentation claim. Polling treats another live claim as unavailable work rather than a workflow error.
 
 ## Engine boundary
 

package/docs/development.md

@@ -159,7 +159,8 @@ workflow stores a long-lived registry token:
 For later versions:
 
 1. Update `version` in `package.json`, `package-lock.json`, `tui/Cargo.toml`,
-   and `tui/Cargo.lock`, then merge that change into the default branch.
+   `tui/Cargo.lock`, and `herdr-plugin.toml`, then merge that change into the
+   default branch.
 2. Publish a GitHub Release whose tag is `v<version>`, such as `v0.2.0`.
 3. Wait for the **Publish npm package** and **Publish crates.io package**
    workflows to finish.