@dudousxd/nestjs-durable-core 0.49.2 → 0.49.4

package/dist/index.d.cts

@@ -330,6 +330,27 @@ interface WorkflowRun {
     createdAt: Date;
     updatedAt: Date;
 }
+/**
+ * WHAT an event-parked suspended run is waiting on, resolved for display — the engine keeps one
+ * generic `suspended` status (it's what drives recovery/timers/queries), but to a human "waiting on
+ * signal `approve`" reads very differently from "waiting on webhook `stripe-cb`". Computed by the
+ * store-backed gateway from the run's signal waiters (`listSignalWaiters`, ONE bulk scan), so the
+ * dashboard can NAME the wait in a list row without fetching each run's timeline. `on` is derived from
+ * the waiter token's prefix (see `classifyWaiterToken`): `wh:<runId>:<seq>` ⇒ `webhook`, `child:<id>`
+ * ⇒ `child`, `event:<name>:…` ⇒ `signal` (name decoded), anything else ⇒ `signal` (the token IS the
+ * signal name).
+ *
+ * Deliberately EVENT-only (no timer/step): `wakeAt` alone can't tell a real `ctx.sleep` from the
+ * reconcile-fallback `wakeAt` an event/step suspend now carries, and the store exposes no cheap bulk
+ * checkpoint scan to disambiguate — so the client shows a non-event suspend with a live worker as
+ * `running` (it flips off "no worker" the moment a worker returns) rather than guessing "sleeping".
+ * The detail view (which has the timeline) still distinguishes sleep vs in-flight step precisely.
+ */
+interface RunWaiting {
+    on: 'signal' | 'webhook' | 'child';
+    /** The token/name the run is parked on — the signal name, webhook token, or awaited child id. */
+    name: string;
+}
 type StepKind = 'local' | 'remote' | 'sleep' | 'signal';
 /**
  * The recorded result of a single step at a deterministic logical position (`seq`).
@@ -709,6 +730,9 @@ type RunRequestKind = {
     kind: 'retryWithInput';
     runId: string;
     input: unknown;
+} | {
+    kind: 'redispatch';
+    runId: string;
 };
 /** The control plane's answer to a {@link RunRequest}, correlated by `requestId`. */
 interface RunReply {
@@ -1797,6 +1821,27 @@ interface WorkflowEngineDeps {
      * for a genuinely-orphaned run. Default 5min; set `0` to disable (the prior wake-forever behavior).
      */
     reconcileMs?: number | undefined;
+    /**
+     * Opt-in self-heal window (ms) for a remote step with NO `timeoutMs` whose dispatched job was LOST —
+     * the worker crashed mid-step leaving no result, or the transport dropped the job (a Redis
+     * flush/eviction, or BullMQ moving a stalled job to `failed` and removing it). The `pending`
+     * checkpoint then has no result to resume on, and — BY DESIGN (see {@link reconcileMs}) — the
+     * reconcile re-drive re-suspends a still-pending step rather than re-dispatching, so a slow-but-live
+     * worker is never double-run. That safety means a genuinely-lost dispatch would otherwise hang
+     * forever. When set, a reconcile re-drive that finds a remote step still `pending` PAST this window
+     * re-dispatches it (bumping `attempts`, bounded by {@link remoteRedispatchMax}). Off by default:
+     * re-dispatch can double-run a step whose original job is merely slow, so the window MUST exceed the
+     * longest such step and the step MUST be idempotent. Prefer a per-step `timeoutMs` (tighter,
+     * heartbeat-aware) where you can; this is the store-driven net for no-timeout steps that must
+     * survive a lost dispatch. {@link WorkflowEngine.redispatchPending} is the manual counterpart.
+     */
+    remoteRedispatchMs?: number | undefined;
+    /**
+     * Max times {@link remoteRedispatchMs} re-dispatches one lost remote step before giving up and
+     * failing it as a {@link RemoteStepError} (`code: 'remote_step_lost'`), so the run fails / dead-letters
+     * instead of re-dispatching forever. Default 10. Ignored when `remoteRedispatchMs` is unset.
+     */
+    remoteRedispatchMax?: number | undefined;
     /**
      * Build the public callback URL for a `ctx.webhook()` token (e.g.
      * ``(t) => `https://api.example.com/durable/webhooks/${t}` ``). Populates
@@ -1873,6 +1918,8 @@ declare class WorkflowEngine {
     private readonly maxRecoveryAttempts?;
     private readonly remoteAdvanceSilenceMs?;
     private readonly reconcileMs;
+    private readonly remoteRedispatchMs;
+    private readonly remoteRedispatchMax;
     private readonly webhookUrl?;
     private readonly traceparent?;
     private readonly context?;
@@ -2165,6 +2212,19 @@ declare class WorkflowEngine {
      * the HTTP request on workflow execution.
      */
     requeue(runId: string): Promise<RunResult | null>;
+    /**
+     * Explicitly re-dispatch every remote step of `runId` stuck `pending` — the OPERATOR escape hatch for
+     * a run whose dispatched step job was LOST (worker crashed with no result, or a transport that dropped
+     * the job). No automatic recovery re-drives these: a reconcile re-drive re-suspends a still-pending
+     * step by design (unless `remoteRedispatchMs` is set), `recoverIncomplete` only reclaims LEASED runs,
+     * and `requeue` just replays back to the pending guard. This re-enqueues the same `stepId` so the
+     * (idempotent) step re-runs and its result resumes the run. Safe to call on a healthy run — it re-runs
+     * only in-flight `pending` remote steps, which are idempotent by the durable contract. Returns the
+     * run's current status (with the count re-dispatched), or null if the run is unknown.
+     */
+    redispatchPending(runId: string): Promise<(RunResult & {
+        redispatched: number;
+    }) | null>;
     /**
      * **Fix-and-replay**: re-run a run (typically a `dead`/`failed` one) with a corrected `input`, as a
      * fresh run with clean history. It's a NEW run — `newRunId` defaults to `<runId>~retry~<uuid>` — so
@@ -2467,6 +2527,10 @@ declare class WorkflowEngine {
      */
     update(runId: string, name: string, arg: unknown): Promise<UpdateResult>;
     private callRemote;
+    /** Enqueue a remote step task to its worker group via the transport pool. Shared by the initial
+     *  dispatch, the opt-in self-heal re-dispatch (see `remoteRedispatchMs`), and the explicit
+     *  {@link redispatchPending}. Carries the current trace/context so a re-dispatch is traceable. */
+    private dispatchRemoteTask;
     /**
      * Complete a durable remote step from its worker result and resume the run — runs on whichever
      * instance receives the result (the dispatching one may be gone), so the run is crash/scale-safe.
@@ -2753,6 +2817,13 @@ declare class RemoteWorkflowExecutor implements WorkflowExecutor {
     dispatch(run: WorkflowRun, history: HistoryEvent[], taskId: string, pendingSignals?: WorkflowTask['pendingSignals']): Promise<void>;
 }
 
+/** A run as returned by the gateway's list — the durable run plus an optional {@link RunWaiting}
+ *  descriptor the control plane resolves (what a suspended run is parked on), so the dashboard can
+ *  name the wait in a list row without fetching each run's timeline. Additive: `waiting` is absent
+ *  on a non-parked run and on gateways/versions that don't compute it. */
+type RunListItem = WorkflowRun & {
+    waiting?: RunWaiting | undefined;
+};
 /** Which durable topology a gateway speaks for — surfaced in the dashboard so an operator can tell a
  *  control plane from a tenant at a glance (the store-backed gateway is the operator; the proxy is a
  *  tenant). Cheap, synchronous, local knowledge — no round-trip. */
@@ -2780,7 +2851,10 @@ interface RunGateway {
     /** This deployment's durable role (control plane vs tenant) — synchronous local metadata. */
     topology(): DurableTopology;
     getRunDetail(runId: string): Promise<RunDetail | null>;
-    listRuns(query: RunQuery): Promise<WorkflowRun[]>;
+    /** List runs, each optionally carrying a {@link RunWaiting} descriptor (what a suspended run is
+     *  parked on). The store-backed gateway resolves `waiting`; a proxy relays whatever the control
+     *  plane sent. */
+    listRuns(query: RunQuery): Promise<RunListItem[]>;
     /** Per-group worker health (queue backlog + live worker heartbeats). On the control plane this is
      *  every group; over a tenant proxy the operator scopes it to the tenant's own groups. */
     workerHealth(): Promise<GroupHealth[]>;
@@ -2789,6 +2863,12 @@ interface RunGateway {
     }): Promise<RunResult | null>;
     retry(runId: string): Promise<RunResult | null>;
     continue(runId: string): Promise<RunResult | null>;
+    /** Re-dispatch every remote step of a run stuck `pending` — the operator recovery for a LOST step
+     *  dispatch (crashed worker / dropped job) that no automatic path re-drives. Returns the run's status
+     *  plus how many steps were re-dispatched, or null if the run is unknown. */
+    redispatchPending(runId: string): Promise<(RunResult & {
+        redispatched: number;
+    }) | null>;
     retryWithInput(runId: string, input: unknown): Promise<{
         runId: string;
     } | null>;
@@ -2796,6 +2876,25 @@ interface RunGateway {
     subscribe(runId: string, onEvent: (event: EngineEvent) => void): () => void;
 }
 
+/**
+ * Resolve WHAT a suspended run is parked on from the token of the {@link SignalWaiter} it registered.
+ * The token prefix carries the kind — no extra store lookup and no new persisted field. Used by the
+ * store-backed run gateway to stamp {@link RunWaiting} onto each listed run so the dashboard can name
+ * the wait in a row without fetching that run's timeline.
+ */
+declare function classifyWaiterToken(token: string): RunWaiting;
+/**
+ * Resolve a suspended run's {@link RunWaiting} from the pending signal waiters (indexed by `runId`).
+ * Event-only by design (see {@link RunWaiting}): a `waitForSignal`/`waitForEvent`/webhook/awaited-child
+ * suspend registers a waiter and gets named here; every other suspend (a bare `ctx.sleep`, an in-flight
+ * remote step, a reconcile-parked orphan) returns `undefined`, so the client layers its own display
+ * state (no-worker, singleton, running) on top — none of which can be told apart from `wakeAt` alone.
+ */
+declare function resolveRunWaiting(run: WorkflowRun, waiterByRun: ReadonlyMap<string, SignalWaiter>): RunWaiting | undefined;
+/** Index signal waiters by `runId`, keeping the first seen per run (a run parks on one waiter at a
+ *  time in the sequential case; the earliest is the one it's blocked on). */
+declare function indexWaitersByRun(waiters: readonly SignalWaiter[]): Map<string, SignalWaiter>;
+
 /**
  * Transforms a payload value as it crosses the store boundary — e.g. encrypt-at-rest, compress, or
  * redact PII. `decode` must be the exact inverse of `encode`. Both are synchronous (use a local
@@ -2859,6 +2958,9 @@ declare class CodecStateStore implements StateStore {
 declare function eventPrefix(name: string): string;
 /** Build the unique waiter token for one `waitForEvent` call (name + match + run position). */
 declare function eventToken(name: string, match: Record<string, unknown> | undefined, runId: string, seq: number): string;
+/** The event name embedded in an event waiter token (the 2nd `:`-segment is the base64 name), so a
+ *  dashboard can show "waiting on event `<name>`" instead of the opaque token. */
+declare function eventNameOf(token: string): string;
 /** The match criteria embedded in an event waiter token (the 3rd `:`-segment is the base64 match). */
 declare function eventMatchOf(token: string): Record<string, unknown>;
 /** Whether `payload` satisfies a waiter's `match`: every match key deep-equals the payload's value. */
@@ -3173,4 +3275,4 @@ declare class InMemoryTransport implements Transport, ControlPlane {
     onControl(handler: (msg: ControlMessage) => void): void;
 }
 
-export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AttributeFilter, type AttributeOp, type BackoffStrategy, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type DurableTopology, type DurableWebhook, DurableWorkflow, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type MetricsCollector, type MetricsSnapshot, type NamedTransport, NonDeterminismError, type PayloadCodec, type QueueConfig, QueueController, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RunAttributeRow, type RunDetail, type RunDispatcher, type RunGateway, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunStatus, STATE_STORE, STATE_STORE_CANONICAL, type ScheduledWorkflow, type SearchAttributes, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StartOptions, type StartRunMessage, type StateStore, type StepCheckpoint, type StepConfig, type StepDef, type StepDispatchOpts, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepRef, type StepResult, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerHeartbeat, type WorkerStatus, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, bindWorkflowClass, breakpointToken, collectMetrics, createStepLogger, currentWorkflowCtx, eventMatchOf, eventMatches, eventPrefix, eventToken, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, runInWorkflowCtx, runSchedules, runStepHandler, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, tenantGroup, workflowName };
+export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AttributeFilter, type AttributeOp, type BackoffStrategy, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type DurableTopology, type DurableWebhook, DurableWorkflow, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type MetricsCollector, type MetricsSnapshot, type NamedTransport, NonDeterminismError, type PayloadCodec, type QueueConfig, QueueController, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RunAttributeRow, type RunDetail, type RunDispatcher, type RunGateway, type RunListItem, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunStatus, type RunWaiting, STATE_STORE, STATE_STORE_CANONICAL, type ScheduledWorkflow, type SearchAttributes, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StartOptions, type StartRunMessage, type StateStore, type StepCheckpoint, type StepConfig, type StepDef, type StepDispatchOpts, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepRef, type StepResult, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerHeartbeat, type WorkerStatus, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, bindWorkflowClass, breakpointToken, classifyWaiterToken, collectMetrics, createStepLogger, currentWorkflowCtx, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, indexWaitersByRun, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, resolveRunWaiting, runInWorkflowCtx, runSchedules, runStepHandler, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, tenantGroup, workflowName };

