@osolmaz/pi-workflows 0.11.2 → 0.12.0

package/docs/plans/2026-08-21-autoimplement-timeout-fallback-plan.md

@@ -0,0 +1,242 @@
+---
+title: Add Autoimplement timeout fallback
+author: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
+date: 2026-08-21
+status: implemented
+---
+
+# Add Autoimplement timeout fallback
+
+Autoimplement must not exit only because one of its agent nodes reached a time limit. It must start one fallback step that inspects the work already done and chooses the safest existing workflow stage to run next.
+
+The `implement` node can take a long time. Increase its limit from 1 hour to 8 hours. Also add `timeoutMs: null` to the public workflow API so other workflows can explicitly disable a node's wall-clock timeout when that is the correct policy.
+
+Keep this graph fallback separate from deferred successor turns. The fallback starts after the timed-out turn has ended. It does not queue, revive, extend, or continue that turn.
+
+## Current behavior
+
+The current built-in Autoimplement workflow has these limits:
+
+- `implement`: 1 hour;
+- `finalizeDelivery`: 30 minutes;
+- omitted node timeout: the engine default of 15 minutes.
+
+A node timeout is recorded as `timed_out`. The engine can route this outcome through `$result.outcome`, but Autoimplement does not use that route. A timeout therefore ends the complete run.
+
+Two run bundles show the problem:
+
+- `20260820T180206Z-autoimplement-2df27615` timed out in `implement` after 3,600,000 ms.
+- `20260820T212618Z-autoimplement-06fcf309` timed out in `finalizeDelivery` after 1,800,000 ms.
+
+The bundles contain the timeout evidence. The missing part is a workflow route that lets an agent inspect the current state and choose what to do next.
+
+## Requirements
+
+### Timeout policy
+
+Extend `WorkflowNodeCommon.timeoutMs` to accept:
+
+```typescript
+number | null | ((context) => number | null | Promise<number | null>);
+```
+
+The values have these meanings:
+
+- omitted: use the engine's 15-minute default;
+- positive number: use that wall-clock deadline;
+- `null`: do not apply a wall-clock deadline.
+
+A callback that returns `null` has the same meaning as a fixed `null`. The existing 30-second limit for resolving a timeout callback still applies.
+
+A null timeout disables only elapsed-time expiry. Cancellation, pause, park, claim loss, host shutdown, late-submission rejection, active-attempt cleanup, and the node's `AbortSignal` keep their current behavior.
+
+Reject zero, negative numbers, `NaN`, infinity, strings, and other invalid values.
+
+### Autoimplement limits
+
+Set the built-in Autoimplement limits as follows:
+
+- `implement`: `8 * 60 * 60_000`;
+- `finalizeDelivery`: keep `30 * 60_000`;
+- all other explicit node limits: unchanged;
+- omitted node limits: keep the 15-minute engine default;
+- `maxSteps`: keep 240.
+
+The new null policy is a public capability. Autoimplement does not use null for `implement`; it uses the explicit 8-hour limit.
+
+### Timeout fallback
+
+Add one shared read-only fallback agent node to Autoimplement. Route supported agent-node `timed_out` outcomes to this node.
+
+The fallback receives:
+
+- the timed-out node ID, attempt ID, error, and prompt result record;
+- the approved plan and current task scope;
+- accepted outputs from earlier workflow steps;
+- the previous fallback results in the current run.
+
+The fallback must inspect:
+
+- the current repository worktree, branch, diff, and commits;
+- the remote branch and pull request, when they exist;
+- current review and CI state when they affect the next route;
+- merge and final-report state when delivery may already be complete.
+
+The fallback itself does not edit files, run a mutation, commit, push, open or update a pull request, post a comment, or merge. It only chooses the next workflow stage.
+
+Its bounded output must contain:
+
+```json
+{
+  "route": "retry | verify | review | ci | deliver | replan | blocked",
+  "reason": "why this is the safest next stage",
+  "evidence": ["state inspected before choosing the route"]
+}
+```
+
+The routes have these meanings:
+
+- `retry`: run the timed-out stage again because inspection shows that its work is incomplete;
+- `verify`: continue at the required verification stage because implementation work is ready;
+- `review`: continue at review because publication is complete for the current head;
+- `ci`: inspect CI because review is complete and CI is the next open stage;
+- `deliver`: run `finalizeDelivery` because delivery is the next open stage or its outcome is uncertain;
+- `replan`: enter the existing `redesign` Autoplan include because current evidence invalidates the approved plan;
+- `blocked`: stop because no safe route is available within the approved scope.
+
+Validate routes against the timed-out source. The fallback must not skip required implementation, verification, review, CI, authorization, or delivery checks.
+
+### Graph routing
+
+Use the existing `$result.outcome` interface. For each supported Autoimplement agent node:
+
+- `ok` follows its current success route;
+- `timed_out` routes to the shared fallback;
+- `failed` keeps normal failure behavior;
+- `cancelled` remains terminal and never enters fallback.
+
+The engine checks cancellation before outcome routing, so user cancellation stays immediate.
+
+A workflow node can have only one outgoing edge. When a successful node currently routes on its output, add a small pure compute router after the `ok` outcome. Keep compute nodes free of external effects.
+
+If an outcome switch needs an explicit `failed` case, route it to a pure failure node that throws the original persisted error. Do not turn ordinary failures into fallback events.
+
+### Bounded fallback
+
+Allow at most three fallback executions in one Autoimplement run. Count them from the durable step records, independently of `maxSteps`.
+
+After the third fallback, a later supported timeout must finish with the normal blocked result and include the timeout history. Do not run a fourth fallback.
+
+If the fallback node itself fails or times out, stop the run. Do not route the fallback back to itself.
+
+### Repeat only missing work
+
+A fallback can send the workflow back to a stage whose earlier attempt may have completed some effects. Consequential nodes must inspect their current state before they act again.
+
+At minimum:
+
+- implementation and fix steps inspect the current diff and commits before changing files;
+- `publish` checks whether the head is already pushed and whether the matching pull request already exists;
+- review reuses accepted review evidence only when it still matches the current head;
+- `finalizeDelivery` checks whether the expected head is already merged and whether the final report already exists.
+
+A repeated node performs only missing work. It must not create a duplicate commit, push, pull request, review, merge, or final report.
+
+## Implementation
+
+1. Update `src/workflows/types.ts` so fixed and computed node timeouts can be `null`.
+2. Update `src/workflows/schema.ts` to accept null and reject other invalid timeout values.
+3. Update `src/workflows/engine.ts` so a null timeout does not create an elapsed-time timer. Keep all abort and cleanup paths active.
+4. Update `src/workflows/store.ts` and `WorkflowNodeSnapshot` so a fixed null is written as `"timeoutMs": null`. Continue to omit timeout callbacks from snapshots.
+5. Set `implement.timeoutMs` to `8 * 60 * 60_000` in `src/builtins/autoimplement.workflow.ts`.
+6. Add the fallback output parser, fallback count guard, read-only fallback agent, deterministic route helpers, and terminal limit result to Autoimplement.
+7. Route supported `timed_out` outcomes to the fallback. Preserve success, failure, and cancellation behavior.
+8. Update consequential-node prompts so repeated attempts inspect state and perform only missing work.
+9. Increment the built-in Autoimplement revision from 5 to 6 in `src/builtins/catalog.ts`.
+10. Update `docs/workflows.md` and `docs/run-bundles.md` when implementation ships so public documentation matches the code.
+
+## Alpha cutover
+
+Keep these identifiers unchanged:
+
+- `pi-workflows.autoimplement.v1`;
+- `pi-workflows.definition-snapshot.v1`;
+- existing run-state, trace, and run-bundle v1 identifiers.
+
+Change their alpha contracts in place. Do not add a v2 schema, compatibility reader, migration, alias, dual route, or feature flag.
+
+Autoimplement revision 6 replaces revision 5. A revision-5 or older run must refuse resume through the existing source-change check. Reload or restart Pi to load the new built-in revision.
+
+## Tests
+
+Add tests for:
+
+- fixed `timeoutMs: null`;
+- a timeout callback that returns null;
+- omitted and numeric timeout behavior remaining unchanged;
+- invalid timeout values;
+- a null-timeout node completing after a short test default would have expired;
+- immediate cancellation of a null-timeout node;
+- fixed null in definition snapshots and callback omission;
+- Autoimplement's 8-hour `implement` limit and unchanged other limits;
+- successful routes remaining unchanged;
+- supported timeouts entering the fallback;
+- failed nodes keeping normal failure behavior;
+- cancellation bypassing fallback;
+- retry, verify, review, CI, delivery, replan, and blocked fallback routes;
+- rejection of a route that would skip a required stage;
+- the three-fallback limit;
+- fallback failure and timeout stopping without recursion;
+- no duplicate push, pull request, merge, or final report after a repeated stage;
+- revision 6 discovery and refusal to resume revision 5;
+- non-destructive real-Pi execution through the installed package path.
+
+Tests must use temporary directories and fake commands. They must not call a real model, mutate a real pull request, or write outside their temporary roots.
+
+## Acceptance criteria
+
+- Autoimplement `implement` can run for up to 8 hours.
+- Workflows can explicitly choose no wall-clock node deadline with `timeoutMs: null`.
+- A supported Autoimplement timeout starts the shared fallback instead of ending the run immediately.
+- The fallback inspects current state and chooses an existing safe stage without mutation.
+- Cancellation remains immediate and terminal.
+- Ordinary failures keep their current terminal behavior.
+- No run executes the fallback more than three times.
+- Repeated stages perform only missing work.
+- Deferred successor-turn behavior is unchanged and remains a separate design.
+- Autoimplement revision 6 is a hard alpha replacement for revision 5.
+- Documentation and tests match the shipped behavior.
+
+## Verification
+
+Run these checks before completion:
+
+```bash
+npm run check
+npm run test:e2e
+npx slophammer-ts@latest dry .
+npx slophammer-ts@latest check . --only ts.dependency-boundaries-required
+npx -y @simpledoc/simpledoc check
+git diff --check
+```
+
+Review the final diff to confirm that it preserves unrelated work on the current branch and does not mix deferred successor turns into timeout fallback.
+
+## Boundaries
+
+- Do not implement deferred successor turns as part of this work.
+- Do not queue, revive, or extend a timed-out turn.
+- Do not change Pi core or use undocumented Pi APIs.
+- Do not add a service, controller, daemon, timeout registry, effect database, or new persistence location.
+- Do not change external repository policy, CI configuration, provider APIs, or credentials.
+- Do not recover explicit cancellation.
+- Do not remove bounded limits from Autoimplement nodes.
+- Do not preserve compatibility with older alpha workflow revisions.
+
+## Contract impact
+
+- **Session state:** normal workflow messages, fallback prompts, and tool results only.
+- **Other persistent data:** fixed null timeout values and normal fallback node outputs in existing v1 run bundles.
+- **Pi internals:** none.
+- **Public Pi API:** existing documented extension APIs only.
+- **Public pi-workflows API:** `timeoutMs` gains explicit null support; existing agent, compute, and `$result.outcome` routing remain in use.

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

