@osolmaz/pi-workflows 0.13.3 → 0.14.0

package/docs/DEFERRED_TURNS.md

@@ -1,8 +1,8 @@
 # Deferred workflow turns
 
-This specification defines how Pi Workflows schedules one successor agent turn after a workflow event stops or strands the current turn. It covers cancellation, timeout, terminal failure, launch failure, controller interruption, and claim loss.
+This specification defines how Pi Workflows schedules one successor agent turn after a workflow event stops or strands the current turn. It covers every top-level interactive terminal result, cancellation, timeout, launch failure, controller interruption, and claim loss.
 
-The implementation plan is [Guarantee one successor turn after workflow interruption](plans/2026-08-21-deferred-turn-intents-plan.md).
+The implementation plans are [Guarantee one successor turn after workflow interruption](plans/2026-08-21-deferred-turn-intents-plan.md) and [Workflow terminal decision and restart](plans/2026-08-27-workflow-terminal-restart-plan.md).
 
 ## Terms
 
@@ -18,10 +18,10 @@ The implementation plan is [Guarantee one successor turn after workflow interrup
 Each eligible source event creates at most one turn intent. Exactly one of these message paths can resolve it:
 
 1. a workflow agent prompt;
-2. a completed or waiting result presentation;
+2. a result presentation;
 3. a factual fallback.
 
-All three paths claim the same intent before sending. A resolved intent cannot start another turn.
+Every top-level interactive terminal run owns one intent. Its presentation and fallback claim that same intent before sending. A waiting presentation can resolve an earlier interruption intent, but waiting state does not create a terminal intent. A resolved intent cannot start another turn.
 
 Cancellation and process termination remain immediate. Pi Workflows does not keep the old assistant turn alive and does not wait for the successor before stopping active work.
 
@@ -56,25 +56,25 @@ Resolution records message delivery into the Pi session or the presence of the s
 Valid causes are:
 
 ```text
-agentCancelled | timedOut | failed | launchFailed | controllerInterrupted | claimLost
+agentCancelled | timedOut | failed | launchFailed | controllerInterrupted | claimLost | terminal | cancelled
 ```
 
 The event policy is:
 
-| Event                                                          | Intent                                                 | Fallback rule                                                                          |
-| -------------------------------------------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------- |
-| Agent calls `workflow cancel` during an active workflow turn   | Create before `ctx.abort()` when storage is available. | Make eligible after durable terminal cancellation.                                     |
-| Agent step times out                                           | Create before `ctx.abort()` when storage is available. | Keep ineligible while a recovery prompt can arrive. Make eligible on terminal timeout. |
-| Active workflow turn ends in terminal failure                  | Create or reuse the abort intent.                      | Make eligible after durable terminal failure.                                          |
-| Workflow reports started, then crashes before its first prompt | Create after durable failure.                          | Create as eligible.                                                                    |
-| Queued launch activation fails                                 | Create after the queue row is durably failed.          | Create as eligible.                                                                    |
-| Controller interrupts an active workflow turn                  | Create before the turn abort when possible.            | Durable terminal or handoff state decides eligibility.                                 |
-| Active workflow turn loses its queue claim                     | Create before the turn abort when possible.            | Keep ineligible while a new owner can continue.                                        |
-| Completed or waiting result has a presentation                 | Do not create a new intent.                            | Resolve an existing intent through presentation.                                       |
-| Direct `/workflow cancel`                                      | Do not create.                                         | No automatic model turn.                                                               |
-| Workflow pause                                                 | Do not create.                                         | No automatic model turn.                                                               |
-| User Escape or held workflow                                   | Do not create.                                         | No automatic model turn.                                                               |
-| Session shutdown                                               | Do not create.                                         | A closing session cannot start another turn.                                           |
+| Event                                                          | Intent                                        | Fallback rule                                                                |
+| -------------------------------------------------------------- | --------------------------------------------- | ---------------------------------------------------------------------------- |
+| Top-level interactive run completes                            | Create one terminal intent.                   | Presentation and factual fallback compete for the intent.                    |
+| Top-level interactive run fails or times out                   | Create or reuse the abort intent.             | Make eligible after the terminal state is durable.                           |
+| Agent or user cancels a top-level run                          | Create before turn abort when needed.         | Make eligible after durable cancellation; the decision defaults to stopping. |
+| Workflow reports started, then crashes before its first prompt | Create after durable failure.                 | Create as eligible.                                                          |
+| Queued launch activation fails                                 | Create after the queue row is durably failed. | Create as eligible.                                                          |
+| Controller interrupts an active workflow turn                  | Create before the turn abort when possible.   | Durable terminal or handoff state decides eligibility.                       |
+| Active workflow turn loses its queue claim                     | Create before the turn abort when possible.   | Keep ineligible while a new owner can continue.                              |
+| Waiting result has a presentation                              | Do not create a terminal intent.              | It can resolve an earlier interruption intent through presentation.          |
+| Controller child or internally owned run ends                  | Do not create a terminal intent.              | Its owner receives the result.                                               |
+| Workflow pause                                                 | Do not create.                                | No automatic model turn.                                                     |
+| User Escape or held workflow                                   | Do not create.                                | No automatic model turn.                                                     |
+| Session shutdown                                               | Do not create.                                | A closing session cannot start another turn.                                 |
 
 A terminal failure after a successful start tool result is eligible even when it did not first call `ctx.abort()`. This rule covers asynchronous runtime validation and startup failures that the user can see in the UI but the model cannot see in its current context.
 
@@ -232,10 +232,22 @@ The message type is `pi-workflows-deferred-turn`. Delivery uses:
 }
 ```
 
-The visible content reports observed facts and asks the agent to inspect durable state before it decides whether an authorized correction is needed. It does not claim that recovery occurred, resume the old run, or retry work.
+For a terminal run, the visible content contains the workflow identity and revision, terminal run ID, exact stored input, bounded result, terminal state and reason, restart count, and earlier terminal outcomes in the chain. It tells the model to use the current conversation, prefer a safe restart for an unfinished task after a technical or temporary failure, and stop for completed work, cancellation, missing authority, a required user decision, or a repeated failure. Values from input and result are data, not instructions.
+
+The content comes only from existing run and queue records. Pi owns conversation history. Pi Workflows does not identify, hash, copy, or store an original user message.
 
 Fallback delivery is disabled during session shutdown and while a user-interrupted workflow is held.
 
+## Selected launch and restart
+
+A terminal decision turn can reserve at most one workflow launch: `restart`, Monitor through normal `start`, or another workflow through normal `start`. The reservation records the source terminal intent, model tool call, and request fingerprint in the new run's existing launch options. It does not activate before `agent_settled`.
+
+Repeating the same tool call adopts the existing reservation or run. A different launch from the same terminal intent fails. Session-start and queue recovery activate a surviving reservation once when the session is idle.
+
+`restart` accepts the terminal run ID. It checks session ownership, terminal state, explicit cancellation, source identity and revision, repeated failure, and the restart limit. It creates a new immutable run from the exact stored reference, input, and safe launch settings. The old run does not change.
+
+Restart lineage in launch options records the root run ID, parent run ID, restart number, and parent terminal fingerprint. The fingerprint covers workflow identity and revision, exact input, terminal state, canonical result or error, and terminal reason. It excludes timestamps and run IDs. The same fingerprint cannot restart twice in one chain. A chain permits three restarts after the original run. Starting Monitor does not add restart lineage.
+
 ## Delivery recovery
 
 Every resolving message includes the intent ID in its custom-message details.
@@ -262,7 +274,7 @@ Pending `launch_failure` rows from the earlier alpha contract are incompatible.
 
 ## Post-completion follow-ups
 
-Deferred turns repair one stranded workflow turn after interruption. Ordered post-completion prompts are different. They represent user-requested normal work after successful completion, use `workflow_follow_up_queues` and `workflow_follow_ups`, and are delivered by the separate follow-up coordinator. Neither feature reads or changes the other's rows.
+Deferred turns provide the terminal decision before ordered post-completion prompts. Those prompts represent user-requested normal work after successful completion, use `workflow_follow_up_queues` and `workflow_follow_ups`, and are delivered by the separate follow-up coordinator after the terminal intent is resolved. Neither feature reads or changes the other's rows.
 
 See [Continue normal work after a workflow finishes](2026-08-25-workflow-follow-ups.md).
 
@@ -293,12 +305,13 @@ This is an alpha hard cutover.
 
 An implementation conforms when:
 
-- one eligible source event produces at most one intent;
-- one intent produces at most one successor message;
-- an agent self-cancel receives one fallback after settlement;
+- every top-level interactive terminal run produces at most one intent and one decision message;
+- an agent self-cancel and a direct cancellation receive one fallback after settlement;
 - an asynchronous crash after a successful start result receives one fallback after settlement;
 - a natural recovery prompt or presentation suppresses fallback by resolving the same intent;
-- direct cancellation, pause, Escape, user hold, and shutdown produce no automatic turn;
+- waiting checkpoints, controller children, internal owners, pause, Escape, user hold, and shutdown do not create terminal turns;
 - claim transfer permits natural resolution by the new owner and prevents stale writes;
-- polling, restart, lease expiry, and send-before-resolution failure do not duplicate turns;
+- one terminal turn reserves at most one launch and activates it after `agent_settled`;
+- exact replay adopts the same launch, while reload, lease expiry, and send-before-resolution failure do not duplicate turns or runs;
+- restart keeps the prior run immutable, preserves exact input, rejects cancellation and repeated fingerprints, and stops after three restarts;
 - passive workflow notifications keep their current behavior.

package/docs/HUMAN_DECISIONS.md

@@ -322,19 +322,23 @@ 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.
+
 ## 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. 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 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.
 
 The engine remains independent from Pi and Telegram. Core code owns decision contracts, validation, durable acceptance, and continuation. The Pi extension owns UI and channel lifecycle. The Telegram adapter 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. The private channel index remains rebuildable.
+- **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. It adds no new persistent shape. The private channel index remains rebuildable.
 - **Pi internals:** none.
 - **Public Pi API:** documented extension lifecycle and UI methods only.
-- **Public pi-workflows API:** typed human choices, `humanDecision().onTimeout`, `humanDecisionEdge()`, the channel interface, the plan approval policy, and the shared plan-change workflow.
+- **Public pi-workflows API:** typed human choices, `humanDecision().onTimeout`, `humanDecisionEdge()`, the channel interface, the plan approval policy, the shared plan-change workflow, and the additive queue prepare-or-adopt operation.
 
 ## Verification requirements
 
@@ -350,6 +354,10 @@ The implementation must test:
 - unauthorized users and chats;
 - 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;
 - identical and conflicting retries;
 - crashes before and after answer acceptance and continuation creation;
 - ambiguous Telegram sends;
@@ -357,4 +365,4 @@ The implementation must test:
 - 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.
+- real Pi execution without real Telegram credentials or network calls, duplicate-start failures, revision conflicts, or a stranded running continuation.

package/docs/SQLITE_STATE.md

@@ -111,6 +111,30 @@ The shared records do not replace domain schemas. The following `STRICT` tables
 
 Foreign keys join projects, runs, attempts, decisions, controllers, effects, and channel records. Partial unique indexes enforce one active node attempt per run, one queued or running reservation per Pi session, one decision winner, and one deterministic effect key. A parked waiting parent does not block its continuation. Reserving that continuation settles the parked parent queue in the same transaction, so a failed reservation leaves the parent recoverable.
 
+### Terminal restart state
+
+The [terminal workflow restart contract](plans/2026-08-27-workflow-terminal-restart-plan.md)
+uses the existing tables. It adds no state store or table. A restarted run keeps
+its root run ID, parent run ID, restart number, and parent terminal fingerprint
+in the existing launch-options value. The fingerprint uses the workflow
+identity and revision, exact input, terminal state, canonical result or error,
+and canonical reason. It excludes run IDs, timestamps, and other values that
+change between equivalent attempts.
+
+One terminal turn intent covers result presentation and factual fallback. A
+selected restart, Monitor run, or other workflow start uses the existing
+session reservation, run queue, and effect receipt. The successor run's launch
+options record the source terminal run, intent, model tool call, and canonical
+request fingerprint. A repeated call adopts that reservation or run. Activation
+waits for `agent_settled`, and normal queue recovery activates a surviving
+reservation once.
+
+Restart creates a new run. The terminal run remains unchanged. Restart lineage
+allows three restarts after the original run and rejects a repeated terminal
+fingerprint in the same chain. A Monitor selection records terminal selection
+but no restart lineage. Conversation history remains in Pi. This state does not
+identify, hash, copy, or store an original user message.
+
 ## Content-addressed values
 
 `blobs` stores canonical JSON and UTF-8 text as bytes. Its primary key is the 32-byte SHA-256 digest of the bytes.

package/docs/WORKFLOW_COMPOSITION.md

@@ -282,7 +282,7 @@ monitor
 
 ## Autoplan, autodoc, and autoimplement
 
-`autoplan` accepts the problem, scope, constraints, an optional previous plan, and new evidence. It records two through four practical candidates plus the ideal, automatically selects the best in-scope solution, and records one rejection reason for every other explicit candidate. It includes `plain-summary` on ready and blocked routes, so the user sees one short normal assistant response before the parent continues. The response calls the choice a plan selected for approval and cannot satisfy the later human decision. Autoplan exits through `ready` or `blocked` and returns the full candidates, selection, detailed plan when ready, plain summary, plan digest, and change status.
+`autoplan` accepts the problem, scope, constraints, an optional previous plan, and new evidence. Its `solutions` step records two through four practical candidates and asks whether each is a Long term elegant and production ready solution. Its `holyGrail` step describes the Holy grail separately. Its `select` step chooses the best in-scope option and records one rejection reason for every other explicit candidate, including the Holy grail. It includes `plain-summary` on ready and blocked routes, so the user sees one short normal assistant response before the parent continues. The response calls the choice a plan selected for approval and cannot satisfy the later human decision. Autoplan exits through `ready` or `blocked` and returns the full candidates, selection, detailed plan when ready, plain summary, plan digest, and change status.
 
 `autodoc` accepts an already selected plan or finds it in the active conversation and referenced canonical documents. It adopts current documentation or updates the canonical specification and implementation plan, runs documentation checks, and returns a documented-plan record. It never selects a solution or implements one.
 

package/docs/plans/2026-08-19-human-decision-gates-plan.md

@@ -52,6 +52,11 @@ Pi and Telegram implement one channel interface. Workflows address a named audie
 - Accept the first valid response with a no-replace write.
 - Adopt identical retries and reject conflicting responses.
 - Derive one continuation identity from the accepted decision.
+- Prepare that continuation through one atomic queue operation.
+- Let the first caller create and claim the queue row.
+- Let compatible concurrent or repeated callers adopt the row without changing its lease, claim generation, queue state, timestamps, or events.
+- Reject incompatible workflow source, definition, input, launch options, parent, or owning session without changing the existing row.
+- Give only the winning caller a claim token and permission to start the engine.
 - Reject stale responses by decision ID and canonical request digest.
 - Rebuild the pending-decision index from immutable records.
 
@@ -83,6 +88,10 @@ Pi and Telegram implement one channel interface. Workflows address a named audie
 - Promise exactly-once Telegram message creation after an ambiguous Bot API response.
 - Add arbitrary forms in the first release. Choice buttons and one text input cover the required flows.
 - Change existing checkpoints or historical run bundles.
+- Add a database field, table, migration, schema version, compatibility reader, or dual-write path for continuation startup.
+- Coordinate continuation startup with a process-local promise map, timing guard, retry loop, or swallowed error.
+- Change general queue claim behavior for unrelated launch paths.
+- Repair an already stranded live continuation as part of this change.
 - Enable human approval by default in existing built-in workflows.
 
 ## Design decisions
@@ -107,7 +116,13 @@ The Telegram adapter accepts replan text only as a reply to the exact `ForceRepl
 
 ### Make answer acceptance exact
 