package/dist/index.d.ts

@@ -330,6 +330,27 @@ interface WorkflowRun {
     createdAt: Date;
     updatedAt: Date;
 }
+/**
+ * WHAT an event-parked suspended run is waiting on, resolved for display — the engine keeps one
+ * generic `suspended` status (it's what drives recovery/timers/queries), but to a human "waiting on
+ * signal `approve`" reads very differently from "waiting on webhook `stripe-cb`". Computed by the
+ * store-backed gateway from the run's signal waiters (`listSignalWaiters`, ONE bulk scan), so the
+ * dashboard can NAME the wait in a list row without fetching each run's timeline. `on` is derived from
+ * the waiter token's prefix (see `classifyWaiterToken`): `wh:<runId>:<seq>` ⇒ `webhook`, `child:<id>`
+ * ⇒ `child`, `event:<name>:…` ⇒ `signal` (name decoded), anything else ⇒ `signal` (the token IS the
+ * signal name).
+ *
+ * Deliberately EVENT-only (no timer/step): `wakeAt` alone can't tell a real `ctx.sleep` from the
+ * reconcile-fallback `wakeAt` an event/step suspend now carries, and the store exposes no cheap bulk
+ * checkpoint scan to disambiguate — so the client shows a non-event suspend with a live worker as
+ * `running` (it flips off "no worker" the moment a worker returns) rather than guessing "sleeping".
+ * The detail view (which has the timeline) still distinguishes sleep vs in-flight step precisely.
+ */
+interface RunWaiting {
+    on: 'signal' | 'webhook' | 'child';
+    /** The token/name the run is parked on — the signal name, webhook token, or awaited child id. */
+    name: string;
+}
 type StepKind = 'local' | 'remote' | 'sleep' | 'signal';
 /**
  * The recorded result of a single step at a deterministic logical position (`seq`).
@@ -709,6 +730,9 @@ type RunRequestKind = {
     kind: 'retryWithInput';
     runId: string;
     input: unknown;
+} | {
+    kind: 'redispatch';
+    runId: string;
 };
 /** The control plane's answer to a {@link RunRequest}, correlated by `requestId`. */
 interface RunReply {
@@ -1797,6 +1821,27 @@ interface WorkflowEngineDeps {
      * for a genuinely-orphaned run. Default 5min; set `0` to disable (the prior wake-forever behavior).
      */
     reconcileMs?: number | undefined;
+    /**
+     * Opt-in self-heal window (ms) for a remote step with NO `timeoutMs` whose dispatched job was LOST —
+     * the worker crashed mid-step leaving no result, or the transport dropped the job (a Redis
+     * flush/eviction, or BullMQ moving a stalled job to `failed` and removing it). The `pending`
+     * checkpoint then has no result to resume on, and — BY DESIGN (see {@link reconcileMs}) — the
+     * reconcile re-drive re-suspends a still-pending step rather than re-dispatching, so a slow-but-live
+     * worker is never double-run. That safety means a genuinely-lost dispatch would otherwise hang
+     * forever. When set, a reconcile re-drive that finds a remote step still `pending` PAST this window
+     * re-dispatches it (bumping `attempts`, bounded by {@link remoteRedispatchMax}). Off by default:
+     * re-dispatch can double-run a step whose original job is merely slow, so the window MUST exceed the
+     * longest such step and the step MUST be idempotent. Prefer a per-step `timeoutMs` (tighter,
+     * heartbeat-aware) where you can; this is the store-driven net for no-timeout steps that must
+     * survive a lost dispatch. {@link WorkflowEngine.redispatchPending} is the manual counterpart.
+     */
+    remoteRedispatchMs?: number | undefined;
+    /**
+     * Max times {@link remoteRedispatchMs} re-dispatches one lost remote step before giving up and
+     * failing it as a {@link RemoteStepError} (`code: 'remote_step_lost'`), so the run fails / dead-letters
+     * instead of re-dispatching forever. Default 10. Ignored when `remoteRedispatchMs` is unset.
+     */
+    remoteRedispatchMax?: number | undefined;
     /**
      * Build the public callback URL for a `ctx.webhook()` token (e.g.
      * ``(t) => `https://api.example.com/durable/webhooks/${t}` ``). Populates
@@ -1873,6 +1918,8 @@ declare class WorkflowEngine {
     private readonly maxRecoveryAttempts?;
     private readonly remoteAdvanceSilenceMs?;
     private readonly reconcileMs;
+    private readonly remoteRedispatchMs;
+    private readonly remoteRedispatchMax;
     private readonly webhookUrl?;
     private readonly traceparent?;
     private readonly context?;
@@ -2165,6 +2212,19 @@ declare class WorkflowEngine {
      * the HTTP request on workflow execution.
      */
     requeue(runId: string): Promise<RunResult | null>;
+    /**
+     * Explicitly re-dispatch every remote step of `runId` stuck `pending` — the OPERATOR escape hatch for
+     * a run whose dispatched step job was LOST (worker crashed with no result, or a transport that dropped
+     * the job). No automatic recovery re-drives these: a reconcile re-drive re-suspends a still-pending
+     * step by design (unless `remoteRedispatchMs` is set), `recoverIncomplete` only reclaims LEASED runs,
+     * and `requeue` just replays back to the pending guard. This re-enqueues the same `stepId` so the
+     * (idempotent) step re-runs and its result resumes the run. Safe to call on a healthy run — it re-runs
+     * only in-flight `pending` remote steps, which are idempotent by the durable contract. Returns the
+     * run's current status (with the count re-dispatched), or null if the run is unknown.
+     */
+    redispatchPending(runId: string): Promise<(RunResult & {
+        redispatched: number;
+    }) | null>;
     /**
      * **Fix-and-replay**: re-run a run (typically a `dead`/`failed` one) with a corrected `input`, as a
      * fresh run with clean history. It's a NEW run — `newRunId` defaults to `<runId>~retry~<uuid>` — so
@@ -2467,6 +2527,10 @@ declare class WorkflowEngine {
      */
     update(runId: string, name: string, arg: unknown): Promise<UpdateResult>;
     private callRemote;
+    /** Enqueue a remote step task to its worker group via the transport pool. Shared by the initial
+     *  dispatch, the opt-in self-heal re-dispatch (see `remoteRedispatchMs`), and the explicit
+     *  {@link redispatchPending}. Carries the current trace/context so a re-dispatch is traceable. */
+    private dispatchRemoteTask;
     /**
      * Complete a durable remote step from its worker result and resume the run — runs on whichever
      * instance receives the result (the dispatching one may be gone), so the run is crash/scale-safe.
@@ -2753,6 +2817,13 @@ declare class RemoteWorkflowExecutor implements WorkflowExecutor {
     dispatch(run: WorkflowRun, history: HistoryEvent[], taskId: string, pendingSignals?: WorkflowTask['pendingSignals']): Promise<void>;
 }
 
+/** A run as returned by the gateway's list — the durable run plus an optional {@link RunWaiting}
+ *  descriptor the control plane resolves (what a suspended run is parked on), so the dashboard can
+ *  name the wait in a list row without fetching each run's timeline. Additive: `waiting` is absent
+ *  on a non-parked run and on gateways/versions that don't compute it. */
+type RunListItem = WorkflowRun & {
+    waiting?: RunWaiting | undefined;
+};
 /** Which durable topology a gateway speaks for — surfaced in the dashboard so an operator can tell a
  *  control plane from a tenant at a glance (the store-backed gateway is the operator; the proxy is a
  *  tenant). Cheap, synchronous, local knowledge — no round-trip. */
@@ -2780,7 +2851,10 @@ interface RunGateway {
     /** This deployment's durable role (control plane vs tenant) — synchronous local metadata. */
     topology(): DurableTopology;
     getRunDetail(runId: string): Promise<RunDetail | null>;
-    listRuns(query: RunQuery): Promise<WorkflowRun[]>;
+    /** List runs, each optionally carrying a {@link RunWaiting} descriptor (what a suspended run is
+     *  parked on). The store-backed gateway resolves `waiting`; a proxy relays whatever the control
+     *  plane sent. */
+    listRuns(query: RunQuery): Promise<RunListItem[]>;
     /** Per-group worker health (queue backlog + live worker heartbeats). On the control plane this is
      *  every group; over a tenant proxy the operator scopes it to the tenant's own groups. */
     workerHealth(): Promise<GroupHealth[]>;
@@ -2789,6 +2863,12 @@ interface RunGateway {
     }): Promise<RunResult | null>;
     retry(runId: string): Promise<RunResult | null>;
     continue(runId: string): Promise<RunResult | null>;
+    /** Re-dispatch every remote step of a run stuck `pending` — the operator recovery for a LOST step
+     *  dispatch (crashed worker / dropped job) that no automatic path re-drives. Returns the run's status
+     *  plus how many steps were re-dispatched, or null if the run is unknown. */
+    redispatchPending(runId: string): Promise<(RunResult & {
+        redispatched: number;
+    }) | null>;
     retryWithInput(runId: string, input: unknown): Promise<{
         runId: string;
     } | null>;
@@ -2796,6 +2876,25 @@ interface RunGateway {
     subscribe(runId: string, onEvent: (event: EngineEvent) => void): () => void;
 }
 
+/**
+ * Resolve WHAT a suspended run is parked on from the token of the {@link SignalWaiter} it registered.
+ * The token prefix carries the kind — no extra store lookup and no new persisted field. Used by the
+ * store-backed run gateway to stamp {@link RunWaiting} onto each listed run so the dashboard can name
+ * the wait in a row without fetching that run's timeline.
+ */
+declare function classifyWaiterToken(token: string): RunWaiting;
+/**
+ * Resolve a suspended run's {@link RunWaiting} from the pending signal waiters (indexed by `runId`).
+ * Event-only by design (see {@link RunWaiting}): a `waitForSignal`/`waitForEvent`/webhook/awaited-child
+ * suspend registers a waiter and gets named here; every other suspend (a bare `ctx.sleep`, an in-flight
+ * remote step, a reconcile-parked orphan) returns `undefined`, so the client layers its own display
+ * state (no-worker, singleton, running) on top — none of which can be told apart from `wakeAt` alone.
+ */
+declare function resolveRunWaiting(run: WorkflowRun, waiterByRun: ReadonlyMap<string, SignalWaiter>): RunWaiting | undefined;
+/** Index signal waiters by `runId`, keeping the first seen per run (a run parks on one waiter at a
+ *  time in the sequential case; the earliest is the one it's blocked on). */
+declare function indexWaitersByRun(waiters: readonly SignalWaiter[]): Map<string, SignalWaiter>;
+
 /**
  * Transforms a payload value as it crosses the store boundary — e.g. encrypt-at-rest, compress, or
  * redact PII. `decode` must be the exact inverse of `encode`. Both are synchronous (use a local
@@ -2859,6 +2958,9 @@ declare class CodecStateStore implements StateStore {
 declare function eventPrefix(name: string): string;
 /** Build the unique waiter token for one `waitForEvent` call (name + match + run position). */
 declare function eventToken(name: string, match: Record<string, unknown> | undefined, runId: string, seq: number): string;
+/** The event name embedded in an event waiter token (the 2nd `:`-segment is the base64 name), so a
+ *  dashboard can show "waiting on event `<name>`" instead of the opaque token. */
+declare function eventNameOf(token: string): string;
 /** The match criteria embedded in an event waiter token (the 3rd `:`-segment is the base64 match). */
 declare function eventMatchOf(token: string): Record<string, unknown>;
 /** Whether `payload` satisfies a waiter's `match`: every match key deep-equals the payload's value. */
@@ -3173,4 +3275,4 @@ declare class InMemoryTransport implements Transport, ControlPlane {
     onControl(handler: (msg: ControlMessage) => void): void;
 }
 
-export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AttributeFilter, type AttributeOp, type BackoffStrategy, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type DurableTopology, type DurableWebhook, DurableWorkflow, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type MetricsCollector, type MetricsSnapshot, type NamedTransport, NonDeterminismError, type PayloadCodec, type QueueConfig, QueueController, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RunAttributeRow, type RunDetail, type RunDispatcher, type RunGateway, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunStatus, STATE_STORE, STATE_STORE_CANONICAL, type ScheduledWorkflow, type SearchAttributes, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StartOptions, type StartRunMessage, type StateStore, type StepCheckpoint, type StepConfig, type StepDef, type StepDispatchOpts, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepRef, type StepResult, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerHeartbeat, type WorkerStatus, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, bindWorkflowClass, breakpointToken, collectMetrics, createStepLogger, currentWorkflowCtx, eventMatchOf, eventMatches, eventPrefix, eventToken, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, runInWorkflowCtx, runSchedules, runStepHandler, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, tenantGroup, workflowName };
+export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AttributeFilter, type AttributeOp, type BackoffStrategy, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type DurableTopology, type DurableWebhook, DurableWorkflow, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type MetricsCollector, type MetricsSnapshot, type NamedTransport, NonDeterminismError, type PayloadCodec, type QueueConfig, QueueController, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RunAttributeRow, type RunDetail, type RunDispatcher, type RunGateway, type RunListItem, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunStatus, type RunWaiting, STATE_STORE, STATE_STORE_CANONICAL, type ScheduledWorkflow, type SearchAttributes, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StartOptions, type StartRunMessage, type StateStore, type StepCheckpoint, type StepConfig, type StepDef, type StepDispatchOpts, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepRef, type StepResult, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerHeartbeat, type WorkerStatus, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, bindWorkflowClass, breakpointToken, classifyWaiterToken, collectMetrics, createStepLogger, currentWorkflowCtx, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, indexWaitersByRun, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, resolveRunWaiting, runInWorkflowCtx, runSchedules, runStepHandler, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, tenantGroup, workflowName };

