@xyne/workflow-sdk 3.2.5 → 3.2.7

package/dist/engine/workflow-executor.js

@@ -2,18 +2,41 @@ import { CONTROL_FLOW_STEP_TYPES } from '../types/known-types.js';
 import { BaseActionStep, BaseControlFlowStep, StepKind, createPauseFunction, } from '../steps/base-step.js';
 import { VariableResolver, stripNullForOptionalKeys, coerceResolvedToSchema } from './variable-resolver.js';
 import { PauseStep } from './pause-step.js';
+import { recordKey, framePrefix } from './node-path.js';
 const noopLogger = {
     info: () => { },
     warn: () => { },
     error: () => { },
 };
+/** Internal signal: a review-gate `abort` reached the walk → cancel the run. */
+class AbortExecution extends Error {
+}
 // ─── WorkflowExecutor ───
 /**
  * Core runtime engine for executing workflows.
  *
- * Orchestrates: step execution, variable resolution, pause/resume
- * (including inside branches), error handling (onError: continue),
- * retry, timeout, credential resolution, and state persistence.
+ * Orchestrates: step execution, variable resolution, durable pause/resume at
+ * any nesting depth (content-addressed step memoization + level-triggered
+ * reconciliation), error handling (onError: continue), retry, timeout,
+ * credential resolution, and state persistence.
+ *
+ * ## Pause/resume model
+ *
+ * Every step — top-level or nested in any control-flow branch — is keyed by a
+ * **node-path** (see `node-path.ts`). The walk always starts from the root and
+ * each step self-decides from its persisted record:
+ *
+ * - `COMPLETED` → restore output, skip (memoized; never re-executes).
+ * - `EXTERNAL_WAIT` leaf → resume via `onResume` if its record carries a
+ *   `resumePayload`, otherwise re-park (still waiting).
+ * - `REVIEW_WAIT` → apply the review decision (approve / retry / abort).
+ * - control step with `EXTERNAL_WAIT` → re-execute (re-enter its branches; the
+ *   completed branch steps memo-skip, the parked one resumes).
+ *
+ * Pausing throws to unwind — it carries no positional path, because the records
+ * hold the position. Resume = a payload written into the target node's record +
+ * re-enqueue; the next walk reconciles. N concurrent pauses, nested arbitrarily,
+ * fall out for free.
  *
  * Host provides: PersistenceAdapter, StepRegistry, TriggerRegistry,
  * ServiceRegistry, and an optional logger.
@@ -49,8 +72,9 @@ export class WorkflowExecutor {
     /**
      * Run or resume an execution by ID.
      *
-     * Loads the execution from persistence, determines if it's a fresh start
-     * or a resume, then walks through the steps.
+     * Loads the execution from persistence, preloads its step records into the
+     * memo map, then walks the steps from the root. Completed steps short-circuit
+     * from the memo; the one (or many) parked step(s) resume from their records.
      */
     async runExecution(executionId) {
         const exec = await this.persistence.getExecution(executionId);
@@ -119,98 +143,44 @@ export class WorkflowExecutor {
                 return;
             }
         }
