@osolmaz/pi-workflows 0.16.5 → 0.16.7

package/docs/WORKFLOW_STEP_MESSAGES.md

@@ -1,10 +1,10 @@
 # Workflow messages in Pi
 
-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.
+This is the current workflow-message contract. The [durable execution plan](2026-09-06-durable-execution-plan.md) supersedes the earlier automatic terminal-turn and reminder behavior.
 
 ## Goal
 
-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 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 and resumed prompts are one step-message kind with different display reasons.
 
 The server 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.
 
@@ -16,13 +16,13 @@ A workflow message is content that Pi Workflows requires Pi to add to one conver
 
 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       |
+| Kind           | Pi behavior                                      | Purpose                                    |
+| -------------- | ------------------------------------------------ | ------------------------------------------ |
+| `step`         | Custom message that starts a model turn          | Initial 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`     | Visible message that does not start a model turn | Recorded terminal result                   |
+| `followUp`     | Custom message that starts normal work           | Work saved for after successful completion |
 
 The server stores one `WorkflowMessage` record before Pi can send it:
 
@@ -61,7 +61,7 @@ Every step message uses the custom type `pi-workflows-step`:
 export type WorkflowAgentStepMessageDetails = {
   schema: "pi-workflows.agent-step-message.v1";
   workflowMessageId: string;
-  reason: "initial" | "reminder" | "resumed";
+  reason: "initial" | "resumed";
   contract: AgentStepContract;
   presentation?: {
     runTitle?: string;
@@ -84,7 +84,7 @@ pi.sendMessage(
 
 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.
 
-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.
+Submitted agent steps call `workflow submit` or `workflow update` with the exact `requestId`. Assistant-message steps reply normally and are accepted only through the separate assistant-response path at `agent_settled`. Ordinary checkpoints accept `answer`; protected decisions accept only the verified human path or their declared timeout policy. Both forms keep the existing `agent` node and use `expectedOutput` to select the completion form.
 
 ## Engine boundary
 
@@ -103,10 +103,10 @@ A collapsed step card shows only the workflow identity and current work. For exa
 Checking the monitored target
 ```
 
-A reminder or resumed prompt adds a short label:
+A resumed prompt adds a short label:
 
 ```text
-↻ monitor › check · reminder
+↻ monitor › check · resumed
 Checking the monitored target
 ```
 
@@ -120,6 +120,16 @@ Notifications keep the custom type `pi-workflows-notification` and use `triggerT
 
 The extension has one `WorkflowMessageCoordinator` for all message kinds. The server 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 coordinator retains only workflow-owned turns. Its local state is absent,
+delivering, running, or settled awaiting acknowledgment. An ordinary chat turn
+never creates an owned turn or blocks later workflow delivery. Recovery requires
+an already recorded active workflow turn and its exact message as the latest
+user or custom input in the active Pi branch. A delivered step with no active
+workflow turn cannot claim a later ordinary chat response.
+A delayed acknowledgment retains the same message, turn ID, and exact response;
+it never creates another model attempt. Unconfirmed delivery stays visible as
+unconfirmed instead of being reported as a received step.
+
 The coordinator follows this sequence:
 
 1. After every server connection, wait for the complete origin-session view and report the active branch before any send or turn report.
@@ -141,58 +151,76 @@ After Pi, the extension, or the server restarts, branch reporting runs before an
 
 ## Model-turn status
 
-`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 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.
-
-A start against a closed message is rejected. Follow-up turns are reported for ordering but do not show the completed workflow as `running`.
-
-The extension creates one workflow turn ID at `agent_start` and keeps it through the matching `agent_end` and server reconnect. It buffers starts and ends until the session view and message receipt are ready.
-
-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 server saves one immutable end result. A repeated report adopts it, and a stale turn ID cannot clear newer activity. A supervised runner 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.
-
-The server 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.
-
-There is no activity heartbeat, refresh lease, or sequence counter. The server shows `running` from the matching start until the matching end. Server 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.
+`agent_start` has no message payload. A locally delivered prompt binds its start
+through the coordinator's saved message identity. Reconnect requires the same
+recorded active turn, run, session, and message, with no later user or custom
+input in the active branch. Neither a session view nor an old branch entry alone
+proves that a message caused the current turn.
+
+Only pending, unpaused agent requests and explicit follow-ups can open model
+turns. Decisions, notifications, and terminal notices cannot. A stale start can
+adopt an already closed result but cannot create new activity. An identity
+mismatch is rejected before a turn changes.
+
+`agent_end` records low-level stop information. The coordinator retains the
+workflow turn through automatic Pi retries and waits for `agent_settled` before
+submitting visible assistant text, recording the turn end, or delivering more
+work. End reports carry `completed`, `aborted`, `error`, or `lost` and the exact
+response-entry evidence when available. A delayed acknowledgment keeps the settled
+response ID pending. Once message and turn ownership are confirmed, the coordinator
+submits that exact response before it reports the end. Later events cannot replace
+the pending turn or its response. Repeated reports adopt the saved result.
+
+An aborted pending step pauses its run. Resume retains the request and attempt,
+advances the request revision, and creates one resumed step message when needed.
+A protected decision keeps its answer revision and decision message. A missing
+submission stays pending: the host adds no reminder turn or hidden retry limit.
+
+Execution status and Pi activity remain separate. A completed run remains
+completed during reporting or follow-up work. A waiting run can have an active
+origin-session turn without changing its execution status to running. Host
+recovery closes active-time intervals at their last durable samples, not the Pi
+turn itself. Only an idle-session branch report can prove an unended turn lost.
 
 ## 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;
