@osolmaz/pi-workflows 0.3.0 → 0.4.0

package/src/builtins/monitor.workflow.ts

@@ -1,8 +1,11 @@
-import { agent, compute, defineWorkflow, shell } from "../workflows/index.js";
+import { agent, compute, defineWorkflow, shell } from "../workflows/definition.js";
 import type { WorkflowNodeContext } from "../workflows/types.js";
 
 const MIN_INTERVAL_MINUTES = 1;
 const MAX_INTERVAL_MINUTES = 24 * 60;
+const MIN_CHECK_TIMEOUT_MINUTES = 5;
+const MAX_CHECK_TIMEOUT_MINUTES = 24 * 60;
+const DEFAULT_MIN_CHECK_TIMEOUT_MINUTES = 60;
 const DEFAULT_MAX_CHECKS = 1_000;
 const MAX_CHECKS = 1_000;
 const MAX_OBSERVATION_CHARS = 8_000;
@@ -17,6 +20,7 @@ type MonitorInput = {
   reportWhen?: string;
   stopWhen?: string;
   maxChecks?: number;
+  checkTimeoutMinutes?: number;
 };
 
 type MonitorConfig = {
@@ -25,6 +29,7 @@ type MonitorConfig = {
   reportWhen: string;
   stopWhen: string;
   maxChecks: number;
+  checkTimeoutMinutes: number;
 };
 
 type MonitorRoute = "continue_quiet" | "continue_report" | "stop_quiet" | "stop_report";
@@ -81,6 +86,17 @@ function prepareInput(input: unknown): MonitorConfig {
   if (!Number.isInteger(maxChecks) || maxChecks <= 0 || maxChecks > MAX_CHECKS) {
     throw new Error(`maxChecks must be an integer from 1 through ${MAX_CHECKS}`);
   }
+  const checkTimeoutMinutes =
+    value.checkTimeoutMinutes ?? Math.max(DEFAULT_MIN_CHECK_TIMEOUT_MINUTES, value.everyMinutes);
+  if (
+    !Number.isInteger(checkTimeoutMinutes) ||
+    checkTimeoutMinutes < MIN_CHECK_TIMEOUT_MINUTES ||
+    checkTimeoutMinutes > MAX_CHECK_TIMEOUT_MINUTES
+  ) {
+    throw new Error(
+      `checkTimeoutMinutes must be an integer from ${MIN_CHECK_TIMEOUT_MINUTES} through ${MAX_CHECK_TIMEOUT_MINUTES}`,
+    );
+  }
   return {
     task,
     everyMinutes: value.everyMinutes,
@@ -93,6 +109,7 @@ function prepareInput(input: unknown): MonitorConfig {
         ? "The user cancels the monitor or it reaches its maximum check count."
         : requireBoundedString(value.stopWhen, "stopWhen", 4_000),
     maxChecks,
+    checkTimeoutMinutes,
   };
 }
 
@@ -100,6 +117,10 @@ function configFrom(outputs: Record<string, unknown>): MonitorConfig {
   return outputs.prepare as MonitorConfig;
 }
 
+function agentTimeoutMs({ outputs }: WorkflowNodeContext): number {
+  return configFrom(outputs).checkTimeoutMinutes * 60_000;
+}
+
 function completedChecks(context: WorkflowNodeContext): number {
   return context.state.steps.filter((step) => step.nodeId === "check" && step.outcome === "ok")
     .length;
@@ -190,6 +211,7 @@ export default defineWorkflow({
     }),
     check: agent({
       statusDetail: "checking monitored target",
+      timeoutMs: agentTimeoutMs,
       prompt: (context) => {
         const config = configFrom(context.outputs);
         const previous = context.outputs.check as MonitorCheck | undefined;
@@ -212,12 +234,14 @@ export default defineWorkflow({
     }),
     report_continue: agent({
       statusDetail: "reporting monitor update",
+      timeoutMs: agentTimeoutMs,
       prompt: ({ outputs }) => reportPrompt(outputs),
       expectedOutput: '{ "reported": true }',
       validate: (output) => validateReportAck(output),
     }),
     report_stop: agent({
       statusDetail: "reporting final monitor update",
+      timeoutMs: agentTimeoutMs,
       prompt: ({ outputs }) => reportPrompt(outputs),
       expectedOutput: '{ "reported": true }',
       validate: (output) => validateReportAck(output),

package/src/controllers/sqlite.ts

@@ -101,8 +101,10 @@ type WorkflowRunQueueRow = {
 /** A user-started workflow run tracked by the durable run queue. */
 export type WorkflowRunQueueRecord = {
   runId: string;
-  workflowRef: string;
-  workflowPath: string;
+  /** Human-readable workflow name used in status and event output. */
+  workflowName: string;
+  /** Canonical source reference used to reopen the run. */
+  workflowSourceRef: string;
   input: unknown;
   status: "claimed" | "parked" | "done";
   runnerId: string | null;
@@ -866,8 +868,8 @@ export class SqliteControllerStore implements ControllerStore {
    */
   enqueueWorkflowRun(options: {
     runId: string;
-    workflowRef: string;
-    workflowPath: string;
+    workflowName: string;
+    workflowSourceRef: string;
     input: unknown;
     runnerId: string;
     claimToken: string;
@@ -877,8 +879,8 @@ export class SqliteControllerStore implements ControllerStore {
     now?: string;
   }): WorkflowRunQueueRecord {
     validateRunId(options.runId);
-    validateKey(options.workflowRef, "workflow ref");
-    validateKey(options.workflowPath, "workflow path");
+    validateKey(options.workflowName, "workflow name");
+    validateKey(options.workflowSourceRef, "workflow source ref");
     validateKey(options.runnerId, "runner id");
     validateKey(options.claimToken, "claim token");
     validateDuration(options.leaseMs, "leaseMs");
@@ -896,8 +898,8 @@ export class SqliteControllerStore implements ControllerStore {
       )
       .run(
         options.runId,
-        options.workflowRef,
-        options.workflowPath,
+        options.workflowName,
+        options.workflowSourceRef,
         inputJson,
         options.runnerId,
         options.claimToken,
@@ -1068,6 +1070,122 @@ export class SqliteControllerStore implements ControllerStore {
     return result.changes === 1;
   }
 
+  /** Repair a canonical bundle's queue source and claim it only when needed. */
+  repairCanonicalWorkflowSourceRun(options: {
+    runId: string;
+    workflowName: string;
+    workflowSourceRef: string;
+    runnerId: string;
+    claimToken: string;
+    leaseMs: number;
+    now?: string;
+  }): "unchanged" | "claimed" | false {
+    validateRunId(options.runId);
+    validateKey(options.workflowName, "workflow name");
+    validateKey(options.workflowSourceRef, "workflow source ref");
+    validateKey(options.runnerId, "runner id");
+    validateKey(options.claimToken, "claim token");
+    validateDuration(options.leaseMs, "leaseMs");
+    const now = validTimestamp(options.now);
+    const nowMs = epoch(now);
+    const expiresAt = nowMs + options.leaseMs;
+    return this.transaction(() => {
+      const row = this.database
+        .prepare("SELECT * FROM workflow_run_queue WHERE run_id = ?")
+        .get(options.runId) as WorkflowRunQueueRow | undefined;
+      if (row === undefined || row.status === "done") return false;
+      if (row.workflow_path === options.workflowSourceRef && row.status === "parked") {
+        return "unchanged";
+      }
+      const claimable =
+        row.status === "parked" ||
+        (row.status === "claimed" &&
+          row.claim_token === options.claimToken &&
+          row.claim_expires_at !== null &&
+          row.claim_expires_at > nowMs) ||
+        (row.status === "claimed" &&
+          row.claim_expires_at !== null &&
+          row.claim_expires_at <= nowMs);
+      if (!claimable) return false;
+      const result = this.database
+        .prepare(
+          `UPDATE workflow_run_queue
+           SET workflow_ref = ?, workflow_path = ?, status = 'claimed', runner_id = ?,
+               claim_token = ?, claim_expires_at = ?, updated_at = ?
+           WHERE run_id = ? AND status != 'done'`,
+        )
+        .run(
+          options.workflowName,
+          options.workflowSourceRef,
+          options.runnerId,
+          options.claimToken,
+          expiresAt,
+          now,
+          options.runId,
+        );
+      return result.changes === 1 ? "claimed" : false;
+    });
+  }
+
+  /** Claim and rewrite one proved legacy workflow source queue row atomically. */
+  claimLegacyWorkflowSourceRun(options: {
+    runId: string;
+    workflowName: string;
+    oldWorkflowPath: string;
+    workflowSourceRef: string;
+    runnerId: string;
+    claimToken: string;
+    leaseMs: number;
+    now?: string;
+  }): boolean {
+    validateRunId(options.runId);
+    validateKey(options.workflowName, "workflow name");
+    validateKey(options.oldWorkflowPath, "legacy workflow path");
+    validateKey(options.workflowSourceRef, "workflow source ref");
+    validateKey(options.runnerId, "runner id");
+    validateKey(options.claimToken, "claim token");
+    validateDuration(options.leaseMs, "leaseMs");
+    const now = validTimestamp(options.now);
+    const nowMs = epoch(now);
+    const expiresAt = nowMs + options.leaseMs;
+    return this.transaction(() => {
+      const row = this.database
+        .prepare("SELECT * FROM workflow_run_queue WHERE run_id = ?")
+        .get(options.runId) as WorkflowRunQueueRow | undefined;
+      if (row === undefined || row.status === "done") return false;
+      const sourceMatches =
+        row.workflow_path === options.oldWorkflowPath ||
+        row.workflow_path === options.workflowSourceRef;
+      const claimable =
+        row.status === "parked" ||
+        (row.status === "claimed" &&
+          row.claim_token === options.claimToken &&
+          row.claim_expires_at !== null &&
+          row.claim_expires_at > nowMs) ||
+        (row.status === "claimed" &&
+          row.claim_expires_at !== null &&
+          row.claim_expires_at <= nowMs);
+      if (!sourceMatches || !claimable) return false;
+      const result = this.database
+        .prepare(
+          `UPDATE workflow_run_queue
+           SET workflow_ref = ?, workflow_path = ?, status = 'claimed', runner_id = ?,
+               claim_token = ?, claim_expires_at = ?, updated_at = ?
+           WHERE run_id = ? AND status != 'done'`,
+        )
+        .run(
+          options.workflowName,
+          options.workflowSourceRef,
+          options.runnerId,
+          options.claimToken,
+          expiresAt,
+          now,
+          options.runId,
+        );
+      return result.changes === 1;
+    });
+  }
+
   /** Append a run lifecycle transition to the event feed. */
   recordRunEvent(options: {
     runId: string;
@@ -1332,8 +1450,8 @@ function workflowFromRow(row: WorkflowRow): ChildWorkflowRecord {
 function workflowRunFromRow(row: WorkflowRunQueueRow): WorkflowRunQueueRecord {
   return {
     runId: row.run_id,
-    workflowRef: row.workflow_ref,
-    workflowPath: row.workflow_path,
+    workflowName: row.workflow_ref,
+    workflowSourceRef: row.workflow_path,
     input: parseStoredJson(row.input_json, "workflow run input"),
     status: row.status,
     runnerId: row.runner_id,

package/src/controllers/workflow-engine-scheduler.ts

@@ -4,6 +4,7 @@ import type {
   WorkflowDefinition,
   WorkflowRunResult,
   WorkflowRunStatus,
+  WorkflowSource,
 } from "../workflows/types.js";
 import type {
   ControllerWorkflowScheduler,
@@ -13,7 +14,7 @@ import type {
 
 export type ResolvedChildWorkflow = {
   workflow: WorkflowDefinition;
-  workflowPath?: string;
+  workflowSource?: WorkflowSource;
 };
 
 export type WorkflowEngineSchedulerOptions = {
@@ -77,7 +78,9 @@ export class WorkflowEngineScheduler implements ControllerWorkflowScheduler {
     const promise = engine
       .run(resolved.workflow, request.input, {
         runId,
-        ...(resolved.workflowPath !== undefined ? { workflowPath: resolved.workflowPath } : {}),
+        ...(resolved.workflowSource !== undefined
+          ? { workflowSource: resolved.workflowSource }
+          : {}),
       })
       .then((result) => {
         callCompletion(onComplete, resultFromRun(result));

package/src/extension/executor.ts

@@ -33,6 +33,8 @@ export type ConversationStepExecutorOptions = {
   maxNudges?: number;
   /** Conversation linkage hooks, wired to the session recorder. */
   conversation?: ConversationHooks;
+  /** Called when the engine aborts a pending agent step. */
+  onAbort?: (contract: AgentStepRequest["contract"], reason: unknown) => void;
 };
 
 type PendingStep = {
@@ -61,6 +63,7 @@ export class ConversationStepExecutor implements AgentStepExecutor {
   private readonly sendPrompt: (delivery: PromptDelivery) => void;
   private readonly maxNudges: number;
   private readonly conversation: ConversationHooks | undefined;
+  private readonly onAbort: ConversationStepExecutorOptions["onAbort"];
   private pending: PendingStep | null = null;
   private streaming = false;
   private heldByUser = false;
@@ -69,6 +72,7 @@ export class ConversationStepExecutor implements AgentStepExecutor {
     this.sendPrompt = options.sendPrompt;
     this.maxNudges = options.maxNudges ?? DEFAULT_MAX_NUDGES;
     this.conversation = options.conversation;
+    this.onAbort = options.onAbort;
   }
 
   /** Track agent streaming state (wire to agent_start / agent_settled). */
@@ -121,8 +125,15 @@ export class ConversationStepExecutor implements AgentStepExecutor {
     return await new Promise<AgentStepSubmission>((resolve, reject) => {
       const onAbort = () => {
         const reason: unknown = signal.reason ?? new Error("Workflow step aborted");
+        if (this.pending?.request !== request) {
+          return;
+        }
         this.clearPending();
-        reject(reason);
+        try {
+          this.onAbort?.(request.contract, reason);
+        } finally {
+          reject(reason);
+        }
       };
       signal.addEventListener("abort", onAbort, { once: true });
       let markCleared!: () => void;

package/src/extension/index.ts

@@ -1,5 +1,7 @@
 import { randomUUID } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { builtinWorkflowCatalog } from "../builtins/catalog.js";
 import {
   projectControllerStorePath,
   type RunEventRecord,
@@ -8,13 +10,14 @@ import {
 import type { JsonObject } from "../controllers/types.js";
 import type { WorkflowSchedulerResult } from "../controllers/workflows.js";
 import { WorkflowEngine } from "../workflows/engine.js";
-import { ClaimLostError, errorMessage, isClaimLostError } from "../workflows/errors.js";
 import {
-  discoverWorkflows,
-  hashWorkflowSource,
-  loadWorkflowFile,
-  resolveWorkflowRef,
-} from "../workflows/loader.js";
+  ClaimLostError,
+  errorMessage,
+  isClaimLostError,
+  TimeoutError,
+} from "../workflows/errors.js";
+import { discoverWorkflows, resolveWorkflowRef } from "../workflows/loader.js";
+import { migrateLegacyWorkflowSources } from "../workflows/migrate-sources.js";
 import {
   createRunId,
   listRunBundles,
@@ -24,6 +27,7 @@ import {
   createDefinitionSnapshot,
 } from "../workflows/store.js";
 import type {
+  AgentStepContract,
   WorkflowDefinition,
   WorkflowDefinitionSnapshot,
   WorkflowRunResult,
@@ -207,6 +211,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
   // One runner identity per session; it names this session in run claims.
   const runnerId = randomUUID();
   let runQueueStore: SqliteControllerStore | null = null;
+  const migrationBlockedRuns = new Set<string>();
   const ensureRunQueueStore = (cwd: string): SqliteControllerStore => {
     runQueueStore ??= new SqliteControllerStore(projectControllerStorePath(cwd));
     return runQueueStore;
@@ -308,7 +313,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
     const rows = runQueueStore.listWorkflowRuns();
     for (const row of rows) {
       if (row.status === "parked") {
-        lines.push(`${row.workflowRef} run ${row.runId} is parked and will resume`);
+        lines.push(`${row.workflowName} run ${row.runId} is parked and will resume`);
       }
     }
     const known = new Set(rows.map((row) => row.runId));
@@ -348,6 +353,8 @@ export default function piWorkflows(pi: ExtensionAPI) {
     runSyncTimer.unref?.();
   };
   let activeRun: ActiveRun | null = null;
+  let systemTurnAbort: AgentStepContract | null = null;
+  let lastExpiredAttempt: { contract: AgentStepContract; reason: string } | null = null;
   let pendingToolLaunch: {
     ctx: ExtensionContext;
     ref: string;
@@ -506,7 +513,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
     if (
       sessionClosed ||
       run.generation !== runGeneration ||
-      state.status === "cancelled" ||
+      (state.status !== "completed" && state.status !== "waiting") ||
       run.presentationPrompt === undefined
     ) {
       return;
@@ -639,7 +646,9 @@ export default function piWorkflows(pi: ExtensionAPI) {
     const summary =
       state.status === "waiting" && state.waitingOn
         ? `Workflow ${state.workflowName} parked at checkpoint ${state.waitingOn} — answer with /workflow answer <json> (run ${state.runId})`
-        : `Workflow ${state.workflowName} ${state.status} (run ${state.runId})`;
+        : `Workflow ${state.workflowName} ${state.status} (run ${state.runId})${
+            state.error !== undefined ? `: ${state.error.slice(0, MAX_STATUS_ERROR_CHARS)}` : ""
+          }`;
     notify(ctx, summary, state.status === "completed" ? "info" : "warning");
     try {
       const childResult =
@@ -689,13 +698,13 @@ export default function piWorkflows(pi: ExtensionAPI) {
     }
     supersedePresentation();
     const generation = runGeneration;
-    const resolved = await resolveWorkflowRef(ref, { cwd: ctx.cwd });
-    const workflow = await loadWorkflowFile(resolved.path);
+    const resolved = await resolveWorkflowRef(ref, { cwd: ctx.cwd }, builtinWorkflowCatalog);
+    const workflow = resolved.definition;
     if (options.signal?.aborted) {
       throw options.signal.reason ?? new Error("Workflow startup aborted");
     }
     const snapshot = createDefinitionSnapshot(workflow);
-    const workflowHash = await hashWorkflowSource(resolved.path);
+    const workflowSource = resolved.source;
     const runId = options.runId ?? createRunId(workflow.name);
 
     // Continuations validate the parent before touching the queue: a
@@ -706,7 +715,10 @@ export default function piWorkflows(pi: ExtensionAPI) {
       if (parent === null || parent.state.status !== "waiting") {
         throw new Error(`Workflow run ${options.parentRunId} is not waiting at a checkpoint`);
       }
-      if (parent.state.workflowHash !== undefined && parent.state.workflowHash !== workflowHash) {
+      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`,
         );
@@ -725,8 +737,11 @@ export default function piWorkflows(pi: ExtensionAPI) {
         const token = randomUUID();
         queueStore.enqueueWorkflowRun({
           runId,
-          workflowRef: ref,
-          workflowPath: resolved.path,
+          workflowName: workflow.name,
+          workflowSourceRef:
+            workflowSource.kind === "builtin"
+              ? `builtin:${workflowSource.id}`
+              : workflowSource.path,
           input,
           runnerId,
           claimToken: token,
@@ -757,6 +772,16 @@ export default function piWorkflows(pi: ExtensionAPI) {
       sendPrompt: ({ prompt, streaming }) => {
         pi.sendUserMessage(prompt, streaming ? { deliverAs: "steer" } : undefined);
       },
+      onAbort: (contract, reason) => {
+        lastExpiredAttempt = {
+          contract,
+          reason: reason instanceof TimeoutError ? "timed out" : `ended: ${errorMessage(reason)}`,
+        };
+        if (!executor.held && !ctx.isIdle()) {
+          systemTurnAbort = contract;
+          ctx.abort();
+        }
+      },
       conversation: {
         beginAttempt: (contract) => run.recorder?.beginAttempt(contract),
         mark: () => run.recorder?.mark() ?? 0,
@@ -840,12 +865,11 @@ export default function piWorkflows(pi: ExtensionAPI) {
 
     run.completion = (
       options.resume === true
-        ? engine.resumeRun(workflow, runId, { workflowHash })
+        ? engine.resumeRun(workflow, runId, { workflowSource })
         : options.parentRunId === undefined
-          ? engine.run(workflow, input, { workflowPath: resolved.path, workflowHash, runId })
+          ? engine.run(workflow, input, { workflowSource, runId })
           : engine.continueRun(workflow, options.parentRunId, input, {
-              workflowPath: resolved.path,
-              workflowHash,
+              workflowSource,
               runId,
             })
     )
@@ -955,13 +979,21 @@ export default function piWorkflows(pi: ExtensionAPI) {
       runnerId,
       claimToken,
       leaseMs: RUN_CLAIM_LEASE_MS,
+      excludeRunIds: [...migrationBlockedRuns],
     });
     if (claimed === undefined) {
       return;
     }
     let started: string | undefined;
     try {
-      started = await startRun(ctx, claimed.workflowPath, claimed.input, {
+      const bundle = await readRunBundle(new WorkflowRunStore().runDirFor(claimed.runId));
+      const sourceRef =
+        bundle?.state.workflowSource === undefined
+          ? claimed.workflowSourceRef
+          : bundle.state.workflowSource.kind === "builtin"
+            ? `builtin:${bundle.state.workflowSource.id}`
+            : bundle.state.workflowSource.path;
+      started = await startRun(ctx, sourceRef, claimed.input, {
         resume: true,
         runId: claimed.runId,
         claimToken,
@@ -971,7 +1003,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
       throw error;
     }
     if (started !== undefined) {
-      notify(ctx, `Resumed workflow run ${claimed.runId} (${claimed.workflowRef}).`);
+      notify(ctx, `Resumed workflow run ${claimed.runId} (${claimed.workflowName}).`);
     } else {
       queueStore.parkWorkflowRun({ runId: claimed.runId, claimToken });
     }
@@ -1051,7 +1083,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
     ctx: ExtensionContext,
     offset = 0,
   ): Promise<WorkflowControlResult> => {
-    const discovered = await discoverWorkflows({ cwd: ctx.cwd });
+    const discovered = await discoverWorkflows({ cwd: ctx.cwd }, builtinWorkflowCatalog);
     if (discovered.length === 0) {
       return {
         message:
@@ -1255,7 +1287,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
   const resolveWaitingWorkflow = async (
     ctx: ExtensionContext,
     requestedRunId?: string,
-  ): Promise<{ parentRunId: string; workflowPath: string }> => {
+  ): Promise<{ parentRunId: string; workflowRef: string }> => {
     let parentRunId = requestedRunId ?? lastWaitingRunId;
     if (parentRunId === null) {
       const rows = ensureRunQueueStore(ctx.cwd).listWorkflowRuns();
@@ -1279,14 +1311,20 @@ export default function piWorkflows(pi: ExtensionAPI) {
     if (
       parent === null ||
       parent.state.status !== "waiting" ||
-      parent.state.workflowPath === undefined
+      parent.state.workflowSource === undefined
     ) {
       if (parentRunId === lastWaitingRunId) {
         lastWaitingRunId = null;
       }
       throw new Error(`Workflow run ${parentRunId} is no longer waiting.`);
     }
-    return { parentRunId, workflowPath: parent.state.workflowPath };
+    return {
+      parentRunId,
+      workflowRef:
+        parent.state.workflowSource.kind === "builtin"
+          ? `builtin:${parent.state.workflowSource.id}`
+          : parent.state.workflowSource.path,
+    };
   };
 
   const answerWorkflowControl = async (
@@ -1295,7 +1333,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
     requestedRunId?: string,
   ): Promise<WorkflowControlResult> => {
     const waiting = await resolveWaitingWorkflow(ctx, requestedRunId);
-    const continued = await startRun(ctx, waiting.workflowPath, input, {
+    const continued = await startRun(ctx, waiting.workflowRef, input, {
       parentRunId: waiting.parentRunId,
     });
     if (continued === undefined) {
@@ -1356,8 +1394,8 @@ export default function piWorkflows(pi: ExtensionAPI) {
     const reservation = { ctx, ref, input, options };
     pendingToolLaunch = reservation;
     try {
-      const resolved = await resolveWorkflowRef(ref, { cwd: ctx.cwd });
-      const workflow = await loadWorkflowFile(resolved.path);
+      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.");
       }
@@ -1382,7 +1420,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
     description:
       "Run or manage a workflow: /workflow <name-or-path> [task | --input-json {…}]; also: status, pause, resume, cancel, answer",
     getArgumentCompletions: async (prefix: string) => {
-      const discovered = await discoverWorkflows({ cwd: process.cwd() });
+      const discovered = await discoverWorkflows({ cwd: process.cwd() }, builtinWorkflowCatalog);
       const items = [
         ...discovered.map((workflow) => ({ value: workflow.name, label: workflow.name })),
         { value: "status", label: "status" },
@@ -1556,13 +1594,21 @@ export default function piWorkflows(pi: ExtensionAPI) {
           break;
         case "answer": {
           const waiting = await resolveWaitingWorkflow(ctx, params.runId);
-          control = await queueToolLaunch(ctx, waiting.workflowPath, params.input, {
+          control = await queueToolLaunch(ctx, waiting.workflowRef, params.input, {
             parentRunId: waiting.parentRunId,
           });
           break;
         }
         case "submit": {
           if (!activeRun) {
+            if (
+              lastExpiredAttempt?.contract.attemptId === params.attempt &&
+              lastExpiredAttempt.contract.nodeId === params.step
+            ) {
+              throw new Error(
+                `Workflow step ${JSON.stringify(params.step)} attempt ${JSON.stringify(params.attempt)} ${lastExpiredAttempt.reason}; its output is no longer accepted.`,
+              );
+            }
             throw new Error("No workflow step is waiting for output.");
           }
           // Flush the conversation into the bundle before accepting, so the
@@ -1603,6 +1649,24 @@ export default function piWorkflows(pi: ExtensionAPI) {
   pi.on("session_start", async (_event, ctx) => {
     sessionClosed = false;
     controllerContext = 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");
+    }
     try {
       syncArmed = true;
       startRunSync(ctx);
@@ -1632,13 +1696,6 @@ export default function piWorkflows(pi: ExtensionAPI) {
   });
 
   pi.on("agent_end", (event, ctx) => {
-    const run = activeRun;
-    if (!run) {
-      return;
-    }
-    // An aborted turn means the user hit escape to take the conversation
-    // back. Nudging or dispatching the next step would immediately steal it
-    // again, so hold the run until an explicit /workflow resume.
     const aborted = event.messages.some(
       (message) =>
         typeof message === "object" &&
@@ -1646,6 +1703,17 @@ export default function piWorkflows(pi: ExtensionAPI) {
         "stopReason" in message &&
         (message as { stopReason?: string }).stopReason === "aborted",
     );
+    if (aborted && systemTurnAbort !== null) {
+      systemTurnAbort = null;
+      return;
+    }
+    const run = activeRun;
+    if (!run) {
+      return;
+    }
+    // An aborted turn means the user hit escape to take the conversation
+    // back. Nudging or dispatching the next step would immediately steal it
+    // again, so hold the run until an explicit /workflow resume.
     if (!aborted || runHeld()) {
       return;
     }
@@ -1719,6 +1787,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
 
   pi.on("session_shutdown", async () => {
     sessionClosed = true;
+    systemTurnAbort = null;
     supersedePresentation();
     const run = activeRun;
     if (run !== null && run.claimToken !== undefined) {