@osolmaz/pi-workflows 0.11.2 → 0.12.1

package/dist/extension/index.js

@@ -6,7 +6,7 @@ import { projectControllerStorePath, SqliteControllerStore, } from "../controlle
 import { compositionMetadata } from "../workflows/composition.js";
 import { humanDecisionChannelRequest } from "../workflows/decision-presentation.js";
 import { WorkflowEngine } from "../workflows/engine.js";
-import { ClaimLostError, errorMessage, isClaimLostError, TimeoutError, } from "../workflows/errors.js";
+import { BuiltinWorkflowRevisionChangedError, ClaimLostError, errorMessage, isClaimLostError, TimeoutError, } from "../workflows/errors.js";
 import { HumanDecisionStore, createHumanDecisionAttemptId, validateHumanDecisionResponse, } from "../workflows/human-decision.js";
 import { discoverWorkflows, resolveWorkflowRef } from "../workflows/loader.js";
 import { migrateLegacyWorkflowSources } from "../workflows/migrate-sources.js";
@@ -14,6 +14,8 @@ import { appendProgressHistory, progressRecordsFromTrace } from "../workflows/pr
 import { createRunId, listRunBundles, readLastTraceEvent, readRunBundle, WorkflowRunStore, createDefinitionSnapshot, } from "../workflows/store.js";
 import { PiControllerHost, parseControllerArgs, } from "./controller-host.js";
 import { PiDecisionChannel, TelegramDecisionChannel, audienceChannels, createTelegramChannels, loadDecisionChannelConfig, verifyTelegramTokenFile, writeDecisionChannelProfile, } from "./decision-channels.js";
+import { DeferredTurnCoordinator, } from "./deferred-turn-coordinator.js";
+import { buildDeferredTurnContent, createDeferredTurnDescriptor, DEFERRED_TURN_MESSAGE_TYPE, deferredTurnMessageDetails, deferredTurnMessageId, deferredTurnSourceEventId, } from "./deferred-turn.js";
 import { ConversationStepExecutor } from "./executor.js";
 import { HerdrWorkflowViewer, parseViewerPlacement, PIW_SHORTCUT, PIW_SHORTCUT_HINT, VIEWER_PLACEMENTS, } from "./herdr-viewer.js";
 import { SessionRecorder } from "./recorder.js";
@@ -25,8 +27,10 @@ const RUN_CLAIM_LEASE_MS = 30_000;
 const RUN_CLAIM_RENEW_MS = 10_000;
 const RUN_SYNC_POLL_MS = 3_000;
 const NOTIFICATION_DELIVERY_LEASE_MS = 30_000;
+const TURN_INTENT_DELIVERY_LEASE_MS = 30_000;
 const WIDGET_KEY = "pi-workflows";
 const PRESENTATION_MESSAGE_TYPE = "pi-workflows-presentation";
+const PRESENTATION_MESSAGE_SCHEMA = "pi-workflows.presentation-message.v1";
 const FINAL_WIDGET_TTL_MS = 60_000;
 const WIDGET_SCROLL_STEP = 3;
 const MAX_PRESENTATION_RESULT_CHARS = 50_000;
@@ -51,10 +55,8 @@ function humanDecisionRequest(value) {
     const schema = value !== null && typeof value === "object"
         ? value.schema
         : undefined;
-    if (schema !== "pi-workflows.human-decision-request.v1" &&
-        schema !== "pi-workflows.human-decision-request.v2") {
+    if (schema !== "pi-workflows.human-decision-request.v1")
         return null;
-    }
     return value;
 }
 function definitionDigest(snapshot) {
@@ -66,6 +68,20 @@ function launchSourceIdentity(workflow, root) {
         mounted: compositionMetadata(workflow)?.sources ?? [],
     };
 }