-Channel delivery can be retried or fail independently. Decision acceptance is one atomic no-replace operation. The accepted response and deterministic continuation identity prevent two channels from starting two continuations.
+Channel delivery can be retried or fail independently. Decision acceptance is one atomic no-replace operation. The accepted response and deterministic continuation identity prevent two channels from selecting different continuations.
+
+### Prepare or adopt one continuation
+
+Direct answer handling and periodic recovery can both see the accepted decision. They use one continuation coordinator and one durable queue operation. The operation creates and claims a missing queue row or returns a compatible existing row as adopted. Only a newly claimed preparation can call `WorkflowEngine.continueRun()`.
+
+An adopted result is normal success. It does not start another engine or change the winning lease, claim generation, queue state, timestamps, or events. The adopter receives no claim token, so it cannot renew, release, park, complete, or replace the winning claim. Incompatible reuse fails without mutation. Existing cleanup handles failure before run initialization, and existing lease expiry and activation recovery handle a winning process that stops after preparation.
 
 ### Handle Telegram delivery limits honestly
 
@@ -171,10 +186,17 @@ A private SQLite index may track pending decisions, channel leases, Telegram upd
 - Validate the accepted response through the node contract.
 - Preserve the parent's original workflow input.
 - Expose the response as the checkpoint output.