-        // Resume: hydrate step context from persisted step rows
-        let startIndex = 0;
-        let resumeAtIndex;
-        let branchResumePath;
-        if (isResume) {
-            const stepRows = await this.persistence.getStepRows(executionId);
-            for (const row of stepRows) {
-                const idx = parseStepIndex(row.stepName);
-                if (idx === null)
-                    continue;
-                const stepConfig = config.steps[idx];
-                if (!stepConfig || !row.data)
-                    continue;
-                const parsed = safeParseJson(row.data);
-                if (parsed) {
-                    const entry = {
-                        type: parsed['type'] ?? stepConfig.type,
-                        output: parsed['output'] ?? {},
-                    };
-                    if (parsed['input'] !== undefined)
-                        entry['input'] = parsed['input'];
-                    // Preserve extra persisted fields (e.g. PARALLEL's __parallelState) so
-                    // control-flow steps can restore paused-branch progress on resume.
-                    for (const k of Object.keys(parsed)) {
-                        if (k !== 'type' && k !== 'input' && k !== 'output') {
-                            entry[k] = parsed[k];
-                        }
-                    }
-                    context.steps[stepConfig.id] =
-                        entry;
-                }
-            }
-            if (state.pauseType === 'review') {
-                // ─── Review-gate resume ───
-                const reviewedIdx = state.currentStepIndex;
-                const reviewedStep = config.steps[reviewedIdx];
-                const resumePayload = await this.persistence.getResumePayload(executionId);
-                const action = resumePayload?.action ?? 'approve';
-                if (action === 'abort') {
-                    await this.persistence.updateExecutionStatus(executionId, 'CANCELLED');
-                    this.emitEvent(executionId, { event: 'execution_cancelled', data: {} });
-                    this.log.info(`run ${executionId} review-gate ABORTED`);
-                    return;
-                }
-                if (action === 'retry' && reviewedStep) {
-                    // Re-execute the reviewed step fresh, with priorState + feedback overrides.
-                    startIndex = reviewedIdx;
-                    const priorRow = await this.persistence.getStep(executionId, `step_${String(reviewedIdx)}`);
-                    const priorState = priorRow?.data
-                        ? safeParseJson(priorRow.data) ?? undefined
-                        : undefined;
-                    context.__meta = {
-                        ...context.__meta,
-                        ...(priorState ? { __priorStepState: priorState } : {}),
-                        __configOverrides: extractConfigOverrides(resumePayload),
-                    };
-                    // Clear the entry so it re-executes (and downstream resolvers don't see stale output)
-                    delete context.steps[reviewedStep.id];
-                }
-                else {
-                    // approve: advance past the reviewed step
-                    startIndex = reviewedIdx + 1;
-                }
-            }
-            else {
-                // ─── Step-level pause resume (existing PausePath logic) ───
-                const savedPausePath = state.pausePath
-                    ? safeParseJson(state.pausePath)
-                    : null;
-                if (savedPausePath && savedPausePath.length > 0) {
-                    const first = savedPausePath[0];
-                    startIndex = first.stepIndex;
-                    resumeAtIndex = first.stepIndex;
-                    branchResumePath =
-                        savedPausePath.length > 1 ? savedPausePath.slice(1) : undefined;
-                }
-                else {
-                    startIndex = state.currentStepIndex;
-                    resumeAtIndex = state.currentStepIndex;
-                }
-            }
+        // Preload step records into the memo map. Empty for a brand-new run;
+        // seeded with COMPLETED rows for a rerun; full for a resume. The walk
+        // consults this by node-path — no positional cursor.
+        const memo = new Map();
+        const stepRows = await this.persistence.getStepRows(executionId);
+        for (const row of stepRows) {
+            memo.set(row.stepName, {
+                status: row.status,
+                data: row.data ? safeParseJson(row.data) : null,
+            });
         }
-        else {
-            // ─── Fresh-run path: check for rerunFromStep seed ───
-            const rerun = context.__meta?.rerunSource;
-            if (rerun) {
-                startIndex = rerun.fromStepIndex;
+        // The sole open gate (single non-control parked record), if any. Used for
+        // the "re-enqueue resumes the one pause" convenience and as the target for
+        // a legacy global resume payload.
+        const gateRows = stepRows.filter((r) => (r.status === 'EXTERNAL_WAIT' || r.status === 'REVIEW_WAIT') &&
+            r.executorType !== 'conditional');
+        const soleGate = gateRows.length === 1 ? gateRows[0].stepName : undefined;
+        // Back-compat bridge: a global resume payload (legacy `persistResumePayload`)
+        // is routed to the sole gate's record, so single-gate resumes that don't go
+        // through the per-node `runtime.resume()` path still work. Multi-gate runs
+        // require per-node routing (no sole gate → payload left untouched).
+        if (isResume && soleGate) {
+            const globalPayload = await this.persistence.getResumePayload(executionId);
+            if (globalPayload) {
+                const entry = memo.get(soleGate);
+                const data = { ...(entry?.data ?? {}), resumePayload: globalPayload };
+                memo.set(soleGate, { status: gateRows[0].status, data });
+                await this.persistence.upsertStep(executionId, soleGate, {
+                    status: gateRows[0].status,
+                    executorType: gateRows[0].executorType,
+                    data: JSON.stringify(data),
+                });
             }
         }
-        // Run — preserve transient seed fields (priorState, configOverrides, rerunSource)
-        // that the resume/rerun paths populated above.
+        // Preserve transient seed fields (rerun priorState/configOverrides) that
+        // the rerun path populated in __meta; reset error/chain bookkeeping.
         const prevMeta = context.__meta ?? {};
+        const entryExtrasPending = prevMeta.__priorStepState !== undefined || prevMeta.__configOverrides !== undefined;
         context.__meta = {
             ...prevMeta,
             error: null,
@@ -220,8 +190,14 @@ export class WorkflowExecutor {
         await this.persistence.persistState(executionId, {
             context: JSON.stringify(context),
         });
-        this.log.info(`run ${isResume ? 'RESUMED' : 'STARTED'} execId=${executionId} workflow=${workflow.id} startIndex=${startIndex}`);
-        await this.runSteps(executionId, context, config.steps, startIndex, resumeAtIndex, branchResumePath, config.settings);
+        this.log.info(`run ${isResume ? 'RESUMED' : 'STARTED'} execId=${executionId} workflow=${workflow.id}`);
+        await this.runWorkflow(executionId, context, config.steps, {
+            executionId,
+            memo,
+            settings: config.settings,
+            entryExtrasPending,
+            soleGate,
+        });
     }
     /**
      * Start a fresh execution for a workflow.
@@ -242,11 +218,10 @@ export class WorkflowExecutor {
      * Create a new execution that reruns from `fromStepId`, using the source
      * execution's cached outputs for all prior steps as the resolved context.
      *
-     * The new execution starts at `fromStepIndex` (not 0). Steps before that
-     * are pre-populated in `context.steps` so variable resolution finds them.
-     * The step at `fromStepIndex` receives the source row's data as
-     * `ctx.priorState` (when `inheritStepState` is true, the default), enabling
-     * agents and other stateful steps to continue from where they left off.
+     * Prior steps are written as COMPLETED records on the new execution, so the
+     * memoized walk skips them. The step at `fromStepId` receives the source
+     * row's data as `ctx.priorState` (when `inheritStepState` is true, the
+     * default), enabling agents and other stateful steps to continue.
      *
      * Returns the new execution ID. Caller is responsible for enqueueing it.
      */
@@ -275,6 +250,7 @@ export class WorkflowExecutor {
         }
         const sourceContext = JSON.parse(sourceState.context);
         // Seed the new context with the source's trigger + steps 0..N-1 outputs.
+        // Records are keyed by node-path; top-level steps key on their id.
         const seededSteps = {};
         const stepRows = await this.persistence.getStepRows(sourceExecutionId);
         const rowByName = new Map();
@@ -283,7 +259,7 @@ export class WorkflowExecutor {
         }
         for (let i = 0; i < fromStepIndex; i++) {
             const stepCfg = config.steps[i];
-            const row = rowByName.get(`step_${String(i)}`);
+            const row = rowByName.get(stepCfg.id);
             if (!row?.data)
                 continue;
             const parsed = safeParseJson(row.data);
@@ -298,7 +274,7 @@ export class WorkflowExecutor {
         // Priorstate for the entry step (the one being re-executed)
         let priorStepState;
         if (inheritStepState) {
-            const entryRow = rowByName.get(`step_${String(fromStepIndex)}`);
+            const entryRow = rowByName.get(fromStepId);
             if (entryRow?.data) {
                 priorStepState =
                     safeParseJson(entryRow.data) ?? undefined;
@@ -328,17 +304,28 @@ export class WorkflowExecutor {
             context: JSON.stringify(newContext),
             sourceExecutionId,
         });
+        // Persist prior steps as COMPLETED on the new execution so the memoized
+        // walk skips them (records are the cursor — there is no positional skip).
+        for (let i = 0; i < fromStepIndex; i++) {
+            const stepCfg = config.steps[i];
+            const entry = seededSteps[stepCfg.id];
+            if (!entry)
+                continue;
+            await this.persistence.upsertStep(newExecutionId, stepCfg.id, {
+                status: 'COMPLETED',
+                executorType: CONTROL_FLOW_STEP_TYPES.has(stepCfg.type)
+                    ? 'conditional'
+                    : 'deterministic',
+                data: JSON.stringify(entry),
+            });
+        }
         this.log.info(`rerun created exec=${newExecutionId} from=${sourceExecutionId} step=${fromStepId}`);
         return newExecutionId;
     }
     // ─── Internal: run loop ───
-    async runSteps(executionId, context, steps, startIndex, resumeAtIndex, branchResumePath, settings) {
+    async runWorkflow(executionId, context, steps, walkCtx) {
         try {
-            const walkResult = await this.walkSteps(steps, context, executionId, startIndex, resumeAtIndex, branchResumePath, settings);
-            if (walkResult.kind === 'paused') {
-                this.log.info(`run ${executionId} PAUSED at path=${JSON.stringify(walkResult.pausePath)}`);
-                return;
-            }
+            await this.walkScope(steps, context, '', walkCtx);
             await this.persistence.updateExecutionStatus(executionId, 'COMPLETED');
             context.__meta = { ...context.__meta, error: null };
             await this.persistence.persistState(executionId, {
@@ -349,6 +336,25 @@ export class WorkflowExecutor {
             this.log.info(`run ${executionId} COMPLETED`);
         }
         catch (err) {
+            if (err instanceof AbortExecution) {
+                await this.persistence.updateExecutionStatus(executionId, 'CANCELLED');
+                this.emitEvent(executionId, { event: 'execution_cancelled', data: {} });
+                this.log.info(`run ${executionId} CANCELLED (review abort)`);
+                return;
+            }
+            if (PauseStep.is(err)) {
+                // walkScope already persisted the paused step record(s). Mark the
+                // execution paused and snapshot the context (top-level outputs; branch
+                // outputs live in their path-qualified records).
+                const pauseCategory = err.pauseCategory;
+                await this.persistence.persistState(executionId, {
+                    context: JSON.stringify(context),
+                    ...(pauseCategory === 'review' ? { pauseType: 'review' } : { pauseType: 'step' }),
+                });
+                await this.persistence.updateExecutionStatus(executionId, 'EXTERNAL_WAIT');
+                this.log.info(`run ${executionId} PAUSED`);
+                return;
+            }
             const errMsg = err instanceof Error ? err.message : String(err);
             await this.persistence.updateExecutionStatus(executionId, 'FAILED');
             context.__meta = { ...context.__meta, error: errMsg };
@@ -360,185 +366,204 @@ export class WorkflowExecutor {
             throw err;
         }
     }
-    async walkSteps(steps, context, executionId, startIndex = 0, resumeAtIndex, branchResumePath, settings) {
-        const onError = settings?.onError ?? 'stop';
-        const retry = settings?.retry;
-        for (let i = startIndex; i < steps.length; i++) {
-            const step = steps[i];
-            const stepName = `step_${String(i)}`;
-            const isResuming = resumeAtIndex === i;
-            // Only pass branchResumePath for the step being resumed
-            const stepBranchResumePath = isResuming ? branchResumePath : undefined;
-            if (!isResuming) {
-                const executorType = CONTROL_FLOW_STEP_TYPES.has(step.type)
-                    ? 'conditional'
-                    : 'deterministic';
-                await this.persistence.upsertStep(executionId, stepName, {
-                    status: 'RUNNING',
-                    executorType,
-                });
+    /**
+     * Walk a scope of steps (the root scope, or one control-flow branch).
+     *
+     * `prefix` is the node-path prefix for this scope (`''` at the root, a frame
+     * prefix like `parallel_x:swot#0` inside a branch). Each step is addressed by
+     * `recordKey(prefix, step.id)`. The walk always starts from the first step;
+     * memoized records short-circuit completed steps so nothing re-executes.
+     *
+     * Throws `PauseStep` to unwind when a step (leaf or control) is parked, and
+     * `AbortExecution` on a review-gate abort. Settings-driven retry / onError
+     * apply at the root only — inside a branch, errors propagate so the enclosing
+     * control step (e.g. PARALLEL) can record them.
+     */
+    async walkScope(steps, context, prefix, walkCtx) {
+        const { executionId, memo } = walkCtx;
+        const topLevel = prefix === '';
+        const onError = topLevel ? (walkCtx.settings?.onError ?? 'stop') : 'stop';
+        const retry = topLevel ? walkCtx.settings?.retry : undefined;
+        for (const step of steps) {
+            const key = recordKey(prefix, step.id);
+            const rec = memo.get(key);
+            const stepImpl = this.stepRegistry.get(step.type);
+            const isControl = stepImpl.kind === StepKind.CONTROL;
+            const executorType = isControl ? 'conditional' : 'deterministic';
+            // 1. Memoized COMPLETED → restore output, skip (never re-executes).
+            if (rec?.status === 'COMPLETED') {
+                if (rec.data)
+                    context.steps[step.id] = entryFromData(rec.data, step.type);
+                continue;
+            }
+            // Decide the execution mode for this step from its record.
+            let resumeData;
+            let priorState;
+            let configOverrides;
+            // 2. REVIEW_WAIT — post-completion `onComplete:'review'` gate.
+            if (rec?.status === 'REVIEW_WAIT') {
+                const payload = rec.data?.['resumePayload'];
+                if (!payload) {
+                    // Still awaiting review — record unchanged, unwind.
+                    throw reviewPause(step.id);
+                }
+                const action = payload.action ?? 'approve';
+                if (action === 'abort')
+                    throw new AbortExecution();
+                if (action !== 'retry') {
+                    // approve → restore output, mark COMPLETED, advance.
+                    if (rec.data)
+                        context.steps[step.id] = entryFromData(rec.data, step.type);
+                    await this.persistStep(executionId, key, 'COMPLETED', executorType, context.steps[step.id], memo);
+                    this.emitEvent(executionId, {
+                        event: 'step_completed',
+                        data: { stepName: step.id, output: (context.steps[step.id]?.output ?? {}) },
+                    });
+                    continue;
+                }
+                // retry → re-execute this step with prior state + feedback overrides.
+                priorState = rec.data ?? undefined;
+                configOverrides = extractConfigOverrides(payload);
+            }
+            else if (rec?.status === 'EXTERNAL_WAIT' && !isControl) {
+                // 3. Parked leaf (WAIT / agent) — resume or re-park.
+                const data = rec.data ?? {};
+                const payload = data['resumePayload'];
+                // Delay-mode waits auto-resume once their deadline elapses (the host
+                // re-enqueues at `resumeAfter`); approval/webhook waits resume only when
+                // a payload has been routed to this node's record. This keeps a delay
+                // branch from resuming early when a *sibling* branch's resume re-runs
+                // the walk.
+                const delayReady = data['waitMode'] === 'delay' && payload === undefined
+                    ? typeof data['resumeAfter'] === 'string'
+                        ? Date.parse(data['resumeAfter']) <= Date.now()
+                        : true
+                    : false;
+                // Resume when: a payload was routed here, a delay elapsed, or this is the
+                // sole open gate (a bare re-enqueue resumes the one pause).
+                const resumeThis = payload !== undefined || delayReady || key === walkCtx.soleGate;
+                if (!resumeThis) {
+                    // Still waiting — unwind without re-executing (preserves the record).
+                    const reason = typeof data['reason'] === 'string' ? String(data['reason']) : 'waiting';
+                    throw new PauseStep(reason);
+                }
+                resumeData = data;
+            }
+            else if (topLevel && walkCtx.entryExtrasPending) {
+                // 4a. First fresh top-level step consumes the rerun seed.
+                priorState = context.__meta?.__priorStepState;
+                configOverrides = context.__meta?.__configOverrides;
+                walkCtx.entryExtrasPending = false;
+                if (context.__meta) {
+                    delete context.__meta.__priorStepState;
+                    delete context.__meta.__configOverrides;
+                }
+            }
+            // (rec EXTERNAL_WAIT + control → resumeData undefined → re-executes below,
+            //  re-entering its branches; completed branch steps memo-skip.)
+            const resuming = resumeData !== undefined;
+            if (!resuming) {
+                await this.persistence.upsertStep(executionId, key, { status: 'RUNNING', executorType });
                 this.emitEvent(executionId, {
                     event: 'step_started',
                     data: { stepName: step.id, stepType: step.type },
                 });
             }
-            // Consume entry-step extras (priorState + configOverrides) on the first
-            // iteration only. These come from review-gate retry or rerunFromStep.
-            const isEntryStep = i === startIndex && !isResuming;
-            const entryPriorState = isEntryStep
-                ? context.__meta?.__priorStepState
-                : undefined;
-            const entryConfigOverrides = isEntryStep
-                ? context.__meta?.__configOverrides
-                : undefined;
-            if (isEntryStep && context.__meta) {
-                // Single-use — clear so subsequent steps don't see them.
-                delete context.__meta.__priorStepState;
-                delete context.__meta.__configOverrides;
-            }
             try {
-                await this.executeStepWithRetry(step, context, { executionId, stepName, isResuming, priorState: entryPriorState, configOverrides: entryConfigOverrides }, stepBranchResumePath, retry);
-                const ctxEntry = context.steps[step.id];
-                await this.persistence.upsertStep(executionId, stepName, {
-                    status: 'COMPLETED',
-                    executorType: CONTROL_FLOW_STEP_TYPES.has(step.type)
-                        ? 'conditional'
-                        : 'deterministic',
-                    data: JSON.stringify(ctxEntry ?? { output: null }),
-                });
-                this.emitEvent(executionId, {
-                    event: 'step_completed',
-                    data: {
-                        stepName: step.id,
-                        output: (ctxEntry?.output ?? {}),
-                    },
-                });
-                // ─── Review gate: pause after step completes if onComplete === 'review' ───
-                if (step.onComplete === 'review') {
-                    const reviewPauseState = {
-                        reason: `Review output of "${step.id}"`,
-                        category: 'review',
-                        display: ctxEntry?.output
-                            ? [{ label: 'Output', value: ctxEntry.output }]
-                            : undefined,
-                        actions: [
-                            { key: 'approve', label: 'Approve', style: 'primary' },
-                            { key: 'retry', label: 'Retry with Feedback', style: 'default', submitsForm: true },
-                            { key: 'abort', label: 'Reject', style: 'danger', abort: true },
-                        ],
-                        form: {
-                            fields: [
-                                {
-                                    type: 'textarea',
-                                    name: 'feedback',
-                                    label: 'Feedback',
-                                    placeholder: 'Optional instructions for retry...',
-                                },
-                            ],
-                        },
-                    };
-                    await this.persistence.persistState(executionId, {
-                        context: JSON.stringify(context),
-                        currentStepIndex: i,
-                        pauseType: 'review',
-                    });
-                    await this.persistence.updateExecutionStatus(executionId, 'EXTERNAL_WAIT');
-                    this.emitEvent(executionId, {
-                        event: 'execution_paused',
-                        data: { stepName: step.id, pauseState: reviewPauseState },
-                    });
-                    this.log.info(`run ${executionId} REVIEW-GATE paused at step=${step.id}`);
-                    return { kind: 'paused', pausePath: [], externalRef: undefined };
+                if (resuming) {
+                    await this.executeStep(step, context, { executionId, stepName: key, isResuming: true }, prefix, walkCtx, resumeData);
+                }
+                else {
+                    await this.executeStepWithRetry(step, context, { executionId, stepName: key, isResuming: false, priorState, configOverrides }, prefix, walkCtx, retry);
                 }
             }
             catch (err) {
                 if (PauseStep.is(err)) {
+                    // Leaf called ctx.pause(), or a control step's branch(es) parked.
                     const pe = err;
-                    const fullPath = [
-                        { stepIndex: i },
-                        ...(pe._pausePath ?? []),
-                    ];
                     const ctxEntry = context.steps[step.id];
-                    const base = ctxEntry ?? { type: step.type, output: {} };
-                    const merged = pe.statePatch
-                        ? { ...base, ...pe.statePatch }
-                        : base;
-                    await this.persistence.upsertStep(executionId, stepName, {
-                        status: 'EXTERNAL_WAIT',
-                        executorType: CONTROL_FLOW_STEP_TYPES.has(step.type)
-                            ? 'conditional'
-                            : 'deterministic',
-                        data: JSON.stringify(merged),
-                    });
-                    await this.persistence.persistState(executionId, {
-                        context: JSON.stringify(context),
-                        currentStepIndex: i,
-                        pausePath: JSON.stringify(fullPath),
-                    });
-                    await this.persistence.updateExecutionStatus(executionId, 'EXTERNAL_WAIT');
+                    const base = ctxEntry
+                        ? { ...ctxEntry }
+                        : { type: step.type, output: {} };
+                    const merged = pe.statePatch ? { ...base, ...pe.statePatch } : base;
+                    await this.persistStep(executionId, key, 'EXTERNAL_WAIT', executorType, merged, memo);
                     this.emitEvent(executionId, {
                         event: 'execution_paused',
                         data: {
                             stepName: step.id,
-                            pauseState: merged['pauseState'] ?? { reason: pe.message },
+                            nodePath: key,
+                            pauseState: merged['pauseState'] ??
+                                { reason: pe.message },
                         },
                     });
-                    return {
-                        kind: 'paused',
-                        pausePath: fullPath,
-                        externalRef: pe.externalRef,
-                    };
+                    throw pe;
                 }
                 const errMsg = err instanceof Error ? err.message : String(err);
                 const ctxEntry = context.steps[step.id];
                 if (onError === 'continue') {
                     context.steps[step.id] = {
                         type: step.type,
-                        ...(ctxEntry?.input !== undefined
-                            ? { input: ctxEntry.input }
-                            : {}),
+                        ...(ctxEntry?.input !== undefined ? { input: ctxEntry.input } : {}),
                         output: ctxEntry?.output ?? {},
                         error: errMsg,
                     };
-                    await this.persistence.upsertStep(executionId, stepName, {
+                    await this.persistence.upsertStep(executionId, key, {
                         status: 'FAILED',
-                        executorType: CONTROL_FLOW_STEP_TYPES.has(step.type)
-                            ? 'conditional'
-                            : 'deterministic',
+                        executorType,
                         data: JSON.stringify({ ...(ctxEntry ?? {}), error: errMsg }),
                     });
-                    this.emitEvent(executionId, {
-                        event: 'step_failed',
-                        data: { stepName: step.id, error: errMsg },
-                    });
+                    memo.set(key, { status: 'FAILED', data: { ...(ctxEntry ?? {}), error: errMsg } });
+                    this.emitEvent(executionId, { event: 'step_failed', data: { stepName: step.id, error: errMsg } });
                     this.log.warn(`step ${step.id} failed but continuing: ${errMsg}`);
                     continue;
                 }
-                await this.persistence.upsertStep(executionId, stepName, {
+                await this.persistence.upsertStep(executionId, key, {
                     status: 'FAILED',
-                    executorType: CONTROL_FLOW_STEP_TYPES.has(step.type)
-                        ? 'conditional'
-                        : 'deterministic',
+                    executorType,
                     data: JSON.stringify({ ...(ctxEntry ?? {}), error: errMsg }),
                 });
+                this.emitEvent(executionId, { event: 'step_failed', data: { stepName: step.id, error: errMsg } });
+                throw err;
+            }
+            const ctxEntry = context.steps[step.id];
+            // Review gate: pause after a fresh success when onComplete === 'review'.
+            // (A resumed leaf already paused once; it does not re-gate.)
+            if (!resuming && step.onComplete === 'review') {
+                const reviewPauseState = buildReviewPauseState(step.id, ctxEntry);
+                const data = { ...(ctxEntry ?? { type: step.type, output: {} }), pauseState: reviewPauseState };
+                await this.persistStep(executionId, key, 'REVIEW_WAIT', executorType, data, memo);
                 this.emitEvent(executionId, {
-                    event: 'step_failed',
-                    data: { stepName: step.id, error: errMsg },
+                    event: 'execution_paused',
+                    data: { stepName: step.id, nodePath: key, pauseState: reviewPauseState },
                 });
-                throw err;
+                throw reviewPause(step.id);
             }
+            await this.persistStep(executionId, key, 'COMPLETED', executorType, ctxEntry, memo);
+            this.emitEvent(executionId, {
+                event: 'step_completed',
+                data: { stepName: step.id, output: (ctxEntry?.output ?? {}) },
+            });
         }
-        return { kind: 'completed' };
     }
-    async executeStepWithRetry(step, context, callCtx, branchResumePath, retry) {
+    /** Persist a step record + mirror it into the in-memory memo for this run. */
+    async persistStep(executionId, key, status, executorType, entry, memo) {
+        const data = entry ? { ...entry } : { output: null };
+        await this.persistence.upsertStep(executionId, key, {
+            status,
+            executorType,
+            data: JSON.stringify(data),
+        });
+        memo.set(key, { status, data });
+    }
+    async executeStepWithRetry(step, context, callCtx, prefix, walkCtx, retry) {
         if (!retry || callCtx.isResuming) {
-            await this.executeStep(step, context, callCtx, branchResumePath);
+            await this.executeStep(step, context, callCtx, prefix, walkCtx);
             return;
         }
         let lastError;
         for (let attempt = 1; attempt <= retry.maxAttempts; attempt++) {
             try {
-                await this.executeStep(step, context, callCtx, branchResumePath);
+                await this.executeStep(step, context, callCtx, prefix, walkCtx);
                 return;
             }
             catch (err) {
@@ -553,7 +578,13 @@ export class WorkflowExecutor {
         }
         throw lastError;
     }
-    async executeStep(step, context, callCtx, branchResumePath) {
+    /**
+     * Execute one step. Control steps recurse into their branches via the
+     * `walkBranch` closure (which addresses each branch with a node-path frame).
+     * Action steps resolve config then either `execute()` fresh or `onResume()`
+     * when `resumeData` (the parked record) is supplied.
+     */
+    async executeStep(step, context, callCtx, prefix, walkCtx, resumeData) {
         const stepImpl = this.stepRegistry.get(step.type);
         if (stepImpl.kind === StepKind.CONTROL) {
             const controlImpl = stepImpl;
@@ -562,17 +593,16 @@ export class WorkflowExecutor {
                 throw new Error(`Step "${step.id}" (${step.type}) config validation failed:\n${formatZodErrors(parsed.error)}`);
             }
             this.log.info(`step ${callCtx.isResuming ? 'RESUME' : 'START'} id=${step.id} type=${step.type}`);
-            const t0 = Date.now();
             const stepCtx = await this.buildStepContext(context, { ...callCtx, stepId: step.id }, stepImpl);
             const output = await controlImpl.execute(parsed.data, {
                 ...stepCtx,
-                walkBranch: (branchSteps, ctx, branchKey, perBranchResumePath) => this.walkBranchSteps(branchSteps, ctx, callCtx.executionId, step.id, branchKey, perBranchResumePath ?? branchResumePath),
+                walkBranch: (branchSteps, branchScope, branchKey, iter) => this.walkScope(branchSteps, branchScope, framePrefix(prefix, step.id, branchKey ?? 'default', iter ?? 0), walkCtx),
             });
             context.steps[step.id] = { type: step.type, output };
-            this.log.info(`step OK id=${step.id} type=${step.type} elapsed=${String(Date.now() - t0)}ms`);
+            this.log.info(`step OK id=${step.id} type=${step.type}`);
             return;
         }
-        // Action step: merge configOverrides → resolve variables → coerce → validate → execute
+        // Action step: merge configOverrides → resolve variables → coerce → validate → execute/resume
         const baseConfig = callCtx.configOverrides
             ? { ...step.config, ...callCtx.configOverrides }
             : step.config;
@@ -591,13 +621,22 @@ export class WorkflowExecutor {
             output: {},
         };
         const actionImpl = stepImpl;
-        const stepCtx = await this.buildStepContext(context, { ...callCtx, stepId: step.id }, stepImpl);
+        const resumePayload = resumeData?.['resumePayload'];
+        const stepCtx = await this.buildStepContext(context, { ...callCtx, stepId: step.id }, stepImpl, resumePayload);
         this.log.info(`step ${callCtx.isResuming ? 'RESUME' : 'START'} id=${step.id} type=${step.type}`);
-        const t0 = Date.now();
         try {
             let output;
-            if (callCtx.isResuming) {
-                output = await this.invokeResume(actionImpl, callCtx.executionId, callCtx.stepName, resolvedInput, stepCtx);
+            if (resumeData !== undefined) {
+                if (typeof actionImpl.onResume === 'function') {
+                    output = await actionImpl.onResume(resumeData, resolvedInput, stepCtx);
+                }
+                else {
+                    const fallback = resumeData['output'];
+                    output =
+                        fallback && typeof fallback === 'object' && !Array.isArray(fallback)
+                            ? fallback
+                            : {};
+                }
             }
             else {
                 output = await actionImpl.execute(resolvedInput, stepCtx);
@@ -607,151 +646,18 @@ export class WorkflowExecutor {
                 input: persistedInput,
                 output,
             };
-            this.log.info(`step OK id=${step.id} type=${step.type} elapsed=${String(Date.now() - t0)}ms`);
+            this.log.info(`step OK id=${step.id} type=${step.type}`);
         }
         catch (err) {
             if (!PauseStep.is(err)) {
-                this.log.error(`step FAIL id=${step.id} type=${step.type} elapsed=${String(Date.now() - t0)}ms err=${err instanceof Error ? err.message : String(err)}`);
+                this.log.error(`step FAIL id=${step.id} type=${step.type} err=${err instanceof Error ? err.message : String(err)}`);
             }
             throw err;
         }
     }
-    /**
-     * Walk steps inside a control-flow branch. Supports nested pause.
-     *
-     * Each sub-step is persisted as its own row (keyed by config `id`) and
-     * emits SSE events, mirroring the top-level `walkSteps` behavior.
-     *
-     * When a step pauses inside a branch, the PauseStep error is enriched
-     * with branch path information and re-thrown so the top-level walkSteps
-     * can persist the full PausePath.
-     */
-    async walkBranchSteps(steps, context, executionId, controlStepId, branchKey, branchResumePath) {
-        const resolvedBranchKey = branchKey ?? 'default';
-        // Determine start position for resume within this branch
-        let startIndex = 0;
-        let innerResuming = false;
-        let deeperResumePath;
-        if (branchResumePath && branchResumePath.length > 0) {
-            const segment = branchResumePath[0];
-            if (segment.branch?.stepId === controlStepId &&
-                segment.branch.branchKey === resolvedBranchKey) {
-                startIndex = segment.stepIndex;
-                innerResuming = true;
-                deeperResumePath =
-                    branchResumePath.length > 1
-                        ? branchResumePath.slice(1)
-                        : undefined;
-            }
-        }
-        for (let j = startIndex; j < steps.length; j++) {
-            const bStep = steps[j];
-            const isResuming = innerResuming && j === startIndex;
-            const executorType = CONTROL_FLOW_STEP_TYPES.has(bStep.type)
-                ? 'conditional'
-                : 'deterministic';
-            // Persist RUNNING + emit event (skip for resuming steps)
-            if (!isResuming && executionId) {
-                await this.persistence.upsertStep(executionId, bStep.id, {
-                    status: 'RUNNING',
-                    executorType,
-                });
-                this.emitEvent(executionId, {
-                    event: 'step_started',
-                    data: { stepName: bStep.id, stepType: bStep.type },
-                });
-            }
-            try {
-                await this.executeStep(bStep, context, {
-                    executionId,
-                    stepName: bStep.id,
-                    isResuming,
-                }, isResuming ? deeperResumePath : undefined);
-                // Persist COMPLETED + emit event
-                if (executionId) {
-                    const ctxEntry = context.steps[bStep.id];
-                    await this.persistence.upsertStep(executionId, bStep.id, {
-                        status: 'COMPLETED',
-                        executorType,
-                        data: JSON.stringify(ctxEntry ?? { output: null }),
-                    });
-                    this.emitEvent(executionId, {
-                        event: 'step_completed',
-                        data: {
-                            stepName: bStep.id,
-                            output: (ctxEntry?.output ?? {}),
-                        },
-                    });
-                }
-            }
-            catch (err) {
-                if (PauseStep.is(err)) {
-                    const pe = err;
-                    // Persist EXTERNAL_WAIT for the sub-step
-                    if (executionId) {
-                        const ctxEntry = context.steps[bStep.id];
-                        const base = ctxEntry ?? { type: bStep.type, output: {} };
-                        const merged = pe.statePatch
-                            ? { ...base, ...pe.statePatch }
-                            : base;
-                        await this.persistence.upsertStep(executionId, bStep.id, {
-                            status: 'EXTERNAL_WAIT',
-                            executorType,
-                            data: JSON.stringify(merged),
-                        });
-                    }
-                    pe._pausePath = [
-                        {
-                            stepIndex: j,
-                            branch: {
-                                stepId: controlStepId,
-                                branchKey: resolvedBranchKey,
-                            },
-                        },
-                        ...(pe._pausePath ?? []),
-                    ];
-                    throw pe;
-                }
-                // Persist FAILED + emit event
-                if (executionId) {
-                    const errMsg = err instanceof Error ? err.message : String(err);
-                    await this.persistence.upsertStep(executionId, bStep.id, {
-                        status: 'FAILED',
-                        executorType,
-                        data: JSON.stringify({ error: errMsg }),
-                    });
-                    this.emitEvent(executionId, {
-                        event: 'step_failed',
-                        data: { stepName: bStep.id, error: errMsg },
-                    });
-                }
-                throw err;
-            }
-        }
-    }
-    async invokeResume(actionImpl, executionId, stepName, resolvedInput, ctx) {
-        const row = await this.persistence.getStep(executionId, stepName);
-        let rowData = row?.data
-            ? (safeParseJson(row.data) ?? {})
-            : {};
-        // Merge user's resume payload (approve/reject/form data) into rowData
-        const resumePayload = await this.persistence.getResumePayload(executionId);
-        if (resumePayload) {
-            rowData = { ...rowData, resumePayload };
-        }
-        if (typeof actionImpl.onResume === 'function') {
-            return actionImpl.onResume(rowData, resolvedInput, ctx);
-        }
-        const fallback = rowData['output'];
-        return fallback &&
-            typeof fallback === 'object' &&
-            !Array.isArray(fallback)
-            ? fallback
-            : {};
-    }
-    async buildStepContext(context, callCtx, stepImpl) {
+    async buildStepContext(context, callCtx, stepImpl, resumePayload) {
         // Resolve credentials if step declares credentialSlots
-        let credentials = {};
+        const credentials = {};
         if (stepImpl.credentialSlots && stepImpl.credentialSlots.length > 0) {
             for (const slot of stepImpl.credentialSlots) {
                 const resolved = await this.persistence.resolveCredential(context.workflow.metadata, slot.name);
@@ -763,6 +669,12 @@ export class WorkflowExecutor {
                 }
             }
         }
+        // The resume payload rides on `runtime.metadata` (a shallow copy so the
+        // persisted workflow metadata isn't polluted) — the agent step reads it
+        // there, and onResume also receives it merged into `rowData`.
+        const metadata = resumePayload
+            ? { ...context.workflow.metadata, resumePayload }
+            : context.workflow.metadata;
         return {
             workflow: context,
             runtime: {
@@ -770,7 +682,7 @@ export class WorkflowExecutor {
                 stepId: callCtx.stepId,
                 stepName: callCtx.stepName,
                 isResuming: callCtx.isResuming,
-                metadata: context.workflow.metadata,
+                metadata,
                 baseUrl: this.baseUrl,
             },
             ...(callCtx.priorState ? { priorState: callCtx.priorState } : {}),
@@ -820,12 +732,44 @@ function safeParseJson(raw) {
         return null;
     }
 }
-function parseStepIndex(name) {
-    const m = /^step_(\d+)$/.exec(name);
-    if (!m?.[1])
-        return null;
-    const n = Number.parseInt(m[1], 10);
-    return Number.isInteger(n) ? n : null;
+/** Reconstruct a context steps entry from a persisted record's parsed data. */
+function entryFromData(data, fallbackType) {
+    return {
+        type: data['type'] ?? fallbackType,
+        ...(data['input'] !== undefined ? { input: data['input'] } : {}),
+        output: data['output'] ?? {},
+    };
+}
+/** A PauseStep tagged as originating from a review gate (drives `pauseType`). */
+function reviewPause(stepId) {
+    const pe = new PauseStep(`review gate at ${stepId}`);
+    pe.pauseCategory = 'review';
+    return pe;
+}
+/** The review-gate PauseState shown to the approver (approve / retry / abort). */
+function buildReviewPauseState(stepId, ctxEntry) {
+    return {
+        reason: `Review output of "${stepId}"`,
+        category: 'review',
+        display: ctxEntry?.output
+            ? [{ label: 'Output', value: ctxEntry.output }]
+            : undefined,
+        actions: [
+            { key: 'approve', label: 'Approve', style: 'primary' },
+            { key: 'retry', label: 'Retry with Feedback', style: 'default', submitsForm: true },
+            { key: 'abort', label: 'Reject', style: 'danger', abort: true },
+        ],
+        form: {
+            fields: [
+                {
+                    type: 'textarea',
+                    name: 'feedback',
+                    label: 'Feedback',
+                    placeholder: 'Optional instructions for retry...',
+                },
+            ],
+        },
+    };
 }
 function formatZodErrors(error) {
     return error.issues