@desplega.ai/agent-swarm 1.74.0 → 1.74.2

package/src/workflows/resume.ts

@@ -1,11 +1,15 @@
 import {
   cancelTask,
   getCompletedStepNodeIds,
+  getPendingEventWaitNames,
+  getPendingWaitsByEvent,
   getTaskByWorkflowRunStepId,
+  getWaitStateById,
   getWorkflow,
   getWorkflowRun,
   getWorkflowRunStep,
   getWorkflowRunStepsByRunId,
+  resolveWaitState,
   updateWorkflowRun,
   updateWorkflowRunStep,
 } from "../be/db";
@@ -13,7 +17,10 @@ import { checkpointStep } from "./checkpoint";
 import { getSuccessors } from "./definition";
 import { findReadyNodes, walkGraph } from "./engine";
 import type { WorkflowEventBus } from "./event-bus";
+import { workflowEventBus } from "./event-bus";
 import type { ExecutorRegistry } from "./executors/registry";
+import { computeNextPort } from "./executors/wait";
+import { matchesFilter } from "./wait-filter";
 
 interface TaskEvent {
   taskId: string;
@@ -341,3 +348,268 @@ async function resumeFromApprovalResolution(
     finalizeOrWait(run.id);
   }
 }
+
+/**
+ * Resume a paused `wait` node. Single entry-point shared by the wait poller
+ * (Phase 2 — time mode + event-mode timeout) and, in Phase 3, the bus listener
+ * for event-mode signal arrival.
+ *
+ * Flow:
+ *   1. Atomically resolve the `wait_states` row (`pending → fired|timeout`).
+ *      Race-safe: `resolveWaitState` returns `{updated: false}` when a
+ *      concurrent caller already won — we bail without further side-effects.
+ *   2. Reload the run + step. Bail if the step is no longer in `waiting`
+ *      (cancelled, failed, or somehow already advanced).
+ *   3. Compute the output port (time → `default`, event+fired → `event`,
+ *      event+timeout → `timeout`).
+ *   4. Checkpoint the step as completed with the wait output, set the run
+ *      back to `running`, and walk the successors of the chosen port.
+ *
+ * NOTE: there are intentionally NO `wait.fired` / `wait.timeout` bus events.
+ * Resumption is an internal function call — the poller invokes this directly,
+ * and the Phase 3 bus listener will too.
+ */
+export async function resumeWaitState(
+  waitId: string,
+  status: "fired" | "timeout",
+  payload: unknown,
+  registry: ExecutorRegistry,
+): Promise<void> {
+  // 1. Cap firedPayload at 64KB (DB-write boundary). Webhook payloads can be
+  // 50KB+ — anything bigger is replaced with a marker so we don't bloat the
+  // row. The same truncated form is also what the workflow sees in
+  // `output.payload` so authors aren't surprised by stored vs delivered
+  // diverging.
+  const cappedPayload = capPayload(payload);
+
+  // 2. Atomic state transition. Only the first caller proceeds.
+  const result = resolveWaitState(waitId, { status, firedPayload: cappedPayload });
+  if (!result.updated || !result.row) return;
+
+  const waitRow = result.row;
+
+  // 2. Load the surrounding run + step. If anything has moved on (cancelled,
+  // failed, retried, etc.), stay quiet.
+  const run = getWorkflowRun(waitRow.workflowRunId);
+  if (!run || (run.status !== "waiting" && run.status !== "running")) return;
+
+  const step = getWorkflowRunStep(waitRow.workflowRunStepId);
+  if (!step || step.status !== "waiting") return;
+
+  const workflow = getWorkflow(run.workflowId);
+  if (!workflow) return;
+
+  // 3. Pick the output port.
+  const nextPort = computeNextPort(waitRow.mode, status);
+
+  // 4. Build step output, checkpoint, transition run, walk successors.
+  const ctx = (run.context ?? {}) as Record<string, unknown>;
+  const stepOutput = {
+    waitId: waitRow.id,
+    mode: waitRow.mode,
+    firedAt: waitRow.resolvedAt,
+    payload: cappedPayload === undefined ? undefined : cappedPayload,
+  };
+
+  checkpointStep(run.id, step.id, step.nodeId, { output: stepOutput, nextPort }, ctx);
+  updateWorkflowRun(run.id, { status: "running" });
+
+  // 5. Bus listener bookkeeping: this wait is no longer pending, so drop it
+  // from the per-event subscription set. If the set empties out, unwire the
+  // bus listener.
+  if (waitRow.mode === "event" && waitRow.eventName) {
+    pruneWaitFromBus(waitRow.id, waitRow.eventName);
+  }
+
+  const successors = getSuccessors(workflow.definition, step.nodeId, nextPort);
+  if (successors.length > 0) {
+    await walkGraph(workflow.definition, run.id, ctx, successors, registry, workflow.id);
+  } else {
+    finalizeOrWait(run.id);
+  }
+}
+
+// ─── 64KB firedPayload cap ──────────────────────────────────────────────────
+
+const FIRED_PAYLOAD_BYTE_CAP = 64 * 1024; // 64KB
+
+/**
+ * Apply the 64KB cap policy to event-mode `firedPayload`. If the JSON-encoded
+ * payload exceeds the cap, replace it with a structured truncation marker so
+ * downstream nodes can detect the truncation and either ignore it or pull the
+ * full payload from the source if needed.
+ *
+ * The same form flows into both the DB row AND the step output — see
+ * docstring above for rationale.
+ */
+function capPayload(payload: unknown): unknown {
+  if (payload === undefined || payload === null) return payload;
+  let encoded: string;
+  try {
+    encoded = JSON.stringify(payload);
+  } catch {
+    // Non-serializable (function, symbol, circular ref, …) — hand back a
+    // marker rather than letting JSON.stringify failure bubble up.
+    return { truncated: true, reason: "non-serializable" };
+  }
+  if (encoded.length <= FIRED_PAYLOAD_BYTE_CAP) {
+    return payload;
+  }
+  // Build a 1KB summary slice for visibility.
+  const summary = encoded.slice(0, 1024);
+  return {
+    truncated: true,
+    originalSize: encoded.length,
+    summary,
+  };
+}
+
+// ─── Wait bus subscription registry (event mode) ────────────────────────────
+//
+// One bus listener per distinct `eventName`. Each listener iterates a Set of
+// pending waitIds, looks up each row, applies scope + filter, and resolves on
+// match. Listeners are created lazily (on first subscribeWaitToBus for an
+// eventName) and torn down when the per-name Set empties.
+
+const waitsByEvent = new Map<string, Set<string>>();
+const listenersByEvent = new Map<string, (data: unknown) => void>();
+let busRegistry: ExecutorRegistry | null = null;
+
+/**
+ * Initialize the wait-bus subscription system. Called from `initWorkflows()`
+ * AFTER `setupWorkflowResumeListener`. Scans all pending event-mode waits and
+ * registers one listener per distinct event name.
+ *
+ * Subsequent calls update the registry reference (idempotent — listeners
+ * already registered are not re-registered).
+ */
+export function initWaitBusSubscriptions(registry: ExecutorRegistry): void {
+  busRegistry = registry;
+  // Pre-existing listeners are fine — they pick up the new registry via the
+  // module-level `busRegistry` reference.
+  // Recover pending event-mode waits from DB so signals fired pre-recovery
+  // arrive at the right wait once the listener is registered.
+  // We use a dedicated DB query rather than getPendingWaitsByEvent so we can
+  // page through ALL distinct event names in one pass.
+  const pendingNames = collectPendingEventNames();
+  for (const name of pendingNames) {
+    const pending = getPendingWaitsByEvent(name);
+    for (const w of pending) {
+      registerWait(w.id, name);
+    }
+  }
+}
+
+function collectPendingEventNames(): Set<string> {
+  return new Set(getPendingEventWaitNames());
+}
+
+/**
+ * Add `waitId` to the subscription set for `eventName` and register the
+ * listener if not already present. Idempotent — safe to call from
+ * `WaitExecutor.execute`.
+ */
+export function subscribeWaitToBus(waitId: string, eventName: string): void {
+  registerWait(waitId, eventName);
+}
+
+function registerWait(waitId: string, eventName: string): void {
+  let set = waitsByEvent.get(eventName);
+  if (!set) {
+    set = new Set();
+    waitsByEvent.set(eventName, set);
+  }
+  set.add(waitId);
+
+  if (!listenersByEvent.has(eventName)) {
+    const listener = (data: unknown) => {
+      // Fire-and-forget: don't block the bus thread. Errors are logged
+      // per-wait inside processBusEvent.
+      void processBusEvent(eventName, data);
+    };
+    listenersByEvent.set(eventName, listener);
+    workflowEventBus.on(eventName, listener);
+  }
+}
+
+function pruneWaitFromBus(waitId: string, eventName: string): void {
+  const set = waitsByEvent.get(eventName);
+  if (!set) return;
+  set.delete(waitId);
+  if (set.size === 0) {
+    waitsByEvent.delete(eventName);
+    const listener = listenersByEvent.get(eventName);
+    if (listener) {
+      workflowEventBus.off(eventName, listener);
+      listenersByEvent.delete(eventName);
+    }
+  }
+}
+
+/**
+ * Bus listener body. Walks the per-event waitId set, applies scope + filter,
+ * resolves on match. Race-safety lives inside `resumeWaitState`.
+ */
+async function processBusEvent(eventName: string, payload: unknown): Promise<void> {
+  const set = waitsByEvent.get(eventName);
+  if (!set || set.size === 0) return;
+  if (!busRegistry) return; // Pre-init — drop the event silently.
+
+  // Snapshot the set so we can mutate (prune) during iteration.
+  const waitIds = [...set];
+  for (const waitId of waitIds) {
+    try {
+      const row = getWaitStateById(waitId);
+      if (!row || row.status !== "pending") {
+        // Already resolved (race) or vanished — drop the stale subscription.
+        set.delete(waitId);
+        continue;
+      }
+
+      // Scope enforcement: 'run' requires payload._runId or
+      // payload.workflowRunId to match the wait's workflowRunId.
+      if (row.eventScope === "run") {
+        if (!isPayloadInRun(payload, row.workflowRunId)) continue;
+      }
+
+      // Filter match.
+      const ok = await matchesFilter(payload, row.eventFilter ?? undefined);
+      if (!ok) continue;
+
+      // Resolve via the shared helper. Race-safe: only the first caller wins.
+      await resumeWaitState(waitId, "fired", payload, busRegistry);
+    } catch (err) {
+      console.error(
+        `[workflows] Wait bus listener failed for wait=${waitId} event=${eventName}:`,
+        err,
+      );
+    }
+  }
+
+  // Clean up: if all waits for this event resolved, drop the listener.
+  if (set.size === 0) {
+    waitsByEvent.delete(eventName);
+    const listener = listenersByEvent.get(eventName);
+    if (listener) {
+      workflowEventBus.off(eventName, listener);
+      listenersByEvent.delete(eventName);
+    }
+  }
+}
+
+function isPayloadInRun(payload: unknown, runId: string): boolean {
+  if (typeof payload !== "object" || payload === null) return false;
+  const rec = payload as Record<string, unknown>;
+  return rec._runId === runId || rec.workflowRunId === runId;
+}
+
+// Test-only: clear in-memory subscription state. Used by unit tests that
+// mount/unmount the bus across describe blocks.
+export function _resetWaitBusSubscriptionsForTests(): void {
+  for (const [name, listener] of listenersByEvent.entries()) {
+    workflowEventBus.off(name, listener);
+  }
+  listenersByEvent.clear();
+  waitsByEvent.clear();
+  busRegistry = null;
+}

