@osolmaz/pi-workflows 0.11.1 → 0.12.0

package/dist/extension/index.js

@@ -1,8 +1,9 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import path from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import { builtinWorkflowCatalog } from "../builtins/catalog.js";
-import { projectControllerStorePath, SqliteControllerStore } from "../controllers/index.js";
+import { projectControllerStorePath, SqliteControllerStore, } from "../controllers/index.js";
+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";
@@ -13,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";
@@ -24,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;
@@ -56,6 +61,44 @@ function humanDecisionRequest(value) {
     }
     return value;
 }
+function definitionDigest(snapshot) {
+    return `sha256:${createHash("sha256").update(JSON.stringify(snapshot)).digest("hex")}`;
+}
+function launchSourceIdentity(workflow, root) {
+    return {
+        root,
+        mounted: compositionMetadata(workflow)?.sources ?? [],
+    };
+}
+function preparedLaunchOptions(options) {
+    return {
+        ...(options.presentation !== undefined ? { presentation: options.presentation } : {}),
+        ...(options.parentRunId !== undefined ? { parentRunId: options.parentRunId } : {}),
+        ...(options.humanDecision !== undefined ? { humanDecision: options.humanDecision } : {}),
+    };
+}
+function parsePreparedLaunchOptions(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Stored workflow launch options are invalid");
+    }
+    return value;
+}
+function safeLaunchError(error) {
+    const raw = errorMessage(error)
+        .replace(/Bearer\s+\S+/giu, "Bearer [redacted]")
+        .replace(/(token|api[_-]?key|secret|password)(\s*[:=]\s*)\S+/giu, "$1$2[redacted]")
+        .replaceAll("\n", " ")
+        .trim();
+    const code = /not found|cannot find|unknown workflow/iu.test(raw)
+        ? "workflow_not_found"
+        : /source changed|source mismatch/iu.test(raw)
+            ? "source_changed"
+            : /invalid|must be/iu.test(raw)
+                ? "workflow_invalid"
+                : "activation_failed";
+    const message = raw.length <= 500 ? raw : `${raw.slice(0, 480)}… [error truncated]`;
+    return { code, message: message || "The deferred workflow could not start" };
+}
 /** Parse `/workflow` arguments. Exported for tests. */
 export function parseWorkflowArgs(args) {
     const trimmed = args.trim();
@@ -178,8 +221,10 @@ export default function piWorkflows(pi) {
     // Run events remain an audit feed and never enter a conversation.
     let syncArmed = false;
     let runSyncTimer = null;
+    let activationRecovery;
     let decisionRecoveryTimer = null;
     let decisionRecoveryActive = false;
+    let turnCoordinator;
     const recordRunEvent = (event) => {
         try {
             runQueueStore?.recordRunEvent({ ...event, runnerId });
@@ -207,6 +252,7 @@ export default function piWorkflows(pi) {
         if (runQueueStore === null || !syncArmed)
             return;
         try {
+            activationRecovery?.(ctx);
             const sessionId = ctx.sessionManager.getSessionId();
             const alreadyDelivered = deliveredNotificationIds(ctx);
             const claimToken = randomUUID();
@@ -234,6 +280,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.
@@ -252,7 +311,6 @@ export default function piWorkflows(pi) {
     let systemTurnAbort = null;
     let suppressWorkflowAssistantTail = false;
     let lastExpiredAttempt = null;
-    let pendingToolLaunch = null;
     // The interactive run currently parked at a checkpoint, if any.
     let lastWaitingRunId = null;
     let widgetTimer = null;
@@ -270,6 +328,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.
@@ -310,6 +397,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;
@@ -470,20 +666,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) {
@@ -498,6 +710,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);
@@ -548,6 +763,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,
@@ -596,6 +824,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);
@@ -671,7 +907,10 @@ export default function piWorkflows(pi) {
                     workflowSourceRef: workflowSource.kind === "builtin"
                         ? `builtin:${workflowSource.id}`
                         : workflowSource.path,
+                    workflowSource: launchSourceIdentity(workflow, workflowSource),
+                    definitionDigest: definitionDigest(snapshot),
                     input,
+                    launchOptions: preparedLaunchOptions(options),
                     runnerId,
                     claimToken: token,
                     leaseMs: RUN_CLAIM_LEASE_MS,
@@ -699,21 +938,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 = {
@@ -721,7 +968,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();
                 }
             },
@@ -799,6 +1054,11 @@ export default function piWorkflows(pi) {
             ...(options.resume === true ? { resume: true } : {}),
             ...(options.parentRunId !== undefined ? { parentRunId: options.parentRunId } : {}),
         };
+        if (queueStore !== null &&
+            claimToken !== undefined &&
+            !queueStore.markWorkflowRunRunning({ runId, claimToken })) {
+            throw new ClaimLostError(runId);
+        }
         activeRun = run;
         if (queueStore !== null && claimToken !== undefined) {
             const store = queueStore;
@@ -809,6 +1069,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();
                     }
                 }
@@ -902,6 +1163,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;
             }
@@ -911,6 +1177,7 @@ export default function piWorkflows(pi) {
                 type: "failed",
                 payload: { error: message },
             });
+            makeRunTurnIntentEligible(ctx, run, "failed", message);
             try {
                 run.onFinish?.({ state: "failed", runId, error: message });
             }
@@ -948,8 +1215,10 @@ export default function piWorkflows(pi) {
                 : bundle.state.workflowSource.kind === "builtin"
                     ? `builtin:${bundle.state.workflowSource.id}`
                     : bundle.state.workflowSource.path;
+            const launchOptions = parsePreparedLaunchOptions(claimed.launchOptions);
             started = await startRun(ctx, sourceRef, claimed.input, {
-                resume: true,
+                ...launchOptions,
+                resume: bundle !== null,
                 runId: claimed.runId,
                 claimToken,
             });
@@ -1103,22 +1372,42 @@ export default function piWorkflows(pi) {
         }
         return null;
     };
-    const cancelWorkflowControl = async (ctx) => {
-        if (activeRun) {
+    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}…`,
                 details: { action: "cancel", workflowName, runId },
             };
         }
-        if (pendingToolLaunch !== null) {
-            const ref = pendingToolLaunch.ref;
-            pendingToolLaunch = null;
+        const queue = ensureRunQueueStore(ctx.cwd);
+        const queued = requestedRunId === undefined
+            ? queue.findSessionReservation(ctx.sessionManager.getSessionId())
+            : queue.getWorkflowRun(requestedRunId);
+        if (queued !== undefined &&
+            ["queued", "starting"].includes(queued.status) &&
+            (queued.originSessionId === null ||
+                queued.originSessionId === ctx.sessionManager.getSessionId())) {
+            if (!queue.cancelWorkflowRun({ runId: queued.runId })) {
+                throw new Error(`Workflow ${queued.runId} could not be cancelled because its state changed.`);
+            }
+            recordRunEvent({
+                runId: queued.runId,
+                workflowRef: queued.workflowName,
+                type: "cancelled",
+            });
             return {
-                message: `Cancelled the queued workflow launch for ${ref}.`,
-                details: { action: "cancel", workflow: ref, queued: false },
+                message: `Cancelled queued workflow ${queued.workflowName} (run ${queued.runId}).`,
+                details: {
+                    action: "cancel",
+                    workflow: queued.workflowName,
+                    runId: queued.runId,
+                    queued: false,
+                },
             };
         }
         if (widgetSource) {
@@ -1180,6 +1469,7 @@ export default function piWorkflows(pi) {
                 },
             };
         }
+        activeRun.suppressTurnIntent = true;
         activeRun.engine.pause();
         renderWidget(ctx);
         return {
@@ -1212,6 +1502,7 @@ export default function piWorkflows(pi) {
                 level: "warning",
             };
         }
+        activeRun.suppressTurnIntent = false;
         activeRun.engine.resume();
         activeRun.executor.release();
         renderWidget(ctx);
@@ -1225,11 +1516,28 @@ export default function piWorkflows(pi) {
             },
         };
     };
+    const workflowLaunchStatus = (record) => ({
+        message: `Workflow ${record.workflowName} is ${record.status} (run ${record.runId}).`,
+        details: {
+            action: "status",
+            active: ["starting", "running"].includes(record.status),
+            queued: record.status === "queued",
+            workflowName: record.workflowName,
+            runId: record.runId,
+            status: record.status,
+            ...(record.errorCode === null ? {} : { errorCode: record.errorCode }),
+            ...(record.errorMessage === null ? {} : { error: record.errorMessage }),
+        },
+        ...(["failed", "cancelled"].includes(record.status) ? { level: "warning" } : {}),
+    });
     const statusWorkflowControl = async (ctx, runId) => {
         if (runId !== undefined) {
             const bundle = await readRunBundle(new WorkflowRunStore().runDirFor(runId));
             if (bundle === null) {
-                throw new Error(`Workflow run not found: ${runId}`);
+                const launch = ensureRunQueueStore(ctx.cwd).getWorkflowRun(runId);
+                if (launch === undefined)
+                    throw new Error(`Workflow run not found: ${runId}`);
+                return workflowLaunchStatus(launch);
             }
             const { state } = bundle;
             return {
@@ -1238,11 +1546,10 @@ export default function piWorkflows(pi) {
             };
         }
         const state = activeRun?.lastState ?? widgetSource?.state;
-        if ((state === undefined || state === null) && pendingToolLaunch !== null) {
-            return {
-                message: `Workflow ${pendingToolLaunch.ref} is queued until the current turn finishes.`,
-                details: { active: false, queued: true, workflow: pendingToolLaunch.ref },
-            };
+        if (state === undefined || state === null) {
+            const queued = ensureRunQueueStore(ctx.cwd).findSessionReservation(ctx.sessionManager.getSessionId());
+            if (queued !== undefined)
+                return workflowLaunchStatus(queued);
         }
         if (state === undefined || state === null) {
             return {
@@ -1545,8 +1852,9 @@ export default function piWorkflows(pi) {
         if (activeRun !== null) {
             throw new Error(`A workflow is already running: ${activeRun.workflowName}.`);
         }
-        if (pendingToolLaunch !== null) {
-            throw new Error("A workflow launch is already waiting for the current turn to finish.");
+        const reserved = ensureRunQueueStore(ctx.cwd).findSessionReservation(ctx.sessionManager.getSessionId());
+        if (reserved !== undefined) {
+            throw new Error(`Workflow ${reserved.workflowName} is already ${reserved.status} (run ${reserved.runId}).`);
         }
         if (presentationPending !== null) {
             throw new Error("The previous workflow result is still being presented.");
@@ -1564,36 +1872,148 @@ export default function piWorkflows(pi) {
         if (activeRun !== null) {
             throw new Error(`A workflow is already running: ${activeRun.workflowName}. Cancel it before starting another.`);
         }
-        if (pendingToolLaunch !== null) {
-            throw new Error("A workflow launch is already waiting for the current turn to finish.");
+        const queue = ensureRunQueueStore(ctx.cwd);
+        const existing = queue.findSessionReservation(ctx.sessionManager.getSessionId());
+        if (existing !== undefined) {
+            throw new Error(`Workflow ${existing.workflowName} is already ${existing.status} (run ${existing.runId}).`);
         }
         if (presentationPending !== null) {
             throw new Error("The previous workflow result is still being presented.");
         }
-        const reservation = { ctx, ref, input, options };
-        pendingToolLaunch = reservation;
-        try {
-            const resolved = await resolveWorkflowRef(ref, { cwd: ctx.cwd }, builtinWorkflowCatalog);
-            const workflow = resolved.definition;
-            if (pendingToolLaunch !== reservation) {
-                throw new Error("The queued workflow launch was cancelled before validation finished.");
+        const resolved = await resolveWorkflowRef(ref, { cwd: ctx.cwd }, builtinWorkflowCatalog);
+        const workflow = resolved.definition;
+        const workflowSource = resolved.source;
+        if (options.parentRunId !== undefined) {
+            const parent = await readRunBundle(new WorkflowRunStore().runDirFor(options.parentRunId));
+            if (parent === null || parent.state.status !== "waiting") {
+                throw new Error(`Workflow run ${options.parentRunId} is not waiting at a checkpoint`);
             }
-            return {
-                message: `Workflow ${workflow.name} will start after this turn finishes.`,
-                details: {
-                    action: "start",
-                    workflow: workflow.name,
-                    source: resolved.source,
-                    queued: true,
-                },
-            };
+            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`);
+            }
+        }
+        const snapshot = createDefinitionSnapshot(workflow);
+        const runId = createRunId(workflow.name);
+        try {
+            queue.reserveWorkflowRun({
+                runId,
+                workflowName: workflow.name,
+                workflowSourceRef: workflowSource.kind === "builtin" ? `builtin:${workflowSource.id}` : workflowSource.path,
+                workflowSource: launchSourceIdentity(workflow, workflowSource),
+                definitionDigest: definitionDigest(snapshot),
+                input,
+                launchOptions: preparedLaunchOptions(options),
+                runnerId,
+                originSessionId: ctx.sessionManager.getSessionId(),
+                ...(options.parentRunId !== undefined ? { parentRunId: options.parentRunId } : {}),
+            });
         }
         catch (error) {
-            if (pendingToolLaunch === reservation) {
-                pendingToolLaunch = null;
+            const reserved = queue.findSessionReservation(ctx.sessionManager.getSessionId());
+            if (reserved !== undefined) {
+                throw new Error(`A workflow launch is already waiting: ${reserved.workflowName} (run ${reserved.runId}).`, { cause: error });
             }
             throw error;
         }
+        recordRunEvent({
+            runId,
+            workflowRef: workflow.name,
+            type: "queued",
+            payload: options.parentRunId === undefined ? {} : { parentRunId: options.parentRunId },
+        });
+        syncArmed = true;
+        return {
+            message: `Workflow ${workflow.name} queued (run ${runId}).`,
+            details: {
+                action: "start",
+                workflow: workflow.name,
+                runId,
+                source: workflowSource,
+                queued: true,
+            },
+        };
+    };
+    const activatePreparedLaunch = async (ctx, prepared) => {
+        const queue = ensureRunQueueStore(ctx.cwd);
+        const claimToken = randomUUID();
+        const claimed = queue.claimWorkflowRun({
+            runId: prepared.runId,
+            runnerId,
+            claimToken,
+            leaseMs: RUN_CLAIM_LEASE_MS,
+        });
+        if (claimed === undefined)
+            return false;
+        try {
+            const resolved = await resolveWorkflowRef(claimed.workflowSourceRef, { cwd: ctx.cwd }, builtinWorkflowCatalog);
+            const snapshot = createDefinitionSnapshot(resolved.definition);
+            if (!isDeepStrictEqual(launchSourceIdentity(resolved.definition, resolved.source), claimed.workflowSource) ||
+                definitionDigest(snapshot) !== claimed.definitionDigest) {
+                throw new Error("Workflow source changed after the launch was queued");
+            }
+            const launchOptions = parsePreparedLaunchOptions(claimed.launchOptions);
+            const started = await startRun(ctx, claimed.workflowSourceRef, claimed.input, {
+                ...launchOptions,
+                runId: claimed.runId,
+                claimToken,
+            });
+            if (started === undefined)
+                throw new Error("The queued workflow could not start");
+            if (launchOptions.parentRunId !== undefined)
+                lastWaitingRunId = null;
+            return true;
+        }
+        catch (error) {
+            const safe = safeLaunchError(error);
+            queue.failWorkflowRun({
+                runId: claimed.runId,
+                claimToken,
+                errorCode: safe.code,
+                errorMessage: safe.message,
+            });
+            recordRunEvent({
+                runId: claimed.runId,
+                workflowRef: claimed.workflowName,
+                type: "launch_failed",
+                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.`;
+            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",
+                    source: "queued-launch",
+                }),
+                observedState: "failedToStart",
+                nodeId: "$launch",
+                reason: safe.message,
+            });
+            try {
+                storeTurnDescriptor(ctx, descriptor, true);
+                syncArmed = true;
+            }
+            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);
+            return false;
+        }
+    };
+    activationRecovery = (ctx) => {
+        if (activeRun !== null)
+            return;
+        const prepared = ensureRunQueueStore(ctx.cwd).findSessionReservation(ctx.sessionManager.getSessionId());
+        if (prepared !== undefined && ["queued", "starting"].includes(prepared.status)) {
+            void activatePreparedLaunch(ctx, prepared).catch(() => undefined);
+        }
     };
     pi.registerCommand("piw", {
         description: "Open the current workflow run in piw through Herdr",
@@ -1639,7 +2059,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;
             }
@@ -1799,6 +2219,7 @@ export default function piWorkflows(pi) {
                     case "stop":
                         if (activeRun?.childKey !== undefined) {
                             activeRun.interruptionRequested = true;
+                            activeRun.pendingAbortCause = "controllerInterrupted";
                             activeRun.engine.cancel();
                         }
                         await host.stop();
@@ -1815,7 +2236,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.",
@@ -1841,7 +2262,7 @@ export default function piWorkflows(pi) {
                     control = resumeWorkflowControl(ctx);
                     break;
                 case "cancel":
-                    control = await cancelWorkflowControl(ctx);
+                    control = await cancelWorkflowControl(ctx, "agent", params.runId);
                     break;
                 case "answer": {
                     const waiting = await resolveWaitingWorkflow(ctx, params.runId);
@@ -1951,7 +2372,13 @@ export default function piWorkflows(pi) {
             notify(ctx, `Could not recover human decisions: ${errorMessage(error)}`, "warning");
         }
         try {
-            await resumeParkedRun(ctx);
+            const prepared = ensureRunQueueStore(ctx.cwd).findSessionReservation(ctx.sessionManager.getSessionId());
+            if (prepared !== undefined && ["queued", "starting"].includes(prepared.status)) {
+                await activatePreparedLaunch(ctx, prepared);
+            }
+            else {
+                await resumeParkedRun(ctx);
+            }
         }
         catch (error) {
             notify(ctx, `Could not resume a parked workflow: ${errorMessage(error)}`, "warning");
@@ -1993,6 +2420,7 @@ export default function piWorkflows(pi) {
         if (!aborted || runHeld()) {
             return;
         }
+        run.suppressTurnIntent = true;
         run.engine.pause();
         run.executor.hold();
         renderWidget(ctx);
@@ -2031,40 +2459,44 @@ export default function piWorkflows(pi) {
         activeRun?.recorder?.handleToolEnd(event);
     });
     pi.on("agent_settled", async (_event, ctx) => {
-        if (activeRun === null && pendingToolLaunch !== null) {
-            const launch = pendingToolLaunch;
-            pendingToolLaunch = null;
+        systemTurnAbort = null;
+        if (activeRun === null) {
             try {
-                const runId = await startRun(launch.ctx, launch.ref, launch.input, launch.options);
-                if (runId === undefined) {
-                    notify(launch.ctx, "The queued workflow could not start.", "error");
-                }
-                else if (launch.options?.parentRunId !== undefined) {
-                    lastWaitingRunId = null;
+                const prepared = ensureRunQueueStore(ctx.cwd).findSessionReservation(ctx.sessionManager.getSessionId());
+                if (prepared !== undefined && ["queued", "starting"].includes(prepared.status)) {
+                    await activatePreparedLaunch(ctx, prepared);
+                    return;
                 }
             }
             catch (error) {
-                notify(launch.ctx, `Could not start queued workflow: ${errorMessage(error)}`, "error");
+                notify(ctx, `Could not activate a queued workflow: ${safeLaunchError(error).message}`, "warning");
+                return;
             }
-            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.
@@ -2076,7 +2508,6 @@ export default function piWorkflows(pi) {
         await run?.recorder?.stop().catch(() => undefined);
         await run?.completion?.catch(() => undefined);
         activeRun = null;
-        pendingToolLaunch = null;
         lastWaitingRunId = null;
         if (runSyncTimer !== null) {
             clearInterval(runSyncTimer);