@osolmaz/pi-workflows 0.16.0 → 0.16.2

package/docs/WORKFLOW_STEP_MESSAGES.md

@@ -1,25 +1,67 @@
-# Workflow step messages
+# Workflow messages in Pi
 
-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.
+Status: this is the implemented workflow-message contract. [Unify workflow messages and restore hosted behavior](2026-09-02-unify-workflow-messages-plan.md) records the approved design and implementation plan.
 
 ## Goal
 
-Agent-step prompts contain the task, workflow identity, attempt identity, output form, and completion rules. Submitted steps call the workflow tool. Assistant-message steps reply normally. This information is required by the model, but showing it as a large user message makes the conversation hard to read.
+Pi Workflows must add several kinds of content to an origin Pi conversation. These include interactive step prompts, protected human decisions, passive notifications, terminal results, and follow-up prompts. Initial, reminder, and resumed prompts are one step-message kind with different display reasons.
 
-pi-workflows sends the same prompt as a custom Pi message. A custom renderer shows a compact summary by default and the full content when expanded.
+The host saves all of them as workflow messages. One extension component sends them through documented Pi APIs. Feature records continue to own workflow results, answers, settings, and timeouts.
 
-Both output forms use the existing `agent` node. The completion form changes through `expectedOutput`; no new node type is added.
+The model receives complete instructions when a workflow message starts a turn. The user sees a compact card for structured workflow content and can expand it.
 
-## Message contract
+## Workflow message contract
 
-Interactive agent-step messages use the custom type `pi-workflows-agent-step`.
+A workflow message is content that Pi Workflows requires Pi to add to one conversation. It does not mean every message in that conversation.
 
-The message has this shape:
+The message kinds are:
+
+| Kind           | Pi behavior                                     | Purpose                                          |
+| -------------- | ----------------------------------------------- | ------------------------------------------------ |
+| `step`         | Custom message that starts a model turn         | Initial, reminder, or resumed interactive prompt |
+| `decision`     | Custom message that does not start a model turn | Protected choice for a person                    |
+| `notification` | Custom message that does not start a model turn | Passive workflow notice                          |
+| `terminal`     | Custom message that starts a model turn         | Final result and safe recovery choice            |
+| `followUp`     | Custom message that starts normal work          | Work saved for after successful completion       |
+
+The host stores one `WorkflowMessage` record before Pi can send it:
+
+```ts
+type WorkflowMessage = {
+  schema: "pi-workflows.workflow-message.v1";
+  workflowMessageId: string;
+  runId: string;
+  targetSessionId: string;
+  kind: "step" | "decision" | "notification" | "terminal" | "followUp";
+  sourceId: string;
+  contentDigest: string;
+  order: number;
+  status: "pending" | "sent" | "cancelled";
+  piSessionEntryId: string | null;
+  createdAt: string;
+  updatedAt: string;
+};
+```
+
+The exact Pi content and custom display details remain in the content-addressed value store. `contentDigest` binds the record to those bytes. `sourceId` links the message to the feature record that created it.
+
+`kind` determines the custom renderer, whether a model turn starts, and the host eligibility rule. The host does not store duplicate flags or message-to-message pointers for those facts.
+
+`order` is the acceptance order for one origin session. The host marks one pending item as next in the origin-session view. An earlier ineligible or cancelled item does not block unrelated eligible work.
+
+A source lifecycle transaction can change `pending` to `cancelled`. Active-branch evidence changes `pending` or `cancelled` to `sent`; evidence wins because Pi already contains the entry. `sent` is terminal. A pending message can be new or uncertain after a process stopped, so the coordinator always checks the active branch before sending it.
+
+Workflow message IDs and internal send state are not included in provider-facing prompt content. The hidden custom-message details contain only the stable workflow message ID needed for branch recovery.
+
+## Agent step card
+
+Every step message uses the custom type `pi-workflows-step`:
 
 ```ts
 export type WorkflowAgentStepMessageDetails = {
   schema: "pi-workflows.agent-step-message.v1";
-  kind: "step" | "reminder" | "resume";
+  workflowMessageId: string;
+  reason: "initial" | "reminder" | "resumed";
   contract: AgentStepContract;
   presentation?: {
     runTitle?: string;
@@ -29,124 +71,173 @@ export type WorkflowAgentStepMessageDetails = {
 
 pi.sendMessage(
   {
-    customType: "pi-workflows-agent-step",
+    customType: "pi-workflows-step",
     content: completeModelPrompt,
     display: true,
     details,
   },
-  {
-    triggerTurn: true,
-  },
+  { triggerTurn: true },
 );
 ```
 
