@osolmaz/pi-workflows 0.16.5 → 0.16.6

package/docs/HUMAN_DECISIONS.md

@@ -18,7 +18,7 @@ A workflow author can:
 - collect exact text with a choice such as `replan`;
 - address a logical audience instead of a Telegram chat or Pi session;
 - reuse a standard plan approval workflow; and
-- rely on one accepted answer and one continuation after a crash or concurrent reply.
+- rely on one accepted answer and one resumed attempt after a crash or concurrent reply.
 
 The feature uses the existing checkpoint execution primitive. It does not add another engine node type.
 
@@ -124,7 +124,7 @@ When the engine reaches the node, it:
 4. asks the configured channels to deliver it; and
 5. parks the run in `waiting` state.
 
-When a valid answer is accepted, the continuation keeps the workflow's original input. The human answer becomes the checkpoint node's output in the continuation. Ordinary checkpoints keep their current behavior, where `/workflow answer` supplies the continuation input.
+A valid answer completes the exact checkpoint attempt in the same run. The original workflow input stays unchanged. The answer becomes that node's output. Ordinary checkpoints also complete in place, but use the normal `answer` action. A protected decision accepts only the verified human path or its declared timeout policy.
 
 ## Request and response contracts
 
@@ -265,15 +265,15 @@ Human decisions use the canonical [SQLite state](SQLITE_STATE.md) database:
 - `human_decisions` stores each immutable request;
 - `human_decision_submissions` records human, policy, channel, and control candidates;
 - `human_decision_resolutions` stores the one accepted-or-cancelled winner;
-- `continuations` links the parent and continuation runs;
-- `effects` and `effect_attempts` record parent settlement, continuation, external delivery, and external settlement work; and
+- `interactive_requests` and `interactive_submissions` bind the accepted resolution to the exact node attempt;
+- `effects` and `effect_attempts` record run settlement, external delivery, and external settlement work; and
 - `channels`, `channel_cursors`, and `channel_messages` store channel identity, polling position, and decision delivery or settlement receipts.
 
 A valid human answer, eligible timeout policy, explicit cancellation, or no-default expiry competes for the same resolution primary key. The winning transaction records the immutable resolution, audit event, and required effects together. A retry adopts the existing matching result. A conflicting or late answer receives the durable winner.
 
-A deadline with a validated default response is timeout-policy acceptance. It cannot become expiry cancellation. No-default expiry can cancel. Automatic policy and continuation creation require the current run owner's token and lease generation. A verified channel can submit a human candidate without gaining run ownership.
+A deadline with a validated default response is timeout-policy acceptance. It cannot become expiry cancellation. No-default expiry can cancel. Automatic policy and execution require the current owner's token and lease generation. A verified channel can submit a human candidate without gaining run ownership.
 
-The continuation run ID is derived from the decision ID. The owner adopts an existing matching continuation or creates it once. The continuation record and redacted receipt carry the resolution provenance, decision ID, request digest, gate node ID, choice, acceptance time, and answer digest. Human actor, channel, event, and idempotency details remain private and do not enter model-visible status output.
+The scheduler resumes the same run and exact request. Accepted resolution and redacted receipt records carry the provenance, decision ID, request digest, gate node ID, choice, acceptance time, and answer digest. Human actor, channel, event, and idempotency details remain private and do not enter model-visible status output.
 
 ## Planning workflow composition
 
@@ -312,7 +312,7 @@ Recovery follows these rules:
 - ambiguous Telegram sends are not retried automatically;
 - duplicate channel updates are harmless;
 - stale responses are rejected;
-- one human or timeout response creates one continuation;
+- one human or timeout response completes one exact checkpoint attempt;
 - the winning human answer or timeout policy settles or cancels the pending Pi decision workflow message;
 - confirmed channel settlement is adopted without another remote call;
 - failed channel settlement has a bounded retry count and cannot create an unbounded record loop; and
@@ -320,20 +320,18 @@ Recovery follows these rules:
 
 A required decision with no available channel remains waiting and reports the configuration problem. An automatic decision does not need a channel to apply its saved response after the deadline. A skipped plan policy creates no decision.
 
