@donkeylabs/server 2.0.26 → 2.0.28

package/docs/workflows.md

@@ -285,6 +285,51 @@ workflow("example")
   .end("done")
 ```
 
+### Poll
+
+Use a poll step for wait → check loops that persist across restarts.
+
+```typescript
+workflow("batch.status")
+  .poll("wait-for-result", {
+    interval: 5000,
+    timeout: 600000,
+    maxAttempts: 120,
+    check: async (input, ctx) => {
+      const status = await fetchStatus(input.operationId);
+      if (status.state === "FAILED") throw new Error(status.error);
+      if (status.state === "SUCCEEDED") {
+        return { done: true, result: status.data };
+      }
+      return { done: false };
+    },
+  })
+  .build();
+```
+
+Each poll cycle emits `workflow.step.poll` events and persists progress to the instance.
+
+### Loop
+
+Use a loop step to jump back to a previous step until a condition is false.
+
+```typescript
+workflow("loop-example")
+  .task("increment", {
+    handler: async (input) => ({ count: (input.count ?? 0) + 1 }),
+  })
+  .loop("repeat", {
+    condition: (ctx) => ctx.steps.increment.count < 3,
+    target: "increment",
+    interval: 1000,
+    maxIterations: 10,
+    timeout: 30000,
+  })
+  .build();
+```
+
+Each loop iteration emits `workflow.step.loop` and persists loop counters to the instance.
+
 ## Workflow Context
 
 Every step receives a `WorkflowContext` with:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@donkeylabs/server",
-  "version": "2.0.26",
+  "version": "2.0.28",
   "type": "module",
   "description": "Type-safe plugin system for building RPC-style APIs with Bun",
   "main": "./src/index.ts",

package/src/admin/routes.ts

@@ -505,6 +505,17 @@ export function createAdminRouter(config: AdminRouteContext) {
         stepName: z.string(),
         error: z.string(),
       }),
+      "step.poll": z.object({
+        stepName: z.string(),
+        pollCount: z.number(),
+        done: z.boolean(),
+        result: z.any().optional(),
+      }),
+      "step.loop": z.object({
+        stepName: z.string(),
+        loopCount: z.number(),
+        target: z.string(),
+      }),
       completed: z.object({
         output: z.any().optional(),
       }),
@@ -548,6 +559,19 @@ export function createAdminRouter(config: AdminRouteContext) {
         workflowName: z.string(),
         error: z.string(),
       }),
+      "workflow.step.poll": z.object({
+        instanceId: z.string(),
+        stepName: z.string(),
+        pollCount: z.number(),
+        done: z.boolean(),
+        result: z.any().optional(),
+      }),
+      "workflow.step.loop": z.object({
+        instanceId: z.string(),
+        stepName: z.string(),
+        loopCount: z.number(),
+        target: z.string(),
+      }),
     },
     handle: (input, ctx) => {
       if (!checkAuth(ctx)) {

package/src/core/index.ts

@@ -149,6 +149,9 @@ export {
   type ChoiceStepDefinition,
   type ChoiceCondition,
   type PassStepDefinition,
+  type PollStepDefinition,
+  type PollStepResult,
+  type LoopStepDefinition,
   type RetryConfig,
   type GetAllWorkflowsOptions,
   type PluginMetadata,

package/src/core/job-adapter-sqlite.ts

@@ -34,6 +34,7 @@ export class SqliteJobAdapter implements JobAdapter {
     this.ensureDir(dbPath);
 
     this.db = new Database(dbPath);
+    this.db.run("PRAGMA busy_timeout = 5000");
     this.init();
 
     // Start cleanup timer

package/src/core/logs-adapter-kysely.ts

@@ -80,6 +80,7 @@ export class KyselyLogsAdapter implements LogsAdapter {
     // Enable WAL mode for better concurrent read/write performance
     sqliteDb.exec("PRAGMA journal_mode = WAL");
     sqliteDb.exec("PRAGMA synchronous = NORMAL");
+    sqliteDb.exec("PRAGMA busy_timeout = 5000");
 
     this.db = new Kysely<Database>({
       dialect: new SqliteDialect({

package/src/core/process-adapter-sqlite.ts

@@ -52,6 +52,7 @@ export class SqliteProcessAdapter implements ProcessAdapter {
     this.ensureDir(dbPath);
 
     this.db = new Database(dbPath);
+    this.db.run("PRAGMA busy_timeout = 5000");
     this.init();
 
     // Start cleanup timer

package/src/core/workflow-adapter-kysely.ts

@@ -258,6 +258,11 @@ export class KyselyWorkflowAdapter implements WorkflowAdapter {
         startedAt: sr.startedAt ? new Date(sr.startedAt) : undefined,
         completedAt: sr.completedAt ? new Date(sr.completedAt) : undefined,
         attempts: sr.attempts,
+        pollCount: sr.pollCount,
+        lastPolledAt: sr.lastPolledAt ? new Date(sr.lastPolledAt) : undefined,
+        loopCount: sr.loopCount,
+        lastLoopedAt: sr.lastLoopedAt ? new Date(sr.lastLoopedAt) : undefined,
+        loopStartedAt: sr.loopStartedAt ? new Date(sr.loopStartedAt) : undefined,
       };
     }
 

package/src/core/workflow-executor.ts

@@ -184,6 +184,27 @@ function createIpcEventBridge(socket: Socket, instanceId: string): StateMachineE
         error,
       });
     },
+    onStepPoll: (id, stepName, pollCount, done, result) => {
+      sendEvent(socket, {
+        type: "step.poll",
+        instanceId: id,
+        timestamp: Date.now(),
+        stepName,
+        pollCount,
+        done,
+        result,
+      });
+    },
+    onStepLoop: (id, stepName, loopCount, target) => {
+      sendEvent(socket, {
+        type: "step.loop",
+        instanceId: id,
+        timestamp: Date.now(),
+        stepName,
+        loopCount,
+        target,
+      });
+    },
     onStepRetry: () => {
       // Retry is internal to the state machine - no IPC event needed
     },

package/src/core/workflow-socket.ts

@@ -20,6 +20,8 @@ export type WorkflowEventType =
   | "step.started"
   | "step.completed"
   | "step.failed"
+  | "step.poll"
+  | "step.loop"
   | "progress"
   | "completed"
   | "failed"
@@ -41,6 +43,11 @@ export interface WorkflowEvent {
   totalSteps?: number;
   /** Next step to execute (for step.completed events) */
   nextStep?: string;
+  pollCount?: number;
+  done?: boolean;
+  result?: any;
+  loopCount?: number;
+  target?: string;
   /** Custom event name (for event type) */
   event?: string;
   /** Custom event payload or log data */

package/src/core/workflow-state-machine.ts

@@ -12,6 +12,8 @@ import type {
   WorkflowContext,
   StepDefinition,
   TaskStepDefinition,
+  LoopStepDefinition,
+  PollStepDefinition,
   ParallelStepDefinition,
   ChoiceStepDefinition,
   PassStepDefinition,
@@ -28,6 +30,8 @@ export interface StateMachineEvents {
   onStepCompleted(instanceId: string, stepName: string, output: any, nextStep?: string): void;
   onStepFailed(instanceId: string, stepName: string, error: string, attempts: number): void;
   onStepRetry(instanceId: string, stepName: string, attempt: number, max: number, delayMs: number): void;
+  onStepPoll(instanceId: string, stepName: string, pollCount: number, done: boolean, result?: any): void;
+  onStepLoop(instanceId: string, stepName: string, loopCount: number, target: string): void;
   onProgress(instanceId: string, progress: number, currentStep: string, completed: number, total: number): void;
   onCompleted(instanceId: string, output: any): void;
   onFailed(instanceId: string, error: string): void;
@@ -136,11 +140,17 @@ export class WorkflowStateMachine {
       this.events.onStepStarted(instanceId, stepName, step.type);
 
       // Update step result as running
+      const previousStep = freshInstance.stepResults[stepName];
       const stepResult: StepResult = {
         stepName,
         status: "running",
-        startedAt: new Date(),
-        attempts: (freshInstance.stepResults[stepName]?.attempts ?? 0) + 1,
+        startedAt: previousStep?.startedAt ?? new Date(),
+        attempts: (previousStep?.attempts ?? 0) + 1,
+        pollCount: previousStep?.pollCount,
+        lastPolledAt: previousStep?.lastPolledAt,
+        loopCount: previousStep?.loopCount,
+        lastLoopedAt: previousStep?.lastLoopedAt,
+        loopStartedAt: previousStep?.loopStartedAt,
       };
       await this.adapter.updateInstance(instanceId, {
         currentStep: stepName,
@@ -166,6 +176,12 @@ export class WorkflowStateMachine {
           case "pass":
             output = await this.executePassStep(step, ctx);
             break;
+          case "poll":
+            output = await this.executePollStep(instanceId, step, ctx, definition);
+            break;
+          case "loop":
+            output = await this.executeLoopStep(instanceId, step, ctx);
+            break;
         }
 
         // Persist step completion
@@ -176,6 +192,8 @@ export class WorkflowStateMachine {
         if (step.type === "choice") {
           // Choice step returns { chosen: "nextStepName" }
           currentStepName = output?.chosen;
+        } else if (step.type === "loop" && output?.loopTo) {
+          currentStepName = output.loopTo;
         } else if (step.end) {
           currentStepName = undefined;
         } else if (step.next) {
@@ -445,6 +463,87 @@ export class WorkflowStateMachine {
     return output;
   }
 
+  private async executePollStep(
+    instanceId: string,
+    step: PollStepDefinition,
+    ctx: WorkflowContext,
+    _definition: WorkflowDefinition,
+  ): Promise<any> {
+    let input: any;
+
+    if (step.inputSchema) {
+      if (typeof step.inputSchema === "function") {
+        input = step.inputSchema(ctx.prev, ctx.input);
+      } else {
+        const parseResult = step.inputSchema.safeParse(ctx.input);
+        if (!parseResult.success) {
+          throw new Error(`Input validation failed: ${parseResult.error.message}`);
+        }
+        input = parseResult.data;
+      }
+    } else {
+      input = ctx.input;
+    }
+
+    let instance = await this.adapter.getInstance(instanceId);
+    const stepResult = instance?.stepResults[step.name];
+    const startedAt = stepResult?.startedAt ?? new Date();
+
+    if (instance && stepResult) {
+      stepResult.input = stepResult.input ?? input;
+      stepResult.pollCount = stepResult.pollCount ?? 0;
+      await this.adapter.updateInstance(instanceId, {
+        stepResults: { ...instance.stepResults, [step.name]: stepResult },
+      });
+    }
+
+    while (true) {
+      if (step.timeout && Date.now() - startedAt.getTime() > step.timeout) {
+        throw new Error(`Poll step "${step.name}" timed out`);
+      }
+
+      instance = await this.adapter.getInstance(instanceId);
+      const sr = instance?.stepResults[step.name];
+      const pollCount = sr?.pollCount ?? 0;
+
+      if (step.maxAttempts && pollCount >= step.maxAttempts) {
+        throw new Error(`Poll step "${step.name}" exceeded maxAttempts`);
+      }
+
+      if (step.interval > 0) {
+        await new Promise((resolve) => setTimeout(resolve, step.interval));
+      }
+
+      const result = await step.check(input, ctx);
+      const nextPollCount = pollCount + 1;
+
+      if (instance && sr) {
+        sr.pollCount = nextPollCount;
+        sr.lastPolledAt = new Date();
+        sr.output = result;
+        await this.adapter.updateInstance(instanceId, {
+          stepResults: { ...instance.stepResults, [step.name]: sr },
+        });
+      }
+
+      this.events.onStepPoll(instanceId, step.name, nextPollCount, result.done, result.result);
+
+      if (result.done) {
+        let output = result.result;
+
+        if (step.outputSchema) {
+          const parseResult = step.outputSchema.safeParse(output);
+          if (!parseResult.success) {
+            throw new Error(`Output validation failed: ${parseResult.error.message}`);
+          }
+          output = parseResult.data;
+        }
+
+        return output;
+      }
+    }
+  }
+
   private async executePassStep(
     step: PassStepDefinition,
     ctx: WorkflowContext,
@@ -458,6 +557,52 @@ export class WorkflowStateMachine {
     return ctx.input;
   }
 
+  private async executeLoopStep(
+    instanceId: string,
+    step: LoopStepDefinition,
+    ctx: WorkflowContext,
+  ): Promise<{ loopTo?: string }> {
+    const instance = await this.adapter.getInstance(instanceId);
+    const stepResult = instance?.stepResults[step.name] ?? {
+      stepName: step.name,
+      status: "running" as const,
+      attempts: 0,
+      startedAt: new Date(),
+    };
+    const loopStartedAt = stepResult.loopStartedAt ?? stepResult.startedAt ?? new Date();
+    const loopCount = stepResult.loopCount ?? 0;
+
+    if (step.timeout && Date.now() - loopStartedAt.getTime() > step.timeout) {
+      throw new Error(`Loop step "${step.name}" timed out`);
+    }
+
+    if (step.maxIterations && loopCount >= step.maxIterations) {
+      throw new Error(`Loop step "${step.name}" exceeded maxIterations`);
+    }
+
+    const shouldLoop = step.condition(ctx);
+
+    if (instance) {
+      stepResult.loopCount = shouldLoop ? loopCount + 1 : loopCount;
+      stepResult.loopStartedAt = loopStartedAt;
+      stepResult.lastLoopedAt = shouldLoop ? new Date() : stepResult.lastLoopedAt;
+      stepResult.output = { looped: shouldLoop };
+      await this.adapter.updateInstance(instanceId, {
+        stepResults: { ...instance.stepResults, [step.name]: stepResult },
+      });
+    }
+
+    if (shouldLoop) {
+      this.events.onStepLoop(instanceId, step.name, loopCount + 1, step.target);
+      if (step.interval && step.interval > 0) {
+        await new Promise((resolve) => setTimeout(resolve, step.interval));
+      }
+      return { loopTo: step.target };
+    }
+
+    return {};
+  }
+
   // ============================================
   // Context Building
   // ============================================

package/src/core/workflows.ts

@@ -59,7 +59,7 @@ type InferZodOutput<T extends ZodSchema> = z.infer<T>;
 // Step Types
 // ============================================
 
-export type StepType = "task" | "parallel" | "choice" | "pass";
+export type StepType = "task" | "parallel" | "choice" | "pass" | "poll" | "loop";
 
 export interface BaseStepDefinition {
   name: string;
@@ -146,11 +146,54 @@ export interface PassStepDefinition extends BaseStepDefinition {
   result?: any;
 }
 
+export interface PollStepResult<T = any> {
+  done: boolean;
+  result?: T;
+}
+
+export interface PollStepDefinition<
+  TInput extends ZodSchema = ZodSchema,
+  TOutput extends ZodSchema = ZodSchema,
+> extends BaseStepDefinition {
+  type: "poll";
+  /** Wait duration between checks in ms */
+  interval: number;
+  /** Max total time before failing this step (ms) */
+  timeout?: number;
+  /** Max number of check cycles before failing */
+  maxAttempts?: number;
+  /** Input schema or mapper */
+  inputSchema?: TInput | ((prev: any, workflowInput: any) => InferZodOutput<TInput>);
+  /** Output schema for the final result */
+  outputSchema?: TOutput;
+  /** Check handler: return done:true to proceed */
+  check: (
+    input: InferZodOutput<TInput>,
+    ctx: WorkflowContext
+  ) => Promise<PollStepResult<InferZodOutput<TOutput>>> | PollStepResult<InferZodOutput<TOutput>>;
+}
+
+export interface LoopStepDefinition extends BaseStepDefinition {
+  type: "loop";
+  /** Condition to continue looping */
+  condition: (ctx: WorkflowContext) => boolean;
+  /** Step name to jump back to when condition is true */
+  target: string;
+  /** Optional delay before looping (ms) */
+  interval?: number;
+  /** Max total time before failing this loop (ms) */
+  timeout?: number;
+  /** Max number of loop iterations before failing */
+  maxIterations?: number;
+}
+
 export type StepDefinition =
   | TaskStepDefinition
   | ParallelStepDefinition
   | ChoiceStepDefinition
-  | PassStepDefinition;
+  | PassStepDefinition
+  | PollStepDefinition
+  | LoopStepDefinition;
 
 // ============================================
 // Workflow Definition
@@ -203,6 +246,11 @@ export interface StepResult {
   startedAt?: Date;
   completedAt?: Date;
   attempts: number;
+  pollCount?: number;
+  lastPolledAt?: Date;
+  loopCount?: number;
+  lastLoopedAt?: Date;
+  loopStartedAt?: Date;
 }
 
 export interface WorkflowInstance {
@@ -569,6 +617,69 @@ export class WorkflowBuilder {
     return this;
   }
 
+  loop(
+    name: string,
+    config: {
+      condition: (ctx: WorkflowContext) => boolean;
+      target: string;
+      interval?: number;
+      timeout?: number;
+      maxIterations?: number;
+      next?: string;
+      end?: boolean;
+    }
+  ): this {
+    const step: LoopStepDefinition = {
+      name,
+      type: "loop",
+      condition: config.condition,
+      target: config.target,
+      interval: config.interval,
+      timeout: config.timeout,
+      maxIterations: config.maxIterations,
+      next: config.next,
+      end: config.end,
+    };
+
+    this.addStep(step);
+    return this;
+  }
+
+  poll<TInput extends ZodSchema = ZodSchema, TOutput extends ZodSchema = ZodSchema>(
+    name: string,
+    config: {
+      check: (
+        input: InferZodOutput<TInput>,
+        ctx: WorkflowContext
+      ) => Promise<PollStepResult<InferZodOutput<TOutput>>> | PollStepResult<InferZodOutput<TOutput>>;
+      interval: number;
+      timeout?: number;
+      maxAttempts?: number;
+      inputSchema?: TInput | ((prev: any, workflowInput: any) => InferZodOutput<TInput>);
+      outputSchema?: TOutput;
+      retry?: RetryConfig;
+      next?: string;
+      end?: boolean;
+    }
+  ): this {
+    const step: PollStepDefinition<TInput, TOutput> = {
+      name,
+      type: "poll",
+      check: config.check,
+      interval: config.interval,
+      timeout: config.timeout,
+      maxAttempts: config.maxAttempts,
+      inputSchema: config.inputSchema,
+      outputSchema: config.outputSchema,
+      retry: config.retry,
+      next: config.next,
+      end: config.end,
+    };
+
+    this.addStep(step);
+    return this;
+  }
+
   /** Add an end step (shorthand for pass with end: true) */
   end(name: string = "end"): this {
     return this.pass(name, { end: true });
@@ -649,8 +760,12 @@ export interface WorkflowsConfig {
   heartbeatTimeout?: number;
   /** Timeout waiting for isolated subprocess readiness (ms, default: 10000) */
   readyTimeout?: number;
+  /** Resume strategy for orphaned workflows (default: "blocking") */
+  resumeStrategy?: WorkflowResumeStrategy;
 }
 
+export type WorkflowResumeStrategy = "blocking" | "background" | "skip";
+
 /** Options for registering a workflow */
 export interface WorkflowRegisterOptions {
   /**
@@ -687,7 +802,7 @@ export interface Workflows {
   /** Get all workflow instances with optional filtering (for admin dashboard) */
   getAllInstances(options?: GetAllWorkflowsOptions): Promise<WorkflowInstance[]>;
   /** Resume workflows after server restart */
-  resume(): Promise<void>;
+  resume(options?: { strategy?: WorkflowResumeStrategy }): Promise<void>;
   /** Stop the workflow service */
   stop(): Promise<void>;
   /** Set core services (called after initialization to resolve circular dependency) */
@@ -739,6 +854,7 @@ class WorkflowsImpl implements Workflows {
   private dbPath?: string;
   private heartbeatTimeoutMs: number;
   private readyTimeoutMs: number;
+  private resumeStrategy!: WorkflowResumeStrategy;
   private workflowModulePaths = new Map<string, string>();
   private isolatedProcesses = new Map<string, IsolatedProcessInfo>();
   private readyWaiters = new Map<
@@ -772,6 +888,7 @@ class WorkflowsImpl implements Workflows {
     this.dbPath = config.dbPath;
     this.heartbeatTimeoutMs = config.heartbeatTimeout ?? 60000;
     this.readyTimeoutMs = config.readyTimeout ?? 10000;
+    this.resumeStrategy = config.resumeStrategy ?? "blocking";
   }
 
   private getSocketServer(): WorkflowSocketServer {
@@ -975,38 +1092,64 @@ class WorkflowsImpl implements Workflows {
     return this.adapter.getAllInstances(options);
   }
 
-  async resume(): Promise<void> {
+  async resume(options?: { strategy?: WorkflowResumeStrategy }): Promise<void> {
+    const strategy = options?.strategy ?? this.resumeStrategy;
     const running = await this.adapter.getRunningInstances();
 
-    for (const instance of running) {
+    if (this.dbPath) {
+      await this.getSocketServer().cleanOrphanedSockets(
+        new Set(running.map((instance) => instance.id))
+      );
+    }
+
+    if (strategy === "skip") {
+      await this.markOrphanedAsFailed(running, "Workflow resume skipped");
+      return;
+    }
+
+    const resumeInstance = async (instance: WorkflowInstance) => {
       const definition = this.definitions.get(instance.workflowName);
       if (!definition) {
-        // Workflow no longer registered, mark as failed
         await this.adapter.updateInstance(instance.id, {
           status: "failed",
           error: "Workflow definition not found after restart",
           completedAt: new Date(),
         });
-        continue;
+        return;
       }
 
       console.log(`[Workflows] Resuming workflow instance ${instance.id}`);
 
-      // Check isolation mode and call appropriate method
       const isIsolated = definition.isolated !== false;
       const modulePath = this.workflowModulePaths.get(instance.workflowName);
 
       if (isIsolated && modulePath && this.dbPath) {
-        try {
-          await this.executeIsolatedWorkflow(instance.id, definition, instance.input, modulePath);
-        } catch (error) {
+        await this.executeIsolatedWorkflow(instance.id, definition, instance.input, modulePath);
+      } else {
+        this.startInlineWorkflow(instance.id, definition);
+      }
+    };
+
+    if (strategy === "background") {
+      for (const instance of running) {
+        resumeInstance(instance).catch((error) => {
           console.error(
-            `[Workflows] Failed to resume isolated workflow ${instance.id}:`,
+            `[Workflows] Failed to resume workflow ${instance.id}:`,
             error instanceof Error ? error.message : String(error)
           );
-        }
-      } else {
-        this.startInlineWorkflow(instance.id, definition);
+        });
+      }
+      return;
+    }
+
+    for (const instance of running) {
+      try {
+        await resumeInstance(instance);
+      } catch (error) {
+        console.error(
+          `[Workflows] Failed to resume workflow ${instance.id}:`,
+          error instanceof Error ? error.message : String(error)
+        );
       }
     }
   }
@@ -1166,6 +1309,51 @@ class WorkflowsImpl implements Workflows {
           });
         }
       },
+      onStepPoll: (id, stepName, pollCount, done, result) => {
+        this.emitEvent("workflow.step.poll", {
+          instanceId: id,
+          stepName,
+          pollCount,
+          done,
+          result,
+        });
+        if (this.sse) {
+          this.sse.broadcast(`workflow:${id}`, "step.poll", {
+            stepName,
+            pollCount,
+            done,
+            result,
+          });
+          this.sse.broadcast("workflows:all", "workflow.step.poll", {
+            instanceId: id,
+            stepName,
+            pollCount,
+            done,
+            result,
+          });
+        }
+      },
+      onStepLoop: (id, stepName, loopCount, target) => {
+        this.emitEvent("workflow.step.loop", {
+          instanceId: id,
+          stepName,
+          loopCount,
+          target,
+        });
+        if (this.sse) {
+          this.sse.broadcast(`workflow:${id}`, "step.loop", {
+            stepName,
+            loopCount,
+            target,
+          });
+          this.sse.broadcast("workflows:all", "workflow.step.loop", {
+            instanceId: id,
+            stepName,
+            loopCount,
+            target,
+          });
+        }
+      },
       onStepRetry: (id, stepName, attempt, max, delayMs) => {
         this.emitEvent("workflow.step.retry", {
           instanceId: id,
@@ -1452,6 +1640,55 @@ class WorkflowsImpl implements Workflows {
         break;
       }
 
+      case "step.poll": {
+        await this.emitEvent("workflow.step.poll", {
+          instanceId,
+          stepName: event.stepName,
+          pollCount: event.pollCount,
+          done: event.done,
+          result: event.result,
+        });
+        if (this.sse) {
+          this.sse.broadcast(`workflow:${instanceId}`, "step.poll", {
+            stepName: event.stepName,
+            pollCount: event.pollCount,
+            done: event.done,
+            result: event.result,
+          });
+          this.sse.broadcast("workflows:all", "workflow.step.poll", {
+            instanceId,
+            stepName: event.stepName,
+            pollCount: event.pollCount,
+            done: event.done,
+            result: event.result,
+          });
+        }
+        break;
+      }
+
+      case "step.loop": {
+        await this.emitEvent("workflow.step.loop", {
+          instanceId,
+          stepName: event.stepName,
+          loopCount: event.loopCount,
+          target: event.target,
+        });
+        if (this.sse) {
+          this.sse.broadcast(`workflow:${instanceId}`, "step.loop", {
+            stepName: event.stepName,
+            loopCount: event.loopCount,
+            target: event.target,
+          });
+          this.sse.broadcast("workflows:all", "workflow.step.loop", {
+            instanceId,
+            stepName: event.stepName,
+            loopCount: event.loopCount,
+            target: event.target,
+          });
+        }
+        break;
+      }
+
       case "progress": {
         await this.emitEvent("workflow.progress", {
           instanceId,
@@ -1710,6 +1947,34 @@ class WorkflowsImpl implements Workflows {
     this.rejectIsolatedReady(instanceId, new Error("Isolated workflow cleaned up"));
   }
 
+  private async markOrphanedAsFailed(
+    instances: WorkflowInstance[],
+    reason: string
+  ): Promise<void> {
+    for (const instance of instances) {
+      await this.adapter.updateInstance(instance.id, {
+        status: "failed",
+        error: reason,
+        completedAt: new Date(),
+      });
+
+      await this.emitEvent("workflow.failed", {
+        instanceId: instance.id,
+        workflowName: instance.workflowName,
+        error: reason,
+      });
+
+      if (this.sse) {
+        this.sse.broadcast(`workflow:${instance.id}`, "failed", { error: reason });
+        this.sse.broadcast("workflows:all", "workflow.failed", {
+          instanceId: instance.id,
+          workflowName: instance.workflowName,
+          error: reason,
+        });
+      }
+    }
+  }
+
   /**
    * Reset heartbeat timeout for an isolated workflow
    */

package/src/server.ts

@@ -81,6 +81,11 @@ export interface ServerConfig {
   rateLimiter?: RateLimiterConfig;
   errors?: ErrorsConfig;
   workflows?: WorkflowsConfig;
+  /**
+   * Resume strategy for workflows on startup.
+   * Defaults to "blocking" for server mode and "background" for adapter mode.
+   */
+  workflowsResumeStrategy?: "blocking" | "background" | "skip";
   processes?: ProcessesConfig;
   audit?: AuditConfig;
   websocket?: WebSocketConfig;
@@ -214,6 +219,8 @@ export class AppServer {
   private isInitialized = false;
   private initializationPromise: Promise<void> | null = null;
   private generateModeSetup = false;
+  private initMode: "adapter" | "server" = "server";
+  private workflowsResumeStrategy?: "blocking" | "background" | "skip";
 
   // Custom services registry
   private serviceFactories = new Map<string, ServiceFactory<any>>();
@@ -225,6 +232,7 @@ export class AppServer {
     const envPort = process.env.PORT ? parseInt(process.env.PORT, 10) : undefined;
     this.port = options.port ?? envPort ?? 3000;
     this.maxPortAttempts = options.maxPortAttempts ?? 5;
+    this.workflowsResumeStrategy = options.workflowsResumeStrategy ?? options.workflows?.resumeStrategy;
 
     // Determine if we should use legacy databases
     const useLegacy = options.useLegacyCoreDatabases ?? false;
@@ -986,6 +994,7 @@ ${factoryFunction}
    * Used by adapters (e.g., SvelteKit) that manage their own HTTP server.
    */
   async initialize(): Promise<void> {
+    this.initMode = "adapter";
     // Handle CLI type generation mode - exit early before any initialization
     if (process.env.DONKEYLABS_GENERATE === "1") {
       this.outputRoutesForGeneration();
@@ -1038,7 +1047,13 @@ ${factoryFunction}
     this.coreServices.cron.start();
     this.coreServices.jobs.start();
     await this.coreServices.workflows.resolveDbPath();
-    await this.coreServices.workflows.resume();
+    const defaultStrategy = this.initMode === "adapter" ? "background" : undefined;
+    const strategy = this.workflowsResumeStrategy ?? defaultStrategy;
+    if (strategy) {
+      await this.coreServices.workflows.resume({ strategy });
+    } else {
+      await this.coreServices.workflows.resume();
+    }
     this.coreServices.processes.start();
     logger.info("Background services started (cron, jobs, workflows, processes)");
 
@@ -1252,6 +1267,7 @@ ${factoryFunction}
    * 5. Start the HTTP server
    */
   async start() {
+    this.initMode = "server";
     // Handle CLI type generation mode - exit early before any initialization
     if (process.env.DONKEYLABS_GENERATE === "1") {
       this.outputRoutesForGeneration();