-`content` is the complete prompt that the existing executor would send as a user message. It remains available to the model and in session history.
-
-`details` contains structured display data. The renderer reads this object directly and never parses the prompt text. `AgentStepContract` remains the source of every identity field, the completion form, the submitted output description, and any explicit assistant character limit.
-
-`kind` distinguishes the first delivery from a reminder or a resume that must repeat the instructions. An ordinary resume that can continue without another prompt does not create a message.
-
-## 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. 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.
+`content` is the complete provider-facing prompt. It includes the task, workflow identity, attempt identity, output form, and completion rules.
 
-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 renderer reads `details` and does not parse the prompt. It shows a compact summary by default and the complete prompt when expanded. If the renderer is unavailable, Pi still retains the custom message and its content.
 
-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.
+Submitted agent steps call the `workflow` tool. Assistant-message steps reply normally. Both forms keep the existing `agent` node and use `expectedOutput` to select the completion form.
 
 ## Engine boundary
 
-The workflow engine remains independent of Pi. It continues to produce an `AgentStepRequest` with a complete prompt and structured contract.
+The workflow engine remains independent of Pi. It produces an `AgentStepRequest` with a complete prompt and structured contract. One pure formatter builds the same provider-facing prompt for interactive and RPC execution. The extension does not shorten or rebuild it from display fields.
 
-The request carries optional presentation data for the run title and node status detail. The workflow host stores the prompt, contract, presentation data, and delivery kind for the origin Pi extension. The RPC executor handles submitted steps. An assistant-message step parks for the origin Pi session; a detached run with no origin session fails before prompting.
+When a workflow has live settings, the formatter adds the settings scope, change number, bounded current value, allowed model paths, and exact `change-settings` action. It also adds the `queue-follow-up` and `remove-follow-up` actions. Actor identity is not model input. The extension derives it from the documented tool call.
 
-One pure formatter remains responsible for the model prompt used by both executors. Interactive delivery must not shorten, summarize, or rebuild the model prompt from display fields.
-
-Before the step contract, the formatter adds the active settings scope, change number, bounded current value, allowed model paths, and exact `change-settings` action when that scope declares settings. It also shows the `queue-follow-up` and `remove-follow-up` actions. Actor identity is never part of model input. The extension derives it from the documented tool call.
+An assistant-message step parks for its origin Pi session. A detached run without an approved origin session fails before it creates that message.
 
 ## Compact display
 
-The collapsed card shows only useful workflow identity and current work. For example:
+A collapsed step card shows only the workflow identity and current work. For example:
 
 ```text
 ▶ monitor › check
 Checking the monitored target
 ```
 
-A reminder or resumed delivery adds a short label:
+A reminder or resumed prompt adds a short label:
 
 ```text
 ↻ monitor › check · reminder
 Checking the monitored target
 ```
 
-The card uses the run title when it is more useful than the workflow name. It omits missing status detail instead of inventing one. Long fields are clipped or wrapped to the available terminal width.
+The card uses the run title when it is more useful than the workflow name. It omits missing detail and clips or wraps long text to the terminal width.
 
-The expanded card shows:
+The expanded card shows the workflow name, run title, run ID, node ID, attempt ID, step reason, completion form, expected output, optional character limit, and complete model prompt. Expansion uses Pi's standard custom-message state and keys. Pi Workflows does not store another expansion setting.
 
-- workflow name and run title
-- run id
-- node id
-- attempt id
-- delivery kind
-- completion form
-- expected output and optional character limit
-- full model prompt
+Notifications keep the custom type `pi-workflows-notification` and use `triggerTurn: false`. Decisions and terminal results use their approved structured renderers. The message kind fixes each send policy; the coordinator cannot change it at run time.
 
-Expansion uses Pi's existing custom-message expansion state and keys. pi-workflows does not add another toggle or store separate expansion state.
+## One sender
 
-## Reminders and resumes
+The extension has one `WorkflowMessageCoordinator` for all message kinds. The host keeps one active coordinator connection and process-local epoch for each origin session. A replacement connection fences the old one, so two Pi processes cannot send for the same session.
 