+- interactive requests own exact response identity, kind, validation, and accepted submissions;
+- node attempts and active intervals own execution history and the active-time budget;
+- human decisions own choices, verified answers, and absolute expiry;
 - 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.
+Submitted and assistant-message steps keep their exact attempt while parked.
+Recovery adopts accepted receipts and matching branch evidence; it does not use
+the oldest pending request or accept text from another request or branch.
 
-## Restored behavior
+Requests and their required messages commit together. Terminal reporting can be
+retried from recorded facts after execution settles; a reporting failure cannot
+reverse execution or cancellation.
 
-The shared contract supports these features without separate send paths:
+## Terminal results and follow-ups
 
-- 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.
+A terminal result is visible but does not start a model turn. It stays in the
+origin-session view while pending and for 60 seconds after confirmed delivery.
+An explicit restart targets the terminal run and revision and creates fresh
+work without copying old steps, changed settings, approvals, or effects. It has
+no terminal-turn prerequisite or hard-coded count limit.
 
-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.
+Explicit follow-ups wait for successful completion, terminal notice delivery,
+prior follow-up settlement, and release of the session reservation. They remain
+normal conversation work. Slash-looking text cannot dispatch an extension
+command. External effects still require saved receipts or explicit recovery of
+an ambiguous outcome. See [terminal workflow messages](DEFERRED_TURNS.md).
 
 ## Session recording
 
 The extension records workflow-related Pi events through a batched server client operation. It uses documented Pi events and does not read or edit Pi session files.
 
-The server 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.
+The server deduplicates settled entries by Pi entry ID. It links attempts to their prompt, response, first, and last entries. The coordinator finalizes capture after the terminal notice has a confirmed entry on the current branch, without starting a model turn. Explicit follow-up turns have their own capture segment. A recording failure does not fail workflow execution or block the next delivery.
 
 ## Public API boundary
 
@@ -205,26 +233,27 @@ This design does not change Pi core, use private Pi APIs, or change Pi session s
 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;
+- one workflow message ID adopts its confirmed Pi entry before another send;
+- an automatic Pi retry cannot submit a partial response before the settled boundary;
 - 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 runner continuation leaves the active session capture open until the matching turn ends;
+- an early `agent_start` and `agent_settled` wait for the message receipt and session view, then apply in order;
+- model activity remains separate from durable execution status;
+- normal runner progress 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;
+- aborted pending turns pause without adding reminder work;
 - 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;
 - server 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;
+- repeated missing submissions remain pending without automatic extra model turns;
+- initial and resumed prompts use the same step kind and differ only by reason;
+- terminal messages never start turns, and follow-ups start only at their declared 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;

package/docs/plans/2026-08-04-controller-runtime-plan.md

@@ -8,6 +8,8 @@ status: implemented
 
 # ResourceManager runtime plan
 
+> Historical plan. The [durable execution plan](../2026-09-06-durable-execution-plan.md) supersedes its continuation, scheduling, and automatic model-turn choices. Use the current reference pages for the implemented contract.
+
 pi-workflows needs a controller mode for automation that spans repeated events, external state changes, and process restarts. The design in [RESOURCE_MANAGERS.md](../RESOURCE_MANAGERS.md) follows the Kubernetes controller pattern. Durable resources hold desired and observed state, events enqueue resource keys, and each reconciliation reads current facts before acting.
 
 The implementation keeps the graph engine focused on finite jobs. Controllers start and observe workflows through a child-run interface. Workflow graphs keep their finite execution model.

