@osolmaz/pi-workflows 0.16.1 → 0.16.2

package/dist/workflows/types.d.ts

@@ -44,9 +44,7 @@ export type WorkflowEffectRecovery = "idempotent" | "manual";
 export type WorkflowManagedEffect = {
     /** Stable external effect category, for example `github.comment`. */
     type: string;
-    /** Stable key. Idempotent adapters must pass this key to the external system. */
-    idempotencyKey: string | ((context: WorkflowNodeContext) => MaybePromise<string>);
-    /** Canonical request data used to reject key reuse with another operation. */
+    /** Canonical request data used to reject engine-owned key reuse with another operation. */
     request: unknown | ((context: WorkflowNodeContext) => MaybePromise<unknown>);
     /** `manual` never retries after an uncertain child exit. */
     recovery: WorkflowEffectRecovery;

package/docs/2026-09-04-workflow-run-state-plan.md

@@ -0,0 +1,363 @@
+---
+title: Unify workflow run state
+author: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
+date: 2026-09-04
+status: implemented
+---
+
+# Unify workflow run state
+
+## Goal
+
+Several Pi Workflows failures appeared together after the out-of-process host change. A provider error left old workflow-turn ownership behind. A composed workflow reused an effect key. Restart treated a failed run as a checkpoint continuation. Terminal code read a text error as JSON. That read error blocked cancellation, while the host repeatedly started a worker that could not make progress.
+
+These failures have the same architectural cause. Important facts are inferred in more than one place. Local node names stand in for compiled identities. A parent run ID stands in for the kind of child run. Callers guess the type of stored data. Process activity stands in for workflow progress. Presentation work can determine whether a control command commits.
+
+The approved design gives each fact one owner and one typed path. The compiler and engine create execution identities. The host state store commits workflow state. A worker executes one explicit run command. The Pi extension delivers messages and reports public Pi events. Renderers display the host view.
+
+This plan replaces the narrower workflow-turn ownership plan. It keeps that fix and adds the effect, restart, terminal-data, cancellation, and worker-retry work needed to remove the shared cause.
+
+## User requirements
+
+- Use the most direct, long-term design instead of separate guards for each symptom.
+- Keep one global out-of-process host as the normal state writer.
+- Keep one client protocol and one production runtime.
+- Use documented Pi extension APIs only.
+- Do not change Pi core or Pi session schemas.
+- Keep schema version 1 and make an alpha hard cut. Do not add migrations, compatibility readers, dual paths, fallbacks, or feature flags.
+- Preserve strict ownership and uniqueness checks.
+- Do not claim exactly-once behavior for model calls or external systems.
+- A paused workflow must remain pausable and cancellable after any earlier run failure.
+
+## Confirmed causes
+
+### Composed effects lose their full node path
+
+`manualEffect()` and `idempotentEffect()` derive a key from `state.currentNode`. Workflow composition projects the state into a child workflow before it evaluates that key. The projection changes a compiled path such as `documentation/workspace/inspect` back to the local name `inspect`.
+
+The outer workspace check and the documentation workspace check therefore shared the run ID and visit number. They also shared the effect type and local node name. Their requests differed, so the effect store correctly rejected the second request with `Managed effect key was reused with another request`.
+
+### Restart uses checkpoint continuation
+
+The run queue records whether a child is a `continuation` or a `restart`. The worker bootstrap receives only `parentRunId`. It calls `continueRun()` for every child with a parent.
+
+`continueRun()` requires a parent that is waiting at a checkpoint. A failed terminal run does not meet that contract. A restart must begin at the workflow start with fresh graph and effect state.
+
+### A failed ancestor error is read with the wrong type
+
+Run errors are stored as text. `terminalAncestorOutcomes()` reads an ancestor `error_hash` with `readJson()`. The blob exists, but its media type is text. The generic database error says that the JSON blob is missing or has the wrong media type.
+
+Terminal-message creation calls this reader. As a result, the error can block child failure handling and cancellation.
+
+### A worker can restart forever without progress
+
+When an uninitialized worker exits, the host parks and claims the same run again. The failed restart never changes its saved workflow revision, but the host keeps launching it. The UI reports `running` because a process is active even though the workflow makes no progress.
+
+### Presentation can roll back control state
+
+Cancellation and terminal-message creation currently share a transaction path. If terminal-message creation cannot read its source data, the cancellation fails too. A display failure must not keep execution authority alive.
+
+## Design
+
+### Clear responsibilities
+
+The compiler assigns complete node paths. The engine uses those paths to identify logical work. Child workflows can receive a local view of inputs and outputs, but that local view cannot replace the compiled identity.
+
+The host state store owns every durable transition. Host orchestration code asks the store to start, pause, finish, cancel, or recover work. It does not update lifecycle tables directly.
+
+The worker receives one explicit command and executes it. It does not infer the command from nullable fields.
+
+The Pi extension keeps only temporary state for the current Pi turn. A host response decides whether that turn belongs to a workflow.
+
+Renderers use the host view. They do not infer workflow progress from process presence, messages, or local timers.
+
+### Complete execution identity
+
+Each logical node visit has a stable identity made from:
+
+- the run ID;
+- the full compiled node path;
+- the visit number.
+
+The visit number is the count for that exact compiled node path. A crash retry of the same unfinished visit keeps the same number. Re-entering the node later gets the next number.
+
+The engine derives managed-effect identity from this logical node visit and the effect type. The projected child context is still used to calculate the effect request, but it is not used to calculate internal identity.
+
+Workflow authors no longer provide the internal effect key. If an external API needs its own idempotency key, the action sends that external key as part of the request to that API. Internal execution identity and an external API key are separate facts.
+
+The effect store keeps its request fingerprint check. Reusing one logical effect identity with a different request remains a hard conflict.
+
+### One run command
+
+The host sends the worker one tagged command:
+
+- `start` begins a root run.
+- `resume` continues the same interrupted run from saved state.
+- `continue` creates a child from an accepted waiting checkpoint.
+- `restart` creates a fresh child after a terminal result.
+
+The worker handles this command with one exhaustive switch. Invalid combinations fail before workflow code runs.
+
+A restart uses the same approved workflow definition and requested input, but it begins at the first node. It does not copy parent steps, outputs, results, open interactions, settings mutations, or effect reservations. The parent run ID and root run ID remain saved as history. The saved history also includes the restart number and terminal fingerprint.
+
+A continuation remains the only path that carries checkpoint state forward. It requires a waiting parent and the exact accepted decision or submission.
+
+The engine should expose one internal entry point that accepts this tagged command. The superseded parent-ID heuristic is removed in the same alpha change.
+
+### One durable transition interface
+
+The existing run store becomes the only interface used by host orchestration for durable run changes. It can use focused internal modules, but callers see typed operations rather than SQL or booleans.
+
+The interface covers:
+
+- starting and ending exact workflow turns;
+- reserving and settling exact effects;
+- starting, pausing, and resuming runs;
+- finishing and timing out runs;
+- cancelling runs;
+- preparing continuations and restarts;
+- recording worker failure and recovery state.
+
+Each operation checks the run generation and claim token in one transaction. It also checks the expected revision and run state against the exact resource identity. It returns one of these results:
+
+- `applied` with the new saved value;
+- `adopted` with an equal saved value;
+- `conflict` with the conflicting evidence;
+- `recoveryRequired` with the saved reason.
+
+A boolean result is not sufficient for a lifecycle change. Callers must know whether another path already completed the same change or whether the request conflicts with current state.
+
+### Workflow-turn ownership
+
+`workflowTurn.report` remains the single version-1 operation for Pi model turns.
+
+At Pi `agent_start`, the extension proposes the exact sent workflow message and a stable turn request ID. The host atomically returns an active turn or reports that no workflow owns the Pi turn. The extension starts workflow recording only after an active result.
+
+At Pi `agent_end`, the extension ends the exact active turn. Matching repeated reports return the saved result. Conflicting evidence remains an error.
+
+When a run becomes terminal, the same state transaction ends its remaining open turns as `lost` and cancels still-pending workflow messages. A late report cannot revive the run. If a connection closes at an uncertain point, the extension does not attach the next Pi turn. The existing branch and idle report lets the host settle an unproved open turn as `lost`.
+
+### Typed run data
+
+Run input and final output are JSON. Run error and presentation instructions are text. Code reads them through named store methods:
+
+- `readRunInput()`;
+- `readRunFinalOutput()`;
+- `readRunError()`;
+- `readPresentationInstructions()`;
+- `readTerminalFacts()`.
+
+Callers do not read these blob hashes directly. `readTerminalFacts()` is the only source for terminal messages and ancestor outcomes. It checks media types and returns one typed result.
+
+The underlying content-addressed blob store remains general. The run store owns the meaning of each run column.
+
+### Control state before presentation
+
+Finishing or cancelling a run commits its execution state first. That transaction saves the final status and ends open turns. It cancels pending interactions and messages before it releases the claim. It also records the terminal facts needed for presentation.
+
+Terminal Pi-message creation is an idempotent follow-up transition derived from those saved facts. A host restart can create a missing terminal message later. A presentation error is recorded for repair, but it cannot undo the terminal state or retain execution authority.
+
+This separation applies to completion, failure, timeout, and cancellation.
+
+### Retry only after progress
+
+Every worker launch records the run revision it received. A normal worker exit reports a typed outcome to the host. Known bootstrap and workflow errors include the phase and error text.
+
+If a worker process disappears without a report, the host compares the current run revision with the launch revision. It may resume automatically only when durable progress or a saved recovery transition changed that revision.
+
+If no revision changed, the host parks the run with the worker failure and stops automatic launch. The user can inspect, cancel, or explicitly resume it. This rule has no arbitrary retry count. The same unchanged state is never executed in a tight loop.
+
+The display reports `running` only while one accepted worker or origin-session turn is doing current work. A parked no-progress failure reports its recovery reason.
+
+## State and protocol changes
+
+This is an alpha hard cut in schema and protocol version 1. The implementation must not add a version-2 identifier or a compatibility path.
+
+Expected changes include:
+
+- a tagged worker run command in the existing worker protocol;
+- full compiled node identity for managed effects;
+- typed results for lifecycle transitions and turn reports;
+- typed run-data readers;
+- durable no-progress worker failure evidence if the existing event records cannot express it without inference.
+
+Prefer existing tables and event records when they express the contract directly. If the durable no-progress rule requires a new column or constraint, change version-1 DDL in place. An old database then fails before mutation with the standard backup-and-reset instruction.
+
+Existing structurally valid state can use normal terminal and idle-session reconciliation. Do not add migration code to repair old table shapes.
+
+## Implementation plan
+
+### Freeze the failures in tests
+
+Add focused tests that reproduce the current behavior before changing it:
+
+- Mount workspace preparation directly and again under documentation, then prove the current automatic effect key collides.
+- Restart a failed workflow and prove the worker selects checkpoint continuation.
+- Build terminal ancestry with a failed parent and prove ancestor reading uses the wrong media type.
+- Cancel a child of a failed run and prove presentation failure rolls back cancellation.
+- Crash an uninitialized worker without a revision change and prove the host repeatedly claims it.
+- End a workflow turn during a terminal race and prove a later ordinary Pi turn can inherit old ownership.
+
+The final versions of these tests must assert the corrected behavior. Do not preserve assertions for the defects.
+
+### Move execution identity into the engine
+
+Change managed-effect identity in `src/workflows/definition.ts`, `src/workflows/composition.ts`, `src/workflows/engine.ts`, and the related types.
+
+The compiled engine passes the full node path and visit number to effect reservation. Child-context projection remains limited to workflow-authored request and action functions. Remove the old automatic key calculation from projected `state.currentNode`.
+
+Update authoring docs and all built-in workflows in the same change. Keep no alias for the old internal key contract.
+
+### Make worker commands explicit
+
+Add the tagged run command to `src/host/worker-protocol.ts`, the host bootstrap response, and `src/host/worker-entry.ts`.
+
+Replace the `initialized` and `parentRunId` dispatch heuristic with an exhaustive command switch. Add the engine path for a fresh restart and keep checkpoint continuation separate. Remove the superseded dispatch code.
+
+### Centralize durable transitions
+
+Move direct lifecycle SQL from `src/host/runner.ts` into typed store operations in the state and workflow-store modules. Replace ambiguous boolean returns used by run failure and cancellation with typed results.
+
+Keep claim fencing and revision checks in each state transaction. The runner handles process supervision and protocol routing only.
+
+### Fix terminal state and cancellation
+
+Add the typed run-data readers and use `readTerminalFacts()` for the current result and every ancestor result. Remove direct JSON reads of error hashes.
+
+Commit terminal control state independently from terminal-message creation. Add idempotent reconciliation for a terminal run that has no terminal workflow message.
+
+After this change, the currently paused failed-child case must cancel without a database reset.
+
+### Finish workflow-turn ownership
+
+Implement the approved host-owned turn contract in the state store and host runner. Apply it to the extension coordinator and session view. Then connect it to recorder integration.
+
+A terminal run must have no open workflow turn. A later ordinary Pi turn must produce no workflow-turn report for the terminal run.
+
+### Stop no-progress worker loops
+
+Add structured worker exit reports for all caught bootstrap and execution failures. Save the launch revision and compare it on an unreported exit.
+
+Park an unchanged run with a clear recovery reason. Resume automatically only after a newer durable revision makes another launch meaningful.
+
+### Remove old paths
+
+Delete:
+
+- effect keys derived from projected local node names;
+- restart dispatch based only on `parentRunId`;
+- direct error-hash JSON reads;
+- lifecycle SQL in host orchestration where a typed store operation replaces it;
+- cancellation paths that depend on successful terminal presentation;
+- automatic relaunch of the same unchanged worker state;
+- extension turn ownership that has not been accepted by the host.
+
+Do not keep feature flags or fallback behavior.
+
+### Update documentation
+
+Update `WORKFLOW_HOST.md`, `SQLITE_STATE.md`, and `workflows.md` after implementation so they describe the shipped interfaces and recovery behavior. Keep this plan as the decision and implementation record.
+
+## Tests
+
+### Composition and effects
+
+- Two mounts of the same action receive different full execution identities.
+- A crash retry of one unfinished node visit reuses its identity.
+- A later loop visit receives a new identity.
+- The same identity and request adopts the saved effect.
+- The same identity with another request returns a controlled conflict.
+
+### Run commands
+
+- Root start begins at the first node.
+- Resume uses the same run and saved current node.
+- Continuation accepts only a waiting checkpoint parent and carries the approved state.
+- Restart accepts a terminal parent and begins with no parent steps, outputs, results, or effects.
+- Invalid command and state combinations fail before workflow code runs.
+
+### Terminal state
+
+- Completed, failed, timed-out, and cancelled ancestors produce typed terminal facts.
+- A text error is never passed to `readJson()`.
+- Cancellation commits even when terminal presentation is forced to fail.
+- A later reconciliation creates the missing terminal message once.
+- Terminalization ends open turns and pending interactions in the same state transaction.
+
+### Worker recovery
+
+- A worker crash after a newer durable revision resumes safely.
+- A worker crash at the same revision parks once and does not relaunch.
+- A known bootstrap error becomes a saved failure instead of a process loop.
+- The widget and `piw` show the same parked reason.
+
+### Pi turn ownership
+
+- A provider error ends the exact accepted turn.
+- Repeated and reordered reports return saved results or controlled conflicts.
+- A terminal race cannot leave an open turn.
+- Reconnect settles an unproved turn as `lost`.
+- A later ordinary Pi message creates no workflow turn or workflow recorder.
+
+### Full regression
+
+Run Autoimplement with its direct workspace preparation and nested Autodoc workspace preparation. Force the first run to fail after a managed action. Restart it and then pause and cancel it. Prove that effect identities do not collide and restart begins cleanly. Also prove that terminal facts remain readable and cancellation commits without a worker loop.
+
+Automated tests use temporary directories and deterministic providers. They do not call a real model.
+
+## Acceptance criteria
+
+- One component owns each identity and state decision.
+- Included workflows cannot collide because they share local node names.
+- Restart and checkpoint continuation cannot enter each other's engine path.
+- Every run column is read with its declared data type.
+- Control commands remain effective when presentation fails.
+- A worker cannot relaunch unchanged state indefinitely.
+- A terminal run has no open workflow turn.
+- Later ordinary Pi turns cannot attach to terminal workflow work.
+- No raw SQLite uniqueness or media-type error reaches normal recovery paths.
+- Host, extension, widget, CLI, Herdr, and `piw` agree on run activity.
+- Pi core and private Pi APIs remain unchanged. Pi session schemas also remain unchanged.
+- One host and one database remain. The system keeps one client protocol and one production runtime.
+
+## Verification
+
+Run:
+
+```bash
+npm run check
+npm run test:e2e
+npm run test:e2e:live -- --runtime-only
+git diff --check
+npx slophammer-ts@latest dry .
+npx slophammer-ts@latest check . --only ts.dependency-boundaries-required
+npx -y @simpledoc/simpledoc check
+cargo test --manifest-path tui/Cargo.toml
+cargo clippy --manifest-path tui/Cargo.toml --all-targets --all-features -- -D warnings
+cargo fmt --manifest-path tui/Cargo.toml --check
+```
+
+After deterministic checks pass, install the built package locally. Run a clean no-op workflow. Then run the composed Autoimplement regression and a forced provider-error recovery check. Confirm the widget and `piw` status at each stage. Use a real model only for the final manual installed-package check, with an explicit provider and model selected by the operator.
+
+Run Pi Reviewer against `main` until no P0 or P1 finding remains. Check pull-request comments and CI before merge.
+
+## Scope
+
+The implementation may change Pi Workflows engine, compiler, worker protocol, host state methods, extension coordination, viewer projection, built-in workflows, tests, and documentation in this repository.
+
+## Non-goals
+
+- No Pi core or private Pi API changes.
+- No Pi session schema changes.
+- No new service, database, state root, or production runtime.
+- No operating-system service installation.
+- No migration or compatibility path for older alpha state.
+- No release or package publication as part of implementation.
+- No exactly-once claim for provider calls or external effects.
+
+## Assumptions
+
+- Pi continues to provide the documented extension lifecycle events and session APIs.
+- The host remains the only production process that opens live SQLite state.
+- A package update can require the documented backup and reset when version-1 DDL changes.
+- External systems remain responsible for their own stable idempotency keys or read-back checks.

package/docs/SQLITE_STATE.md

@@ -104,7 +104,7 @@ A domain row and its event are written in one transaction. Normal APIs never upd
 
 `effect_attempts` records each application attempt and ownership generation. A matching repeated request adopts the existing effect. A different request under the same key is a conflict.
 
-Local effects use deterministic transactions. Run queue settlement effects are created only for runs that have a `run_queue` row; direct engine and controller-child runs do not create phantom queue work. External effects use provider idempotency or observation when available. An uncertain result becomes `ambiguous` and is not repeated without evidence.
+Local effects use deterministic transactions. For workflow action nodes, the engine creates the idempotency key from the run ID, effect type, full compiled node path, and node visit number. A projected child-workflow view cannot replace that full identity. Run queue settlement effects are created only for runs that have a `run_queue` row; direct engine and controller-child runs do not create phantom queue work. External effects use provider idempotency or observation when available. An uncertain result becomes `ambiguous` and is not repeated without evidence.
 
 Telegram delivery and settlement use these shared effect records. The host records one numbered attempt before it tells the supervised adapter child to act. A confirmed result stores Telegram message references in the effect result. `channel_messages` stores the decision feature's delivery or settlement receipt; it does not copy effect state or external message references.
 
@@ -125,11 +125,13 @@ The shared records do not replace domain schemas. The following `STRICT` tables
 | Human decisions     | `human_decisions`, `human_decision_resolutions`, `human_decision_submissions`, `continuations`                               |
 | Controllers         | `controller_resources`, `controller_finalizers`, `controller_queue`, `controller_workflows`                                  |
 | Effects             | `effects`, `effect_attempts`                                                                                                 |
-| Pi messages         | `workflow_messages`                                                                                                          |
+| Pi messages         | `workflow_messages`, `workflow_turns`                                                                                        |
 | Channels            | `channels`, `channel_cursors`, `channel_messages`                                                                            |
 
 `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_turns` stores the host-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 host 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, controllers, 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.
@@ -158,6 +160,8 @@ Runs do not store a nested `WorkflowRunState` blob. `runs` stores run-level fact
 
 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.
 
+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.
+
 ### 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.
@@ -215,7 +219,7 @@ 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, controller effects, retry scheduling, and channel settlement through their domain constraints and expected revisions.
+The same rule applies to run terminal outcomes, continuation admission, queue settlement, controller 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
 
@@ -225,7 +229,7 @@ A settings scope uses its resource revision as its public change number. Each ac
 
 `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 host 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.
 
-- A terminal run fact overrides stale message state.
+- 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.
 - A cancelled decision is cancelled even if parent cleanup is still pending.
 - A stale owner is not shown as current.

package/docs/WORKFLOW_HOST.md

@@ -1,6 +1,6 @@
 # Workflow host
 
-Status: the out-of-process host, unified live client, workflow-message contract, and restored session behavior are implemented. [Unify workflow messages and restore hosted behavior](2026-09-02-unify-workflow-messages-plan.md), [run workflows outside Pi](2026-08-30-out-of-process-workflow-host-plan.md), [restore workflow session delivery and controls](2026-09-01-restore-session-delivery-controls-plan.md), and [unify live workflow clients](2026-09-01-unified-workflow-client-plan.md) record the design and implementation plans.
+Status: the out-of-process host, unified live client, workflow-message contract, and restored session behavior are implemented. [Unify workflow run state](2026-09-04-workflow-run-state-plan.md) records the approved refactor for turn ownership, managed effects, restarts, terminal data, cancellation, and worker recovery. [Unify workflow messages and restore hosted behavior](2026-09-02-unify-workflow-messages-plan.md), [run workflows outside Pi](2026-08-30-out-of-process-workflow-host-plan.md), [restore workflow session delivery and controls](2026-09-01-restore-session-delivery-controls-plan.md), and [unify live workflow clients](2026-09-01-unified-workflow-client-plan.md) record the earlier design and implementation plans.
 
 ## Purpose
 
@@ -133,6 +133,8 @@ The run and queue projections follow these states:
 
 A lifecycle transaction updates the run, queue, attempt, decision, lease, event, and viewer facts that belong to one transition. The database must not commit a failed event while the run remains running, or a terminal queue row while the run remains nonterminal.
 
+A terminal state commits before the host builds its terminal workflow message. Missing or invalid presentation data can prevent that message, but it cannot roll back completion, failure, or cancellation. The host schedules another attempt and also finds missing terminal messages when it starts, so repaired presentation data can produce the same terminal message later.
+
 Waiting and paused work does not keep a worker or a live claim. Resume takes a new claim generation and starts a new worker from the last durable boundary.
 
 ## Worker lifecycle
@@ -162,6 +164,8 @@ A worker launch envelope contains:
 
 Before it loads workflow modules, the worker verifies the root identity and every saved mounted file hash or built-in revision. After loading, it also checks the complete mounted-source map against the saved map. A mismatch parks the run with `workflowSourceChanged`. The normal scheduler does not claim that run again. The operator can restore the recorded source and explicitly resume the run, or cancel it. Changed included code does not execute.
 
+After the ready message, the host sends one explicit command: `start`, `resume`, `continue`, or `restart`. A continuation names its waiting checkpoint parent. A restart begins a new run from the workflow start. The worker never infers the command from a nullable parent ID.
+
 The host records a worker epoch before spawn. The child must return a ready message before the startup deadline. Every later child message includes the run ID, generation, and worker epoch.
 
 The host records one terminal worker outcome:
@@ -173,7 +177,7 @@ The host records one terminal worker outcome:
 - `claimLost`
 - `orphaned`
 
-A worker exit is not automatically a run failure. The host decides from the last committed attempt and effect state whether it can resume, must park, or must fail.
+A worker exit is not automatically a run failure. The host decides from the last committed attempt and effect state whether it can resume, must park, or must fail. If the saved run revision did not advance after the worker became ready, the host parks the run with `workerNoProgress` and does not claim it again automatically. An explicit resume can make one new attempt after the operator corrects the cause.
 
 ## Process supervision
 
@@ -365,7 +369,11 @@ The coordinator waits until Pi is idle and has no queued user input, keeps the m
 
 After a send, the coordinator waits for the matching Pi entry and reports the active branch so the host records its entry ID and marks the message `sent`. Branch evidence marks a matching message `sent` even if its source cancelled it after the send. If Pi emits `agent_start` before that report or before the session view loads, the coordinator buffers the start and matching end, records the message first, and then reports the turn events in order.
 
-Active-branch absence is usable only when the branch has no matching ID, Pi is idle, and Pi has no pending messages. If Pi or the extension disappears after the send call but before inspection, the message stays `pending`. A replacement extension reports the branch before another send. Documented Pi APIs do not prove cross-branch absence or exactly-once model execution.
+The host alone decides whether that Pi model turn belongs to the workflow message. `workflowTurn.report` returns a version-1 receipt with `active`, `settled`, or `absent` ownership and the exact saved turn when one exists. The extension exposes workflow activity and starts session capture only after an `active` receipt. It clears its temporary copy after settlement, rejection, or disconnect. Every new Pi `agent_start` replaces any older local copy and requires fresh host acceptance before the turn can become workflow work.
+
+Turn start and end use the exact message, run, session, and turn IDs. A matching repeat adopts the saved result. A conflicting repeat remains an error. When a run becomes terminal, the same transaction ends its open turns as `lost` and cancels pending step and decision messages. Failure and cancellation also cancel pending follow-ups. A committed notification stays eligible for delivery. A late matching end report adopts that terminal cleanup. A terminal run cannot start another step turn, and a later ordinary Pi turn cannot inherit its old workflow ownership.
+
+Active-branch absence is usable only when the branch has no matching ID, Pi is idle, and Pi has no pending messages. If Pi or the extension disappears after the send call but before inspection, the message stays `pending`. A replacement extension reports the branch before another send. The idle branch report settles an unproved open host turn as `lost`. Documented Pi APIs do not prove cross-branch absence or exactly-once model execution.
 
 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.
 
@@ -427,7 +435,7 @@ Side-effecting action and shell behavior must have one of these contracts:
 - a managed effect with a read-back check that proves whether it applied;
 - an explicit non-resumable result that becomes `ambiguous` after an uncertain crash.
 
-The host reserves an effect before execution. The effect key includes the source resource, effect type, and author-provided idempotency key. The request fingerprint prevents key reuse with another payload.
+The host reserves an effect before execution. The engine creates the idempotency key from the run ID, effect type, full compiled node path, and node visit number. Workflow code provides the effect type and request, but it does not provide this internal key. Included workflows can use the same local node name without sharing a key. The request fingerprint prevents key reuse with another payload.
 
 An applied, rejected, or cancelled effect is terminal. An ambiguous effect is also terminal for automatic retry. An operator may use a separate reviewed recovery action after inspecting the external system.
 
@@ -444,7 +452,8 @@ Controller reconcile code runs in a supervised controller worker, not in the hos
 Use separate states and messages for these failures:
 
 - `claimLost`: another generation owns the run, or the claim expired.
-- `workerCrashed`: the child exited without a terminal protocol message.
+- `workerCrashed`: the child exited without a terminal protocol message after it saved progress.
+- `workerNoProgress`: the child exited before the saved run revision advanced and needs explicit resume or cancellation.
 - `workerTimedOut`: the child exceeded a declared deadline.
 - `hostUnavailable`: the client cannot reach or start the host.
 - `sourceChanged`: the workflow source does not match the saved identity.

package/docs/workflows.md

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

package/herdr-plugin.toml

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osolmaz/pi-workflows",
-  "version": "0.16.1",
+  "version": "0.16.2",
   "description": "Workflow and controller runtime with a live terminal viewer for the pi coding agent",
   "keywords": [
     "pi-package"

package/src/client/view.ts

@@ -3,6 +3,8 @@ import type { WorkflowMessage, WorkflowTurn } from "../state/workflow-messages.j
 
 export const RUN_VIEW_SCHEMA = "pi-workflows.run-view.v1" as const;
 export const SESSION_VIEW_SCHEMA = "pi-workflows.session-view.v1" as const;
+export const WORKFLOW_TURN_REPORT_RECEIPT_SCHEMA =
+  "pi-workflows.workflow-turn-report-receipt.v1" as const;
 
 export type WorkflowDisplayStatus =
   | "queued"
@@ -142,6 +144,12 @@ export type WorkflowBranchReport = {
   hasPendingMessages: boolean;
 };
 
+export type WorkflowTurnReportReceipt = {
+  schema: typeof WORKFLOW_TURN_REPORT_RECEIPT_SCHEMA;
+  ownership: "active" | "settled" | "absent";
+  turn: WorkflowTurn | null;
+};
+
 export type WorkflowTurnReport =
   | {
       state: "started";