-The existing bounded reminder behavior stays in place for submitted steps. A reminder uses the same custom message type and renderer. It keeps the contract and sets `kind: "reminder"`. Assistant-message steps do not nudge or retry after a visible response.
+The coordinator follows this sequence:
 
-A resumed step uses `kind: "resume"` only when the executor must send the instructions again. An interrupted assistant-message step keeps its attempt id. If its matching prompt already has a completed assistant child on the active branch, the executor adopts that exact response instead of displaying it again. Stale attempts and responses from another branch remain invalid.
+1. After every host connection, wait for the complete origin-session view and report the active branch before any send or turn report.
+2. Wait until the host view names the next eligible pending message, Pi is idle, and Pi has no queued user input.
+3. Save the message ID in the coordinator's queued map.
+4. Search the active Pi branch for the same hidden message ID and report a matching entry.
+5. Recheck synchronously that Pi is idle, has no pending input, the message is absent, and this connection still owns the active session epoch.
+6. Call `pi.sendMessage()` with no `await` between that final check and call.
+7. Wait until the new Pi entry is visible.
+8. Report the active branch so the host saves its Pi entry ID and marks the message `sent`.
 
-## Notifications
+The coordinator sends only one workflow message at a time. A poll can find work, but it cannot send an ID already in its queued map.
 
-Workflow notifications keep the separate custom type `pi-workflows-notification`.
+Pi can emit `agent_start` before the host saves the new Pi entry ID. The coordinator keeps that start and any matching end in its in-memory session map. It first marks the workflow message `sent`, then reports the saved turn events in order. It does not drop a turn event while host confirmation is in progress.
 
-Agent-step messages use `triggerTurn: true` because they ask the model to work. Notifications use `triggerTurn: false` because they report state to the user without asking for an assistant response.
+A visible active-branch entry with the hidden ID is `sent`, even if the source lifecycle cancelled the message before the evidence arrived. Active-branch absence is usable only when the branch has no matching ID, Pi is idle, and Pi has no pending messages in the same observation. If Pi or the extension disappears after the send call, the message stays `pending`; reconnect reports the branch before another send. These rules do not prove cross-branch absence or exactly-once model execution.
 
-The two message types use the same delivery coordinator but keep separate send policies. The coordinator never changes whether a message starts a model turn.
+After Pi, the extension, or the host restarts, branch reporting runs before any new send. It re-creates a message of the source's own kind only when the active branch has no entry for that source. A pending interaction gets one `step` with reason `resumed`; a pending decision gets one `decision`. Old incompatible workflow state is not reinterpreted.
 
-## Session and persistence impact
+## Model-turn status
 
-Interactive step deliveries use `sendMessage` instead of `sendUserMessage`. Existing session entries remain readable and are not rewritten.
+`agent_start` has no message payload. The extension binds it through the current origin-session view. Turn binding ignores branch membership; only branch reporting and re-presentation inspect the active branch:
 
-The custom prompt and visible assistant response are normal documented Pi session messages. pi-workflows adds no Pi session schema, private entry type, or separate persistent store. SQLite stores each settled Pi entry once. Small relational links connect the workflow attempt to its prompt, response, first, and last entries. The attempt keeps only the assistant digest receipt. It does not copy the prompt or visible response into another blob.
+- the latest sent step is open while its interaction remains pending and its run is not paused;
+- a terminal or follow-up message is open only until its first turn ends;
+- decisions and notifications never open a turn.
 
-If the renderer is unavailable, Pi still retains the custom message content. pi-workflows does not add a fallback path that sends a duplicate user message.
+A start against a closed message is rejected. Follow-up turns are reported for ordering but do not show the completed workflow as `running`.
 
-## Public API boundary
+The extension creates one workflow turn ID at `agent_start` and keeps it through the matching `agent_end` and host reconnect. It buffers starts and ends until the session view and message receipt are ready.
 
-This design uses the documented `pi.sendMessage()` and `pi.registerMessageRenderer()` APIs. The renderer uses Pi's standard `expanded` state.
+At `agent_end`, it derives `completed`, `aborted`, or `error` from the documented assistant messages. It reads response-entry evidence from `ctx.sessionManager.getBranch()`; the entry ID can be null. The host saves one immutable end result. A repeated report adopts it, and a stale turn ID cannot clear newer activity. A supervised worker can continue after accepted tool output while that Pi turn is still open. This normal continuation leaves the session capture recording until `agent_end`; it does not mark the capture as interrupted.
 