package/docs/plans/2026-08-21-deferred-turn-intents-plan.md

@@ -6,6 +6,8 @@ date: 2026-08-21
 
 # Guarantee one successor turn after workflow interruption
 
+> Historical plan. The [durable execution plan](../2026-09-06-durable-execution-plan.md) supersedes its continuation, scheduling, and automatic model-turn choices. Use the current reference pages for the implemented contract.
+
 Pi Workflows can stop the active agent turn before the agent receives a tool result or can take its next action. This happens when an active workflow step is cancelled, times out, loses its queue claim, or is interrupted by a controller. The workflow can also return a successful start result and then fail asynchronously before it sends its first prompt. In that case, the user can see a UI error while the model still believes that the workflow started successfully.
 
 Add one general rule: an eligible workflow event creates one durable obligation for one later agent turn. The next normal workflow prompt or result presentation satisfies the obligation when one exists. Otherwise, Pi Workflows sends one factual fallback turn after the old turn settles.

package/docs/plans/2026-08-27-workflow-terminal-restart-plan.md

@@ -6,6 +6,8 @@ date: 2026-08-27
 
 # Full plan
 
+> Historical plan. The [durable execution plan](../2026-09-06-durable-execution-plan.md) supersedes its continuation, scheduling, and automatic model-turn choices. Use the current reference pages for the implemented contract.
+
 ## Goal
 
 After every top-level workflow run ends, give the model one normal successor turn.

package/docs/workflows.md

@@ -5,6 +5,23 @@ covers the file format, every node type, edge routing, the step contract the
 model sees, and how runs behave at runtime. For durable state, see
 [SQLITE_STATE.md](SQLITE_STATE.md).
 
+## Starting and resuming runs
+
+A successful start call confirms that a run was created. Wait for the delivered
+step contract before submitting an agent result. Report worktree creation or
+implementation progress only after the corresponding recorded steps succeed.
+The status view distinguishes unconfirmed step delivery, active agent work,
+required results, and a durable pause. Waiting uses a different glyph from pause.
+
+Resume uses the run's original source and graph, including ordinary workflows
+without included workflows. Source and graph checks run before any durable
+mutation. `WorkflowEngine.resumeRun` has no `force` option. Restore the original
+source to resume its accepted work, or explicitly start a new run for changed
+code. A new run does not inherit outputs, approvals, or effect receipts.
+File and built-in source identities verify code; callers of the direct engine
+API must supply source identity to detect callback-body changes that leave the
+structural graph unchanged.
+
 ## Workflow files
 
 A workflow is a TypeScript module whose default export is `defineWorkflow(...)`.
@@ -126,12 +143,12 @@ pi-workflows server run
 `server run` stays attached. The other commands start, inspect, or stop the
 on-demand process. No command installs an operating-system service.
 
-The extension, CLI, and `piw` use the same version-1 client protocol over a Unix socket or Windows named pipe. The server sends byte-bounded run-list and run-view pages. Clients collect a complete run list for one revision and reject stale run pages whose cursor or revision no longer matches. The server reads only the selected history ranges and reuses an unchanged subscribed view after a lightweight revision check. It waits for a slow socket to drain and removes every subscription when its client unsubscribes. Large values stay available through verified content chunks. Server-generated aggregate values are saved and linked to the run before the server advertises them.
+The extension, CLI, and `piw` use the same version-1 client protocol over a Unix socket or Windows named pipe. The server sends byte-bounded run-list and run-view pages. Clients collect a complete run list for one revision and reject stale run pages whose cursor or revision no longer matches. A run view's `revision` is the presentation cursor; `runRevision` is the execution resource revision used by restart and other exact execution commands. The server reads only the selected history ranges and reuses an unchanged subscribed view after a lightweight revision check. It waits for a slow socket to drain and removes every subscription when its client unsubscribes. Large values stay available through verified content chunks. Server-generated aggregate values are saved and linked to the run before the server advertises them.
 
 A runner verifies the root and all mounted source identities before it loads
 workflow modules. It then checks the resolved mounted-source map and executes