package/src/workflows/wait-filter.ts

@@ -0,0 +1,311 @@
+/**
+ * Wait-node event filter matcher.
+ *
+ * Filter shapes (discriminated by `typeof`):
+ *
+ * 1. **Object form** — flat key/dot-path equality. Each filter key may use
+ *    dot-path segments (e.g. `"pr.number"`) and each value is compared by
+ *    deep-equal (numbers/strings/booleans/arrays/objects). Missing keys or
+ *    type mismatches → no-match. ALL keys must match.
+ *
+ * 2. **String form** — JS arrow-function body, evaluated in a sandbox. The
+ *    body must evaluate to a function `(payload) => boolean`. Result is
+ *    `!!`-coerced. Throws → no-match. Hard-capped at 50ms wall-clock.
+ *
+ * No filter (undefined) → matches anything.
+ *
+ * SECURITY:
+ * - The string-form sandbox shadows dangerous globals (incl. `eval`,
+ *   `Function`, `AsyncFunction`) — STRICTER than `code-match` because filter
+ *   strings are higher-volume and authored by less-trusted workflow authors.
+ * - Payload is `structuredClone`d before being passed to the user fn so
+ *   side-effects on the cloned argument do not leak back to the bus payload.
+ * - The 50ms timeout defangs infinite loops and pathological-regex DoS.
+ */
+
+// ─── Sandbox config ─────────────────────────────────────────
+
+/**
+ * Globals to shadow when invoking the user filter via `new Function`.
+ *
+ * - `PARAM_SHADOW_KEYS`: passed as parameter names to `new Function` so they
+ *   resolve to `undefined` at call time. `"use strict"` forbids `eval`,
+ *   `arguments`, `Function`, `AsyncFunction` as parameter names — we shadow
+ *   those via `var`-declared locals inside the function body instead.
+ * - `BODY_SHADOW_KEYS`: shadowed via `var X = undefined;` at the top of the
+ *   body so identifier resolution finds the local before climbing to the
+ *   global scope. This blocks `eval()`, `Function(...)`, and the
+ *   constructor-chain escape `payload.constructor.constructor(...)` because
+ *   the inner `Function` resolves to undefined.
+ *
+ * STRICTER than `src/workflows/executors/code-match.ts:19-30` because filter
+ * strings are higher-volume and authored by less-trusted workflow authors.
+ */
+const PARAM_SHADOW_KEYS = [
+  "require",
+  "process",
+  "Bun",
+  "globalThis",
+  "global",
+  "fetch",
+  "setTimeout",
+  "setInterval",
+] as const;
+
+const PARAM_SHADOW_VALUES = PARAM_SHADOW_KEYS.map(() => undefined);
+
+// Identifier names that strict mode reserves as parameter names. Shadowed via
+// `var X = undefined;` declarations at the top of the function body.
+const BODY_SHADOW_KEYS = ["eval", "Function", "AsyncFunction"] as const;
+const BODY_SHADOW_PREAMBLE = BODY_SHADOW_KEYS.map((k) => `var ${k} = undefined;`).join(" ");
+
+const FILTER_TIMEOUT_MS = 50;
+
+// ─── Object-form helpers ────────────────────────────────────
+
+function getByDotPath(obj: unknown, path: string): { found: boolean; value: unknown } {
+  if (obj === null || typeof obj !== "object") {
+    return { found: false, value: undefined };
+  }
+  const segments = path.split(".");
+  let cursor: unknown = obj;
+  for (const seg of segments) {
+    if (cursor === null || typeof cursor !== "object") {
+      return { found: false, value: undefined };
+    }
+    const rec = cursor as Record<string, unknown>;
+    if (!(seg in rec)) {
+      return { found: false, value: undefined };
+    }
+    cursor = rec[seg];
+  }
+  return { found: true, value: cursor };
+}
+
+function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (typeof a !== typeof b) return false;
+  if (a === null || b === null) return false;
+  if (Array.isArray(a)) {
+    if (!Array.isArray(b)) return false;
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      if (!deepEqual(a[i], b[i])) return false;
+    }
+    return true;
+  }
+  if (typeof a === "object" && typeof b === "object") {
+    const aKeys = Object.keys(a as Record<string, unknown>);
+    const bKeys = Object.keys(b as Record<string, unknown>);
+    if (aKeys.length !== bKeys.length) return false;
+    for (const k of aKeys) {
+      if (!deepEqual((a as Record<string, unknown>)[k], (b as Record<string, unknown>)[k])) {
+        return false;
+      }
+    }
+    return true;
+  }
+  return false;
+}
+
+function matchObjectFilter(payload: unknown, filter: Record<string, unknown>): boolean {
+  for (const [key, expected] of Object.entries(filter)) {
+    const { found, value } = getByDotPath(payload, key);
+    if (!found) return false;
+    if (!deepEqual(value, expected)) return false;
+  }
+  return true;
+}
+
+// ─── String-form helpers ────────────────────────────────────
+
+/**
+ * Run the user fn with a 50ms wall-clock cap. Returns `null` on timeout / throw.
+ *
+ * Note: this is a soft timeout — a tight CPU-bound loop in the user fn cannot
+ * be pre-empted by JS (single-threaded). The cap works because the timeout
+ * timer fires AFTER the synchronous fn returns or throws; if the fn never
+ * returns we still return `null` to the caller via the race below, but the
+ * fn itself keeps running on the event loop until it yields. In practice the
+ * sandbox blocks `setTimeout`/`setInterval`/async patterns, so an infinite
+ * loop will block the listener until the JIT or GC interrupts it; we accept
+ * that bounded risk per the plan's security note. The race ensures we DO NOT
+ * propagate a hung promise into the caller.
+ */
+async function runWithTimeout<T>(fn: () => T): Promise<T | null> {
+  return new Promise<T | null>((resolve) => {
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      resolve(null);
+    }, FILTER_TIMEOUT_MS);
+
+    // Run synchronously on the next microtask so we can race the timer.
+    queueMicrotask(() => {
+      if (settled) return;
+      try {
+        const v = fn();
+        // If v is a Promise, the contract says "filters are synchronous":
+        // attach a no-op catch IMMEDIATELY (so a sync rejection from inside
+        // the user fn doesn't crash the runtime) and resolve to a sentinel
+        // that the caller treats as "no-match". We wrap in a marker object
+        // so the outer `await` can't unwrap a Thenable for us.
+        if (
+          v !== null &&
+          typeof v === "object" &&
+          typeof (v as { then?: unknown }).then === "function"
+        ) {
+          (v as unknown as Promise<unknown>).catch(() => {});
+          settled = true;
+          clearTimeout(timer);
+          resolve({ __asyncRejected: true } as unknown as T);
+          return;
+        }
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve(v);
+      } catch {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve(null);
+      }
+    });
+  });
+}
+
+const ASYNC_SENTINEL = "__asyncRejected";
+
+function isAsyncSentinel(value: unknown): boolean {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    (value as Record<string, unknown>)[ASYNC_SENTINEL] === true
+  );
+}
+
+/**
+ * Compile and validate a string filter at executor-init time. Throws if the
+ * filter does not parse as `(${filter})`. Returns a callable.
+ */
+export function compileStringFilter(filter: string): (payload: unknown) => unknown {
+  // Length cap is enforced by the Zod schema (`.max(2048)`); this is a
+  // defense-in-depth check.
+  if (filter.length > 2048) {
+    throw new Error(`wait filter source exceeds 2KB cap (${filter.length} bytes)`);
+  }
+  // Compile — surfaces SyntaxError early.
+  //
+  // We do NOT use `"use strict"` here because strict-mode FORBIDS declaring
+  // `eval`, `Function`, etc. as bindings (the very thing we need to do). We
+  // use sloppy mode + var-shadowing inside an IIFE-style wrapper so the user
+  // fn body sees `eval`, `Function`, `AsyncFunction` (and the param-shadowed
+  // `process`, `require`, etc.) as `undefined`.
+  //
+  // The user's fn itself is wrapped as `(filter)(payload)`. If the user
+  // writes their own `"use strict"` directive, it applies only inside the
+  // IIFE — that's fine, because by then the shadowed names are already
+  // bound to undefined in the enclosing scope.
+  let fn: (...args: unknown[]) => unknown;
+  try {
+    fn = new Function(
+      ...PARAM_SHADOW_KEYS,
+      "payload",
+      `${BODY_SHADOW_PREAMBLE} return (${filter})(payload);`,
+    ) as (...args: unknown[]) => unknown;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`wait filter compile error: ${msg}`);
+  }
+  return (payload: unknown) => fn(...PARAM_SHADOW_VALUES, payload);
+}
+
+// ─── Prototype-stripping helper ─────────────────────────────
+
+/**
+ * Recursively rebuild `obj` with `null` prototypes on every plain object so
+ * the user fn cannot reach the global `Function` constructor via
+ * `payload.constructor.constructor(...)`. Arrays keep `Array.prototype` so
+ * `.some()`, `.map()`, etc. still work for legitimate predicates — Array's
+ * constructor chain still leaks `Function`, but that's a known acceptable
+ * trade-off (callers needing array methods accept the residual surface).
+ *
+ * For deep safety on arrays, callers can use object form filters instead.
+ *
+ * Returns primitives and arrays unchanged in shape; rebuilds objects.
+ */
+function nullifyPrototypes(value: unknown): unknown {
+  if (value === null || typeof value !== "object") return value;
+  if (Array.isArray(value)) {
+    // Array methods like `.some` are useful for filter authors. Array's
+    // constructor IS still reachable via `payload.someArr.constructor`. The
+    // fix below also nullifies the per-element objects so most legitimate
+    // queries are safe; users who need stricter deep-blocking should use
+    // the object-form filter.
+    return value.map(nullifyPrototypes);
+  }
+  const out = Object.create(null) as Record<string, unknown>;
+  for (const [k, v] of Object.entries(value)) {
+    out[k] = nullifyPrototypes(v);
+  }
+  return out;
+}
+
+// ─── Public matcher ─────────────────────────────────────────
+
+/**
+ * Returns true iff `payload` satisfies `filter`. See module-level docstring
+ * for filter shape semantics.
+ *
+ * NEVER throws — sandbox errors / timeouts are coerced to false.
+ */
+export async function matchesFilter(payload: unknown, filter: unknown): Promise<boolean> {
+  // No filter → match everything.
+  if (filter === undefined || filter === null) return true;
+
+  // Object form.
+  if (typeof filter === "object" && !Array.isArray(filter)) {
+    return matchObjectFilter(payload, filter as Record<string, unknown>);
+  }
+
+  // String form.
+  if (typeof filter === "string") {
+    let userFn: (payload: unknown) => unknown;
+    try {
+      userFn = compileStringFilter(filter);
+    } catch {
+      return false;
+    }
+
+    // Defensive copy with null-prototype: prevents (a) mutation leaking back
+    // to the bus payload, and (b) the `payload.constructor.constructor`
+    // escape from reaching the global Function constructor through the
+    // prototype chain.
+    let cloned: unknown;
+    try {
+      const cloneOnce = structuredClone(payload);
+      cloned = nullifyPrototypes(cloneOnce);
+    } catch {
+      // Some payloads (functions, symbols) cannot be structuredClone'd —
+      // fall back to the raw payload but still apply nullifyPrototypes if
+      // possible.
+      try {
+        cloned = nullifyPrototypes(payload);
+      } catch {
+        cloned = payload;
+      }
+    }
+
+    const result = await runWithTimeout(() => userFn(cloned));
+    if (result === null) return false; // timeout / throw
+    // The runWithTimeout helper substitutes a sentinel for Promise returns
+    // (filters are synchronous by contract — async predicates → no-match).
+    if (isAsyncSentinel(result)) return false;
+    return !!result;
+  }
+
+  // Anything else (array, number, etc.) → no match.
+  return false;
+}