-It does not require a Pi core change or private Pi API.
+The host applies the end and its workflow consequence in one transaction. An aborted turn sets the run pause and cancels the request's pending step messages; the interaction derives its paused state from the run. Resuming that submitted-output step atomically clears the pause, increments the interaction revision, and creates one new step message with reason `resumed`. That message starts a fresh Pi model turn. A protected decision does not start a model turn, so its revision and decision message do not change when its run resumes. A completed, recoverably failed, or proved-lost turn increments `unproductiveTurnEnds` only when the submitted-output step is pending, not paused, and has no accepted or validating submission. Values one and two create one step message with reason `reminder`; a value above two fails the attempt. A partial unique index enforces at most one pending step message for the request, regardless of reason. Acceptance, pause, cancel, timeout, and branch re-presentation cancel all pending step messages. A cancelled message did not start a turn and does not increment the counter.
 
-The workflow package adds `assistantMessage()` as an `expectedOutput` value for the existing `agent` node. It adds no node type, graph action, Pi tool, private API, or message-rendering option.
+There is no activity heartbeat, refresh lease, or sequence counter. The host shows `running` from the matching start until the matching end. Host startup never marks a Pi turn lost. On `session_start`, only an idle-session branch report can close an open sent message with synthetic stop reason `lost`. Polling and time alone cannot create a reminder.
 
-## Validation and tests
+## Feature ownership
+
+The workflow message stores only Pi send facts. Other records remain authoritative:
+
+- interactive requests own step contracts, attempts, deadlines, validation, model submissions, and `unproductiveTurnEnds`;
+- human decisions own choices, verified answers, expiry, and continuation;
+- terminal runs own outcomes, reasons, restart lineage, and results;
+- notification nodes own their node results;
+- follow-up records own prompt source and authority;
+- settings records own current values and accepted changes.
+
+Submitted-output steps can use reminders. Assistant-message steps do not send a reminder after a visible response. An interrupted assistant-message step keeps its attempt ID and adopts a matching completed response from the active branch. A stale attempt or another branch remains invalid.
+
+Each source event creates its workflow message in the same SQLite transaction. The message cannot exist without its source fact, and a source fact cannot require a Pi message without the matching record.
+
+## Restored behavior
+
+The shared contract supports these features without separate send paths:
 
-Tests verify:
+- at most two reminder-reason step messages after model turns end without a valid submission;
+- one resumed-reason step message after a presented paused step resumes;
+- one terminal result and recovery turn for the final outcome of each interactive continuation chain;
+- safe restart with lineage, a limit of three, and repeated-failure protection;
+- ordered follow-up prompts after successful completion, terminal turn end, and release of later workflow reservations;
+- protected decisions in Pi and approved external channels;
+- passive notifications that do not start model turns;
+- terminal result retention while its message is pending or its first turn is open, and then for 60 seconds after that turn ends, in the widget and `piw`;
+- conversation recording linked to workflow attempts.
 
-- interactive and RPC executors give the model the same complete prompt
-- one step message starts one model turn, even when Pi stays busy longer than the poll interval and delivery claim lease
-- collapsed rendering does not show the full prompt
-- expanded rendering shows the full prompt, settings scope and change number, allowed paths, and exact contract ids
-- long and missing display fields render safely
-- reminders and resumed deliveries keep the active attempt id
-- submitted steps still reject stale attempts after timeout or cancellation
-- assistant steps wait for `agent_settled` and capture only visible text
-- empty, failed, aborted, tool-only, and explicitly over-limit responses fail once
-- session replay restores the same custom prompt and adopts an existing response once
-- detached execution parks for the origin session or fails clearly when none exists
-- notifications still enter context without starting a model turn
-- no duplicate prompt or assistant response is sent
+A terminal or follow-up message does not reopen the completed workflow. A slash-looking follow-up remains plain model input because `pi.sendMessage()` does not dispatch extension commands or expand prompt templates. External effects remain idempotent or explicitly ambiguous.
+
+## Session recording
+
+The extension records workflow-related Pi events through a batched host client operation. It uses documented Pi events and does not read or edit Pi session files.
+
+The host deduplicates settled entries by Pi entry ID. It links attempts to their prompt, response, first, and last entries. A recording failure does not fail workflow execution.
+
+## Public API boundary
+
+The extension uses documented `pi.sendMessage()`, `pi.registerMessageRenderer()`, session lifecycle events, agent lifecycle events, widgets, status, commands, shortcuts, and session IDs.
+
+This design does not change Pi core, use private Pi APIs, or change Pi session schemas. It does not add another database or runtime.
+
+## Validation and tests
 
