@osolmaz/pi-workflows 0.11.2 → 0.12.1

package/dist/workflows/types.d.ts

@@ -52,9 +52,10 @@ export type WorkflowProgressData = {
 export type WorkflowNodeCommon = {
     /**
      * Per-node timeout or a callback that derives it from the run context.
-     * Falls back to the engine default (15 minutes).
+     * Null disables the wall-clock deadline. Omission falls back to the engine
+     * default (15 minutes).
      */
-    timeoutMs?: number | ((context: WorkflowNodeContext) => MaybePromise<number>);
+    timeoutMs?: number | null | ((context: WorkflowNodeContext) => MaybePromise<number | null>);
     /** Short human-readable label shown in the viewer while the node runs. */
     statusDetail?: string;
 };
@@ -182,31 +183,26 @@ export type DecisionPresentation = {
     summary: string;
     blocks: DecisionPresentationBlock[];
 };
-export type LegacyHumanDecisionPrompt = {
-    title: string;
-    body: unknown;
-    subject?: never;
-    presentation?: never;
-    revision?: never;
-    /** Optional absolute expiry. An expired request cannot accept an answer. */
-    expiresAt?: string;
-};
-export type PresentedHumanDecisionPrompt<TSubject = unknown> = {
+export type HumanDecisionPrompt<TSubject = unknown> = {
     title: string;
     subject: TSubject;
     presentation: DecisionPresentation;
-    body?: never;
     /** Positive revision of the decision subject and presentation. Defaults to 1. */
     revision?: number;
     /** Optional absolute expiry. An expired request cannot accept an answer. */
     expiresAt?: string;
 };
-export type HumanDecisionPrompt = LegacyHumanDecisionPrompt | PresentedHumanDecisionPrompt;
 export type HumanDecisionAudience = string | ((context: WorkflowNodeContext) => MaybePromise<string>);
+export type HumanDecisionTimeout = {
+    afterMs: number;
+    response: HumanDecisionResponse;
+};
+export type HumanDecisionTimeoutPolicy = HumanDecisionTimeout | ((context: WorkflowNodeContext) => MaybePromise<HumanDecisionTimeout | undefined>);
 export type HumanDecisionNodeContract = {
     audience: HumanDecisionAudience;
     choices: HumanDecisionChoiceMap;
     request: (context: WorkflowNodeContext) => MaybePromise<HumanDecisionPrompt>;
+    onTimeout?: HumanDecisionTimeoutPolicy;
 };
 type HumanDecisionRequestCommon = {
     decisionId: string;
@@ -220,23 +216,19 @@ type HumanDecisionRequestCommon = {
     choices: HumanDecisionChoiceMap;
     createdAt: string;
     expiresAt?: string;
+    defaultResponse?: HumanDecisionResponse;
 };
-export type HumanDecisionRequestV1 = HumanDecisionRequestCommon & {
+export type HumanDecisionRequest = HumanDecisionRequestCommon & {
     schema: "pi-workflows.human-decision-request.v1";
-    body: unknown;
-};
-export type HumanDecisionRequestV2 = HumanDecisionRequestCommon & {
-    schema: "pi-workflows.human-decision-request.v2";
     subject: unknown;
     presentation: DecisionPresentation;
     revision: number;
     subjectDigest: string;
     presentationDigest: string;
 };
-export type HumanDecisionRequest = HumanDecisionRequestV1 | HumanDecisionRequestV2;
 /**
  * Complete operator-facing request passed to a decision channel. It excludes
- * the canonical subject and legacy body by design.
+ * the canonical subject by design.
  */
 export type HumanDecisionChannelRequest = HumanDecisionRequestCommon & {
     schema: "pi-workflows.human-decision-channel-request.v1";
@@ -260,60 +252,55 @@ export type HumanDecisionSubmission = HumanDecisionResponse & {
     source: HumanDecisionAnswerSource;
     idempotencyKey: string;
 };
-type AcceptedHumanDecisionCommon = {
+type ResolvedHumanDecisionCommon = {
     decisionId: string;
     requestDigest: string;
     response: HumanDecisionResponse;
-    source: HumanDecisionAnswerSource;
-    idempotencyKey: string;
+    provenance: "human" | "timeout";
     acceptedAt: string;
     answerDigest: string;
 };
-export type AcceptedHumanDecisionV1 = AcceptedHumanDecisionCommon & {
+type AcceptedHumanDecisionCommon = ResolvedHumanDecisionCommon & {
+    provenance: "human";
+    source: HumanDecisionAnswerSource;
+    idempotencyKey: string;
+};
+type DefaultedHumanDecisionCommon = ResolvedHumanDecisionCommon & {
+    provenance: "timeout";
+};
+export type AcceptedHumanDecision = AcceptedHumanDecisionCommon & {
     schema: "pi-workflows.human-decision-accepted.v1";
+    subjectDigest: string;
+    presentationDigest: string;
+    revision: number;
 };
-export type AcceptedHumanDecisionV2 = AcceptedHumanDecisionCommon & {
-    schema: "pi-workflows.human-decision-accepted.v2";
+export type DefaultedHumanDecision = DefaultedHumanDecisionCommon & {
+    schema: "pi-workflows.human-decision-accepted.v1";
     subjectDigest: string;
     presentationDigest: string;
     revision: number;
 };
-export type AcceptedHumanDecision = AcceptedHumanDecisionV1 | AcceptedHumanDecisionV2;
+export type ResolvedHumanDecision = AcceptedHumanDecision | DefaultedHumanDecision;
 type HumanDecisionReceiptCommon = {
     decisionId: string;
     requestDigest: string;
     nodeId: string;
     response: HumanDecisionResponse;
+    provenance: "human" | "timeout";
     acceptedAt: string;
     answerDigest: string;
 };
-export type HumanDecisionReceiptV1 = HumanDecisionReceiptCommon & {
+export type HumanDecisionReceipt = HumanDecisionReceiptCommon & {
     schema: "pi-workflows.human-decision-receipt.v1";
-};
-export type HumanDecisionReceiptV2 = HumanDecisionReceiptCommon & {
-    schema: "pi-workflows.human-decision-receipt.v2";
     subjectDigest: string;
     presentationDigest: string;
     revision: number;
 };
-export type HumanDecisionReceipt = HumanDecisionReceiptV1 | HumanDecisionReceiptV2;
-export type HumanDecisionDeliveryRecordV1 = {
+export type HumanDecisionDeliveryRecord = {
     schema: "pi-workflows.human-decision-delivery.v1";
     attemptId: string;
     decisionId: string;
     requestDigest: string;
-    channel: string;
-    state: "intent" | "confirmed" | "failed" | "unknown";
-    createdAt: string;
-    finishedAt?: string;
-    messageCount?: number;
-    errorCode?: string;
-};
-export type HumanDecisionDeliveryRecordV2 = {
-    schema: "pi-workflows.human-decision-delivery.v2";
-    attemptId: string;
-    decisionId: string;
-    requestDigest: string;
     presentationDigest: string;
     channel: string;
     phase: "intent" | "part" | "complete";
@@ -327,7 +314,6 @@ export type HumanDecisionDeliveryRecordV2 = {
     messageCount?: number;
     errorCode?: string;
 };
-export type HumanDecisionDeliveryRecord = HumanDecisionDeliveryRecordV1 | HumanDecisionDeliveryRecordV2;
 export type HumanDecisionSettlementRecord = {
     schema: "pi-workflows.human-decision-settlement.v1";
     attemptId: string;
@@ -350,6 +336,7 @@ export type HumanDecisionContinuationRecord = {
     schema: "pi-workflows.human-decision-continuation.v1";
     decisionId: string;
     requestDigest: string;
+    provenance: "human" | "timeout";
     parentRunId: string;
     runId: string;
     createdAt: string;
@@ -586,7 +573,7 @@ export type WorkflowRunState = {
 };
 export type WorkflowNodeSnapshot = {
     nodeType: WorkflowNodeDefinition["nodeType"];
-    timeoutMs?: number;
+    timeoutMs?: number | null;
     statusDetail?: string;
     summary?: string;
     expectedOutput?: string;
@@ -598,6 +585,8 @@ export type WorkflowNodeSnapshot = {
         audience: string;
         dynamicAudience?: boolean;
         choices: HumanDecisionChoiceMap;
+        onTimeout?: HumanDecisionTimeout;
+        dynamicTimeout?: boolean;
     };
 };
 export type WorkflowDefinitionSnapshot = {

package/docs/2026-08-18-herdr-piw-plan.md

@@ -8,7 +8,7 @@ date: 2026-08-18
 
 ## Purpose
 
-When Pi Workflows runs inside Herdr, show a shortcut that opens the current run in `piw`. The integration must belong to Pi Workflows and ship as one package, repository, version, and release. The same repository must also qualify for Herdr's public plugin marketplace.
+When pi-workflows runs inside Herdr, show a shortcut that opens the current run in `piw`. The integration must belong to pi-workflows and ship as one package, repository, version, and release. The same repository must also qualify for Herdr's public plugin marketplace.
 
 ## Requirements
 

package/docs/2026-08-20-durable-workflow-launch-plan.md

@@ -6,17 +6,19 @@ date: 2026-08-20
 
 # Make deferred workflow launches durable
 
+The launch queue and activation contract in this plan remain current. [Deferred workflow turns](DEFERRED_TURNS.md) replaces the launch-specific failure-notification mechanism with the general successor-turn intent contract.
+
 ## Goal
 
 A successful `workflow start` call must create a real queued workflow before it returns. The model
-must receive the final run ID, and Pi Workflows must start that run only after the current agent turn
+must receive the final run ID, and pi-workflows must start that run only after the current agent turn
 settles.
 
-If startup then fails, Pi Workflows must save the failure and start one new model turn with an
+If startup then fails, pi-workflows must save the failure and start one new model turn with an
 actionable error. The model can correct the request and call `workflow start` again. A failed launch
 must release the session reservation so the corrected run can start.
 
-This change stays inside Pi Workflows. It uses the existing project-scoped SQLite controller store
+This change stays inside pi-workflows. It uses the existing project-scoped SQLite controller store
 and documented Pi extension APIs. It does not change Pi, add a service, or add another database.
 
 ## Current failure
@@ -39,7 +41,7 @@ the workflow had started.
 
 Use a durable prepared run and one model-visible failure follow-up.
 
-During the `workflow start` tool call, Pi Workflows will:
+During the `workflow start` tool call, pi-workflows will:
 
 1. Resolve and validate the workflow and all available start conditions.
 2. Allocate the final run ID.
@@ -47,7 +49,7 @@ During the `workflow start` tool call, Pi Workflows will:
 4. Reserve the initiating Pi session.
 5. Return the run ID and say that the workflow is queued.
 
-After the current agent turn settles, Pi Workflows will:
+After the current agent turn settles, pi-workflows will:
 
 1. Claim the queued record.
 2. Change it to `starting`.
@@ -55,22 +57,21 @@ After the current agent turn settles, Pi Workflows will:
 4. Change the record to `running`.
 5. Release the engine to run the first node.
 
-If startup fails, Pi Workflows will:
+If startup fails, pi-workflows will:
 
 1. Change the record to `failed`.
 2. Save a bounded safe error.
 3. Release the session reservation.
-4. Queue one durable failure notification for the owning Pi session.
-5. Send that notification through `pi.sendMessage` with `triggerTurn: true` and
-   `deliverAs: "followUp"`.
+4. Create one eligible deferred-turn intent for the owning Pi session.
+5. Resolve that intent with one factual follow-up after settlement.
 
 The new model turn will contain the failed run ID and an actionable error. The model can fix the
 workflow reference, input, source, or local condition and call `workflow start` again. Each retry is
-an explicit model action with a new run ID. Pi Workflows does not perform a blind automatic retry.
+an explicit model action with a new run ID. pi-workflows does not perform a blind automatic retry.
 
 ## Alpha compatibility contract
 
-Pi Workflows is in alpha. Change the current storage and tool contracts in place.
+pi-workflows is in alpha. Change the current storage and tool contracts in place.
 
 - Keep `pi-workflows.controller-store.v1`.
 - Keep existing run-bundle schema identifiers.
@@ -80,7 +81,7 @@ Pi Workflows is in alpha. Change the current storage and tool contracts in place
 - Change the SQLite table definitions and TypeScript types directly.
 - Remove the superseded status values and launch path in the same change.
 
-An existing controller store with the old alpha table layout is incompatible. On open, Pi Workflows
+An existing controller store with the old alpha table layout is incompatible. On open, pi-workflows
 must verify the required table columns and status contract. If the layout is old, it must stop with a
 clear instruction to preserve any needed run evidence and reset the project-scoped controller store.
 It must not silently reinterpret or delete old state.
@@ -150,10 +151,7 @@ Inspect the error and call workflow start again only after you correct the cause
 The message does not contain raw workflow input, prompt text, credentials, request headers, or a
 stack trace.
 
-The failure notification has a deterministic ID derived from the run ID. Pi Workflows records its
-delivery in the existing notification outbox. Before a delivery retry, it checks the native Pi
-session for that notification ID. This prevents a duplicate after a crash between session append and
-outbox acknowledgement.
+The turn intent has a deterministic ID derived from the session, run, and launch event. Pi Workflows records it in `workflow_turn_intents`. Before a delivery retry, it checks the Pi session branch for the intent ID. This prevents a duplicate after a crash between session append and intent resolution.
 
 A failed launch releases the one-workflow session reservation before it sends the follow-up. The
 model can therefore call `workflow start` during the new turn. If that launch also fails, the same
@@ -217,9 +215,7 @@ and `running` state its meaning directly.
 Clear private queue input when the launch becomes `running`, `failed`, or `cancelled`. The normal run
 bundle owns input after the engine starts.
 
-Extend the existing `workflow_notifications` table in place so a notification can be run-level.
-Add `launch_failure` to its kind contract and allow node and attempt identity to be absent for a
-run-level notification. Reuse its delivery claim, lease, and delivered timestamp.
+Keep `workflow_notifications` limited to passive `progress` and `final` reports. A launch failure creates an eligible row in `workflow_turn_intents`; it does not add a run-level notification kind.
 
 The project-scoped controller store remains private local state. Tests must verify restrictive file
 and directory permissions.
@@ -384,8 +380,8 @@ Add or update these tests:
 10. Cancellation before claim, during `starting`, and before executor release.
 11. Source change between preparation and activation.
 12. Safe error redaction and byte bounds.
-13. One durable launch-failure notification.
-14. Crash before session append, after append, and before outbox acknowledgement.
+13. One durable launch-failure turn intent.
+14. Crash before session append, after append, and before intent resolution.
 15. Failed reservation release followed by a corrected model start.
 16. Repeated model correction attempts with one active reservation at a time.
 17. Status for every launch and run state.
@@ -411,7 +407,7 @@ or external service.
 - The start tool never reports success without a committed queued record and final run ID.
 - The model can correct synchronous start errors in the same turn.
 - A deferred startup failure always becomes durable before notification.
-- One failure notification starts one new model turn.
+- One launch-failure intent starts one new model turn.
 - The model can correct the cause and start a new run.
 - Failed and cancelled launches release the session reservation.
 - No two runs activate for one reservation.
@@ -433,7 +429,7 @@ npx slophammer-ts@latest check . --only ts.dependency-boundaries-required
 git diff --check
 ```
 
-Run Pi Reviewer against the base branch and fix all valid P0 and P1 findings before release work.
+Run pi-reviewer against the base branch and fix all valid P0 and P1 findings before release work.
 
 Package publication and OnurPi adoption are separate tasks. Do not edit an installed `node_modules`
 copy as the implementation source.

package/docs/CONTROLLERS.md

@@ -1,10 +1,10 @@
 # Controller runtime specification
 
-Pi Workflows runs finite TypeScript graphs. A graph starts with an input, follows explicit edges, and ends with a result or checkpoint. This works well for one bounded task.
+pi-workflows runs finite TypeScript graphs. A graph starts with an input, follows explicit edges, and ends with a result or checkpoint. This works well for one bounded task.
 
 Long-running automation has a different job. It must keep comparing a requested state with the current state of another system. Events can arrive more than once, processes can stop between an external request and its local receipt, and the external state can change while work is running.
 
-This specification adds a Kubernetes-style controller runtime to Pi Workflows. The controller runtime sits beside the graph engine. Controllers manage durable resources, while workflows remain finite jobs that a controller can start and observe.
+This specification adds a Kubernetes-style controller runtime to pi-workflows. The controller runtime sits beside the graph engine. Controllers manage durable resources, while workflows remain finite jobs that a controller can start and observe.
 
 The design follows the Kubernetes [controller pattern](https://kubernetes.io/docs/concepts/architecture/controller/), its [`spec` and `status` split](https://kubernetes.io/docs/concepts/overview/working-with-objects/), and the [idempotent reconciliation guidance](https://book.kubebuilder.io/reference/good-practices).
 

package/docs/DEFERRED_TURNS.md

@@ -0,0 +1,298 @@
+# 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.
+
+The implementation plan is [Guarantee one successor turn after workflow interruption](plans/2026-08-21-deferred-turn-intents-plan.md).
+
+## Terms
+
+- **Source event:** The workflow event that creates the need for another turn.
+- **Turn intent:** The durable obligation to send one successor turn.
+- **Natural successor:** The next workflow agent prompt or result presentation.
+- **Fallback:** A factual model-facing message sent when no natural successor remains.
+- **Resolution:** The recorded fact that one message path satisfied the intent.
+- **Target session:** The Pi session that owns the successor turn.
+
+## Core rule
+
+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;
+3. a factual fallback.
+
+All three paths claim the same intent before sending. 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.
+
+## Intent lifecycle
+
+An intent has two stored states:
+
+| State    | Condition                                                     | Meaning                                                   |
+| -------- | ------------------------------------------------------------- | --------------------------------------------------------- |
+| Pending  | `resolvedAt` is null                                          | No message path has resolved the intent.                  |
+| Resolved | `resolvedAt`, `resolution`, and `resolutionMessageId` are set | One message path was sent or found in the session branch. |
+
+Pending intents have separate fallback eligibility:
+
+| Eligibility | Condition            | Meaning                                                          |
+| ----------- | -------------------- | ---------------------------------------------------------------- |
+| Ineligible  | `eligibleAt` is null | A natural workflow prompt or presentation can still arrive.      |
+| Eligible    | `eligibleAt` is set  | Durable state shows that no immediate natural successor remains. |
+
+A claim is temporary coordination state. A claim does not resolve an intent. An expired claim can be acquired again.
+
+Valid resolutions are:
+
+```text
+workflowPrompt | presentation | fallback
+```
+
+Resolution records message delivery into the Pi session or the presence of the same message in the session branch. It does not prove that a model turn started or completed.
+
+## Source events
+
+Valid causes are:
+
+```text
+agentCancelled | timedOut | failed | launchFailed | controllerInterrupted | claimLost
+```
+
+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.                                           |
+
+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.
+
+## Stable identity
+
+`intentId` is a deterministic digest of:
+
+- target session ID;
+- run ID;
+- source event ID;
+- node ID or `$launch`;
+- attempt ID when known;
+- cause.
+
+The same source event must always produce the same ID. Reusing an ID with different immutable facts is an error.
+
+`sourceEventId` identifies the source transition independently of delivery retries. Terminal handling must reuse an earlier abort event instead of creating a second terminal event for the same interruption.
+
+IDs use the existing controller-store key limit of 512 characters. The digest representation must be stable across processes and extension restarts.
+
+## Stored record
+
+`workflow_turn_intents` lives in the existing controller SQLite database.
+
+| Column                      | Null | Meaning                                      |
+| --------------------------- | ---- | -------------------------------------------- |
+| `intent_id`                 | No   | Deterministic primary key.                   |
+| `source_event_id`           | No   | Stable source transition identity.           |
+| `run_id`                    | No   | Related workflow run.                        |
+| `workflow_ref`              | No   | Workflow identity used in messages.          |
+| `target_session_id`         | No   | Session that can receive the successor.      |
+| `cause`                     | No   | Closed cause value.                          |
+| `node_id`                   | Yes  | Source node when known.                      |
+| `attempt_id`                | Yes  | Source attempt when known.                   |
+| `fallback_facts_json`       | No   | Bounded factual payload.                     |
+| `requested_at`              | No   | Absolute ISO 8601 creation time.             |
+| `eligible_at`               | Yes  | Absolute ISO 8601 fallback eligibility time. |
+| `resolved_at`               | Yes  | Absolute ISO 8601 resolution time.           |
+| `resolution`                | Yes  | Closed resolution value.                     |
+| `resolution_message_id`     | Yes  | Stable message identity.                     |
+| `delivery_claim_token`      | Yes  | Current claimant.                            |
+| `delivery_claim_expires_at` | Yes  | Claim expiry as epoch milliseconds.          |
+
+The table requires these indexes:
+
+- unresolved intents by run and target session;
+- unresolved eligible intents by target session, eligibility time, and intent ID.
+
+A resolved row has all three resolution fields. A pending row has none of them. A row cannot change immutable identity or source fields after creation.
+
+## Fallback facts
+
+`fallback_facts_json` uses this versioned camelCase object:
+
+```json
+{
+  "schema": "pi-workflows.deferred-turn-facts.v1",
+  "workflowName": "autoimplement",
+  "runId": "20260821T081731Z-autoimplement-407480dd",
+  "observedState": "failed",
+  "cause": "failed",
+  "nodeId": "$launch",
+  "attemptId": null,
+  "reason": "scope must be a non-empty string",
+  "handoff": false
+}
+```
+
+Rules:
+
+- `schema` is required and has the exact value shown above.
+- `workflowName`, `runId`, `observedState`, and `cause` are required strings.
+- `nodeId`, `attemptId`, and `reason` are strings or null.
+- `handoff` is a required boolean.
+- `reason` is safe diagnostic text with at most 8,192 characters.
+- The serialized object is at most 64 KiB.
+- Unknown fields are rejected during alpha.
+- The object must not contain credentials, raw environment values, or unbounded command output.
+
+`handoff: true` means another runner can continue. A handoff message must not describe the run as terminal unless separate durable state proves it.
+
+## Store operations
+
+The controller store provides these internal operations:
+
+- `ensureWorkflowTurnIntent`
+- `getWorkflowTurnIntent`
+- `claimWorkflowTurnIntentForRun`
+- `claimEligibleWorkflowTurnIntentsForSession`
+- `makeWorkflowTurnIntentEligible`
+- `resolveWorkflowTurnIntent`
+- `releaseWorkflowTurnIntentClaim`
+- a bounded diagnostic list operation
+
+`ensureWorkflowTurnIntent` is idempotent when all immutable fields match. It fails on an identity collision.
+
+Claim operations use a caller-supplied token and lease duration. Resolution requires the matching live claim token. Conditional updates ensure that natural delivery and fallback cannot both resolve the same intent.
+
+List operations require a positive bounded limit and deterministic ordering.
+
+## Abort ordering
+
+For an eligible active-turn abort, Pi Workflows performs these steps in order:
+
+1. Record abort provenance on the active run.
+2. Build the source event and intent ID.
+3. Attempt to persist the intent.
+4. Record the intent ID in system-abort bookkeeping.
+5. Call `ctx.abort()`.
+
+The persistence attempt is synchronous because cancellation immediately crosses the turn boundary. A store failure does not prevent `ctx.abort()`. Terminal handling retries the same intent ID. If retry also fails, Pi Workflows reports that it could not preserve the successor-turn guarantee.
+
+## Natural delivery
+
+All extension-owned workflow prompts and result presentations pass through one `DeferredTurnCoordinator`.
+
+If no intent exists, the coordinator preserves current message content and delivery options.
+
+If a pending intent exists, the coordinator:
+
+1. waits until the old turn has settled or the session is verified idle;
+2. claims the intent for the run and session;
+3. adds `turnIntentId` to the message details;
+4. sends the normal prompt or presentation;
+5. resolves the intent with the matching resolution and message ID;
+6. releases the claim if sending fails.
+
+A prompt generated during abort handling must not be sent into the aborting turn. The coordinator releases it after `agent_settled`.
+
+## Fallback delivery
+
+Fallback synchronization runs:
+
+- after `agent_settled` and system-abort cleanup;
+- when the target session starts;
+- during the existing periodic synchronization pass while the session is idle.
+
+The fallback custom message uses this details object:
+
+```json
+{
+  "schema": "pi-workflows.deferred-turn-message.v1",
+  "turnIntentId": "deferred-turn:...",
+  "runId": "20260821T081731Z-autoimplement-407480dd",
+  "cause": "failed"
+}
+```
+
+The message type is `pi-workflows-deferred-turn`. Delivery uses:
+
+```ts
+{
+  deliverAs: "followUp",
+  triggerTurn: true,
+}
+```
+
+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.
+
+Fallback delivery is disabled during session shutdown and while a user-interrupted workflow is held.
+
+## Delivery recovery
+
+Every resolving message includes the intent ID in its custom-message details.
+
+Before sending, the coordinator scans the current session branch for that ID. If the message is already present, the coordinator resolves the intent without sending again. This repairs a crash or SQLite failure that occurs after `sendMessage` succeeds but before resolution is stored.
+
+Store leases prevent concurrent processes from sending the same resolution. Branch identity handles the remaining send-before-resolution window.
+
+## Claim transfer
+
+Claim loss stops the old runner's work and all fenced run-bundle writes. The intent stays pending and fallback-ineligible while another runner can resume the run.
+
+The new runner's next workflow prompt can resolve the intent. If durable state later proves a terminal outcome with no natural successor, terminal handling makes the intent eligible for fallback to its target session.
+
+Time alone does not prove terminal failure.
+
+## Launch notifications
+
+Workflow-authored `progress` and `final` notifications remain passive. They do not trigger model turns.
+
+The `launch_failure` notification kind is removed. Queued launch failure creates an eligible turn intent instead.
+
+Pending `launch_failure` rows from the earlier alpha contract are incompatible. Pi Workflows must stop with a clear controller-store reset instruction. It must not reinterpret, migrate, or silently delete those rows.
+
+## Availability limits
+
+Pi Workflows can guarantee only the facts under its control:
+
+- the intent was stored;
+- a claimant acquired it;
+- a custom message was sent or found in the session branch;
+- the local intent was resolved.
+
+Pi Workflows cannot guarantee model start or completion with the current Pi API. It also cannot deliver after permanent loss of the process, target session, controller store, machine, or model provider.
+
+Undelivered intents remain pending. The implementation does not add a service to process them outside a live Pi session.
+
+## Compatibility
+
+This is an alpha hard cutover.
+
+- Keep `pi-workflows.controller-store.v1`.
+- Add `workflow_turn_intents` to the existing database.
+- Remove the launch-trigger runtime path.
+- Add no v2 schema, compatibility reader, dual write, alias, or feature flag.
+- Keep historical terminal run bundles readable because their contract does not change.
+
+## Conformance
+
+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;
+- 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;
+- 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;
+- passive workflow notifications keep their current behavior.

package/docs/DESIGN_PHILOSOPHY.md

@@ -1,6 +1,6 @@
 # Design philosophy
 
-Pi Workflows should stay small and easy to combine. A small set of clear, general parts should support many kinds of work.
+pi-workflows should stay small and easy to combine. A small set of clear, general parts should support many kinds of work.
 
 ## Primary rule