-from committed state through a server-backed store. Resume and continuation
-reads return only `WorkflowRunState`. Session messages, tool results, activity
+from committed state through a server-backed store. Resume reads return only
+`WorkflowRunState`. Session messages, tool results, activity
 events, viewer history, settings, follow-ups, and other inspection data stay in
 server-owned SQLite. If one required result exceeds the runner protocol frame,
 the server returns a digest-bound reference and the runner reads and verifies it
@@ -154,7 +171,7 @@ 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. Step prompts, protected decisions, notifications, terminal
 results, and follow-ups use the server-owned `workflow_messages` table and one
-extension sender. Initial, reminder, and resumed prompts are the same step-message
+extension sender. Initial 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 resource manager child
 without an origin session can use a supervised headless `pi --mode rpc` child
@@ -208,10 +225,11 @@ the client stops waiting but does not cancel the durable server 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 server 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,
+without submitting, the exact request stays pending. The server does not add
+reminder turns or apply a hidden retry limit. Additional model work must follow
+a declared graph path or an explicit user request. 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.
@@ -226,6 +244,28 @@ 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
 snapshots omit them. Snapshots keep fixed numbers and fixed `null` values.
 
+### Explicit summaries and fresh restarts
+
+Terminal notices show the recorded status, result, and error. They are visible
+messages, not model prompts. Use an explicit `assistantMessage()` node when a
+workflow needs a written explanation. `presentationPrompt` is not supported.
+Autoimplement prepares its structured result, runs an explicit summary node,
+and then returns the prepared result. A failed summary cannot erase accepted work.
+
+The extension submits visible assistant text and records the end of a workflow
+turn at `agent_settled`. `agent_end` records only low-level activity. Automatic Pi
+retries keep the same unsettled turn and cannot submit an unfinished response.
+Branch evidence must identify the exact workflow message before reconnect can
+adopt its turn.
+
+A fresh restart requires an explicit user request and targets `runId` plus
+`expectedRevision`. It starts from the original input in a new run. It does not
+copy old steps, changed settings, decisions, or effects. The host rejects a stale
+revision or unsettled external effects before reserving work. An identical retry
+adopts the same child run. There is no terminal-message requirement or hard-coded
+restart count. Explicit queued follow-ups become eligible after terminal notice
+delivery; they do not wait for a terminal model turn.
+
 ### compute
 
 Runs a TypeScript function inline. Use it for pure data shaping.
@@ -340,20 +380,21 @@ a manual effect becomes ambiguous. This is not an exactly-once claim.
 
 ### checkpoint
 