-- derive and adopt the continuation identity; and
-- leave the legacy checkpoint path unchanged.
-
-Test crashes before acceptance, after acceptance, during continuation creation, and after continuation completion.
+- Derive the deterministic continuation identity.
+- Add a typed atomic prepare-or-adopt operation to the existing SQLite queue store.
+- Compare the stored workflow source, definition digest, input, launch options, parent, and owning session before adoption.
+- Build one prepared continuation value in the Pi extension.
+- Route direct verified answers and recovery through one continuation coordinator.
+- Start `WorkflowEngine.continueRun()` only with the new claim token.
+- Return normal started or already-continuing success to the answer path.
+- Keep enqueue and lease behavior unchanged for other launch paths.
+- Leave legacy checkpoint continuation unchanged.
+
+Test crashes before acceptance, after acceptance, during continuation creation, and after continuation completion. Add a focused race test for direct answer handling and recovery. It must prove one claim generation, one engine start, one continuation, one execution of each continuation node, coherent queue and run state, and no duplicate-start or revision-conflict failure. Add a real-Pi version of the same regression with a durable barrier instead of sleep-only timing.
 
 ### Channel management
 
@@ -248,7 +270,9 @@ The setup command uses an existing mode-`0600` token file instead of collecting
 - The workflow tool cannot answer a protected human decision.
 - Pi and Telegram can receive the same decision through one audience profile.
 - The first concurrent valid answer wins and creates one continuation.