+function continuationSourceChangedError(runId, previous, current) {
+    if (previous.kind === "builtin" &&
+        current.kind === "builtin" &&
+        previous.id === current.id &&
+        previous.revision !== current.revision) {
+        return new BuiltinWorkflowRevisionChangedError({
+            runId,
+            workflowId: current.id,
+            previousRevision: previous.revision,
+            currentRevision: current.revision,
+        });
+    }
+    return new Error(`Workflow source changed since run ${runId} started; revert the edit to answer its checkpoint`);
+}
 function preparedLaunchOptions(options) {
     return {
         ...(options.presentation !== undefined ? { presentation: options.presentation } : {}),
@@ -220,6 +236,7 @@ export default function piWorkflows(pi) {
     let activationRecovery;
     let decisionRecoveryTimer = null;
     let decisionRecoveryActive = false;
+    let turnCoordinator;
     const recordRunEvent = (event) => {
         try {
             runQueueStore?.recordRunEvent({ ...event, runnerId });
@@ -266,9 +283,7 @@ export default function piWorkflows(pi) {
                             runId: notification.runId,
                             kind: notification.kind,
                         },
-                    }, notification.kind === "launch_failure"
-                        ? { triggerTurn: true, deliverAs: "followUp" }
-                        : { triggerTurn: false });
+                    }, { triggerTurn: false });
                     alreadyDelivered.add(notification.notificationId);
                 }
                 runQueueStore.markWorkflowNotificationDelivered({
@@ -277,6 +292,19 @@ export default function piWorkflows(pi) {
                     claimToken,
                 });
             }