-Direct answer handling and recovery can notice the same accepted decision at the same time. Both paths use one continuation coordinator. The coordinator prepares the deterministic continuation through the existing durable run queue. The first caller creates and claims the queue row. Only that caller receives the claim token and starts the engine. A compatible later caller adopts the existing row without starting another engine.
-
-Adoption does not change the lease, claim generation, queue state, timestamps, or events. An adopter cannot renew, release, park, complete, or replace the winning claim. Reuse with a different workflow source, definition, input, launch options, parent, or owning session fails without changing the existing run. If the winning process stops after it claims the row, existing lease expiry and activation recovery can continue the prepared run.
+Direct answer handling and recovery can observe the same accepted decision. Both use the exact saved request and the common scheduler. Response acceptance makes the original run eligible; it does not create or directly launch another run. One lease generation owns execution. An identical response retry adopts its receipt, while a conflicting payload or wrong request kind is rejected before queue changes. Source verification and generation fencing remain required after interruption.
 
 ## Compatibility
 
-This alpha change updates the current request, accepted-result, receipt, resolution, continuation, and snapshot contracts in place. Old active runs refuse resume through normal source and definition identity checks. There is no compatibility reader, migration, dual path, or new schema generation. The continuation startup fix uses existing queue and lease records. It adds no field, table, migration, or schema version. Existing compatible prepared or initialized continuations are adopted. Updated viewers label a human decision as a checkpoint, show its deadline and automatic action when present, and keep the canonical subject separate. Private channel configuration and transport identifiers remain hidden.
+This alpha contract changes in place. Incompatible state remains untouched and fails with a backup-and-reset instruction. There is no compatibility reader, migration, dual path, or new schema generation. Viewers show the decision deadline and declared automatic action, while keeping the canonical subject separate. Private channel configuration and transport identifiers remain hidden.
 
-The engine remains independent from Pi and Telegram. Core code owns decision contracts and validation. The server owns durable acceptance, continuation, workflow messages, and channel-child supervision. The Pi extension owns documented session presentation and controls. The Telegram adapter child owns Bot API translation. Workflow definitions own only the question, choices, audience, and routes.
+The engine remains independent from Pi and Telegram. Core code owns decision contracts and validation. The server owns durable acceptance, scheduling, workflow messages, and channel-child supervision. The Pi extension owns documented session presentation and controls. The Telegram adapter child owns Bot API translation. Workflow definitions own only the question, choices, audience, and routes.
 
 ## Contract impact
 
 - **Session state:** Pi records normal workflow messages and interactive decision results.
-- **Other persistent data:** decision requests and resolutions can carry a deadline, automatic response, and resolution provenance in the existing decision store. Continuation startup uses existing run, queue, source, binding, lease, event, continuation, and decision-effect records. External channel attempts use the shared effect records, and channel delivery and settlement records remain separate feature evidence.
+- **Other persistent data:** decision requests and resolutions can carry a deadline, automatic response, and resolution provenance in the existing decision store. Same-run resumption uses the existing request, queue, source, binding, lease, event, and effect records. External channel attempts use the shared effect records, and channel delivery and settlement records remain separate feature evidence.
 - **Pi internals:** none.
 - **Public Pi API:** documented extension lifecycle, message, command, session, and status APIs only.
 - **Public pi-workflows API:** typed human choices, `humanDecision().onTimeout`, `humanDecisionEdge()`, channel profile configuration, the plan approval policy, the shared plan-change workflow, and the additive queue prepare-or-adopt operation.
@@ -345,7 +343,7 @@ The implementation must test:
 - compile-time exhaustive choice routing;
 - choices with no input and choices with exact text input;
 - runtime choice and input validation;
-- legacy checkpoint continuation;
+- ordinary and protected checkpoints completing in the original run;
 - model-tool answer rejection;
 - Pi decision workflow messages, branch adoption, branch-specific decision messages, and verified answers;
 - supervised channel-child protocol fencing and restart recovery;
@@ -354,14 +352,14 @@ The implementation must test:
 - stale request digests;
 - concurrent Pi and Telegram answers;
 - a direct verified answer racing recovery for the same accepted decision;
-- one claim generation, one engine start, one continuation, and one execution of each continuation node;
-- compatible continuation adoption without lease, queue, timestamp, or event mutation;
-- incompatible continuation identity reuse without mutation;
+- one authoritative claim generation and no extra run after a decision;
+- accepted-response adoption without new model work or copied state;
+- request identity and response-kind mismatches rejected before domain mutation;
 - identical and conflicting retries;
