@osolmaz/pi-workflows 0.11.1 → 0.12.0

package/src/extension/index.ts

@@ -1,11 +1,20 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import path from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
 import { builtinWorkflowCatalog } from "../builtins/catalog.js";
-import { projectControllerStorePath, SqliteControllerStore } from "../controllers/index.js";
+import {
+  projectControllerStorePath,
+  SqliteControllerStore,
+  type WorkflowRunQueueRecord,
+} from "../controllers/index.js";
+import type {
+  WorkflowTurnIntentCause,
+  WorkflowTurnIntentResolution,
+} from "../controllers/sqlite.js";
 import type { JsonObject } from "../controllers/types.js";
 import type { WorkflowSchedulerResult } from "../controllers/workflows.js";
+import { compositionMetadata } from "../workflows/composition.js";
 import { humanDecisionChannelRequest } from "../workflows/decision-presentation.js";
 import { WorkflowEngine } from "../workflows/engine.js";
 import {
@@ -58,6 +67,19 @@ import {
   type HumanDecisionChannelAnswer,
   type SettledHumanDecision,
 } from "./decision-channels.js";
+import {
+  DeferredTurnCoordinator,
+  type BranchIntentResolution,
+} from "./deferred-turn-coordinator.js";
+import {
+  buildDeferredTurnContent,
+  createDeferredTurnDescriptor,
+  DEFERRED_TURN_MESSAGE_TYPE,
+  deferredTurnMessageDetails,
+  deferredTurnMessageId,
+  deferredTurnSourceEventId,
+  type DeferredTurnDescriptor,
+} from "./deferred-turn.js";
 import { ConversationStepExecutor } from "./executor.js";
 import {
   HerdrWorkflowViewer,
@@ -103,8 +125,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;
@@ -133,6 +157,12 @@ type PresentationPromptBuilder = Exclude<
   string | undefined
 >;
 
+type AbortProvenance = {
+  cause: WorkflowTurnIntentCause;
+  descriptor?: DeferredTurnDescriptor;
+  storageError?: string;
+};
+
 type ActiveRun = {
   runId: string;
   workflowName: string;
@@ -148,6 +178,9 @@ type ActiveRun = {
   onFinish?: (result: WorkflowSchedulerResult) => void;
   completion?: Promise<void>;
   interruptionRequested?: boolean;
+  pendingAbortCause?: WorkflowTurnIntentCause | undefined;
+  abortProvenance?: AbortProvenance | undefined;
+  suppressTurnIntent?: boolean | undefined;
   claimToken?: string | undefined;
   renewTimer?: ReturnType<typeof setInterval> | undefined;
   /** True for runs this session resumed from the queue. */
@@ -170,6 +203,12 @@ function humanDecisionRequest(value: unknown): HumanDecisionRequest | null {
   return value as HumanDecisionRequest;
 }
 
+type PreparedLaunchOptions = {
+  presentation?: boolean;
+  parentRunId?: string;
+  humanDecision?: AcceptedHumanDecision;
+};
+
 type StartRunOptions = {
   runId?: string;
   childKey?: string;
@@ -187,6 +226,49 @@ type StartRunOptions = {
   claimToken?: string;
 };
 
+function definitionDigest(snapshot: WorkflowDefinitionSnapshot): string {
+  return `sha256:${createHash("sha256").update(JSON.stringify(snapshot)).digest("hex")}`;
+}
+
+function launchSourceIdentity(workflow: WorkflowDefinition, root: unknown): unknown {
+  return {
+    root,
+    mounted: compositionMetadata(workflow)?.sources ?? [],
+  };
+}
+
+function preparedLaunchOptions(options: StartRunOptions): PreparedLaunchOptions {
+  return {
+    ...(options.presentation !== undefined ? { presentation: options.presentation } : {}),
+    ...(options.parentRunId !== undefined ? { parentRunId: options.parentRunId } : {}),
+    ...(options.humanDecision !== undefined ? { humanDecision: options.humanDecision } : {}),
+  };
+}
+
+function parsePreparedLaunchOptions(value: unknown): PreparedLaunchOptions {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Stored workflow launch options are invalid");
+  }
+  return value as PreparedLaunchOptions;
+}
+
+function safeLaunchError(error: unknown): { code: string; message: string } {
+  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" };
+}
+
 export type ParsedWorkflowArgs =
   | { kind: "list" }
   | { kind: "cancel" }
@@ -343,8 +425,10 @@ export default function piWorkflows(pi: ExtensionAPI) {
   // Run events remain an audit feed and never enter a conversation.
   let syncArmed = false;
   let runSyncTimer: ReturnType<typeof setInterval> | null = null;
+  let activationRecovery: ((ctx: ExtensionContext) => void) | undefined;
   let decisionRecoveryTimer: ReturnType<typeof setInterval> | null = null;
   let decisionRecoveryActive = false;
+  let turnCoordinator: DeferredTurnCoordinator;
 
   const recordRunEvent = (event: {
     runId: string;
@@ -377,6 +461,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
   const runSyncPass = (ctx: ExtensionContext): void => {
     if (runQueueStore === null || !syncArmed) return;
     try {
+      activationRecovery?.(ctx);
       const sessionId = ctx.sessionManager.getSessionId();
       const alreadyDelivered = deliveredNotificationIds(ctx);
       const claimToken = randomUUID();
@@ -407,6 +492,25 @@ export default function piWorkflows(pi: ExtensionAPI) {
           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.
     }
@@ -422,15 +526,9 @@ export default function piWorkflows(pi: ExtensionAPI) {
     runSyncTimer.unref?.();
   };
   let activeRun: ActiveRun | null = null;
-  let systemTurnAbort: AgentStepContract | null = null;
+  let systemTurnAbort: { contract: AgentStepContract; intentId?: string } | null = null;
   let suppressWorkflowAssistantTail = false;
   let lastExpiredAttempt: { contract: AgentStepContract; reason: string } | null = null;
-  let pendingToolLaunch: {
-    ctx: ExtensionContext;
-    ref: string;
-    input: unknown;
-    options?: StartRunOptions;
-  } | null = null;
   // The interactive run currently parked at a checkpoint, if any.
   let lastWaitingRunId: string | null = null;
   let widgetTimer: NodeJS.Timeout | null = null;
@@ -449,6 +547,30 @@ export default function piWorkflows(pi: ExtensionAPI) {
   let controllerHost: PiControllerHost | undefined;
   let controllerContext: ExtensionContext | null = null;
 
+  const branchIntentResolution = (intentId: string): BranchIntentResolution | null => {
+    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 as { turnIntentId?: unknown }).turnIntentId !== intentId) continue;
+      let resolution: WorkflowTurnIntentResolution | null = 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.
@@ -490,6 +612,145 @@ export default function piWorkflows(pi: ExtensionAPI) {
   const runHeld = (): boolean =>
     activeRun !== null && (activeRun.engine.pauseRequested || activeRun.executor.held);
 
+  const originSessionId = (ctx: ExtensionContext, runId: string): string =>
+    ensureRunQueueStore(ctx.cwd).getWorkflowRun(runId)?.originSessionId ??
+    ctx.sessionManager.getSessionId();
+
+  const storeTurnDescriptor = (
+    ctx: ExtensionContext,
+    descriptor: DeferredTurnDescriptor,
+    eligible: boolean,
+  ): void => {
+    ensureRunQueueStore(ctx.cwd).ensureWorkflowTurnIntent({ ...descriptor, eligible });
+  };
+
+  const ensureAbortTurnIntent = (
+    ctx: ExtensionContext,
+    run: ActiveRun,
+    cause: WorkflowTurnIntentCause,
+    contract: AgentStepContract,
+    reason: unknown,
+  ): DeferredTurnDescriptor => {
+    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: ExtensionContext,
+    run: ActiveRun,
+    observedState: string,
+    reason?: string,
+  ): void => {
+    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: WorkflowRunState): string => {
     const label = runHeld() || state.paused ? "paused" : state.status;
     const node = state.currentNode ?? state.waitingOn;
@@ -690,24 +951,41 @@ export default function piWorkflows(pi: ExtensionAPI) {
         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;
       }
-      presentationPending = run.generation;
-      suppressWorkflowAssistantTail = false;
-      pi.sendMessage(
+      if (instructions === undefined || instructions.trim().length === 0) {
+        if (run.abortProvenance !== undefined) {
+          makeRunTurnIntentEligible(ctx, run, state.status, "No result presentation was available");
+        }
+        return;
+      }
+      turnCoordinator.sendNatural(
         {
-          customType: PRESENTATION_MESSAGE_TYPE,
-          content: buildPresentationMessage(instructions, state),
-          display: false,
+          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,
+              },
+            );
+          },
         },
-        { deliverAs: "steer", triggerTurn: true },
+        ctx.isIdle() && systemTurnAbort === null,
       );
     } catch (error) {
       if (presentationPending === run.generation) {
@@ -725,6 +1003,9 @@ export default function piWorkflows(pi: ExtensionAPI) {
           ? `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);
       if (presentationAbort === abort) {
@@ -777,6 +1058,22 @@ export default function piWorkflows(pi: ExtensionAPI) {
       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,
@@ -828,6 +1125,15 @@ export default function piWorkflows(pi: ExtensionAPI) {
     } 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);
@@ -927,7 +1233,10 @@ export default function piWorkflows(pi: ExtensionAPI) {
             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,
@@ -956,23 +1265,34 @@ export default function piWorkflows(pi: ExtensionAPI) {
 
     const executor = new ConversationStepExecutor({
       sendPrompt: ({ prompt, contract, presentation, kind, streaming }) => {
-        const details: WorkflowAgentStepMessageDetails = {
-          schema: WORKFLOW_AGENT_STEP_MESSAGE_SCHEMA,
-          kind,
-          contract,
-          ...(presentation !== undefined ? { presentation } : {}),
-        };
-        pi.sendMessage(
+        turnCoordinator.sendNatural(
           {
-            customType: WORKFLOW_AGENT_STEP_MESSAGE_TYPE,
-            content: prompt,
-            display: true,
-            details,
-          },
-          {
-            triggerTurn: true,
-            deliverAs: streaming ? "steer" : "followUp",
+            runId,
+            targetSessionId: originSessionId(ctx, runId),
+            resolution: "workflowPrompt",
+            send: (turnIntentId) => {
+              const details: WorkflowAgentStepMessageDetails = {
+                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) => {
@@ -981,7 +1301,16 @@ export default function piWorkflows(pi: ExtensionAPI) {
           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();
         }
       },
@@ -1063,6 +1392,13 @@ export default function piWorkflows(pi: ExtensionAPI) {
       ...(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;
@@ -1075,6 +1411,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
           if (
             !store.renewWorkflowRunClaim({ runId, claimToken: token, leaseMs: RUN_CLAIM_LEASE_MS })
           ) {
+            run.pendingAbortCause = "claimLost";
             run.engine.cancel();
           }
         } catch {
@@ -1177,6 +1514,13 @@ export default function piWorkflows(pi: ExtensionAPI) {
         }
         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;
         }
@@ -1186,6 +1530,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
           type: "failed",
           payload: { error: message },
         });
+        makeRunTurnIntentEligible(ctx, run, "failed", message);
         try {
           run.onFinish?.({ state: "failed", runId, error: message });
         } catch {
@@ -1224,8 +1569,10 @@ export default function piWorkflows(pi: ExtensionAPI) {
           : 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,
       });
@@ -1412,22 +1759,51 @@ export default function piWorkflows(pi: ExtensionAPI) {
     return null;
   };
 
-  const cancelWorkflowControl = async (ctx: ExtensionContext): Promise<WorkflowControlResult> => {
-    if (activeRun) {
+  const cancelWorkflowControl = async (
+    ctx: ExtensionContext,
+    origin: "agent" | "user",
+    requestedRunId?: string,
+  ): Promise<WorkflowControlResult> => {
+    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) {
@@ -1491,6 +1867,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
         },
       };
     }
+    activeRun.suppressTurnIntent = true;
     activeRun.engine.pause();
     renderWidget(ctx);
     return {
@@ -1524,6 +1901,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
         level: "warning",
       };
     }
+    activeRun.suppressTurnIntent = false;
     activeRun.engine.resume();
     activeRun.executor.release();
     renderWidget(ctx);
@@ -1538,6 +1916,21 @@ export default function piWorkflows(pi: ExtensionAPI) {
     };
   };
 
+  const workflowLaunchStatus = (record: WorkflowRunQueueRecord): WorkflowControlResult => ({
+    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" as const } : {}),
+  });
+
   const statusWorkflowControl = async (
     ctx: ExtensionContext,
     runId?: string,
@@ -1545,7 +1938,9 @@ export default function piWorkflows(pi: ExtensionAPI) {
     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 {
@@ -1554,11 +1949,11 @@ export default function piWorkflows(pi: ExtensionAPI) {
       };
     }
     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 {
@@ -1903,8 +2298,13 @@ export default function piWorkflows(pi: ExtensionAPI) {
     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.");
@@ -1930,35 +2330,171 @@ export default function piWorkflows(pi: ExtensionAPI) {
         `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: ExtensionContext,
+    prepared: WorkflowRunQueueRecord,
+  ): Promise<boolean> => {
+    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" as const;
+      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", {
@@ -2008,7 +2544,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
         return;
       }
       if (parsed.kind === "cancel") {
-        const result = await cancelWorkflowControl(ctx);
+        const result = await cancelWorkflowControl(ctx, "user");
         notify(ctx, result.message, result.level);
         return;
       }
@@ -2176,6 +2712,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
           case "stop":
             if (activeRun?.childKey !== undefined) {
               activeRun.interruptionRequested = true;
+              activeRun.pendingAbortCause = "controllerInterrupted";
               activeRun.engine.cancel();
             }
             await host.stop();
@@ -2192,7 +2729,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
     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.",
@@ -2218,7 +2755,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
           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);
@@ -2348,7 +2885,14 @@ export default function piWorkflows(pi: ExtensionAPI) {
       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");
     }
@@ -2393,6 +2937,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
     if (!aborted || runHeld()) {
       return;
     }
+    run.suppressTurnIntent = true;
     run.engine.pause();
     run.executor.hold();
     renderWidget(ctx);
@@ -2443,30 +2988,39 @@ export default function piWorkflows(pi: ExtensionAPI) {
   });
 
   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 () => {
@@ -2474,8 +3028,10 @@ export default function piWorkflows(pi: ExtensionAPI) {
     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.
@@ -2486,7 +3042,6 @@ export default function piWorkflows(pi: ExtensionAPI) {
     await run?.recorder?.stop().catch(() => undefined);
     await run?.completion?.catch(() => undefined);
     activeRun = null;
-    pendingToolLaunch = null;
     lastWaitingRunId = null;
     if (runSyncTimer !== null) {
       clearInterval(runSyncTimer);