-Ends the run in a `waiting` state for human review. The checkpoint run is
-terminal, so no process keeps running while the run waits. The human answers
-with `/workflow answer <json>` (or plain text), which starts a **continuation
-run**: a new run with its own state and events, linked to the checkpointed run
-through `parentRunId`. The continuation receives the answer as its input,
-carries forward every output the parent produced (including the checkpoint's),
-and continues routing along the checkpoint's outgoing edge. Outgoing edges
-from checkpoint nodes are allowed exactly so continuations have somewhere to
-go; step accounting carries over, so `maxSteps` bounds the whole chain.
+Creates a durable input request and parks the worker. The run is waiting, not
+terminal. Its input, settings, history, and active attempt stay unchanged.
+The optional callback creates the request content once. It does not complete
+the node.
+
+An answer completes that exact request in the same run. The answer becomes the
+checkpoint output, and execution follows its outgoing edge. A checkpoint at the
+end of the graph completes the run with its answer. Each answered checkpoint
+counts once toward `maxSteps`. Invalid responses do not create another run or
+change another request.
 
 ```typescript
 checkpoint({
   summary: "human decides how to proceed",
-  run: ({ outputs }) => outputs.reconcile, // optional; default output is { summary }
+  run: ({ outputs }) => outputs.reconcile, // optional request content; defaults to { summary }
 });
 ```
 
@@ -388,9 +429,9 @@ 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 server 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 waiting run stores the request and asks every channel configured for the audience. The structured `subject` remains machine data. Channels receive the normalized `presentation`, title, choices, input prompts, and deadline policy. The first valid verified human answer wins. When `onTimeout` is present and no human answer wins before the saved deadline, the server accepts the declared response with `timeout` provenance and resumes the same run. This policy can continue without a configured channel. The original input remains unchanged, and the resolved response becomes the checkpoint output. `humanDecisionEdge()` provides exhaustive routing for the choices.
 
-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 server-owned path. Ordinary checkpoints can also use the model-facing `answer` action.
+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 <requestId> <response>` to send the answer through the server-owned path. Ordinary checkpoints can also use the model-facing `answer` action.
 
 See [Human decisions](HUMAN_DECISIONS.md) for channels, recovery, persistence, and plan approval.
 
@@ -488,9 +529,9 @@ The model sees one `workflow` tool. Its `action` field supports:
 - `status` for the active run or a supplied run ID;
 - `pause` and `resume` for the active session run;
 - `cancel` for the active run or a supplied run ID;
-- `answer` with checkpoint input and an optional run ID;
-- `update` for a non-completing update from the current agent attempt;
-- `submit` for the current workflow step contract.
+- `answer` with an exact checkpoint `requestId` and input;
+- `update` with an exact agent `requestId` and a non-completing update;
+- `submit` with an exact agent `requestId` and its output.
 
 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
@@ -678,36 +719,42 @@ and resume later by running that wait again from the beginning.
 A monitor uses the session's single active workflow slot. It does not provide
 cron syntax, calendar scheduling, OS notifications, or a background service.
 
+## Worker capacity
+
+Workflow runs and resource-manager reconciles share one host scheduler. Start, restart, resume, result validation, and timeout recovery all wait for the same worker capacity. The default is four execution workers; set `PI_WORKFLOWS_MAX_WORKERS` before starting the host to change it. Waiting and paused requests keep their durable identity without occupying a worker. A submitted candidate stays durable until a worker can validate it. Cancellation does not wait for capacity.
+
+One unfinished interactive run reserves its origin Pi session, including while waiting or paused. Independent headless work does not reserve that session.
+
 ## The step contract
 
 Every `agent` prompt ends with a step contract block naming the workflow, the
-step id, the attempt id, and the expected output shape:
+step id, attempt id, durable request id, and expected output shape:
 
 ```
 ---
 Workflow step contract (workflow: autoimplement, step: review, attempt: 6f9d…)
 
 Complete this step by calling the `workflow` tool exactly once with:
-{"action": "submit", "step": "review", "attempt": "6f9d…", "output": <your result>}
+{"action": "submit", "requestId": "request-EXACT_ID_FROM_CONTRACT", "output": <your result>}
 Expected output: { "route": "clean" | "issues_found", "reason": "short justification" }
 The step is complete only after the workflow tool accepts the output.
 If the tool reports a validation error, correct the output and call it again.
 ```
 
-The `workflow` tool uses `{ action: "submit", step, attempt, output }` for step
-results. Submissions are rejected (with a reason the model sees) when no step
-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.
+The `workflow` tool uses `{ action: "submit", requestId, output }` for step
+results. The request binds one run and one attempt. Loops and retries get new
+request IDs; they cannot accept an earlier request's output. A missing, stale,
+wrong-kind, or other-session request is rejected, as is output that fails
+`validate`. The server never selects the oldest pending request.
 Acceptance resolves the step and the engine advances. In an interactive Pi
 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. Step messages with reason `reminder` or `resumed` use the same card and keep the active attempt ID.
+Ctrl+O shows the exact contract and full prompt. Step messages with reason `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 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
+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 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).
 
@@ -726,31 +773,34 @@ returns its stored receipt.
 
 A headless resource manager child cannot produce a visible assistant message without
 an approved origin-session binding. Use structured agent output for detached
-work. A final continuation-chain outcome creates its own terminal workflow message through the shared coordinator only after the outcome is durable.
+work. A terminal run creates its own terminal workflow message through the shared coordinator only after the outcome is durable.
 
 ## Runtime behavior
 
-Runs execute one node at a time. Every transition is persisted to the run
-database transaction before the engine moves on, which is what makes the live viewer
-possible. Defaults worth knowing:
+Runs execute one node at a time. Workers propose narrow transitions; the host
+validates and commits them before execution moves on. A start must follow the
+accepted graph route. A completed run must return its accepted final node output.
+Workers cannot skip a checkpoint, rewrite an active attempt's start, or replace
+the full saved run state. Defaults worth knowing:
 
 - Node timeout is 15 minutes unless the node sets `timeoutMs` to a positive
   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 deadline before they park. The server advances it only during a