@@ -0,0 +1,324 @@
+---
+title: Guarantee one successor turn after workflow interruption
+author: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
+date: 2026-08-21
+---
+
+# Guarantee one successor turn after workflow interruption
+
+Pi Workflows can stop the active agent turn before the agent receives a tool result or can take its next action. This happens when an active workflow step is cancelled, times out, loses its queue claim, or is interrupted by a controller. The workflow can also return a successful start result and then fail asynchronously before it sends its first prompt. In that case, the user can see a UI error while the model still believes that the workflow started successfully.
+
+Add one general rule: an eligible workflow event creates one durable obligation for one later agent turn. The next normal workflow prompt or result presentation satisfies the obligation when one exists. Otherwise, Pi Workflows sends one factual fallback turn after the old turn settles.
+
+This plan replaces the earlier corrective-notification idea. A corrective message is one possible fallback. The underlying mechanism is a purpose-neutral successor-turn obligation.
+
+Related documents:
+
+- [Deferred workflow turns](../DEFERRED_TURNS.md)
+- [Make deferred workflow launches durable](../2026-08-20-durable-workflow-launch-plan.md)
+- [Route workflow reports to their starting session](2026-08-13-session-addressed-workflow-notifications-plan.md)
+- [Workflow authoring reference](../workflows.md)
+
+## Goals
+
+- Keep workflow cancellation and process termination immediate.
+- Give an agent that causes its own turn to stop one later normal turn when the Pi session remains available.
+- Give asynchronous workflow failures one model-facing turn when the start tool already returned success.
+- Let the next workflow prompt or presentation satisfy the obligation instead of sending a duplicate fallback.
+- Preserve the obligation across ordinary extension restart, polling, and delivery races.
+- Keep user Escape, pause, direct administrative cancellation, and session shutdown quiet.
+- Keep workflow recovery separate from turn delivery.
+
+## Non-goals
+
+- Do not keep the aborted assistant turn alive.
+- Do not return the cancel tool result to the aborted turn.
+- Do not retry a workflow node, resume a terminal run, or repeat an external mutation.
+- Do not add a workflow-engine primitive or a public workflow-author API.
+- Do not add a service, another database file, an external queue, or a controller.
+- Do not change Pi core or use a private Pi API.
+- Do not guarantee a turn after permanent process, session, machine, storage, or model-provider loss.
+- Do not treat message insertion as proof that the model started or completed a turn.
+- Do not include the separate Autoimplement node-timeout recovery change in this implementation.
+
+## Successor-turn rule
+
+A source event can create at most one `DeferredTurnIntent`. The intent starts pending and resolves once as one of:
+
+- `workflowPrompt`: the next workflow agent prompt was sent;
+- `presentation`: a completed or waiting result presentation was sent;
+- `fallback`: Pi Workflows sent a factual fallback message because no natural successor remained.
+
+The three paths compete for the same record. A successful claim by one path prevents the other paths from sending another turn.
+
+Fallback eligibility is separate from pending state. An intent can remain pending but ineligible while the workflow can still route to another agent step or presentation. Durable terminal or handoff evidence makes the intent eligible only when no immediate natural successor remains.
+
+## Event policy
+
+| Event                                                        | Create an intent | Initial fallback eligibility      | Notes                                                                                                     |
+| ------------------------------------------------------------ | ---------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| Agent calls `workflow cancel` during an active workflow turn | Yes              | No                                | Persist before `ctx.abort()`. Terminal cancellation makes it eligible.                                    |
+| Agent-step timeout                                           | Yes              | No                                | A later recovery prompt can resolve it naturally. Terminal timeout makes it eligible.                     |
+| Terminal workflow failure after an active turn abort         | Yes              | No                                | Terminal handling updates the existing intent and makes it eligible.                                      |
+| Workflow reports started, then crashes asynchronously        | Yes              | Yes, after durable failure        | Covers failures before the first workflow prompt, including invalid runtime input discovered after start. |
+| Queued launch activation fails                               | Yes              | Yes, after durable launch failure | Replaces the `launch_failure` notification trigger.                                                       |
+| Controller stops an active workflow agent turn               | Yes              | No                                | Terminal or handoff policy decides eligibility.                                                           |
+| Queue claim is lost during an active agent turn              | Yes              | No                                | Treat as ownership transfer, not failure.                                                                 |
+| Completed or waiting run has a presentation                  | No new intent    | Not applicable                    | The presentation resolves an existing intent when present.                                                |
+| Direct `/workflow cancel`                                    | No               | Not applicable                    | The user explicitly requested control and no automatic model turn.                                        |
+| Ordinary workflow pause                                      | No               | Not applicable                    | The current step stops only at its normal boundary.                                                       |
+| User Escape                                                  | No               | Not applicable                    | Keep the workflow held until explicit resume.                                                             |
+| Session shutdown                                             | No               | Not applicable                    | A closing session cannot run another turn.                                                                |
+
+A later distinct event can create a new intent. Repeated handling of the same source event must return the existing intent.
+
+## Storage
+
+Add `workflow_turn_intents` to the existing `SqliteControllerStore` database. Keep the database path and `pi-workflows.controller-store.v1` schema identifier.
+
+The existing `workflow_notifications` table remains a passive outbox for workflow-authored `progress` and `final` reports. It cannot represent this lifecycle clearly because it has one delivery transition and identifies node notification output. Adding natural resolution, fallback eligibility, and competing claims to that table would mix two different contracts.
+
+The intent table stores:
+
+| Field                       | Meaning                                                                                      |
+| --------------------------- | -------------------------------------------------------------------------------------------- |
+| `intent_id`                 | Deterministic primary key                                                                    |
+| `source_event_id`           | Stable identity of the event that requires a successor                                       |
+| `run_id`                    | Related workflow run                                                                         |
+| `workflow_ref`              | Workflow identity used in factual messages                                                   |
+| `target_session_id`         | Pi session that owns the successor turn                                                      |
+| `cause`                     | Closed event cause                                                                           |
+| `node_id`                   | Source node when known                                                                       |
+| `attempt_id`                | Source attempt when known                                                                    |
+| `fallback_facts_json`       | Bounded `pi-workflows.deferred-turn-facts.v1` camelCase facts used to build fallback content |
+| `requested_at`              | Time the obligation was created                                                              |
+| `eligible_at`               | Time fallback became eligible, or null                                                       |
+| `resolved_at`               | Time one path resolved the intent, or null                                                   |
+| `resolution`                | `workflowPrompt`, `presentation`, `fallback`, or null                                        |
+| `resolution_message_id`     | Stable custom-message identity for the resolving send                                        |
+| `delivery_claim_token`      | Current resolution claimant                                                                  |
+| `delivery_claim_expires_at` | Claim lease expiry                                                                           |
+
+Causes are:
+
+```text
+agentCancelled | timedOut | failed | launchFailed | controllerInterrupted | claimLost
+```
+
+The deterministic intent ID includes the target session, run, source event, source node or `$launch`, attempt when known, and cause. Reusing an ID with different immutable facts is an error.
+
+Store methods must support:
+
+- idempotent intent creation;
+- exact lookup;
+- a natural-resolution claim for one run and session;
+- an eligible fallback claim for one session;
+- fallback eligibility updates;
+- resolution with the matching claim token;
+- claim release and lease expiry;
+- bounded diagnostic listing.
+
+Every claim and resolution uses an immediate transaction or conditional update.
+
+## Abort handling
+
+Track abort provenance on the active run before cancellation occurs. The provenance distinguishes:
+
+- agent tool cancellation;
+- direct user cancellation;
+- timeout;
+- controller interruption;
+- claim loss;
+- Escape;
+- shutdown.
+
+When the executor abort callback is about to call `ctx.abort()` for an eligible active turn:
+
+1. Build the deterministic source event and intent ID.
+2. Call `ensureWorkflowTurnIntent` synchronously.
+3. Record the intent ID in system-abort bookkeeping.
+4. Call `ctx.abort()` immediately.
+
+A storage error must not prevent cancellation. Save a bounded error and retry the same intent during terminal handling. If both writes fail, show a clear warning and record a run event. Do not claim that a successor turn is guaranteed.
+
+## Turn coordinator
+
+Add one `DeferredTurnCoordinator` in `src/extension`. All extension-owned workflow agent prompts and result presentations pass through it.
+
+When no intent exists, the coordinator preserves current message content and delivery options.
+
+When an intent exists, the coordinator:
+
+1. Defers the Pi send while the old turn is still active or aborting.
+2. Waits for `agent_settled` or verified idle session state.
+3. Claims the pending intent for natural resolution.
+4. Adds `turnIntentId` to custom-message details.
+5. Sends the normal workflow prompt or presentation.
+6. Resolves the intent as `workflowPrompt` or `presentation`.
+7. Releases the claim if sending fails.
+
+This settlement rule applies to natural prompts as well as fallback messages. A recovery prompt sent while the old turn is aborting can otherwise be lost with that turn.
+
+If the message send succeeds but SQLite resolution fails, later recovery scans the current session branch for `turnIntentId`. An existing message resolves the intent without another send.
+
+## Terminal and asynchronous failures
+
+Terminal handling uses the durable run or launch state as its source of truth.
+
+For `cancelled`, `timed_out`, or `failed` outcomes with no natural successor:
+
+1. Find or recreate the deterministic intent.
+2. Update its bounded fallback facts from the observed terminal state.
+3. Make it fallback-eligible.
+
+A workflow can also fail after `workflow start` returns success but before an active agent step calls `ctx.abort()`. The run completion rejection path must create an already-eligible intent for this case. The current turn can finish normally, and the fallback arrives afterward with the actual failure. This prevents the model from reporting that a crashed workflow is still running.
+
+Completed and waiting outcomes continue through normal presentation. That presentation resolves an existing intent and prevents fallback.
+
+Parked runs remain pending for resume and do not claim a terminal outcome.
+
+## Fallback delivery
+
+The coordinator checks eligible intents:
+
+- after `agent_settled`, after system-abort bookkeeping is clear;
+- when a session starts;
+- during the existing periodic synchronization pass while the session is idle.
+
+For each claimed intent, it sends one `pi-workflows-deferred-turn` custom message with:
+
+- the stable `turnIntentId`;
+- the workflow and run identity;
+- the observed terminal or handoff state;
+- the source node and attempt when known;
+- a bounded safe reason;
+- an instruction to inspect durable state before any authorized correction.
+
+Delivery uses:
+
+```ts
+{
+  deliverAs: "followUp",
+  triggerTurn: true,
+}
+```
+
+The message does not say that recovery ran or succeeded. It does not resume the old run or grant permission for new work.
+
+The coordinator does not deliver while the session is shutting down or while an Escape-interrupted workflow is held.
+
+## Claim loss
+
+Claim loss transfers execution responsibility. It is not proof that the run failed.
+
+The old runner must:
+
+1. Ensure the pending intent before aborting the active turn when possible.
+2. Stop all fenced run-bundle writes.
+3. Leave the intent unresolved and fallback-ineligible while another runner can continue.
+
+The new runner's next workflow prompt can claim and resolve the same intent naturally. Only durable terminal state or explicit no-successor handoff evidence can make the intent fallback-eligible. A timer alone cannot establish failure.
+
+## Launch failure change
+
+Queued launch activation failure moves from `workflow_notifications` to deferred-turn intents.
+
+After the queue row is durably marked failed:
+
+1. Record the launch failure event.
+2. Create one already-eligible intent keyed by the run and `$launch`.
+3. Let post-settlement synchronization deliver the fallback.
+
+Immediate `workflow start` validation errors remain ordinary tool errors in the current live turn and create no intent.
+
+Remove the `launch_failure` runtime notification kind and trigger branch. Existing pending `launch_failure` rows are incompatible alpha state. Detect them before synchronization and give a precise controller-store reset instruction. Do not reinterpret, migrate, or silently delete them.
+
+## Implementation order
+
+1. Add the intent types, validation, row mapping, schema, and store operations.
+2. Add storage tests for identity, eligibility, claims, leases, resolution, and collisions.
+3. Add the event policy, stable identity helper, and fallback builder.
+4. Add abort provenance to active-run control paths.
+5. Persist intents before eligible `ctx.abort()` calls and retry during terminal handling.
+6. Add the coordinator and route workflow prompts and presentations through it.
+7. Add terminal eligibility and asynchronous post-start failure handling.
+8. Move queued launch failure to intents and remove its notification trigger.
+9. Add post-settlement fallback synchronization.
+10. Add claim-loss transfer behavior.
+11. Apply the alpha storage checks and reset error.
+12. Update the workflow documentation to match the shipped behavior.
+13. Run focused tests, real-Pi end-to-end tests, and all repository checks.
+
+## Acceptance criteria
+
+- Agent-issued active cancellation aborts the old turn and produces exactly one later fallback turn.
+- The aborted turn does not receive the cancel result and does not continue work.
+- A timeout with a natural recovery prompt resolves the intent through that prompt and sends no fallback.
+- A terminal timeout sends one fallback after settlement.
+- A workflow that returns a successful start result and then crashes sends one later model-facing failure turn.
+- A completed or waiting presentation resolves an existing intent and sends no fallback.
+- Queued launch failure uses an intent instead of a triggered workflow notification.
+- Direct cancellation, pause, Escape, user hold, and shutdown send no automatic successor turn.
+- Claim loss performs no stale fenced write and can resolve through the new runner's prompt.
+- Polling, extension restart, lease expiry, and repeated terminal handling do not duplicate turns.
+- A send-before-resolution crash is repaired from the session message identity.
+- Permanent intent-store failure is reported without weakening cancellation or claiming delivery.
+- Existing passive progress and final notifications keep their current behavior.
+
+## Tests
+
+Add or extend tests for:
+
+- persisted type validation and JSON round trips;
+- deterministic identity and collision rejection;
+- fresh and existing controller stores;
+- intent creation, eligibility, claims, lease expiry, release, and all resolutions;
+- intent persistence before `ctx.abort()`;
+- agent cancellation and direct user cancellation;
+- terminal timeout and timeout with a natural successor;
+- terminal workflow failure;
+- successful start followed by asynchronous runtime failure before the first prompt;
+- completed and waiting presentation;
+- queued launch failure and immediate start validation failure;
+- controller interruption and claim-loss transfer between two runners;
+- deferred natural prompts and presentations after settlement;
+- busy-session deferral and session-start recovery;
+- duplicate polling and extension restart;
+- send failure and send-before-resolution recovery;
+- Escape, pause, user hold, and shutdown;
+- real-Pi cancellation and timeout ordering with a mock provider.
+
+Use temporary databases and run directories. Tests must not call real models, mutate remote systems, or write outside temporary directories.
+
+## Verification
+
+Run these checks before completion:
+
+```bash
+npm run check
+npm run test:e2e
+npx slophammer-ts@latest dry .
+npx slophammer-ts@latest check . --only ts.dependency-boundaries-required
+git diff --check
+npx -y @simpledoc/simpledoc check
+```
+
+Keep coverage at or above 85 percent. Inspect the final diff for duplicate turn sources, unresolved claims, stale launch-trigger code, quiet-event regressions, hidden retries, and dependency-boundary violations.
+
+## Rollout
+
+Keep the controller store at `pi-workflows.controller-store.v1` during alpha. Add the intent table in place and remove the launch-trigger runtime path in the same change.
+
+Do not add a schema v2, compatibility reader, dual write, alias, or feature flag. If pending legacy launch notifications exist, stop with a clear reset instruction. Historical terminal run bundles remain readable because this change does not alter the run-bundle contract.
+
+Do not publish a package or create a release without separate authorization.
+
+## Contract impact
+
+- **Session state:** internal workflow messages gain an optional `turnIntentId`; fallback uses `pi-workflows-deferred-turn`.
+- **Controller storage:** add `workflow_turn_intents`; restrict workflow notifications to passive `progress` and `final` kinds.
+- **Run bundles:** unchanged.
+- **Workflow engine:** unchanged.
+- **Workflow author API:** unchanged.
+- **Pi core:** unchanged.
+- **Public Pi APIs:** use existing `sendMessage`, `followUp`, `triggerTurn`, session lifecycle events, and `ctx.abort()`.