-The end-to-end test inspects the provider-facing prompt as well as the TUI message record. A correct card with missing model instructions is a failure.
+Tests must prove:
+
+- every message kind uses the one coordinator;
+- one workflow message ID creates at most one confirmed Pi entry and one automatic model turn;
+- a later manual turn uses a new workflow turn ID without creating another Pi entry;
+- two Pi processes that open one session cannot both send because one process-local coordinator epoch is active;
+- restart recovery reports the branch and adopts an existing entry before it sends;
+- branch absence is usable only when Pi is idle and has no pending input;
+- a crash after send leaves the message pending and cannot cause a resend before branch reporting;
+- messages remain in saved order without message-pointer deadlocks;
+- an early `agent_start` and `agent_end` wait for the message receipt and session view, then apply in order;
+- every matching model turn shows `running` for its full duration;
+- normal worker continuation leaves the active session capture open until the matching turn ends;
+- stale turn-end reports and starts against closed messages are rejected;
+- a manual turn cancels pending step messages that it supersedes;
+- a turn cannot bind to an interaction whose run is paused;
+- aborted turns pause without incrementing the unproductive-turn counter;
+- resuming an aborted step creates one new resumed message and one fresh model turn;
+- resuming a protected decision keeps its answer revision and does not create a duplicate decision message;
+- host restart does not close a live Pi turn, while an idle-session branch report can close an unended turn as lost;
+- two reminder-reason steps are sent at most once and the next unproductive turn fails;
+- initial, reminder, and resumed prompts use the same step kind and differ only by reason;
+- terminal and follow-up messages each start only at their durable boundary;
+- a branch switch creates one resumed-reason step only when that branch has no entry for the interaction;
+- a missing protected decision creates another decision message, not a step;
+- branch evidence changes a cancelled message to sent;
+- a follow-up-started workflow blocks the next follow-up through its session reservation;
+- notifications and protected decisions do not start model turns;
+- the provider receives the complete step prompt but no workflow message ID or internal send state;
+- collapsed and expanded cards remain safe and complete;
+- session recording adopts each settled Pi entry once.
+
+The real Pi end-to-end test must use a clean Pi home with only the packed pi-workflows extension. It must accept any provider and model supported by base Pi. `openai` and `openai-codex` are separate providers.
 
 ## Security
 
-Workflow prompts and expected-output descriptions may contain untrusted text. The renderer treats them as text, applies terminal-safe wrapping, and does not interpret control sequences or markup from workflow data.
+Workflow prompts and expected-output descriptions can contain untrusted text. Renderers treat them as text, wrap them safely, and do not interpret workflow control sequences or markup.
 
-Collapsed cards avoid showing full prompts in the normal conversation view. Expanded content and session files still contain the complete prompt, so existing session privacy rules continue to apply.
+Collapsed cards hide full prompts from the normal conversation view. Expanded cards and Pi session files still contain the full content, so normal session privacy rules apply. Credentials, internal send state, and internal message IDs do not enter provider-facing content.

package/docs/live-replay-protocol.md

@@ -78,7 +78,9 @@ Only the host computes this status. A parked queue is not a pause. `paused` requ
 
 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.
 
-An origin-session subscription returns `pi-workflows.session-view.v1`, which contains the current active run view, an ordered byte-bounded window of pending interaction records, their complete count, and read-only notification and turn availability in one read. A session with no active reservation returns no run, even when that session has older terminal runs. The Pi extension assembles the active run's complete step history and hydrates its definition and referenced values before it updates the widget or delivery coordinator. It sends a durable claim command only when the matching availability fact is true. After a turn claim, it reads the claimed run by its exact run ID. It does not use the latest run in the session. An idle session does not create empty claim or status commands.
+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.
+
+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.
 
