@osolmaz/pi-workflows 0.12.0 → 0.13.0

package/src/extension/index.ts

@@ -1,13 +1,8 @@
 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,
-  type WorkflowRunQueueRecord,
-} from "../controllers/index.js";
+import { SqliteControllerStore, type WorkflowRunQueueRecord } from "../controllers/index.js";
 import type {
   WorkflowTurnIntentCause,
   WorkflowTurnIntentResolution,
@@ -18,6 +13,7 @@ import { compositionMetadata } from "../workflows/composition.js";
 import { humanDecisionChannelRequest } from "../workflows/decision-presentation.js";
 import { WorkflowEngine } from "../workflows/engine.js";
 import {
+  BuiltinWorkflowRevisionChangedError,
   ClaimLostError,
   errorMessage,
   isClaimLostError,
@@ -29,18 +25,17 @@ import {
   validateHumanDecisionResponse,
 } from "../workflows/human-decision.js";
 import { discoverWorkflows, resolveWorkflowRef } from "../workflows/loader.js";
-import { migrateLegacyWorkflowSources } from "../workflows/migrate-sources.js";
 import { appendProgressHistory, progressRecordsFromTrace } from "../workflows/progress.js";
 import {
   createRunId,
-  listRunBundles,
-  readLastTraceEvent,
-  readRunBundle,
+  listWorkflowRuns,
+  readWorkflowRun,
   WorkflowRunStore,
   createDefinitionSnapshot,
 } from "../workflows/store.js";
 import type {
   AcceptedHumanDecision,
+  ResolvedHumanDecision,
   AgentStepContract,
   HumanDecisionRequest,
   HumanDecisionSubmission,
@@ -48,6 +43,7 @@ import type {
   WorkflowDefinitionSnapshot,
   WorkflowRunResult,
   WorkflowRunState,
+  WorkflowSource,
   WorkflowUpdateRecord,
 } from "../workflows/types.js";
 import {
@@ -93,6 +89,7 @@ import {
 } from "./herdr-viewer.js";
 import { SessionRecorder } from "./recorder.js";
 import {
+  recoverAssistantStep,
   registerWorkflowAgentStepMessageRenderer,
   WORKFLOW_AGENT_STEP_MESSAGE_SCHEMA,
   WORKFLOW_AGENT_STEP_MESSAGE_TYPE,
@@ -194,19 +191,14 @@ function humanDecisionRequest(value: unknown): HumanDecisionRequest | null {
     value !== null && typeof value === "object"
       ? (value as { schema?: unknown }).schema
       : undefined;
-  if (
-    schema !== "pi-workflows.human-decision-request.v1" &&
-    schema !== "pi-workflows.human-decision-request.v2"
-  ) {
-    return null;
-  }
+  if (schema !== "pi-workflows.human-decision-request.v1") return null;
   return value as HumanDecisionRequest;
 }
 
 type PreparedLaunchOptions = {
   presentation?: boolean;
   parentRunId?: string;
-  humanDecision?: AcceptedHumanDecision;
+  humanDecision?: ResolvedHumanDecision;
 };
 
 type StartRunOptions = {
@@ -218,8 +210,8 @@ type StartRunOptions = {
   signal?: AbortSignal;
   /** Continue a checkpointed run: input becomes the legacy answer payload. */
   parentRunId?: string;
-  /** Accepted verified-human answer for a protected decision continuation. */
-  humanDecision?: AcceptedHumanDecision;
+  /** Durable human or timeout response for a protected decision continuation. */
+  humanDecision?: ResolvedHumanDecision;
   /** Resume a parked run at its stopped node instead of starting fresh. */
   resume?: boolean;
   /** An existing queue claim token, when the caller already claimed the run. */
@@ -237,6 +229,29 @@ function launchSourceIdentity(workflow: WorkflowDefinition, root: unknown): unkn
   };
 }
 
+function continuationSourceChangedError(
+  runId: string,
+  previous: WorkflowSource,
+  current: WorkflowSource,
+): Error {
+  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: StartRunOptions): PreparedLaunchOptions {
   return {
     ...(options.presentation !== undefined ? { presentation: options.presentation } : {}),
@@ -258,7 +273,7 @@ function safeLaunchError(error: unknown): { code: string; message: string } {
     .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)
+  const code = /not found|cannot find|unknown workflow|no such file or directory/iu.test(raw)
     ? "workflow_not_found"
     : /source changed|source mismatch/iu.test(raw)
       ? "source_changed"
@@ -415,11 +430,29 @@ export default function piWorkflows(pi: ExtensionAPI) {
       ...[...telegramDecisionChannels.values()].map(async (channel) => channel.settle(decision)),
     ]);
   };
-  const migrationBlockedRuns = new Set<string>();
   const ensureRunQueueStore = (cwd: string): SqliteControllerStore => {
-    runQueueStore ??= new SqliteControllerStore(projectControllerStorePath(cwd));
+    runQueueStore ??= new SqliteControllerStore(undefined, { projectPath: cwd });
     return runQueueStore;
   };
+  const workflowStore = (
+    cwd: string,
+    options: Omit<ConstructorParameters<typeof WorkflowRunStore>[1], "state"> = {},
+  ): WorkflowRunStore => {
+    const queue = ensureRunQueueStore(cwd);
+    return new WorkflowRunStore(queue.filePath, { ...options, state: queue.state });
+  };
+  const humanDecisionStore = (
+    cwd: string,
+    authorityProvider?: NonNullable<
+      ConstructorParameters<typeof HumanDecisionStore>[1]
+    >["authorityProvider"],
+  ): HumanDecisionStore => {
+    const queue = ensureRunQueueStore(cwd);
+    return new HumanDecisionStore(queue.filePath, {
+      state: queue.state,
+      ...(authorityProvider === undefined ? {} : { authorityProvider }),
+    });
+  };
 
   // Session-addressed delivery: each session polls only its durable outbox.
   // Run events remain an audit feed and never enter a conversation.
@@ -817,7 +850,6 @@ export default function piWorkflows(pi: ExtensionAPI) {
     workflowViewTarget = {
       runId: state.runId,
       workflowName: state.workflowName,
-      runDir: path.resolve(new WorkflowRunStore().runDirFor(state.runId)),
     };
     renderWidget(ctx);
   };
@@ -1027,12 +1059,16 @@ export default function piWorkflows(pi: ExtensionAPI) {
     }
     try {
       if (outcome === "park") {
-        runQueueStore.parkWorkflowRun({ runId: run.runId, claimToken: run.claimToken });
-      } else {
-        runQueueStore.completeWorkflowRun({ runId: run.runId, claimToken: run.claimToken });
+        if (runQueueStore.parkWorkflowRun({ runId: run.runId, claimToken: run.claimToken })) {
+          runQueueStore.settleRunEffect(run.runId, "run.park_queue");
+        }
+      } else if (
+        runQueueStore.completeWorkflowRun({ runId: run.runId, claimToken: run.claimToken })
+      ) {
+        runQueueStore.settleRunEffect(run.runId, "run.settle_queue");
       }
     } catch {
-      // Queue bookkeeping is best-effort next to the durable bundle.
+      // Queue bookkeeping is best-effort next to the durable run fact.
     } finally {
       run.claimToken = undefined;
     }
@@ -1047,7 +1083,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
       activeRun = null;
     }
     if (result.state.status === "running") {
-      // The run was parked for another runner; its bundle stays resumable
+      // The run was parked for another runner; its SQLite state stays resumable
       // and its queue row becomes claimable. The recorder drains first: its
       // finalization writes share the fenced store, so the claim must stay
       // valid until capture is complete. Nothing else to present.
@@ -1074,7 +1110,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
       );
       return;
     }
-    releaseClaim(run, "done");
+    releaseClaim(run, result.state.status === "waiting" ? "park" : "done");
     recordRunEvent({
       runId: run.runId,
       workflowRef: run.workflowName,
@@ -1202,7 +1238,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
     // refused continuation (edited source, missing parent) must not consume
     // the parent's one-continuation slot.
     if (options.parentRunId !== undefined) {
-      const parent = await readRunBundle(new WorkflowRunStore().runDirFor(options.parentRunId));
+      const parent = readWorkflowRun(options.parentRunId);
       if (parent === null || parent.state.status !== "waiting") {
         throw new Error(`Workflow run ${options.parentRunId} is not waiting at a checkpoint`);
       }
@@ -1210,8 +1246,10 @@ export default function piWorkflows(pi: ExtensionAPI) {
         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,
         );
       }
     }
@@ -1235,6 +1273,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
               : workflowSource.path,
           workflowSource: launchSourceIdentity(workflow, workflowSource),
           definitionDigest: definitionDigest(snapshot),
+          definitionSnapshot: snapshot,
           input,
           launchOptions: preparedLaunchOptions(options),
           runnerId,
@@ -1316,16 +1355,20 @@ export default function piWorkflows(pi: ExtensionAPI) {
       },
       conversation: {
         beginAttempt: (contract) => run.recorder?.beginAttempt(contract),
+        recoverAssistant: (contract) =>
+          recoverAssistantStep(ctx.sessionManager.getBranch(), contract),
         mark: () => run.recorder?.mark() ?? 0,
         rangeSince: (mark) => run.recorder?.rangeSince(mark),
       },
     });
-    // The store is shared between the engine and the session recorder so the
-    // trace sequence stays single-writer (see docs/run-bundles.md). Queued
-    // runs are fenced: every write proves the claim is still ours first.
-    const store = new WorkflowRunStore(
-      undefined,
-      fence === undefined ? {} : { fenceProvider: () => fence },
+    // The engine and session recorder share one transactional SQLite store.
+    const store = workflowStore(
+      ctx.cwd,
+      queueStore === null || claimToken === undefined
+        ? {}
+        : {
+            authorityProvider: () => queueStore.workflowRunAuthority(runId, claimToken),
+          },
     );
     const engine = new WorkflowEngine({
       executor,
@@ -1350,8 +1393,8 @@ export default function piWorkflows(pi: ExtensionAPI) {
       },
       // Awaited by the engine after run_started is persisted, so the session
       // binding and its trace event always precede node and terminal events.
-      onRunStarted: async (runDir, state) => {
-        const recorder = new SessionRecorder(store, runDir, state.runId);
+      onRunStarted: async (runId) => {
+        const recorder = new SessionRecorder(store, runId);
         try {
           await recorder.bind(ctx);
           run.recorder = recorder;
@@ -1451,23 +1494,22 @@ export default function piWorkflows(pi: ExtensionAPI) {
         // once the cause is fixed, and say so in the feed.
         let resumeFailed = run.resume === true && !isClaimLostError(error);
         let terminalStatus: string | undefined;
-        // Re-parking only makes sense while the bundle is still resumable.
-        // A terminal or waiting bundle closes the queue row instead, or
-        // every session start would retry it forever — and the feed reports
-        // the bundle's real state, not a bogus failure.
+        // Re-parking only makes sense while the run is still resumable.
+        // A terminal or waiting run closes the queue row instead, and the feed
+        // reports the authoritative run state.
         if (resumeFailed) {
           try {
-            const bundle = await readRunBundle(new WorkflowRunStore().runDirFor(runId));
+            const bundle = readWorkflowRun(runId);
             if (bundle === null || bundle.state.status !== "running") {
               resumeFailed = false;
               terminalStatus = bundle?.state.status;
             }
           } catch {
-            // Unreadable bundles close the row too.
+            // Unreadable run state closes the row too.
             resumeFailed = false;
           }
         }
-        // A continuation that failed before its bundle exists frees the
+        // A continuation that failed before its run row exists frees the
         // parent's continuation slot instead of consuming it forever.
         let continuationSlotFreed = false;
         if (
@@ -1476,7 +1518,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
           !isClaimLostError(error)
         ) {
           try {
-            const bundle = await readRunBundle(new WorkflowRunStore().runDirFor(runId));
+            const bundle = readWorkflowRun(runId);
             if (bundle === null) {
               continuationSlotFreed =
                 runQueueStore?.deleteWorkflowRun({ runId, claimToken: run.claimToken }) === true;
@@ -1554,7 +1596,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
       runnerId,
       claimToken,
       leaseMs: RUN_CLAIM_LEASE_MS,
-      excludeRunIds: [...migrationBlockedRuns],
+      excludeRunIds: [],
       sessionId: ctx.sessionManager.getSessionId(),
     });
     if (claimed === undefined) {
@@ -1562,7 +1604,11 @@ export default function piWorkflows(pi: ExtensionAPI) {
     }
     let started: string | undefined;
     try {
-      const bundle = await readRunBundle(new WorkflowRunStore().runDirFor(claimed.runId));
+      const bundle = readWorkflowRun(claimed.runId);
+      if (bundle?.state.status === "waiting") {
+        queueStore.parkWorkflowRun({ runId: claimed.runId, claimToken });
+        return;
+      }
       const sourceRef =
         bundle?.state.workflowSource === undefined
           ? claimed.workflowSourceRef
@@ -1572,7 +1618,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
       const launchOptions = parsePreparedLaunchOptions(claimed.launchOptions);
       started = await startRun(ctx, sourceRef, claimed.input, {
         ...launchOptions,
-        resume: bundle !== null,
+        resume: claimed.initialized,
         runId: claimed.runId,
         claimToken,
       });
@@ -1600,16 +1646,13 @@ export default function piWorkflows(pi: ExtensionAPI) {
         ? { state: "running", runId: activeRun.runId }
         : workflowSchedulerResult(activeRun.lastState);
     }
-    const store = new WorkflowRunStore();
-    const bundle = await readRunBundle(store.runDirFor(request.runId));
+    const store = workflowStore(controllerContext?.cwd ?? process.cwd());
+    const bundle = store.readRun(request.runId);
     if (bundle !== null) {
       const recovered =
         bundle.state.status === "running" ? await store.markRunInterrupted(request.runId) : bundle;
       if (recovered !== null) {
-        const lastTraceEvent = await readLastTraceEvent(
-          recovered.runDir,
-          recovered.manifest.paths.trace,
-        );
+        const lastTraceEvent = recovered.traceEvents?.at(-1) ?? null;
         return workflowSchedulerResult(recovered.state, lastTraceEvent?.type === "run_interrupted");
       }
       return { state: "pending" };
@@ -1617,7 +1660,6 @@ export default function piWorkflows(pi: ExtensionAPI) {
     if (controllerContext === null) {
       return { state: "pending" };
     }
-    await store.quarantineIncompleteRun(request.runId);
     const runId = await startRun(controllerContext, request.workflow, request.input, {
       runId: request.runId,
       childKey,
@@ -1723,11 +1765,17 @@ export default function piWorkflows(pi: ExtensionAPI) {
     notify(ctx, result.message, result.level);
   };
 
-  const cancelHumanDecision = async (request: HumanDecisionRequest): Promise<void> => {
-    const store = new HumanDecisionStore(new WorkflowRunStore().outputRoot);
+  const cancelHumanDecision = async (
+    ctx: ExtensionContext,
+    request: HumanDecisionRequest,
+  ): Promise<void> => {
+    const store = humanDecisionStore(ctx.cwd);
     await store.cancel(request, "cancelled");
     const cancellation = await store.readCancellation(request.decisionId);
-    if (cancellation !== null) await settleHumanDecisionChannels(cancellation);
+    if (cancellation !== null) {
+      await settleHumanDecisionChannels(cancellation);
+      store.markEffectApplied(request.decisionId, "decision.settle_presentations");
+    }
     lastWaitingRunId = null;
   };
 
@@ -1744,7 +1792,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
     const continued = new Set(
       rows.map((row) => row.parentRunId).filter((parent): parent is string => parent !== null),
     );
-    const bundles = await listRunBundles(new WorkflowRunStore().outputRoot);
+    const bundles = listWorkflowRuns();
     for (const bundle of bundles) {
       if (
         bundle.state.status !== "waiting" ||
@@ -1810,7 +1858,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
       const { state } = widgetSource;
       const request = humanDecisionRequest(state.finalOutput);
       if (state.status === "waiting" && request !== null) {
-        await cancelHumanDecision(request);
+        await cancelHumanDecision(ctx, request);
         clearWidgetTimer();
         clearWidget(ctx);
         return {
@@ -1831,7 +1879,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
     }
     const recovered = await findOwnedWaitingHumanDecision(ctx);
     if (recovered !== null) {
-      await cancelHumanDecision(recovered.request);
+      await cancelHumanDecision(ctx, recovered.request);
       return {
         message: `Cancelled the pending human decision for workflow ${recovered.state.workflowName}.`,
         details: {
@@ -1936,9 +1984,15 @@ export default function piWorkflows(pi: ExtensionAPI) {
     runId?: string,
   ): Promise<WorkflowControlResult> => {
     if (runId !== undefined) {
-      const bundle = await readRunBundle(new WorkflowRunStore().runDirFor(runId));
+      const launch = ensureRunQueueStore(ctx.cwd).getWorkflowRun(runId);
+      if (
+        launch !== undefined &&
+        ["queued", "starting", "failed", "cancelled"].includes(launch.status)
+      ) {
+        return workflowLaunchStatus(launch);
+      }
+      const bundle = readWorkflowRun(runId);
       if (bundle === null) {
-        const launch = ensureRunQueueStore(ctx.cwd).getWorkflowRun(runId);
         if (launch === undefined) throw new Error(`Workflow run not found: ${runId}`);
         return workflowLaunchStatus(launch);
       }
@@ -1985,7 +2039,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
       const continued = new Set(
         rows.map((row) => row.parentRunId).filter((parent): parent is string => parent !== null),
       );
-      const bundles = await listRunBundles(new WorkflowRunStore().outputRoot);
+      const bundles = listWorkflowRuns();
       parentRunId =
         bundles.find(
           (bundle) =>
@@ -2006,7 +2060,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
     ) {
       throw new Error(`Workflow run ${parentRunId} belongs to another Pi session.`);
     }
-    const parent = await readRunBundle(new WorkflowRunStore().runDirFor(parentRunId));
+    const parent = readWorkflowRun(parentRunId);
     if (
       parent === null ||
       parent.state.status !== "waiting" ||
@@ -2033,7 +2087,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
     verified?: HumanDecisionChannelAnswer,
   ): Promise<WorkflowControlResult> => {
     const waiting = await resolveWaitingWorkflow(ctx, requestedRunId, verified !== undefined);
-    const parent = await readRunBundle(new WorkflowRunStore().runDirFor(waiting.parentRunId));
+    const parent = readWorkflowRun(waiting.parentRunId);
     if (parent === null) throw new Error(`Workflow run ${waiting.parentRunId} is unreadable.`);
     const request = humanDecisionRequest(parent.state.finalOutput);
     let accepted: AcceptedHumanDecision | undefined;
@@ -2059,9 +2113,9 @@ export default function piWorkflows(pi: ExtensionAPI) {
         },
         idempotencyKey: verified?.idempotencyKey ?? createHumanDecisionAttemptId(),
       };
-      const store = new HumanDecisionStore(new WorkflowRunStore().outputRoot);
+      const store = humanDecisionStore(ctx.cwd);
       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;
@@ -2087,21 +2141,9 @@ export default function piWorkflows(pi: ExtensionAPI) {
         };
       }
     }
-    const decisionStore = new HumanDecisionStore(new WorkflowRunStore().outputRoot);
-    if (request !== null && continuationRunId !== undefined && accepted !== undefined) {
-      await decisionStore.recordContinuation(request.decisionId, {
-        schema: "pi-workflows.human-decision-continuation.v1",
-        decisionId: request.decisionId,
-        requestDigest: request.requestDigest,
-        parentRunId: waiting.parentRunId,
-        runId: continuationRunId,
-        createdAt: accepted.acceptedAt,
-      });
-    }
+    const decisionStore = humanDecisionStore(ctx.cwd);
     if (continuationRunId !== undefined) {
-      const existingContinuation = await readRunBundle(
-        new WorkflowRunStore().runDirFor(continuationRunId),
-      );
+      const existingContinuation = readWorkflowRun(continuationRunId);
       if (existingContinuation !== null) {
         if (accepted !== undefined) await settleHumanDecisionChannels(accepted);
         lastWaitingRunId = null;
@@ -2125,7 +2167,18 @@ export default function piWorkflows(pi: ExtensionAPI) {
       throw new Error("Could not start the checkpoint continuation.");
     }
     if (request !== null && accepted !== undefined) {
+      await decisionStore.recordContinuation(request.decisionId, {
+        schema: "pi-workflows.human-decision-continuation.v1",
+        decisionId: request.decisionId,
+        requestDigest: request.requestDigest,
+        provenance: accepted.provenance,
+        parentRunId: waiting.parentRunId,
+        runId: continued,
+        createdAt: accepted.acceptedAt,
+      });
+      decisionStore.markEffectApplied(request.decisionId, "decision.continue");
       await settleHumanDecisionChannels(accepted);
+      decisionStore.markEffectApplied(request.decisionId, "decision.settle_presentations");
     }
     lastWaitingRunId = null;
     return {
@@ -2146,7 +2199,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
     const channel = new PiDecisionChannel({
       actorId: ctx.sessionManager.getSessionId(),
       ui: ctx.ui,
-      store: new HumanDecisionStore(new WorkflowRunStore().outputRoot),
+      store: humanDecisionStore(ctx.cwd),
       onAnswer: async (answer) => {
         const result = await answerWorkflowControl(ctx, answer.response, request.runId, answer);
         notify(ctx, result.message, result.level);
@@ -2183,7 +2236,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
       config: loaded.channels,
       credentials: loaded.credentials,
       configDir: loaded.configDir,
-      store: new HumanDecisionStore(new WorkflowRunStore().outputRoot),
+      store: humanDecisionStore(ctx.cwd),
       onAnswer: async (answer) => {
         await answerWorkflowControl(ctx, answer.response, answer.request.runId, answer);
       },
@@ -2197,13 +2250,13 @@ export default function piWorkflows(pi: ExtensionAPI) {
     ctx: ExtensionContext,
     deliverPending = true,
   ): Promise<void> => {
-    const runStore = new WorkflowRunStore();
-    const store = new HumanDecisionStore(runStore.outputRoot);
+    const runStore = workflowStore(ctx.cwd);
+    const store = humanDecisionStore(ctx.cwd);
     const requests = (await store.listRequests()).sort((left, right) =>
       left.createdAt.localeCompare(right.createdAt),
     );
     for (const request of requests) {
-      const parent = await readRunBundle(runStore.runDirFor(request.runId));
+      const parent = runStore.readRun(request.runId);
       if (parent === null || parent.state.status !== "waiting") continue;
       const currentRequest = humanDecisionRequest(parent.state.finalOutput);
       if (
@@ -2218,60 +2271,110 @@ export default function piWorkflows(pi: ExtensionAPI) {
         queueRecord !== undefined &&
         (queueRecord.originSessionId === null ||
           queueRecord.originSessionId === ctx.sessionManager.getSessionId());
-      const accepted = await store.readAccepted(request.decisionId);
-      if (accepted === null) {
+      if (!ownedBySession) continue;
+      const recoveryToken = randomUUID();
+      const recoveryQueue = ensureRunQueueStore(ctx.cwd);
+      const claimed = recoveryQueue.claimWorkflowRun({
+        runId: request.runId,
+        runnerId: ctx.sessionManager.getSessionId(),
+        claimToken: recoveryToken,
+        leaseMs: RUN_CLAIM_LEASE_MS,
+      });
+      if (claimed === undefined) continue;
+      const ownerStore = humanDecisionStore(ctx.cwd, () =>
+        recoveryQueue.workflowRunAuthority(request.runId, recoveryToken),
+      );
+      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 ownerStore.cancel(request, "expired");
+            cancellation = await ownerStore.readCancellation(request.decisionId);
+          } else {
+            try {
+              resolved = (await ownerStore.resolveTimeout(request)).decision;
+            } catch {
+              cancellation = await store.readCancellation(request.decisionId);
+              resolved = await store.readResolved(request.decisionId);
+            }
+          }
         }
         if (cancellation !== null) {
+          recoveryQueue.completeWorkflowRun({ runId: request.runId, claimToken: recoveryToken });
+          ownerStore.markEffectApplied(request.decisionId, "decision.cancel_parent");
           await settleHumanDecisionChannels(cancellation);
+          ownerStore.markEffectApplied(request.decisionId, "decision.settle_presentations");
+          ownerStore.close();
           continue;
         }
-        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));
+        if (resolved === null) {
+          if (!deliverPending) {
+            recoveryQueue.parkWorkflowRun({ runId: request.runId, claimToken: recoveryToken });
+            ownerStore.close();
+            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));
+          }
+          recoveryQueue.parkWorkflowRun({ runId: request.runId, claimToken: recoveryToken });
+          ownerStore.close();
+          continue;
         }
-        continue;
       }
 
-      if (!ownedBySession) continue;
+      const currentParent = runStore.readRun(request.runId);
+      if (currentParent === null || currentParent.state.status !== "waiting") {
+        recoveryQueue.parkWorkflowRun({ runId: request.runId, claimToken: recoveryToken });
+        ownerStore.close();
+        continue;
+      }
       const runId = `continuation-${request.decisionId.slice("decision-".length)}`;
       const continuation = (await store.readContinuation(request.decisionId)) ?? {
         schema: "pi-workflows.human-decision-continuation.v1" as const,
         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));
+      recoveryQueue.parkWorkflowRun({
+        runId: request.runId,
+        claimToken: recoveryToken,
+      });
+      const existing = runStore.readRun(continuation.runId);
       if (existing === null && activeRun === null) {
-        if (parent.state.workflowSource === undefined) continue;
+        if (currentParent.state.workflowSource === undefined) {
+          ownerStore.close();
+          continue;
+        }
         const workflowRef =
-          parent.state.workflowSource.kind === "builtin"
-            ? `builtin:${parent.state.workflowSource.id}`
-            : parent.state.workflowSource.path;
-        await startRun(ctx, workflowRef, parent.state.input, {
+          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);
+      if (runStore.readRun(continuation.runId) !== null) {
+        await ownerStore.recordContinuation(request.decisionId, continuation);
+        ownerStore.markEffectApplied(request.decisionId, "decision.continue");
+      }
+      await settleHumanDecisionChannels(resolved);
+      ownerStore.markEffectApplied(request.decisionId, "decision.settle_presentations");
+      ownerStore.close();
       if (activeRun !== null) break;
     }
   };
@@ -2332,7 +2435,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
     }
     const queue = ensureRunQueueStore(ctx.cwd);
     const existing = queue.findSessionReservation(ctx.sessionManager.getSessionId());
-    if (existing !== undefined) {
+    if (existing !== undefined && existing.runId !== options.parentRunId) {
       throw new Error(
         `Workflow ${existing.workflowName} is already ${existing.status} (run ${existing.runId}).`,
       );
@@ -2344,7 +2447,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
     const workflow = resolved.definition;
     const workflowSource = resolved.source;
     if (options.parentRunId !== undefined) {
-      const parent = await readRunBundle(new WorkflowRunStore().runDirFor(options.parentRunId));
+      const parent = readWorkflowRun(options.parentRunId);
       if (parent === null || parent.state.status !== "waiting") {
         throw new Error(`Workflow run ${options.parentRunId} is not waiting at a checkpoint`);
       }
@@ -2352,8 +2455,10 @@ export default function piWorkflows(pi: ExtensionAPI) {
         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,
         );
       }
     }
@@ -2367,6 +2472,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
           workflowSource.kind === "builtin" ? `builtin:${workflowSource.id}` : workflowSource.path,
         workflowSource: launchSourceIdentity(workflow, workflowSource),
         definitionDigest: definitionDigest(snapshot),
+        definitionSnapshot: snapshot,
         input,
         launchOptions: preparedLaunchOptions(options),
         runnerId,
@@ -2575,7 +2681,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
           const message = errorMessage(error);
           notify(
             ctx,
-            /workflow_run_queue_parent/.test(message)
+            /continuations\.parent_run_id/.test(message)
               ? "That checkpoint was already answered; see its continuation run."
               : `Could not continue workflow: ${message}`,
             "error",
@@ -2730,9 +2836,10 @@ export default function piWorkflows(pi: ExtensionAPI) {
     label: "Workflow",
     description: [
       "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.",
+      "When the user asks to monitor, watch, poll, or check something repeatedly, start the built-in monitor workflow with input keys task, stopWhen, everyMinutes, and optional maxChecks.",
+      "Put the exact goal, authority, limits, and recovery rules in task; Monitor observes first, performs only safe authorized actions, verifies them immediately, and waits only while target work is moving or an external event is pending.",
       "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.",
+      "Do not start repeated work without the user's request.",
     ].join(" "),
     parameters: WorkflowToolParameters,
     async execute(toolCallId, rawParams, _signal, _onUpdate, ctx) {
@@ -2759,7 +2866,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
           break;
         case "answer": {
           const waiting = await resolveWaitingWorkflow(ctx, params.runId);
-          const parent = await readRunBundle(new WorkflowRunStore().runDirFor(waiting.parentRunId));
+          const parent = readWorkflowRun(waiting.parentRunId);
           if (parent !== null && humanDecisionRequest(parent.state.finalOutput) !== null) {
             throw new Error(
               "This checkpoint requires a verified human answer from Pi UI or a configured decision channel.",
@@ -2797,7 +2904,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
             }
             throw new Error("No workflow step is waiting for output.");
           }
-          // Flush the conversation into the bundle before accepting, so the
+          // Flush the conversation into SQLite before accepting, so the
           // attempt range includes the assistant message carrying this call.
           await activeRun.recorder?.record(ctx).catch(() => undefined);
           await activeRun.recorder?.synchronize(ctx).catch(() => undefined);
@@ -2844,24 +2951,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
     sessionClosed = false;
     controllerContext = ctx;
     if (herdrEnabled) void refreshHerdrCapability(ctx);
-    try {
-      const queue = ensureRunQueueStore(ctx.cwd);
-      const migration = await migrateLegacyWorkflowSources({
-        catalog: builtinWorkflowCatalog,
-        queue,
-      });
-      migrationBlockedRuns.clear();
-      for (const blocked of migration.blocked) migrationBlockedRuns.add(blocked.runId);
-      if (migration.blocked.length > 0) {
-        notify(
-          ctx,
-          `Could not migrate ${migration.blocked.length} legacy workflow source(s).`,
-          "warning",
-        );
-      }
-    } catch (error) {
-      notify(ctx, `Could not migrate legacy workflow sources: ${errorMessage(error)}`, "warning");
-    }
+    ensureRunQueueStore(ctx.cwd);
     try {
       await reloadDecisionChannels(ctx);
     } catch {
@@ -2953,6 +3043,9 @@ export default function piWorkflows(pi: ExtensionAPI) {
 
   pi.on("turn_end", async (event, ctx) => {
     await activeRun?.recorder?.handleTurnEnd(event, ctx).catch(() => undefined);
+    // turn_end observes the message after message_end replacement handlers,
+    // so this is the exact assistant message that remains visible.
+    activeRun?.executor.handleMessageEnd(event.message);
   });
 
   pi.on("message_start", async (event, ctx) => {
@@ -3007,11 +3100,9 @@ export default function piWorkflows(pi: ExtensionAPI) {
         return;
       }
     }
-    const flushedNatural = turnCoordinator.flushNatural(
-      ctx.isIdle() && !sessionClosed && !runHeld(),
-    );
     const run = activeRun;
     if (!run) {
+      turnCoordinator.flushNatural(ctx.isIdle() && !sessionClosed && !runHeld());
       presentationPending = null;
       runSyncPass(ctx);
       return;
@@ -3019,7 +3110,16 @@ export default function piWorkflows(pi: ExtensionAPI) {
     await run.recorder?.synchronize(ctx).catch(() => undefined);
     run.recorder?.settleAttempt();
     run.executor.setStreaming(false);
-    if (flushedNatural === 0) run.executor.handleAgentSettled();
+    if (run.executor.pendingCompletion === "assistant") {
+      // The visible response is the step output. Resolve it before any
+      // unrelated deferred turn can start and replace the captured message.
+      run.executor.handleAgentSettled();
+    } else {
+      const flushedNatural = turnCoordinator.flushNatural(
+        ctx.isIdle() && !sessionClosed && !runHeld(),
+      );
+      if (flushedNatural === 0) run.executor.handleAgentSettled();
+    }
     runSyncPass(ctx);
   });