+            const idle = ctx.isIdle() && systemTurnAbort === null && !sessionClosed && !runHeld();
+            turnCoordinator.flushNatural(idle);
+            turnCoordinator.deliverFallbacks({
+                targetSessionId: sessionId,
+                send: (intent) => {
+                    pi.sendMessage({
+                        customType: DEFERRED_TURN_MESSAGE_TYPE,
+                        content: buildDeferredTurnContent(intent),
+                        display: true,
+                        details: deferredTurnMessageDetails(intent),
+                    }, { triggerTurn: true, deliverAs: "followUp" });
+                },
+            }, idle);
         }
         catch {
             // Delivery retries on the next poll. It never affects workflow execution.
@@ -312,6 +340,35 @@ export default function piWorkflows(pi) {
     let presentationPending = null;
     let controllerHost;
     let controllerContext = null;
+    const branchIntentResolution = (intentId) => {
+        if (controllerContext === null)
+            return null;
+        for (const entry of controllerContext.sessionManager.getBranch()) {
+            if (entry.type !== "custom_message")
+                continue;
+            const details = entry.details;
+            if (details === null || typeof details !== "object" || Array.isArray(details))
+                continue;
+            if (details.turnIntentId !== intentId)
+                continue;
+            let resolution = null;
+            if (entry.customType === WORKFLOW_AGENT_STEP_MESSAGE_TYPE)
+                resolution = "workflowPrompt";
+            if (entry.customType === PRESENTATION_MESSAGE_TYPE)
+                resolution = "presentation";
+            if (entry.customType === DEFERRED_TURN_MESSAGE_TYPE)
+                resolution = "fallback";
+            if (resolution !== null) {
+                return { resolution, messageId: deferredTurnMessageId(intentId, resolution) };
+            }
+        }
+        return null;
+    };
+    turnCoordinator = new DeferredTurnCoordinator({
+        store: () => runQueueStore,
+        branchResolution: branchIntentResolution,
+        leaseMs: TURN_INTENT_DELIVERY_LEASE_MS,
+    });
     // UI updates are best-effort: a captured ctx becomes stale after session
     // replacement or shutdown, and pi throws on any access (even `ctx.hasUI`).
     // A workflow finishing right as the session goes away must not crash pi.
@@ -352,6 +409,115 @@ export default function piWorkflows(pi) {
     };
     /** True when the run is held for the user (escape or /workflow pause). */
     const runHeld = () => activeRun !== null && (activeRun.engine.pauseRequested || activeRun.executor.held);
+    const originSessionId = (ctx, runId) => ensureRunQueueStore(ctx.cwd).getWorkflowRun(runId)?.originSessionId ??
+        ctx.sessionManager.getSessionId();
+    const storeTurnDescriptor = (ctx, descriptor, eligible) => {
+        ensureRunQueueStore(ctx.cwd).ensureWorkflowTurnIntent({ ...descriptor, eligible });
+    };
+    const ensureAbortTurnIntent = (ctx, run, cause, contract, reason) => {
+        if (run.abortProvenance?.descriptor !== undefined) {
+            return run.abortProvenance.descriptor;
+        }
+        const descriptor = createDeferredTurnDescriptor({
+            runId: run.runId,
+            workflowName: run.workflowName,
+            targetSessionId: originSessionId(ctx, run.runId),
+            cause,
+            sourceEventId: deferredTurnSourceEventId({
+                runId: run.runId,
+                cause,
+                nodeId: contract.nodeId,
+                attemptId: contract.attemptId,
+                source: "agent-step-abort",
+            }),
+            observedState: cause === "claimLost" ? "handedOff" : "interrupted",
+            nodeId: contract.nodeId,
+            attemptId: contract.attemptId,
+            reason: errorMessage(reason),
+            handoff: cause === "claimLost",
+        });
+        run.abortProvenance = { cause, descriptor };
+        try {
+            storeTurnDescriptor(ctx, descriptor, false);
+        }
+        catch (error) {
+            run.abortProvenance.storageError = errorMessage(error);
+        }
+        return descriptor;
+    };
+    const makeRunTurnIntentEligible = (ctx, run, observedState, reason) => {
+        if (sessionClosed ||
+            run.suppressTurnIntent === true ||
+            run.abortProvenance?.cause === "claimLost") {
+            return;
+        }
+        const targetSessionId = originSessionId(ctx, run.runId);
+        const pending = ensureRunQueueStore(ctx.cwd).findPendingWorkflowTurnIntent({
+            runId: run.runId,
+            targetSessionId,
+        });
+        if (run.childKey !== undefined &&
+            run.abortProvenance === undefined &&
+            pending?.cause !== "claimLost") {
+            return;
+        }
+        const cause = pending?.cause ??
+            run.abortProvenance?.cause ??
+            (observedState === "timed_out" ? "timedOut" : "failed");
+        if (observedState === "cancelled" &&
+            run.abortProvenance === undefined &&
+            pending === undefined) {
+            return;
+        }
+        const previous = run.abortProvenance?.descriptor;
+        const sourceEventId = pending?.sourceEventId ??
+            previous?.sourceEventId ??
+            deferredTurnSourceEventId({
+                runId: run.runId,
+                cause,
+                nodeId: "$terminal",
+                source: "terminal",
+            });
+        const descriptor = createDeferredTurnDescriptor({
+            runId: run.runId,
+            workflowName: pending?.workflowRef ?? run.workflowName,
+            targetSessionId,
+            cause,
+            sourceEventId,
+            observedState,
+            nodeId: pending?.nodeId ?? previous?.nodeId ?? "$terminal",
+            attemptId: pending?.attemptId ?? previous?.attemptId ?? null,
+            reason: reason ?? null,
+            handoff: false,
+        });
+        run.abortProvenance = {
+            cause,
+            descriptor,
+            ...(run.abortProvenance?.storageError === undefined
+                ? {}
+                : { storageError: run.abortProvenance.storageError }),
+        };
+        try {
+            storeTurnDescriptor(ctx, descriptor, false);
+            ensureRunQueueStore(ctx.cwd).makeWorkflowTurnIntentEligible({
+                intentId: descriptor.intentId,
+                fallbackFacts: descriptor.fallbackFacts,
+            });
+            delete run.abortProvenance.storageError;
+            syncArmed = true;
+        }
+        catch (error) {
+            const message = errorMessage(error);
+            run.abortProvenance.storageError = message;
+            recordRunEvent({
+                runId: run.runId,
+                workflowRef: run.workflowName,
+                type: "turn_intent_failed",
+                payload: { error: message },
+            });
+            notify(ctx, `Workflow ${run.workflowName} ended, but Pi Workflows could not preserve its successor turn: ${message}`, "warning");
+        }
+    };
     const footerStatus = (state) => {
         const label = runHeld() || state.paused ? "paused" : state.status;
         const node = state.currentNode ?? state.waitingOn;
@@ -512,20 +678,36 @@ export default function piWorkflows(pi) {
             const instructions = typeof run.presentationPrompt === "function"
                 ? await resolvePresentationPrompt(run.presentationPrompt, state, abort.signal)
                 : run.presentationPrompt;
-            if (sessionClosed ||
-                run.generation !== runGeneration ||
-                abort.signal.aborted ||
-                instructions === undefined ||
-                instructions.trim().length === 0) {
+            if (sessionClosed || run.generation !== runGeneration || abort.signal.aborted) {
+                return;
+            }
+            if (instructions === undefined || instructions.trim().length === 0) {
+                if (run.abortProvenance !== undefined) {
+                    makeRunTurnIntentEligible(ctx, run, state.status, "No result presentation was available");
+                }
                 return;
             }
-            presentationPending = run.generation;
-            suppressWorkflowAssistantTail = false;
-            pi.sendMessage({
-                customType: PRESENTATION_MESSAGE_TYPE,
-                content: buildPresentationMessage(instructions, state),
-                display: false,
-            }, { deliverAs: "steer", triggerTurn: true });
+            turnCoordinator.sendNatural({
+                runId: run.runId,
+                targetSessionId: originSessionId(ctx, run.runId),
+                resolution: "presentation",
+                send: (turnIntentId) => {
+                    presentationPending = run.generation;
+                    suppressWorkflowAssistantTail = false;
+                    pi.sendMessage({
+                        customType: PRESENTATION_MESSAGE_TYPE,
+                        content: buildPresentationMessage(instructions, state),
+                        display: false,
+                        details: {
+                            schema: PRESENTATION_MESSAGE_SCHEMA,
+                            ...(turnIntentId === undefined ? {} : { turnIntentId }),
+                        },
+                    }, {
+                        deliverAs: turnIntentId === undefined ? "steer" : "followUp",
+                        triggerTurn: true,
+                    });
+                },
+            }, ctx.isIdle() && systemTurnAbort === null);
         }
         catch (error) {
             if (presentationPending === run.generation) {
@@ -540,6 +722,9 @@ export default function piWorkflows(pi) {
                 ? `timed out after ${PRESENTATION_TIMEOUT_MS}ms`
                 : errorMessage(error);
             notify(ctx, `Could not present workflow result: ${message}`, "warning");
+            if (run.abortProvenance !== undefined) {
+                makeRunTurnIntentEligible(ctx, run, state.status, message);
+            }
         }
         finally {
             clearTimeout(timer);
@@ -590,6 +775,19 @@ export default function piWorkflows(pi) {
             clearWidget(ctx);
             return;
         }
+        if (run.abortProvenance?.cause === "claimLost") {
+            await run.recorder?.stop().catch(() => undefined);
+            releaseClaim(run, "lost");
+            recordRunEvent({
+                runId: run.runId,
+                workflowRef: run.workflowName,
+                type: "claim_lost",
+            });
+            stopWidgetTicker();
+            clearWidget(ctx);
+            notify(ctx, `Workflow ${run.workflowName} continues under another runner (run ${run.runId}).`);
+            return;
+        }
         releaseClaim(run, "done");
         recordRunEvent({
             runId: run.runId,
@@ -638,6 +836,14 @@ export default function piWorkflows(pi) {
         catch (error) {
             notify(ctx, `Could not record child workflow completion: ${errorMessage(error)}`, "warning");
         }
+        if (state.status === "failed" || state.status === "timed_out" || state.status === "cancelled") {
+            makeRunTurnIntentEligible(ctx, run, state.status, state.error);
+        }
+        else if (run.abortProvenance !== undefined &&
+            run.presentationPrompt === undefined &&
+            (state.status === "completed" || state.status === "waiting")) {
+            makeRunTurnIntentEligible(ctx, run, state.status, state.error);
+        }
         void presentRun(ctx, run, state);
         if (pendingDecision !== null && state.status === "waiting") {
             const channels = audienceChannels(decisionChannelConfig, pendingDecision.audience);
@@ -694,7 +900,7 @@ export default function piWorkflows(pi) {
             }
             if (parent.state.workflowSource !== undefined &&
                 !isDeepStrictEqual(parent.state.workflowSource, workflowSource)) {
-                throw new Error(`Workflow source changed since run ${options.parentRunId} started; revert the edit to answer its checkpoint`);
+                throw continuationSourceChangedError(options.parentRunId, parent.state.workflowSource, workflowSource);
             }
         }
         // Interactive runs are queued and claimed atomically, so this session
@@ -744,21 +950,29 @@ export default function piWorkflows(pi) {
         }
         const executor = new ConversationStepExecutor({
             sendPrompt: ({ prompt, contract, presentation, kind, streaming }) => {
-                const details = {
-                    schema: WORKFLOW_AGENT_STEP_MESSAGE_SCHEMA,
-                    kind,
-                    contract,
-                    ...(presentation !== undefined ? { presentation } : {}),
-                };
-                pi.sendMessage({
-                    customType: WORKFLOW_AGENT_STEP_MESSAGE_TYPE,
-                    content: prompt,
-                    display: true,
-                    details,
-                }, {
-                    triggerTurn: true,
-                    deliverAs: streaming ? "steer" : "followUp",
-                });
+                turnCoordinator.sendNatural({
+                    runId,
+                    targetSessionId: originSessionId(ctx, runId),
+                    resolution: "workflowPrompt",
+                    send: (turnIntentId) => {
+                        const details = {
+                            schema: WORKFLOW_AGENT_STEP_MESSAGE_SCHEMA,
+                            kind,
+                            contract,
+                            ...(presentation !== undefined ? { presentation } : {}),
+                            ...(turnIntentId === undefined ? {} : { turnIntentId }),
+                        };
+                        pi.sendMessage({
+                            customType: WORKFLOW_AGENT_STEP_MESSAGE_TYPE,
+                            content: prompt,
+                            display: true,
+                            details,
+                        }, {
+                            triggerTurn: true,
+                            deliverAs: streaming ? "steer" : "followUp",
+                        });
+                    },
+                }, ctx.isIdle() && systemTurnAbort === null);
             },
             onAbort: (contract, reason) => {
                 lastExpiredAttempt = {
@@ -766,7 +980,15 @@ export default function piWorkflows(pi) {
                     reason: reason instanceof TimeoutError ? "timed out" : `ended: ${errorMessage(reason)}`,
                 };
                 if (!executor.held && !ctx.isIdle()) {
-                    systemTurnAbort = contract;
+                    const cause = reason instanceof TimeoutError ? "timedOut" : run.pendingAbortCause;
+                    const descriptor = cause === undefined
+                        ? undefined
+                        : ensureAbortTurnIntent(ctx, run, cause, contract, reason);
+                    run.pendingAbortCause = undefined;
+                    systemTurnAbort = {
+                        contract,
+                        ...(descriptor === undefined ? {} : { intentId: descriptor.intentId }),
+                    };
                     ctx.abort();
                 }
             },
@@ -859,6 +1081,7 @@ export default function piWorkflows(pi) {
             run.renewTimer = setInterval(() => {
                 try {
                     if (!store.renewWorkflowRunClaim({ runId, claimToken: token, leaseMs: RUN_CLAIM_LEASE_MS })) {
+                        run.pendingAbortCause = "claimLost";
                         run.engine.cancel();
                     }
                 }
@@ -952,6 +1175,11 @@ export default function piWorkflows(pi) {
             }
             if (terminalStatus !== undefined) {
                 recordRunEvent({ runId, workflowRef: workflow.name, type: terminalStatus, payload: {} });
+                if (terminalStatus === "failed" ||
+                    terminalStatus === "timed_out" ||
+                    terminalStatus === "cancelled") {
+                    makeRunTurnIntentEligible(ctx, run, terminalStatus, message);
+                }
                 notify(ctx, `Workflow ${workflow.name} ${terminalStatus} (run ${runId}).`);
                 return;
             }
@@ -961,6 +1189,7 @@ export default function piWorkflows(pi) {
                 type: "failed",
                 payload: { error: message },
             });
+            makeRunTurnIntentEligible(ctx, run, "failed", message);
             try {
                 run.onFinish?.({ state: "failed", runId, error: message });
             }
@@ -1155,10 +1384,12 @@ export default function piWorkflows(pi) {
         }
         return null;
     };
-    const cancelWorkflowControl = async (ctx, requestedRunId) => {
+    const cancelWorkflowControl = async (ctx, origin, requestedRunId) => {
         if (activeRun && (requestedRunId === undefined || requestedRunId === activeRun.runId)) {
             const workflowName = activeRun.workflowName;
             const runId = activeRun.runId;
+            activeRun.pendingAbortCause = origin === "agent" ? "agentCancelled" : undefined;
+            activeRun.suppressTurnIntent = origin === "user";
             activeRun.engine.cancel();
             return {
                 message: `Cancelling workflow ${workflowName}…`,
@@ -1250,6 +1481,7 @@ export default function piWorkflows(pi) {
                 },
             };
         }
+        activeRun.suppressTurnIntent = true;
         activeRun.engine.pause();
         renderWidget(ctx);
         return {
@@ -1282,6 +1514,7 @@ export default function piWorkflows(pi) {
                 level: "warning",
             };
         }
+        activeRun.suppressTurnIntent = false;
         activeRun.engine.resume();
         activeRun.executor.release();
         renderWidget(ctx);
@@ -1412,7 +1645,7 @@ export default function piWorkflows(pi) {
             };
             const store = new HumanDecisionStore(new WorkflowRunStore().outputRoot);
             const acceptance = await store.accept(request, submission);
-            if (acceptance.status === "conflict") {
+            if (acceptance.status === "conflict" || acceptance.decision.provenance !== "human") {
                 throw new Error("That human decision was already answered differently.");
             }
             accepted = acceptance.decision;
@@ -1442,6 +1675,7 @@ export default function piWorkflows(pi) {
                 schema: "pi-workflows.human-decision-continuation.v1",
                 decisionId: request.decisionId,
                 requestDigest: request.requestDigest,
+                provenance: accepted.provenance,
                 parentRunId: waiting.parentRunId,
                 runId: continuationRunId,
                 createdAt: accepted.acceptedAt,
@@ -1554,60 +1788,76 @@ export default function piWorkflows(pi) {
             const ownedBySession = queueRecord !== undefined &&
                 (queueRecord.originSessionId === null ||
                     queueRecord.originSessionId === ctx.sessionManager.getSessionId());
-            const accepted = await store.readAccepted(request.decisionId);
-            if (accepted === null) {
+            let resolved = await store.readResolved(request.decisionId);
+            if (resolved === null) {
                 let cancellation = await store.readCancellation(request.decisionId);
-                if (cancellation === null &&
-                    request.expiresAt !== undefined &&
-                    Date.parse(request.expiresAt) <= Date.now()) {
-                    await store.cancel(request, "expired");
-                    cancellation = await store.readCancellation(request.decisionId);
+                const expired = request.expiresAt !== undefined && Date.parse(request.expiresAt) <= Date.now();
+                if (cancellation === null && expired) {
+                    if (request.defaultResponse === undefined) {
+                        await store.cancel(request, "expired");
+                        cancellation = await store.readCancellation(request.decisionId);
+                    }
+                    else {
+                        try {
+                            resolved = (await store.resolveTimeout(request)).decision;
+                        }
+                        catch {
+                            cancellation = await store.readCancellation(request.decisionId);
+                            resolved = await store.readResolved(request.decisionId);
+                        }
+                    }
                 }
                 if (cancellation !== null) {
                     await settleHumanDecisionChannels(cancellation);
                     continue;
                 }
-                if (!deliverPending || !ownedBySession)
+                if (resolved === null) {
+                    if (!deliverPending || !ownedBySession)
+                        continue;
+                    const channels = audienceChannels(decisionChannelConfig, request.audience);
+                    for (const channelId of channels) {
+                        const channel = telegramDecisionChannels.get(channelId);
+                        if (channel !== undefined)
+                            await channel.deliver(humanDecisionChannelRequest(request));
+                    }
+                    if (ctx.mode === "tui" && channels.includes("pi") && lastWaitingRunId === null) {
+                        lastWaitingRunId = request.runId;
+                        queueMicrotask(() => void promptHumanDecision(ctx, request));
+                    }
                     continue;
-                const channels = audienceChannels(decisionChannelConfig, request.audience);
-                for (const channelId of channels) {
-                    const channel = telegramDecisionChannels.get(channelId);
-                    if (channel !== undefined)
-                        await channel.deliver(humanDecisionChannelRequest(request));
-                }
-                if (ctx.mode === "tui" && channels.includes("pi") && lastWaitingRunId === null) {
-                    lastWaitingRunId = request.runId;
-                    queueMicrotask(() => void promptHumanDecision(ctx, request));
                 }
-                continue;
             }
             if (!ownedBySession)
                 continue;
+            const currentParent = await readRunBundle(runStore.runDirFor(request.runId));
+            if (currentParent === null || currentParent.state.status !== "waiting")
+                continue;
             const runId = `continuation-${request.decisionId.slice("decision-".length)}`;
             const continuation = (await store.readContinuation(request.decisionId)) ?? {
                 schema: "pi-workflows.human-decision-continuation.v1",
                 decisionId: request.decisionId,
                 requestDigest: request.requestDigest,
+                provenance: resolved.provenance,
                 parentRunId: request.runId,
                 runId,
-                createdAt: accepted.acceptedAt,
+                createdAt: resolved.acceptedAt,
             };
             await store.recordContinuation(request.decisionId, continuation);
             const existing = await readRunBundle(runStore.runDirFor(continuation.runId));
             if (existing === null && activeRun === null) {
-                if (parent.state.workflowSource === undefined)
+                if (currentParent.state.workflowSource === undefined)
                     continue;
-                const workflowRef = parent.state.workflowSource.kind === "builtin"
-                    ? `builtin:${parent.state.workflowSource.id}`
-                    : parent.state.workflowSource.path;
-                await startRun(ctx, workflowRef, parent.state.input, {
+                const workflowRef = currentParent.state.workflowSource.kind === "builtin"
+                    ? `builtin:${currentParent.state.workflowSource.id}`
+                    : currentParent.state.workflowSource.path;
+                await startRun(ctx, workflowRef, currentParent.state.input, {
                     parentRunId: request.runId,
-                    humanDecision: accepted,
+                    humanDecision: resolved,
                     runId: continuation.runId,
                     quiet: true,
                 });
             }
-            await settleHumanDecisionChannels(accepted);
+            await settleHumanDecisionChannels(resolved);
             if (activeRun !== null)
                 break;
         }
@@ -1669,7 +1919,7 @@ export default function piWorkflows(pi) {
             }
             if (parent.state.workflowSource !== undefined &&
                 !isDeepStrictEqual(parent.state.workflowSource, workflowSource)) {
-                throw new Error(`Workflow source changed since run ${options.parentRunId} started; revert the edit to answer its checkpoint`);
+                throw continuationSourceChangedError(options.parentRunId, parent.state.workflowSource, workflowSource);
             }
         }
         const snapshot = createDefinitionSnapshot(workflow);
@@ -1758,20 +2008,28 @@ export default function piWorkflows(pi) {
                 payload: { errorCode: safe.code, error: safe.message },
             });
             const content = `Workflow ${claimed.workflowName} failed to start (run ${claimed.runId}): ${safe.message}. Inspect the error and call workflow start again only after you correct the cause.`;
-            try {
-                queue.enqueueWorkflowNotification({
+            const cause = "launchFailed";
+            const descriptor = createDeferredTurnDescriptor({
+                runId: claimed.runId,
+                workflowName: claimed.workflowName,
+                targetSessionId: claimed.originSessionId ?? ctx.sessionManager.getSessionId(),
+                cause,
+                sourceEventId: deferredTurnSourceEventId({
                     runId: claimed.runId,
+                    cause,
                     nodeId: "$launch",
-                    attemptId: claimed.runId,
-                    notificationIndex: 1,
-                    targetSessionId: claimed.originSessionId ?? ctx.sessionManager.getSessionId(),
-                    kind: "launch_failure",
-                    content,
-                    notificationId: `launch-failure:${claimed.runId}`,
-                });
+                    source: "queued-launch",
+                }),
+                observedState: "failedToStart",
+                nodeId: "$launch",
+                reason: safe.message,
+            });
+            try {
+                storeTurnDescriptor(ctx, descriptor, true);
+                syncArmed = true;
             }
-            catch {
-                // A deterministic notification id makes duplicate insertion harmless.
+            catch (intentError) {
+                notify(ctx, `Workflow ${claimed.workflowName} failed to start, but Pi Workflows could not preserve its successor turn: ${errorMessage(intentError)}`, "warning");
             }
             notify(ctx, content, "error");
             runSyncPass(ctx);
@@ -1830,7 +2088,7 @@ export default function piWorkflows(pi) {
                 return;
             }
             if (parsed.kind === "cancel") {
-                const result = await cancelWorkflowControl(ctx);
+                const result = await cancelWorkflowControl(ctx, "user");
                 notify(ctx, result.message, result.level);
                 return;
             }
@@ -1990,6 +2248,7 @@ export default function piWorkflows(pi) {
                     case "stop":
                         if (activeRun?.childKey !== undefined) {
                             activeRun.interruptionRequested = true;
+                            activeRun.pendingAbortCause = "controllerInterrupted";
                             activeRun.engine.cancel();
                         }
                         await host.stop();
@@ -2006,7 +2265,7 @@ export default function piWorkflows(pi) {
         name: "workflow",
         label: "Workflow",
         description: [
-            "List, start, inspect, pause, resume, cancel, answer, update, or complete Pi Workflows runs.",
+            "List, start, inspect, pause, resume, cancel, answer, update, or complete pi-workflows runs.",
             "When the user asks to monitor, watch, poll, or check something repeatedly, start the built-in monitor workflow with input keys task, everyMinutes, stopWhen, and optional maxChecks.",
             "Use update or submit only when a workflow step contract asks for it, and pass the exact step and attempt ids.",
             "Do not start repeated work without the user's request, and keep monitoring observation-only unless the user authorizes mutations.",
@@ -2032,7 +2291,7 @@ export default function piWorkflows(pi) {
                     control = resumeWorkflowControl(ctx);
                     break;
                 case "cancel":
-                    control = await cancelWorkflowControl(ctx, params.runId);
+                    control = await cancelWorkflowControl(ctx, "agent", params.runId);
                     break;
                 case "answer": {
                     const waiting = await resolveWaitingWorkflow(ctx, params.runId);
@@ -2190,6 +2449,7 @@ export default function piWorkflows(pi) {
         if (!aborted || runHeld()) {
             return;
         }
+        run.suppressTurnIntent = true;
         run.engine.pause();
         run.executor.hold();
         renderWidget(ctx);
@@ -2228,6 +2488,7 @@ export default function piWorkflows(pi) {
         activeRun?.recorder?.handleToolEnd(event);
     });
     pi.on("agent_settled", async (_event, ctx) => {
+        systemTurnAbort = null;
         if (activeRun === null) {
             try {
                 const prepared = ensureRunQueueStore(ctx.cwd).findSessionReservation(ctx.sessionManager.getSessionId());
@@ -2241,23 +2502,30 @@ export default function piWorkflows(pi) {
                 return;
             }
         }
+        const flushedNatural = turnCoordinator.flushNatural(ctx.isIdle() && !sessionClosed && !runHeld());
         const run = activeRun;
         if (!run) {
             presentationPending = null;
+            runSyncPass(ctx);
             return;
         }
         await run.recorder?.synchronize(ctx).catch(() => undefined);
         run.recorder?.settleAttempt();
         run.executor.setStreaming(false);
-        run.executor.handleAgentSettled();
+        if (flushedNatural === 0)
+            run.executor.handleAgentSettled();
+        runSyncPass(ctx);
     });
     pi.on("session_shutdown", async () => {
         sessionClosed = true;
         herdrProbeGeneration += 1;
         systemTurnAbort = null;
         suppressWorkflowAssistantTail = false;
+        turnCoordinator.clearDeferred();
         supersedePresentation();
         const run = activeRun;
+        if (run !== null)
+            run.suppressTurnIntent = true;
         if (run !== null && run.claimToken !== undefined) {
             // Queued interactive runs park: no terminal event, no recorded partial
             // attempt, and the claim releases so another runner can resume.