-- An identical retry is adopted; a conflicting or stale answer is rejected.
+- Direct answer handling and recovery can race without starting it twice or replacing its lease.
+- The first queue preparation starts the engine, and a compatible repeat adopts it without mutation.
+- An incompatible continuation identity, conflicting answer, or stale answer is rejected without mutation.
 - The original workflow input survives a human-decision continuation.
 - Old checkpoints and old bundles pass their existing tests unchanged.
 - The Telegram adapter accepts text only from the bound reply and approved numeric actor.
@@ -267,6 +291,8 @@ npx vitest run test/human-decision-api.test.ts test/human-decision-store.test.ts
 npx vitest run test/human-decision-engine.test.ts test/run-resume.test.ts
 npx vitest run test/pi-decision-channel.test.ts test/telegram-decision-channel.test.ts
 npx vitest run test/plan-approval.test.ts test/composition.test.ts
+npx vitest run test/run-queue.test.ts test/extension.test.ts
+npx vitest run --config vitest.e2e.config.ts test/e2e/workflow.e2e.test.ts
 ```
 
 Run all repository gates before review:
@@ -290,7 +316,7 @@ This work adds compatible public APIs and additive persisted records. Release it
 ## Contract impact
 
 - **Session state:** normal workflow messages and interactive decision results.
-- **Other persistent data:** additive decision records, a rebuildable private channel index, and private channel configuration.
+- **Other persistent data:** additive decision records, a rebuildable private channel index, private channel configuration, and existing run queue and lease records. The continuation startup fix adds no persistent field, table, migration, or schema version.
 - **Pi internals:** none.
 - **Public Pi API:** documented extension lifecycle plus command and UI methods only.
-- **Public pi-workflows API:** typed human choices, `humanDecision()`, `humanDecisionEdge()`, the channel interface, and the `plan-approval` workflow.
+- **Public pi-workflows API:** typed human choices, `humanDecision()`, `humanDecisionEdge()`, the channel interface, the `plan-approval` workflow, and an additive queue prepare-or-adopt operation.