@osolmaz/pi-workflows 0.13.4 → 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/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.

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

@@ -0,0 +1,357 @@
+---
+title: Workflow terminal decision and restart plan
+author: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
+date: 2026-08-27
+---
+
+# Full plan
+
+## Goal
+
+After every top-level workflow run ends, give the model one normal successor turn.
+
+That turn contains the workflow result and terminal reason. The model uses the conversation it already has to decide whether to:
+
+- stop because the user’s task is complete
+- restart the same workflow as a new run
+- start Monitor for an authorized external wait
+- ask the user for a required decision or authority
+- take another safe authorized action
+
+The system does not save or identify the original user message. It does not restart automatically. It gives the model one clear decision opportunity and makes safe retry the default for unfinished work after technical failures.
+
+## Shared terminal behavior
+
+The shared terminal message must include:
+
+- workflow name and revision
+- terminal run ID
+- exact workflow input
+- workflow result
+- terminal state
+- terminal reason
+- restart count
+- earlier terminal outcomes in the same restart chain
+
+The message must tell the model:
+
+> A workflow run ended, but that does not prove the user’s task is complete. Use the current conversation and this result to decide what to do next. If the task is unfinished because of an unexpected technical or temporary failure, prefer a safe restart. Stop if the work is complete, the user cancelled it, new authority is required, the user must make a decision, or the same failure has repeated. Use Monitor only for an authorized external wait.
+
+Use the term **result**, not “durable result.”
+
+## Implementation steps
+
+### 1. Build one shared terminal-decision message
+
+**Where**
+
+- `src/extension/deferred-turn.ts`
+- Add `src/extension/terminal-decision.ts` if a separate pure module keeps the code smaller.
+
+**Change**
+
+Add a pure builder that reads the existing run record and produces the shared terminal facts and prompt.
+
+It must not read, copy, hash, or store an original user message.
+
+Use the existing stored workflow input and result. Apply the existing output-size rules to large results, but always include the run ID, state, reason, and restart history.
+
+**Verification**
+
+Unit tests must cover completed, failed, timed-out, maxSteps, cancelled, and blocked results.
+
+### 2. Create one terminal turn for every top-level run
+
+**Where**
+
+- `finishRun` in `src/extension/index.ts`
+- `src/extension/deferred-turn-coordinator.ts`
+- Existing turn-intent state in `src/controllers/sqlite.ts`
+
+**Change**
+
+Create one terminal turn intent when a top-level interactive run reaches a terminal state.
+
+Normal presentation and fallback delivery must compete for the same intent. The first successful delivery settles it. Every later delivery attempt becomes a no-op.
+
+Do not create this turn for:
+
+- waiting checkpoints
+- controller child runs
+- internal helper runs that already report to an owner
+
+**Verification**
+
+Race tests must prove that presentation, fallback, reload recovery, and crash recovery produce one model turn, not two.
+
+### 3. Replace the current terminal presentation instruction
+
+**Where**
+
+- `buildPresentationMessage`
+- `buildDeferredTurnContent`
+- Related presentation helpers in `src/extension/index.ts`
+
+**Change**
+
+Remove the current instruction that says the model must not call the workflow tool.
+
+Replace it with the shared decision instructions. The terminal turn must permit one workflow launch selected by the model.
+
+Completed runs still get a result turn. A workflow state of `completed` does not always mean the larger user task is complete. For example, the result can say that work is blocked.
+
+Explicit human cancellation must default to stopping.
+
+**Verification**
+
+Tests must prove that the model can select restart or Monitor during the terminal turn and that ordinary completed work does not cause an automatic restart.
+
+### 4. Add a generic restart action
+
+**Where**
+
+- `src/workflows/tool-input.ts`
+- Workflow tool registration, schema, help text, and control switch under `src/workflows/`
+- Restart handling in `src/extension/index.ts`
+
+**Contract**
+
+```json
+{
+  "action": "restart",
+  "runId": "terminal-run-id"
+}
+```
+
+**Change**
+
+The action must:
+
+1. Read the terminal run.
+2. Confirm that it belongs to the current session.
+3. Confirm that it is terminal.
+4. Reuse the exact workflow reference, input, and safe launch settings.
+5. Create a new immutable run.
+6. Record the restart relationship.
+7. Leave the old run unchanged.
+
+Reject restart when:
+
+- the run is active or waiting
+- the run is unknown
+- the run belongs to another session
+- the run was explicitly cancelled
+- the workflow source or revision is no longer available
+- the restart limit was reached
+- the same terminal failure already repeated
+
+A later explicit user request can still use normal `start`.
+
+**Verification**
+
+Tool-schema and extension tests must prove exact input reuse, immutable old runs, session checks, source checks, and correct rejection behavior.
+
+### 5. Permit one selected launch during the terminal turn
+
+**Where**
+
+- `queueToolLaunch`
+- presentation tracking in `src/extension/index.ts`
+- `agent_settled`
+- existing queued-launch recovery
+
+**Change**
+
+The current presentation guard rejects workflow launches. Add one narrow exception for the active terminal-decision turn.
+
+The model can reserve one of these:
+
+- restart
+- Monitor
+- another workflow start
+
+The reservation must not activate until the model turn settles. A second workflow launch from the same terminal turn must fail.
+
+Other tool calls remain subject to their normal rules.
+
+**Verification**
+
+Tests must prove that:
+
+- one launch can be reserved during presentation
+- it starts only after `agent_settled`
+- a second launch is rejected
+- reload after reservation does not lose it
+- crash recovery does not start it twice
+
+### 6. Add bounded restart lineage
+
+**Where**
+
+- Add `src/extension/restart-policy.ts`
+- Existing run launch-options JSON and accessors
+- No new database table
+
+**Change**
+
+Store this information for restarted runs:
+
+- root run ID
+- parent run ID
+- restart number
+- parent terminal fingerprint
+
+A terminal fingerprint is a stable hash of:
+
+- workflow identity and revision
+- exact input
+- terminal state
+- canonical result or error
+- canonical terminal reason
+
+Do not include timestamps or new run IDs in the fingerprint.
+
+Allow at most three restart actions after the original run. This permits at most four runs in one chain.
+
+If a terminal fingerprint occurs again in the same chain, reject another restart immediately. If the result changes because the workflow made progress, another restart can remain eligible until the total limit is reached.
+
+Starting Monitor does not consume a restart.
+
+**Verification**
+
+Tests must cover:
+
+- first technical retry
+- progress followed by a different failure
+- repeated identical maxSteps failure
+- three-restart limit
+- Monitor selection
+- restart history after database reopen
+
+### 7. Make restart reservation idempotent
+
+**Where**
+
+- Existing effect records
+- Existing run queue and reservation code
+- Terminal turn-intent settlement code
+
+**Change**
+
+Key the selected launch to the source terminal turn intent and tool call.
+
+If the host repeats the same tool call after a crash or reload, return the existing reservation or new run instead of creating another one.
+
+The terminal turn intent, launch reservation, and resulting run must have one inspectable chain.
+
+**Verification**
+
+Inject failures after:
+
+- turn-intent claim
+- launch reservation
+- run creation
+- terminal response settlement
+
+After recovery, there must still be one terminal message and one successor run.
+
+### 8. Document the contract
+
+**Where**
+
+- `docs/workflows.md`
+- `docs/SQLITE_STATE.md`
+- Workflow tool reference and examples
+- Relevant README text
+
+**Change**
+
+Document:
+
+- the shared terminal decision turn
+- the `restart` action
+- the difference between a workflow ending and the user’s task finishing
+- retry defaults and limits
+- Monitor selection
+- explicit cancellation behavior
+- top-level versus child-run behavior
+- recovery and duplicate prevention
+- that conversation context remains owned by Pi
+- that Pi Workflows does not capture or persist an original user message
+
+No workflow definition needs an opt-in or terminal restart step.
+
+## Contract changes
+
+- The workflow tool gains `restart`.
+- Every top-level terminal run owns one terminal turn intent.
+- Restart always creates a new run.
+- Restart reuses the exact prior workflow input.
+- The model makes the continuation decision from the current conversation.
+- Restart is preferred, not forced, for unfinished work after technical or temporary failures.
+- Explicit cancellation, missing authority, required user decisions, repeated failures, and completed work stop.
+- Restart lineage uses existing run launch data.
+- No new store, service, controller, or Pi API is added.
+- No original-message provenance contract is added.
+
+## Test plan
+
+Add regression coverage for:
+
+1. Successful completion produces one result turn and no automatic restart.
+2. A blocked result from a completed workflow lets the model select restart.
+3. Failed, timed-out, and maxSteps runs offer restart.
+4. Explicit cancellation is not restartable through the shortcut.
+5. Waiting checkpoints do not produce a terminal turn.
+6. Controller child runs do not produce competing turns.
+7. Presentation and fallback races produce one turn.
+8. Restart uses the exact workflow reference and input.
+9. Restart leaves the prior run unchanged.
+10. Monitor starts through the normal start path.
+11. A selected launch waits for `agent_settled`.
+12. Reload and crash recovery do not duplicate turns or runs.
+13. The same terminal failure cannot repeat indefinitely.
+14. A chain cannot exceed three restarts.
+15. No new code captures, hashes, or stores an original user message.
+16. The maxSteps failure that caused this incident produces a terminal decision turn instead of silently ending the task.
+
+Run the full repository checks:
+
+```bash
+npm run check
+npm run test:e2e
+npx slophammer-ts@latest dry .
+npx slophammer-ts@latest check . --only ts.dependency-boundaries-required
+```
+
+## Main risks
+
+- **The model restarts completed work.**
+  Make stopping the default for successful results and enforce restart limits.
+
+- **A retry repeats external effects.**
+  Include the prior result and restart history so the model can inspect the current state before it retries.
+
+- **Presentation and fallback both fire.**
+  Make both settle the same turn intent.
+
+- **A launch starts while the terminal response is still active.**
+  Reserve it first and activate it after `agent_settled`.
+
+- **A temporary outage causes a loop.**
+  Use Monitor for external waits, stop repeated fingerprints, and allow only three restarts.
+
+## Boundaries
+
+Do not:
+
+- modify Pi core or private APIs
+- store or identify an original user message
+- add restart nodes to individual workflows
+- modify Autoimplement, Monitor, or other workflow definitions
+- create a new controller, database, service, or daemon
+- bypass cancellation, checkpoints, reviews, CI, authority, or safety rules
+- add compatibility shims or parallel state contracts
+- release or deploy anything as part of this plan
+
+This is the selected plan.