-  reported model turn from an active connected origin session. Message delivery,
-  waiting, pauses, disconnects, and server downtime do not consume the limit. This
-  active-time budget survives server restart.
+  resolved budget before they park. The host records active intervals with a
+  monotonic clock. Message delivery, waiting, pauses, disconnects, wall-clock
+  changes, and server downtime do not consume the limit. Recovery keeps the last
+  saved elapsed-time sample without rewriting the attempt's start timestamp.
+  Human decision deadlines remain absolute wall-clock deadlines.
 - `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 runner before process-group shutdown. `/workflow
 resume` takes a new generation and reruns only work after the last durable
   boundary.
-- The server tells each runner 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.
+- The server tells each runner to `start`, `resume`, or `restart`.
+  An answered checkpoint resumes its exact attempt in the same run. An explicit
+  restart creates a new run at the workflow start.
 - 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
@@ -773,7 +823,7 @@ resume` takes a new generation and reruns only work after the last durable
 
 ## Run history retention
 
-Pi Workflows keeps a terminal root run and all its restart or continuation descendants for 30 days from `finished_at`. The server can remove the tree after that point only when every descendant is terminal and no protected work or outside reference remains.
+Pi Workflows keeps a terminal root run and all its explicit restart descendants for 30 days from `finished_at`. The server can remove the tree after that point only when every descendant is terminal and no protected work or outside reference remains.
 
 Protected work includes waiting or parked runs, live queue rows, pending workflow messages, open workflow turns, pending interactions or decisions, recording session segments, queued follow-ups, active leases, unsettled effects, controller ownership, active runner content, resumable checkpoints, and undelivered terminal results.
 
@@ -862,8 +912,24 @@ npm run test:e2e:live -- \
   --model gpt-5.6-luna
 ```
 
+For providers that reserve credit against the requested output allowance, pass
+`--max-output-tokens N` with the generated profile. OpenRouter can reject a
+small smoke test when the model's catalog default requests hundreds of thousands
+of output tokens. This option changes only the exact built-in model's `maxTokens`
+through Pi's documented `modelOverrides`. It does not change the provider, model
+ID, API, endpoint, or credentials. The test verifies and reports the allowance,
+keeps the complete response, and fails immediately on a provider error.
+
+```bash
+npm run test:e2e:live -- \
+  --provider openrouter \
+  --model deepseek/deepseek-v4-flash \
+  --max-output-tokens 4096
+```
+
 For subscription authentication, use a dedicated Pi profile that has no other
-extensions or resources:
+extensions or resources. The output-budget option cannot modify this existing
+profile:
 
 ```bash
 npm run test:e2e:live -- \

package/examples/workflows/autoresearch.workflow.ts

@@ -24,8 +24,6 @@ export default defineWorkflow({
     const goal = (input as AutoresearchInput).goal;
     return goal ? `autoresearch: ${goal.slice(0, 60)}` : undefined;
   },
-  presentationPrompt:
-    "Report the research conclusion in plain language: the winner and its numbers, or the strongest negative result, plus the journal path.",
   maxSteps: 40,
   startAt: "setup",
   nodes: {

package/examples/workflows/branch.workflow.ts

@@ -12,10 +12,6 @@ const classifyChoices = ["continue", "checkpoint"] as const;
  */
 export default defineWorkflow({
   name: "branch",
-  presentationPrompt: ({ state }) =>
-    state.status === "waiting"
-      ? "Explain briefly why the task needs clarification, then ask the user one concrete clarification question."
-      : "Tell the user in one concise sentence how the workflow recommends proceeding.",
   startAt: "classify",
   nodes: {
     classify: decision({

package/examples/workflows/echo.workflow.ts

@@ -7,8 +7,6 @@ type EchoInput = {
 /** Smallest possible workflow: one agent step that submits a JSON reply. */
 export default defineWorkflow({
   name: "echo",
-  presentationPrompt:
-    "Give the user the concise reply from the workflow result, with no extra commentary.",
   startAt: "reply",
   nodes: {
     reply: agent({

package/examples/workflows/live-settings.workflow.ts

@@ -88,6 +88,4 @@ export default defineWorkflow({
       switch: { on: "$.route", cases: { normal: "normal", careful: "careful" } },
     },
   ],
-  presentationPrompt:
-    "Explain which route and settings were used. Any queued follow-up prompts run only after this response settles.",
 });

package/examples/workflows/two-turn.workflow.ts

@@ -11,8 +11,6 @@ type TwoTurnInput = {
  */
 export default defineWorkflow({
   name: "two-turn",
-  presentationPrompt:
-    "Present the final validation checklist clearly, including its concrete file references.",
   startAt: "inspect",
   nodes: {
     inspect: agent({

package/herdr-plugin.toml

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