@@ -90,13 +92,15 @@ Large prompt, output, event, settings, follow-up, and update values use a conten
 
 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.
 
-A slow or disconnected client cannot stop the host, another client, claim renewal, or workflow execution. The host waits for socket drain before it publishes another snapshot to that connection. Polling coalesces while the connection is blocked, so the socket buffer cannot grow by one snapshot on every poll. When a connection closes, the host removes its subscriptions and exact origin-session activity immediately.
+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.
 
 ## Origin-session activity
 
-The Pi extension reports `started`, `refresh`, and `settled` activity for the exact session, run, interaction request, delivery, and Pi session entry. Reports use a monotonic sequence. The first report on each protocol connection is `started`; only later reports on that same connection use `refresh`. Refresh happens before the connection-scoped lease expires.
+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 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.
 
-The host accepts activity only when its session, run, request, deterministic `interaction:<request-id>` delivery ID, and presented Pi session entry match the durable presented interaction. Activity entries are keyed by connection and request, so another caller-supplied delivery label cannot create a duplicate overlay. Activity changes display only. It does not grant authority, renew a workflow claim, settle a step, or change durable pause state. A disconnect or expired activity lease removes the overlay.
+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.
 
 ## Commands and uncertain results
 

package/docs/tui-viewer.md

@@ -11,9 +11,11 @@ The viewer uses the [incremental and virtualized viewer design](plans/2026-08-28
 
 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.
 
+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.
+
 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 them in bounded chunks when the user opens the related detail, verifies the byte count and SHA-256 digest, and then shows the complete text or JSON value. Page and content requests run outside input and drawing through the shared client protocol. A newer page selection replaces the previous request, including when the user returns to an earlier page. A failed first read leaves the run browser usable. A failed refresh keeps the last good view and marks it stale.
+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
 

package/docs/workflows.md

@@ -147,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
@@ -200,15 +202,19 @@ 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
@@ -317,7 +323,10 @@ keeps normal output capture. Lines and update data are each limited to 64 KiB.
 See [WORKFLOW_UPDATES.md](WORKFLOW_UPDATES.md) for the envelope, progress
 schema, limits, estimation, and error rules.
 
-The host reserves the effect before it lets the action run. A repeated key with
+The host reserves the effect before it lets the action run. The engine creates
+the internal key from the run ID, effect type, full compiled node path, and node
+visit number. Workflow code does not supply that key. Two included workflows
+can use the same local node name without sharing an effect. A repeated key with
 the same request adopts the durable record; the same key with another request
 is a conflict. A normal caught error settles the attempt as rejected. After an
 uncertain process exit, an idempotent effect returns to pending for retry, while
@@ -373,7 +382,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.
 
@@ -480,18 +489,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
@@ -684,18 +694,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
 
@@ -712,7 +720,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
 
@@ -724,14 +732,19 @@ 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
   receipt, and fences the worker before process-group shutdown. `/workflow
 resume` takes a new generation and reruns only work after the last durable
   boundary.
+- The host tells each worker to `start`, `resume`, `continue`, or `restart`.
+  A checkpoint continuation names its waiting parent. A restart begins at the
+  workflow start and does not reuse checkpoint continuation rules.
 - Resuming an active run adopts the existing work. Duplicate start, control,
   update, and submission messages return their stored receipts.
 - A start is committed as `queued` with its final run ID before the command
@@ -746,6 +759,9 @@ resume` takes a new generation and reruns only work after the last durable
   same transaction. Claim loss does not write a failed run event.
 - An uncommitted pure or idempotent node can run again after a worker crash. An
   uncertain manual effect parks as ambiguous and never retries automatically.
+  If a ready worker exits before the saved run revision advances, the host parks
+  the run with `workerNoProgress`. The scheduler does not claim it again until
+  an operator explicitly resumes or cancels it.
 - Host status reports safe counts and timestamps. It does not report session
   IDs, project paths, prompts, payloads, tokens, process IDs, or credentials.
 

package/herdr-plugin.toml

@@ -1,6 +1,6 @@
 id = "osolmaz.pi-workflows"
 name = "pi-workflows"
-version = "0.16.0"
+version = "0.16.2"
 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.16.0",
+  "version": "0.16.2",
   "description": "Workflow and controller runtime with a live terminal viewer for the pi coding agent",
   "keywords": [
     "pi-package"