package/src/workflows/wait-poller.ts

@@ -0,0 +1,63 @@
+import { getDueWaitStates } from "../be/db";
+import type { ExecutorRegistry } from "./executors/registry";
+import { resumeWaitState } from "./resume";
+
+let pollerTimeout: ReturnType<typeof setTimeout> | null = null;
+
+/**
+ * Start the wait-state poller.
+ *
+ * Mirrors `startRetryPoller`: chains `setTimeout` (NOT `setInterval`) so the
+ * next tick is only scheduled after the current one finishes. Default tick is
+ * 5s — same cadence as the retry poller.
+ *
+ * Each tick:
+ *   1. `getDueWaitStates()` — pending rows with `wakeUpAt <= now`
+ *      (time mode) OR `expiresAt <= now` (event-mode timeout).
+ *   2. For each row, call `resumeWaitState(id, kind, undefined, registry)`.
+ *      Time-mode rows resume as `fired`; event-mode overdue rows resume as
+ *      `timeout`. `resumeWaitState` is race-safe (atomic UPDATE) — concurrent
+ *      callers no-op.
+ *
+ * Errors per row are logged and the loop continues; one bad wait must not
+ * starve the rest.
+ */
+export function startWaitPoller(registry: ExecutorRegistry, intervalMs = 5000): void {
+  if (pollerTimeout !== null) return; // Already running
+
+  async function poll(): Promise<void> {
+    try {
+      const dueWaits = getDueWaitStates();
+
+      for (const wait of dueWaits) {
+        try {
+          // Decide resume kind from wait shape:
+          //   - time mode → fired
+          //   - event mode + expired → timeout
+          // (Event-mode "fired by signal" goes through the bus listener in
+          // Phase 3, not the poller. The poller only handles overdue rows.)
+          const kind: "fired" | "timeout" = wait.mode === "time" ? "fired" : "timeout";
+          await resumeWaitState(wait.id, kind, undefined, registry);
+        } catch (err) {
+          console.error(`[workflows] Wait poller failed for wait ${wait.id}:`, err);
+        }
+      }
+    } catch (err) {
+      console.error("[workflows] Wait poller tick error:", err);
+    }
+
+    // Schedule the next tick after this one completes.
+    pollerTimeout = setTimeout(poll, intervalMs);
+  }
+
+  // Start the first tick.
+  pollerTimeout = setTimeout(poll, intervalMs);
+}
+
+/** Stop the wait poller (clean shutdown). */
+export function stopWaitPoller(): void {
+  if (pollerTimeout !== null) {
+    clearTimeout(pollerTimeout);
+    pollerTimeout = null;
+  }
+}