package/dist/index.js

@@ -780,6 +780,14 @@ function eventToken(name, match, runId, seq) {
   return `${eventPrefix(name)}${enc(JSON.stringify(match ?? {}))}:${runId}#${seq}`;
 }
 __name(eventToken, "eventToken");
+function eventNameOf(token) {
+  try {
+    return dec(token.split(":")[1] ?? "");
+  } catch {
+    return token;
+  }
+}
+__name(eventNameOf, "eventNameOf");
 function eventMatchOf(token) {
   try {
     return JSON.parse(dec(token.split(":")[2] ?? ""));
@@ -1721,6 +1729,8 @@ var WorkflowEngine = class {
   maxRecoveryAttempts;
   remoteAdvanceSilenceMs;
   reconcileMs;
+  remoteRedispatchMs;
+  remoteRedispatchMax;
   webhookUrl;
   traceparent;
   context;
@@ -1792,6 +1802,8 @@ var WorkflowEngine = class {
     this.maxRecoveryAttempts = deps.maxRecoveryAttempts;
     this.remoteAdvanceSilenceMs = deps.remoteAdvanceSilenceMs;
     this.reconcileMs = deps.reconcileMs === void 0 ? 3e5 : deps.reconcileMs || void 0;
+    this.remoteRedispatchMs = deps.remoteRedispatchMs || void 0;
+    this.remoteRedispatchMax = Math.max(1, deps.remoteRedispatchMax ?? 10);
     this.webhookUrl = deps.webhookUrl;
     this.traceparent = deps.traceparent;
     this.context = deps.context;
@@ -2503,6 +2515,49 @@ var WorkflowEngine = class {
     };
   }
   /**
+  * Explicitly re-dispatch every remote step of `runId` stuck `pending` — the OPERATOR escape hatch for
+  * a run whose dispatched step job was LOST (worker crashed with no result, or a transport that dropped
+  * the job). No automatic recovery re-drives these: a reconcile re-drive re-suspends a still-pending
+  * step by design (unless `remoteRedispatchMs` is set), `recoverIncomplete` only reclaims LEASED runs,
+  * and `requeue` just replays back to the pending guard. This re-enqueues the same `stepId` so the
+  * (idempotent) step re-runs and its result resumes the run. Safe to call on a healthy run — it re-runs
+  * only in-flight `pending` remote steps, which are idempotent by the durable contract. Returns the
+  * run's current status (with the count re-dispatched), or null if the run is unknown.
+  */
+  async redispatchPending(runId) {
+    const run = await this.store.getRun(runId);
+    if (!run) return null;
+    const pending = (await this.store.listCheckpoints(runId)).filter((cp) => cp.kind === "remote" && cp.status === "pending");
+    let redispatched = 0;
+    for (const cp of pending) {
+      if (!cp.stepId) continue;
+      const reAttempt = cp.attempts + 1;
+      const reEnqueuedAt = /* @__PURE__ */ new Date();
+      await this.store.saveCheckpoint({
+        ...cp,
+        attempts: reAttempt,
+        enqueuedAt: reEnqueuedAt,
+        startedAt: reEnqueuedAt,
+        finishedAt: reEnqueuedAt
+      });
+      await this.dispatchRemoteTask({
+        runId,
+        seq: cp.seq,
+        name: cp.name,
+        stepId: cp.stepId,
+        group: cp.workerGroup ?? sanitizeQueueToken(cp.name),
+        input: cp.input,
+        attempt: reAttempt
+      });
+      redispatched += 1;
+    }
+    return {
+      runId,
+      status: run.status,
+      redispatched
+    };
+  }
+  /**
   * **Fix-and-replay**: re-run a run (typically a `dead`/`failed` one) with a corrected `input`, as a
   * fresh run with clean history. It's a NEW run — `newRunId` defaults to `<runId>~retry~<uuid>` — so
   * the original stays inspectable. Returns the new run's id, or null if `runId` is unknown.
@@ -3990,7 +4045,47 @@ var WorkflowEngine = class {
     if (existing?.status === "completed") return existing.output;
     if (this.pool.size === 0) throw new Error("remote steps require a Transport");
     if (step.timeoutMs) return this.callRemoteInMemory(runId, seq, step, input, transport);
-    if (existing?.status === "pending") throw new WorkflowSuspended();
+    if (existing?.status === "pending") {
+      if (this.remoteRedispatchMs == null) throw new WorkflowSuspended();
+      if (existing.wakeAt == null) {
+        const wakeAt = this.clock() + this.remoteRedispatchMs;
+        await this.store.saveCheckpoint({
+          ...existing,
+          wakeAt
+        });
+        throw new WorkflowSuspended(wakeAt);
+      }
+      if (this.clock() < existing.wakeAt) throw new WorkflowSuspended(existing.wakeAt);
+      if (existing.attempts >= this.remoteRedispatchMax) {
+        throw new RemoteStepError({
+          message: `remote step "${step.name}" lost \u2014 no result after ${existing.attempts} re-dispatch(es)`,
+          code: "remote_step_lost"
+        });
+      }
+      const reAttempt = existing.attempts + 1;
+      const nextDeadline = this.clock() + this.remoteRedispatchMs;
+      const reEnqueuedAt = /* @__PURE__ */ new Date();
+      await this.store.saveCheckpoint({
+        ...existing,
+        attempts: reAttempt,
+        wakeAt: nextDeadline,
+        enqueuedAt: reEnqueuedAt,
+        startedAt: reEnqueuedAt,
+        finishedAt: reEnqueuedAt
+      });
+      await this.dispatchRemoteTask({
+        runId,
+        seq,
+        name: step.name,
+        stepId: existing.stepId ?? stepId(runId, seq),
+        group: existing.workerGroup ?? tenantGroup(sanitizeQueueToken(step.name), step.partition),
+        input: existing.input,
+        priority: admission?.priority,
+        attempt: reAttempt,
+        transport
+      });
+      throw new WorkflowSuspended(nextDeadline);
+    }
     let attempt = 1;
     if (existing?.status === "failed") {
       const maxAttempts = Math.max(1, step.retries ?? 1);
@@ -4038,18 +4133,17 @@ var WorkflowEngine = class {
       startedAt: enqueuedAt,
       finishedAt: enqueuedAt
     });
-    await this.pool.dispatch({
+    await this.dispatchRemoteTask({
       runId,
       seq,
       name: step.name,
       stepId: id,
       group: tenantGroup(sanitizeQueueToken(step.name), step.partition),
       input,
-      traceparent: this.traceparent?.(),
-      context: this.context?.(),
       priority: admission?.priority,
-      attempt
-    }, transport);
+      attempt,
+      transport
+    });
     this.emit({
       type: "step.started",
       runId,
@@ -4059,6 +4153,23 @@ var WorkflowEngine = class {
     });
     throw new WorkflowSuspended();
   }
+  /** Enqueue a remote step task to its worker group via the transport pool. Shared by the initial
+  *  dispatch, the opt-in self-heal re-dispatch (see `remoteRedispatchMs`), and the explicit
+  *  {@link redispatchPending}. Carries the current trace/context so a re-dispatch is traceable. */
+  dispatchRemoteTask(task) {
+    return this.pool.dispatch({
+      runId: task.runId,
+      seq: task.seq,
+      name: task.name,
+      stepId: task.stepId,
+      group: task.group,
+      input: task.input,
+      traceparent: this.traceparent?.(),
+      context: this.context?.(),
+      priority: task.priority,
+      attempt: task.attempt
+    }, task.transport);
+  }
   /**
   * Complete a durable remote step from its worker result and resume the run — runs on whichever
   * instance receives the result (the dispatching one may be gone), so the run is crash/scale-safe.
@@ -4295,6 +4406,42 @@ var TERMINAL_RUN_STATUSES = [
   "dead"
 ];
 
+// src/run-waiting.ts
+var WEBHOOK_PREFIX = "wh:";
+var CHILD_PREFIX = "child:";
+var EVENT_PREFIX = "event:";
+function classifyWaiterToken(token) {
+  if (token.startsWith(WEBHOOK_PREFIX)) return {
+    on: "webhook",
+    name: token
+  };
+  if (token.startsWith(CHILD_PREFIX)) return {
+    on: "child",
+    name: token.slice(CHILD_PREFIX.length)
+  };
+  if (token.startsWith(EVENT_PREFIX)) return {
+    on: "signal",
+    name: eventNameOf(token)
+  };
+  return {
+    on: "signal",
+    name: token
+  };
+}
+__name(classifyWaiterToken, "classifyWaiterToken");
+function resolveRunWaiting(run, waiterByRun) {
+  if (run.status !== "suspended") return void 0;
+  const waiter = waiterByRun.get(run.id);
+  return waiter ? classifyWaiterToken(waiter.token) : void 0;
+}
+__name(resolveRunWaiting, "resolveRunWaiting");
+function indexWaitersByRun(waiters) {
+  const byRun = /* @__PURE__ */ new Map();
+  for (const w of waiters) if (!byRun.has(w.runId)) byRun.set(w.runId, w);
+  return byRun;
+}
+__name(indexWaitersByRun, "indexWaitersByRun");
+
 // src/codec-state-store.ts
 var CodecStateStore = class {
   static {
@@ -5049,17 +5196,21 @@ export {
   attributeOperand,
   bindWorkflowClass,
   breakpointToken,
+  classifyWaiterToken,
   collectMetrics,
   createStepLogger,
   currentWorkflowCtx,
   eventMatchOf,
   eventMatches,
+  eventNameOf,
   eventPrefix,
   eventToken,
+  indexWaitersByRun,
   matchesAttributes,
   normalizeAttributeRows,
   parseDuration,
   prevCronFireMs,
+  resolveRunWaiting,
   runInWorkflowCtx,
   runSchedules,
   runStepHandler,