-- crashes before and after answer acceptance and continuation creation;
+- crashes before and after answer acceptance and same-run resumption;
 - ambiguous Telegram sends;
 - one supervised long-poll adapter per profile and server-restart recovery;
 - decision cancellation and expiry;
 - included `plan-approval` routes and bounded replan loops;
 - viewer redaction; and
-- real Pi execution without real Telegram credentials or network calls, duplicate-start failures, revision conflicts, or a stranded running continuation.
+- real Pi execution without real Telegram credentials or network calls, duplicate-start failures, revision conflicts, or a stranded resumed run.

package/docs/HUMAN_DECISION_PRESENTATIONS.md

@@ -279,7 +279,7 @@ presentation. Renderers treat all text as untrusted and inert.
 - Ambiguous Telegram delivery remains unknown and is not retried blindly.
 - A channel failure does not choose a default answer.
 - Rules for the first valid answer and stale answers remain unchanged, as do
-  cancellation and settlement rules together with exactly-once continuation.
+  cancellation and settlement rules together with exact same-run response adoption.
 
 ## Verification
 

package/docs/SQLITE_STATE.md

@@ -16,6 +16,8 @@ The database includes the [incremental and virtualized viewer design](plans/2026
 
 `viewer_runs` stores one presentation revision and retained revision floor for each run. `viewer_deltas` stores ordered target patches by run, presentation revision, and delta index. `viewer_session_checkpoints` stores the bounded active message and tool state at each 256-event boundary. `run_view_content` stores generated reference bytes under the exact run ID, content digest, and media type. It is separate from general state blobs, and content reads require all three identities. A viewer-visible transaction writes the domain change, advances the presentation revision, and writes its patch blobs before the same commit. Session-event transactions write each reached replay checkpoint in that transaction.
 
+Run views expose the presentation cursor as `revision` and the execution resource revision as `runRevision`. Commands such as restart use `runRevision`. Conversation capture can advance the presentation cursor without changing execution, so the two values must not be substituted for each other.
+
 The store retains 256 presentation revisions. A reader with an older cursor must take a bounded snapshot. Patches use `add`, `replace`, `remove`, and `append`. They target small projection documents or pages. Patch creation does not reconstruct and compare complete run views.
 
 `session_entries` and `session_events` have run-wide sequence numbers and indexed `(run_id, run_seq)` ranges. Step, trace, entry, and event reads contain at most 256 rows. Run-list queries read metadata, status, lease facts, and the presentation revision. They do not read payload bodies.
@@ -30,7 +32,7 @@ The database stores:
 - global server epochs, command receipts, runner epochs, and runner messages
 - durable origin-session interaction requests and submissions
 - captured Pi session entries and events
-- run and resource manager queues, claims, retries, and continuations
+- run and resource manager queues, claims, and declared retries
 - human-decision requests, submissions, resolutions, and cancellations
 - managed resources, finalizers, effects, and child workflows
 - workflow messages that Pi must add to origin conversations
@@ -112,31 +114,31 @@ Telegram delivery and settlement use these shared effect records. The server rec
 
 The shared records do not replace domain schemas. The following `STRICT` tables keep the state explicit:
 
-| Area                | Tables                                                                                                                       |
-| ------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| Schema and projects | `schema_meta`, `projects`                                                                                                    |
-| Content             | `blobs`, `run_view_content`                                                                                                  |
-| Shared lifecycle    | `resources`, `leases`, `events`, `workflow_host_state`                                                                       |
-| Server protocol     | `host_commands`, `run_workers`, `worker_messages`, `interactive_requests`, `interactive_submissions`                         |
-| Workflows           | `workflow_definitions`, `runs`, `run_sources`, `run_steps`, `run_bindings`, `run_queue`, `node_attempts`, `workflow_updates` |
-| Live settings       | `workflow_settings`, `workflow_setting_changes`                                                                              |
-| Post-run follow-ups | `workflow_follow_ups`                                                                                                        |
-| Session capture     | `session_segments`, `session_entries`, `attempt_entries`, `session_events`                                                   |
-| Human decisions     | `human_decisions`, `human_decision_resolutions`, `human_decision_submissions`, `continuations`                               |
-| Managed resources   | `controller_resources`, `controller_finalizers`, `controller_queue`, `controller_workflows`                                  |
-| Effects             | `effects`, `effect_attempts`                                                                                                 |
-| Pi messages         | `workflow_messages`, `workflow_turns`                                                                                        |
-| Channels            | `channels`, `channel_cursors`, `channel_messages`                                                                            |
+| Area                | Tables                                                                                                                                                   |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Schema and projects | `schema_meta`, `projects`                                                                                                                                |
+| Content             | `blobs`, `run_view_content`                                                                                                                              |
+| Shared lifecycle    | `resources`, `leases`, `events`, `workflow_host_state`                                                                                                   |
+| Server protocol     | `host_commands`, `run_workers`, `worker_messages`, `interactive_requests`, `interactive_submissions`                                                     |
+| Workflows           | `workflow_definitions`, `runs`, `run_sources`, `run_steps`, `run_bindings`, `run_queue`, `node_attempts`, `attempt_active_intervals`, `workflow_updates` |
+| Live settings       | `workflow_settings`, `workflow_setting_changes`                                                                                                          |
+| Post-run follow-ups | `workflow_follow_ups`                                                                                                                                    |
+| Session capture     | `session_segments`, `session_entries`, `attempt_entries`, `session_events`                                                                               |
+| Human decisions     | `human_decisions`, `human_decision_resolutions`, `human_decision_submissions`                                                                            |
+| Managed resources   | `controller_resources`, `controller_finalizers`, `controller_queue`, `controller_workflows`                                                              |
+| Effects             | `effects`, `effect_attempts`                                                                                                                             |
+| Pi messages         | `workflow_messages`, `workflow_turns`                                                                                                                    |
+| Channels            | `channels`, `channel_cursors`, `channel_messages`                                                                                                        |
 
 The `host_*`, `run_workers`, `worker_*`, and `controller_*` names remain version-1 internal SQLite identifiers. The `host` and `controller` actor and owner values and the `~/.pi/agent/workflows/host/` state directory also remain internal identifiers. Public APIs and documentation call these components the workflow server, workflow runner, resource manager, resource runner, and managed resource. The alpha hard cut adds no alias or second storage path.
 
-`workflow_messages` is the only table that owns adding workflow content to Pi. It stores the target session, message kind, source record, content digest, session order, `pending`, `sent`, or `cancelled` state, confirmed Pi entry ID, and creation and update times. The table stores no sender, send lease, `sending` state, or separate sent time. Active-branch evidence changes `pending` or `cancelled` to `sent`. Initial, reminder, and resumed prompts are all `step` messages; their custom details contain the reason. Interactive requests, decisions, terminal runs, notifications, follow-ups, and settings keep their own domain state.
+`workflow_messages` is the only table that owns adding workflow content to Pi. It stores the target session, message kind, source record, content digest, session order, `pending`, `sent`, or `cancelled` state, confirmed Pi entry ID, and creation and update times. The table stores no sender, send lease, `sending` state, or separate sent time. Active-branch evidence changes `pending` or `cancelled` to `sent`. Initial and resumed prompts are all `step` messages; their custom details contain the reason. Interactive requests, decisions, terminal runs, notifications, follow-ups, and settings keep their own domain state.
 
 `workflow_turns` stores the server-approved ownership of one Pi model turn. Each row names the exact workflow message, run, session, and turn ID. A partial unique index permits only one open turn for a message. The server checks for an exact saved turn or another open turn before insertion, so a normal conflict returns a controlled protocol error instead of a raw SQLite error. Terminalization ends every open turn for that run as `lost` in the same transaction. It cancels pending step and decision messages, plus follow-ups when the run did not complete successfully. Committed notifications remain eligible. Matching late reports adopt the saved result, while conflicting identities remain errors.
 
 `channels` stores configured channel resource identities. `channel_cursors` stores the last accepted external polling position. `channel_messages` stores immutable decision delivery and settlement records for audit and duplicate evidence. External application state and Telegram message references belong to `effects` and `effect_attempts`.
 
-Foreign keys join projects, runs, attempts, decisions, managed resources, effects, and channel records. Partial unique indexes enforce one active node attempt per run, one pending step message per interaction request, one nonterminal interactive continuation-chain reservation per Pi session, one decision winner, and one deterministic effect key. A run waiting for a checkpoint or protected decision keeps that chain reservation. A parked waiting parent does not block its own continuation. Reserving that continuation transfers the reservation and settles the parked parent queue in the same transaction, so a failed reservation leaves the parent recoverable.
+Foreign keys join projects, runs, attempts, decisions, managed resources, effects, and channel records. Partial unique indexes enforce one active node attempt per run, one pending step message per request, one nonterminal interactive run per Pi session, one decision winner, and one deterministic effect key. A waiting or paused run keeps its session reservation. Checkpoint responses complete nodes in that same run; they do not reserve child runs.
 
 ### ServerBacked commands and interactions
 
@@ -150,7 +152,7 @@ conflict.
 process identity and terminal outcome. `worker_messages` deduplicates accepted
 state-changing child messages.
 
-`interactive_requests` owns the durable request contract and workflow state for origin-session work. It stores the run, node attempt, target session, contract, request status, accepted submission, `unproductiveTurnEnds`, and revision. Pause is stored once on the run and derived for its one pending interaction. `interactive_submissions` stores the idempotency key, payload, outcome, and receipt. It stores no Pi presentation claim or Pi session entry. `workflow_messages` owns those facts, and the extension reports the active Pi branch after reload.
+`interactive_requests` owns the durable request contract and workflow state for origin-session work. It stores the run, node attempt, target session, contract, request status, accepted submission, and revision. Pause is stored once on the run and derived for its one pending interaction. `interactive_submissions` stores the idempotency key, payload, outcome, and receipt. It stores no Pi presentation claim or Pi session entry. `workflow_messages` owns those facts, and the extension reports the active Pi branch after reload.
 
 ## Content-addressed values
 
@@ -158,19 +160,56 @@ state-changing child messages.
 
 Insertion verifies the digest, media type, byte length, and exact bytes. Repeated content adopts the existing row. This replaces separate artifact files while keeping outputs, errors, settled Pi entries, and rendered channel text deduplicated. Automatic retention and explicit prune remove unreferenced blobs after they delete safe old run trees. They retain each blob referenced by a database foreign key or active runner transfer.
 
-Runs do not store a nested `WorkflowRunState` blob. `runs` stores run-level facts and hashes for independent values. `run_sources` stores source identity without source JSON blobs. `node_attempts` stores structured workflow outputs and small execution receipts. `session_entries` is the only stored copy of each settled Pi entry. `attempt_entries` links an attempt to its prompt, response, first, and last Pi entries. `run_steps` stores ordered attempt membership and only stores an output override when a continuation changes a carried checkpoint answer.
+Runs do not store a nested `WorkflowRunState` blob. `runs` stores run-level facts and hashes for independent values. `run_sources` stores source identity without source JSON blobs. `node_attempts` stores structured workflow outputs and small execution receipts. `session_entries` is the only stored copy of each settled Pi entry. `attempt_entries` links an attempt to its prompt, response, first, and last Pi entries. `run_steps` stores ordered attempt membership. Each completed checkpoint keeps its own accepted output.
 
-Readers derive `steps`, `outputs`, `results`, carried-step count, current-node fields, waiting state, source objects, and continuation decision receipts from these rows. Compact trace events do not copy prompts, node outputs, run inputs, final outputs, action receipts, or assistant receipts.
+Readers derive `steps`, `outputs`, `results`, current-node fields, waiting state, source objects, and accepted decision receipts from these rows. Compact trace events do not copy prompts, node outputs, run inputs, final outputs, action receipts, or assistant receipts.
 
 The run store reads each independent value through its declared media type. Input and final output use JSON readers. Run errors and presentation instructions use text readers. Terminal-message construction uses one typed terminal-data result instead of guessing the blob type. A missing or wrong media type fails presentation after the terminal state commits; it cannot roll back that state.
 
+### State verification
+
+`state status` reports invariant violations with the affected run IDs. `state verify`
+and inactive-backup verification check the same facts after SQLite integrity and
+foreign-key checks. They detect terminal queue mismatches, waiting runs without
+responses, pending requests on inactive attempts, missing accepted submissions,
+invalid active clocks, and conflicting Pi turns. Verification does not repair
+state or create replacement work.
+
+Queued, starting, running, and parked queue phases can coexist with live execution
+states during admission and response validation. They are not contradictions by
+themselves. A pending settlement effect also explains a terminal result whose queue
+has not yet settled. Expired claims remain recovery facts, not proof of completed
+work.
+
+### Active execution time
+
+`node_attempts.started_at` is historical data and never changes. `timeout_ms`
+stores the resolved active-time budget: SQL `NULL` means not yet configured,
+zero means explicitly unlimited, and a positive value is the budget in milliseconds.
+The public contract uses `null` for an unlimited timeout.
+
+`attempt_active_intervals` records numbered active intervals in the same database.
+Only one interval can be open for an attempt. Each interval keeps its start,
+last observation, end, and measured elapsed time. The host measures duration with
+a monotonic clock and saves samples during normal polling. Wall-clock changes
+cannot spend or restore the active budget. Pause, disconnect, and settlement close
+the interval. Reconnect opens another interval only for an unpaused, active model
+turn. Duplicate starts and overlapping inactive causes cannot count time twice.
+
+After a crash, recovery closes an open interval at its last durable observation.
+It does not charge the unobserved gap or server downtime. At most the time since
+the last sample is uncounted. Human decision expiry remains an absolute wall-clock
+deadline. Step start and finish timestamps remain wall-clock history, separate
+from the active-time budget. Interval rows follow their attempt through existing
+foreign-key retention and backup rules.
+
 ### Assistant-message attempts
 
 An agent definition records `expectedOutput` as either a submitted-output description or `{ "kind": "assistant-message", "maxChars"?: number }`. Omitted `maxChars` means that Pi Workflows adds no character limit.
 
 A completed interactive assistant-message attempt stores the accepted visible text as its node output. Its small receipt keeps the text digest, final Pi session entry ID, optional author-supplied limit, and whether recovery adopted an existing response.
 
-An interrupted assistant-message attempt keeps its attempt ID. The extension adopts a matching durable request and existing Pi branch entry instead of displaying the prompt or accepting the response twice. Submitted and non-agent attempts use a fresh execution attempt after an uncommitted runner exit.
+An interrupted assistant-message attempt keeps its attempt ID. The extension adopts a matching durable request and existing Pi branch entry instead of displaying the prompt or accepting the response twice. A submitted agent request also retains its exact attempt while waiting, validating, or recovering an accepted receipt. A declared execution retry creates a new attempt; transport recovery does not.
 
 ## Write contract
 
@@ -202,7 +241,7 @@ A TypeScript write permit carries the expected facts between layers. It is not a
 
 Reading or finding a row never gives write authority.
 
-- A run owner may advance the run, apply automatic decision policy, create its continuation, settle its parent, and complete its queue work.
+- A run owner may advance the exact run, apply its declared automatic decision policy, and settle its queue work.
 - A resource manager claim owner may update resource manager status, reserve effects, and start child workflows for that resource.
 - A verified human channel actor may submit one answer candidate for the named decision. It does not gain run ownership.
 - The server-owned channel adapter path may update only its channel cursor, decision delivery and settlement records, and exact managed effects.
@@ -221,18 +260,18 @@ A deadline with a validated default response is timeout-policy acceptance. It ca
 
 Late or repeated commands return or adopt the durable winner. They do not overwrite it.
 
-The same rule applies to run terminal outcomes, continuation admission, queue settlement, resource manager effects, retry scheduling, channel settlement, and workflow-turn reports through their domain constraints and expected revisions. A matching turn report adopts the saved ownership result. A different report for the same turn ID remains a conflict.
+The same rule applies to run terminal outcomes, exact-request acceptance, queue settlement, resource manager effects, retry scheduling, channel settlement, and workflow-turn reports through their domain constraints and expected revisions. A matching turn report adopts the saved ownership result. A different report for the same turn ID remains a conflict.
 
 ## Read contract
 
 Durable status is a pure projection of domain rows, immutable facts, current leases, effect results, and exact workflow-turn start and end reports. The server uses these facts to produce one live run view. An open workflow turn can change display status only. It cannot change workflow authority. Every renderer consumes the server-produced display status and allowed controls without running another status reducer.
 
-A settings scope uses its resource revision as its public change number. Each accepted patch, current value, and node binding is saved in one transaction. A checkpoint continuation keeps the same settings resources and transfers them to the continuation run.
+A settings scope uses its resource revision as its public change number. Each accepted patch, current value, and node binding is saved in one transaction. A checkpoint resumes in the same run and keeps the same settings resources.
 
-`workflow_follow_ups` records source acceptance order, removal, and cancellation. The source and message stay attached to the continuation-chain member that accepted them; rows are not rewritten when the chain continues. The server walks the chain to find its final outcome. `workflow_messages` owns message state and Pi entry evidence. Failure, timeout, and cancellation cancel unsent follow-up messages.
+`workflow_follow_ups` records source acceptance order, removal, and cancellation. The source and message stay attached to the run that accepted them. The server uses that run's outcome; an explicit restart does not retarget the prompt. `workflow_messages` owns message state and Pi entry evidence. Failure, timeout, and cancellation cancel unsent follow-up messages.
 
 - A terminal run fact overrides stale message state and has no open workflow turn.
-- An accepted decision is accepted even if its continuation effect is still pending.
+- An accepted decision stays accepted while the scheduler waits for execution capacity.
 - A cancelled decision is cancelled even if parent cleanup is still pending.
 - A stale owner is not shown as current.
 - An ambiguous external effect is shown as unresolved.
@@ -249,9 +288,9 @@ This contract is for local storage on one machine. It does not claim distributed
 
 ## Automatic retention
 
-The server keeps terminal root-run trees for 30 days from `finished_at`. A tree is eligible only when every restart or continuation descendant is terminal, older than the cutoff, free of protected work, and free of references from outside the tree.
+The server keeps terminal root-run trees for 30 days from `finished_at`. A tree is eligible only when every restart descendant is terminal, older than the cutoff, free of protected work, and free of references from outside the tree.
 
-Automatic cleanup keeps a tree when it has a waiting or parked run, a live queue row, a pending workflow message, an open workflow turn, a pending interaction or human decision, a recording session segment, a queued follow-up, an active lease, an unsettled effect, controller ownership, an active runner content hash, a resumable checkpoint, an undelivered terminal result, or a continuation or step reference from outside the tree. Unknown or conflicting ownership also blocks deletion.
+Automatic cleanup keeps a tree when it has a waiting or parked run, a live queue row, a pending workflow message, an open workflow turn, a pending interaction or human decision, a recording session segment, a queued follow-up, an active lease, an unsettled effect, controller ownership, an active runner content hash, a resumable checkpoint, an undelivered terminal result, or a run or step reference from outside the tree. Unknown or conflicting ownership also blocks deletion.
 
 The server requests cleanup after startup recovery and after workflow runners exit. It also schedules the next daily check after a completed sweep. Overlapping requests use one in-process task. Cleanup starts only while there is no active or pending workflow runner, resource-manager runner, state-maintenance command, or shutdown. One server process completes no more than one sweep in 24 hours. A due sweep that finds work active or stops between trees remains due. The next idle lifecycle trigger or a five-minute idle retry continues it.
 

package/docs/WORKFLOW_SERVER.md

@@ -115,6 +115,16 @@ Claim rejection uses `ClaimLostError` with one internal reason:
 
 Logs may show the run ID, generation, and reason. They must not show a raw token or token hash.
 
+## Worker scheduling
+
+`WorkflowRunQueueStore` in `src/workflows/queue.ts` owns run reservations, queue state, and execution claims. `SqliteResourceManagerStore` owns managed resources and reconcile state, not workflow scheduling. The host is the only reconciliation runtime; the separate `ResourceManagerRuntime` API has been removed. Reconcile results and failure requeues commit atomically, and a worker that loses its claim cannot write a failure or start a retry. They share the existing SQLite connection and revision helpers; neither introduces another database.
+
+One scheduler admits workflow runners and resource-manager reconciles. Start and restart reserve a queued run; resume makes existing work eligible. Accepted responses, validation candidates, and expired interactive deadlines use the same admission path. Requests remain durable while capacity is full.
+
+The default capacity is four execution workers. Set `PI_WORKFLOWS_MAX_WORKERS` to a positive integer before starting the host to change it. Embedded test hosts can use `WorkflowServer({ maxWorkers })`. Capacity includes pending launches and live workers. The scheduler alternates workflow and resource-manager admissions when both have work. Claim renewal, cancellation, and cleanup do not wait for an execution slot.
+
+An interactive run holds its origin-session reservation while queued, running, waiting, or paused. Independent headless runs do not reserve a Pi session. Only terminal completion or explicit cancellation releases an interactive reservation.
+
 ## Run lifecycle
 
 The run and queue projections follow these states:
@@ -259,15 +269,16 @@ Each history page has both an item limit and an encoded byte budget. Oversized v
 
 The closed `display.status` set is `queued`, `running`, `waiting`, `paused`, `completed`, `failed`, `timed_out`, `cancelled`, and `ambiguous`.
 
-The server computes effective status in this order:
+The server keeps execution status separate from worker and Pi activity:
+
+1. A durable terminal result keeps its terminal label, including during reporting or cleanup. An unresolved external effect still exposes a review action.
+2. A nonterminal run with an ambiguous external effect is `ambiguous`.
+3. A durable pause is `paused`, even while its worker or Pi turn stops.
+4. A pending request is `waiting`. Its kind determines the response action: `submit` and `update` for an agent, `answer` for an ordinary checkpoint, `human-answer` for a protected decision, and no tool completion action for a visible-response request.
+5. Otherwise, active worker or Pi execution is `running`.
+6. Parked resumable work or admitted work that has not started is `queued`.
 
-1. A durable ambiguous external effect that requires explicit review is `ambiguous`. An effect that is still applying under a live runner is not ambiguous.
-2. A live supervised runner or an exact active origin-session workflow turn is `running`.
-3. A durable terminal result keeps its terminal label after its presentation turn ends.
-4. A durable pause is `paused` after its active Pi turn ends.
-5. A pending interaction, decision, or presentation with no exact active turn is `waiting`.
-6. Parked resumable work with no pending interaction is `queued`.
-7. Admitted work that has not started is `queued`.
+`display.activity` reports the supervised worker or exact Pi turn independently. Waiting alone never permits an answer. Command handlers check the exact request again before they change state.
 
 Server connection failure is the client condition `unavailable`, not a `display.status` value. `paused` is never inferred from a parked queue, pending interaction, stale cursor, or missing activity report.
 
@@ -383,7 +394,7 @@ Active-branch absence is usable only when the branch has no matching ID, Pi is i
 
 The extension subscribes to the active origin-session live run view and projects it into Pi's documented widget and status APIs. It never opens SQLite, runs workflow code, or derives a display status. `Shift+Up` and `Shift+Down` scroll the widget. When Herdr is available, the widget also shows `Ctrl+Shift+R piw`, and `/piw` remains the command fallback. Both actions open or focus the exact run from the same view.
 
-A tool update or submission goes to the server. It includes the exact request, node, attempt, expected revision, and tool-call idempotency key. The server first checks this transport contract and records a provisional `validating` submission. It then schedules a supervised workflow child. Only that child loads workflow code and runs the node's `validate` function. The child reports `interaction.accepted` or `interaction.rejected` to the server. The server settles the request only after acceptance. A rejected payload leaves the same request pending and returns the stored actionable error to the model. If the child stops before it reports a result, the server rejects the provisional submission and leaves the request ready for a corrected retry.
+A tool update or submission goes to the server with an exact `requestId`, the tool-call idempotency key, and the current origin-session coordinator authority. The server resolves the immutable node and attempt from that request. It checks session ownership and request kind before receipt lookup or mutation. An identical submission can adopt its saved result after settlement. A new submission records a provisional `validating` candidate. It then schedules a supervised workflow child. Only that child loads workflow code and runs the node's `validate` function. The child reports `interaction.accepted` or `interaction.rejected` to the server. The server settles the request only after acceptance. A rejected payload leaves the same request pending and returns the stored actionable error to the model. If the child stops before it reports a result, the server rejects the provisional submission and leaves the request ready for a corrected retry.
 
 An ordinary checkpoint accepts the model-facing `answer` action and starts a continuation run. A protected human decision never accepts that tool action. The extension displays the decision without starting a model turn, and a person answers it with `/workflow answer` through `decision.answer`. When a protected decision reaches its saved `onTimeout` deadline, the server takes a control claim on the waiting parent, atomically records the validated default, closes the pending interaction, releases the parent claim, and reserves the continuation. A human answer cannot win after that deadline.
 
@@ -397,7 +408,7 @@ A notify node creates a passive `notification` message in the same transaction a
 
 A run with headless execution mode uses the existing `pi --mode rpc` integration for agent steps. The Pi child uses a separate process group registered with the server. The runner stops that group during normal completion. Cancellation gives the runner a bounded cleanup interval, and the server reaps the registered group if the runner exits first.
 
-The headless child receives only the workflow step prompt, configured model arguments, and the bridge extension. Its submission uses the same step and attempt contract as origin-session work. A headless run cannot use a visible assistant-message step because it has no origin Pi session.
+The headless child receives only the workflow step prompt, configured model arguments, and the bridge extension. Its submission uses the same exact request contract as origin-session work. A headless run cannot use a visible assistant-message step because it has no origin Pi session.
 
 The run binding records `interactive` or `headless` execution mode. Viewers show that mode without exposing provider credentials.