nx 23.2.0-beta.0 → 23.2.0-beta.10

package/dist/src/command-line/migrate/migrate.js

@@ -1,46 +1,36 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ChangedDepInstaller = exports.isHybridMigration = exports.isPromptOnlyMigration = exports.filterDowngradedUpdates = exports.Migrator = exports.normalizeVersion = void 0;
+exports.isHybridMigration = exports.isPromptOnlyMigration = exports.filterDowngradedUpdates = exports.Migrator = exports.normalizeVersion = void 0;
 exports.formatCommandFailure = formatCommandFailure;
 exports.resolveCanonicalNxPackage = resolveCanonicalNxPackage;
 exports.resolveInclude = resolveInclude;
 exports.parseMigrationsOptions = parseMigrationsOptions;
 exports.createFetcher = createFetcher;
 exports.generateMigrationsJsonAndUpdatePackageJson = generateMigrationsJsonAndUpdatePackageJson;
-exports.isNpmPeerDepsError = isNpmPeerDepsError;
-exports.resolveAgenticRunId = resolveAgenticRunId;
 exports.formatSkippedPromptsNextStep = formatSkippedPromptsNextStep;
-exports.resolveCreateCommits = resolveCreateCommits;
-exports.confirmCommitsOnDefaultBranch = confirmCommitsOnDefaultBranch;
-exports.resolveShouldRunValidation = resolveShouldRunValidation;
 exports.executeMigrations = executeMigrations;
-exports.runNxOrAngularMigration = runNxOrAngularMigration;
-exports.parseMigrationReturn = parseMigrationReturn;
+exports.isRunPhaseInvocation = isRunPhaseInvocation;
 exports.migrate = migrate;
+exports.readLocalNxVersion = readLocalNxVersion;
 exports.runMigration = runMigration;
-exports.readMigrationCollection = readMigrationCollection;
-exports.getImplementationPath = getImplementationPath;
 exports.resolveMigrationForRun = resolveMigrationForRun;
-exports.resolveDocumentationFileToWorkspacePath = resolveDocumentationFileToWorkspacePath;
 exports.nxCliPath = nxCliPath;
 const tslib_1 = require("tslib");
 const pc = tslib_1.__importStar(require("picocolors"));
 const child_process_1 = require("child_process");
 const safe_prompt_1 = require("./safe-prompt");
-const handle_import_1 = require("../../utils/handle-import");
 const path_1 = require("path");
 const module_1 = require("module");
 const path_2 = require("../../utils/path");
 const semver_1 = require("semver");
 const node_url_1 = require("node:url");
 const util_1 = require("util");
-const tree_1 = require("../../generators/tree");
 const fileutils_1 = require("../../utils/fileutils");
 const tar_1 = require("../../utils/tar");
 const write_formatted_json_file_1 = require("../../utils/write-formatted-json-file");
+const shell_quoting_1 = require("../../utils/shell-quoting");
 const logger_1 = require("../../utils/logger");
 const git_utils_1 = require("../../utils/git-utils");
-const command_line_utils_1 = require("../../utils/command-line-utils");
 const package_json_1 = require("../../utils/package-json");
 const package_manager_1 = require("../../utils/package-manager");
 const errors_1 = require("../../utils/min-release-age/errors");
@@ -57,8 +47,7 @@ const configuration_1 = require("../../config/configuration");
 const child_process_2 = require("../../utils/child-process");
 const client_1 = require("../../daemon/client/client");
 const nx_cloud_utils_1 = require("../../utils/nx-cloud-utils");
-const project_graph_1 = require("../../project-graph/project-graph");
-const format_changed_files_with_prettier_if_available_1 = require("../../generators/internal-utils/format-changed-files-with-prettier-if-available");
+const format_changed_files_1 = require("../../generators/internal-utils/format-changed-files");
 const provenance_1 = require("../../utils/provenance");
 const catalog_1 = require("../../utils/catalog");
 const migrate_analytics_1 = require("./migrate-analytics");
@@ -66,7 +55,6 @@ const multi_major_1 = require("./multi-major");
 const prompt_files_1 = require("./prompt-files");
 const command_object_1 = require("./command-object");
 const migrate_config_1 = require("./migrate-config");
-const handoff_gitignore_1 = require("./agentic/handoff-gitignore");
 const migrate_commits_1 = require("./migrate-commits");
 const migrate_output_1 = require("./migrate-output");
 const migration_shape_1 = require("./migration-shape");
@@ -76,6 +64,13 @@ const update_filters_1 = require("./update-filters");
 Object.defineProperty(exports, "filterDowngradedUpdates", { enumerable: true, get: function () { return update_filters_1.filterDowngradedUpdates; } });
 const version_utils_1 = require("./version-utils");
 Object.defineProperty(exports, "normalizeVersion", { enumerable: true, get: function () { return version_utils_1.normalizeVersion; } });
+const execute_migration_1 = require("./execute-migration");
+const step_actions_1 = require("./step-actions");
+const sort_migrations_1 = require("./sort-migrations");
+const inception_1 = require("./agentic/inception");
+const version_skew_guard_1 = require("./version-skew-guard");
+const versions_1 = require("../../utils/versions");
+tslib_1.__exportStar(require("./execute-migration"), exports);
 const execAsync = (0, util_1.promisify)(child_process_1.exec);
 function formatCommandFailure(command, error) {
     const normalizeCommandOutput = (output) => {
@@ -118,6 +113,8 @@ class Migrator {
         this.packageUpdates = {};
         this.collectedVersions = {};
         this.promptAnswers = {};
+        this.pendingPackageJsonUpdates = new Map();
+        this.appliedPackageJsonUpdates = new Set();
         if ((opts.include === 'required' || opts.include === 'optional') &&
             !opts.requiredPackages) {
             throw new Error(`Error: 'requiredPackages' is required when 'include' is '${opts.include}'.`);
@@ -145,6 +142,7 @@ class Migrator {
             version: targetVersion,
             addToPackageJson: false,
         });
+        await this.applyPendingPackageJsonUpdates();
         this.applyIncludeFilter();
         const { migrations, promptContents } = await this.createMigrateJson();
         return {
@@ -190,29 +188,66 @@ class Migrator {
         for (const packageToCheck of packagesToCheck) {
             const filteredUpdates = {};
             for (const [packageUpdateKey, packageUpdate] of Object.entries(packageToCheck.updates)) {
-                if (this.areRequirementsMet(packageUpdate.requires) &&
-                    !this.areIncompatiblePackagesPresent(packageUpdate.incompatibleWith) &&
-                    (!this.interactive ||
-                        (await this.runPackageJsonUpdatesConfirmationPrompt(packageUpdate, packageUpdateKey, packageToCheck.package)))) {
-                    const updateEntries = Object.entries(packageUpdate.packages);
-                    // Validate all up front so invalid metadata fails fast, before any
-                    // resolution does I/O.
-                    for (const [name, update] of updateEntries) {
-                        this.validatePackageUpdateVersion(packageToCheck.package, name, update);
-                    }
-                    // Resolve serially: resolution can prompt (pnpm strict cooldown) and
-                    // append to minimumReleaseAgeExclude, so a serial loop avoids
-                    // overlapping prompts and keeps packageUpdates ordering stable.
-                    for (const [name, update] of updateEntries) {
-                        const resolvedUpdate = {
-                            ...update,
-                            version: await this.resolveVersionForCascade(name, update.version),
-                        };
-                        filteredUpdates[name] = resolvedUpdate;
-                        this.packageUpdates[name] = resolvedUpdate;
-                    }
+                Object.assign(filteredUpdates, await this.applyPackageJsonUpdate(packageToCheck.package, packageUpdateKey, packageUpdate));
+            }
+            await Promise.all(Object.entries(filteredUpdates).map(([name, update]) => this.buildPackageJsonUpdates(name, update)));
+        }
+    }
+    async applyPackageJsonUpdate(sourcePackage, packageUpdateKey, packageUpdate) {
+        const appliedKey = JSON.stringify([sourcePackage, packageUpdateKey]);
+        if (this.appliedPackageJsonUpdates.has(appliedKey)) {
+            this.pendingPackageJsonUpdates.delete(appliedKey);
+            return {};
+        }
+        if (!this.areRequirementsMet(packageUpdate.requires) ||
+            this.areIncompatiblePackagesPresent(packageUpdate.incompatibleWith)) {
+            this.pendingPackageJsonUpdates.set(appliedKey, {
+                package: sourcePackage,
+                key: packageUpdateKey,
+                update: packageUpdate,
+            });
+            return {};
+        }
+        this.pendingPackageJsonUpdates.delete(appliedKey);
+        if (this.interactive &&
+            !(await this.runPackageJsonUpdatesConfirmationPrompt(packageUpdate, packageUpdateKey, sourcePackage))) {
+            return {};
+        }
+        this.appliedPackageJsonUpdates.add(appliedKey);
+        const updateEntries = Object.entries(packageUpdate.packages);
+        // Validate all up front so invalid metadata fails fast, before any
+        // resolution does I/O.
+        for (const [name, update] of updateEntries) {
+            this.validatePackageUpdateVersion(sourcePackage, name, update);
+        }
+        const filteredUpdates = {};
+        // Resolve serially: resolution can prompt (pnpm strict cooldown) and append
+        // to minimumReleaseAgeExclude, so a serial loop avoids overlapping prompts
+        // and keeps packageUpdates ordering stable.
+        for (const [name, update] of updateEntries) {
+            const resolvedUpdate = {
+                ...update,
+                version: await this.resolveVersionForCascade(name, update.version),
+            };
+            this.addPackageUpdate(name, resolvedUpdate);
+            filteredUpdates[name] = this.packageUpdates[name];
+        }
+        return filteredUpdates;
+    }
+    async applyPendingPackageJsonUpdates() {
+        while (this.pendingPackageJsonUpdates.size) {
+            let applied = false;
+            const filteredUpdates = {};
+            for (const pending of [...this.pendingPackageJsonUpdates.values()]) {
+                const updates = await this.applyPackageJsonUpdate(pending.package, pending.key, pending.update);
+                if (Object.keys(updates).length) {
+                    applied = true;
+                    Object.assign(filteredUpdates, updates);
                 }
             }
+            if (!applied) {
+                return;
+            }
             await Promise.all(Object.entries(filteredUpdates).map(([name, update]) => this.buildPackageJsonUpdates(name, update)));
         }
     }
@@ -416,7 +451,7 @@ class Migrator {
     }
     addPackageUpdate(name, packageUpdate) {
         if (!this.packageUpdates[name] ||
-            this.gt(packageUpdate.version, this.packageUpdates[name].version)) {
+            !this.lt(packageUpdate.version, this.packageUpdates[name].version)) {
             this.packageUpdates[name] = packageUpdate;
         }
     }
@@ -482,17 +517,14 @@ class Migrator {
             // a same prompt was already answered, skip
             return Promise.resolve(false);
         }
-        const promptConfig = {
-            name: 'shouldApply',
-            type: 'confirm',
-            message: packageUpdate['x-prompt'],
+        // No footer slot, so the docs link is appended to the message.
+        const detailsLink = packageName.startsWith('@nx/')
+            ? pc.dim(`\n  View migration details at https://nx.dev/nx-api/${packageName.replace('@nx/', '')}#${packageUpdateKey.replace(/[-\.]/g, '')}packageupdates`)
+            : '';
+        return await (0, safe_prompt_1.migrateConfirm)({
+            message: `${packageUpdate['x-prompt']}${detailsLink}`,
             initial: true,
-        };
-        if (packageName.startsWith('@nx/')) {
-            // @ts-expect-error -- enquirer types aren't correct, footer does exist
-            promptConfig.footer = () => pc.dim(`  View migration details at https://nx.dev/nx-api/${packageName.replace('@nx/', '')}#${packageUpdateKey.replace(/[-\.]/g, '')}packageupdates`);
-        }
-        return await (0, safe_prompt_1.migratePrompt)([promptConfig]).then(({ shouldApply }) => {
+        }).then((shouldApply) => {
             this.promptAnswers[promptKey] = shouldApply;
             if (!shouldApply &&
                 (!this.minVersionWithSkippedUpdates ||
@@ -593,8 +625,8 @@ async function resolveInclude(include, context, configuredInclude) {
     }
     const choices = [
         {
-            name: 'required',
-            message: 'Required only (the target package and the packages it ships with)',
+            value: 'required',
+            label: 'Required only (the target package and the packages it ships with)',
         },
     ];
     // `--interactive` keeps the legacy x-prompt flow, which the `optional` value
@@ -603,8 +635,8 @@ async function resolveInclude(include, context, configuredInclude) {
         !context.hasExcludeAppliedMigrations &&
         context.interactive !== true) {
         choices.push({
-            name: 'optional',
-            message: 'Optional only (the dependency updates those packages recommend)',
+            value: 'optional',
+            label: 'Optional only (the dependency updates those packages recommend)',
         });
     }
     if (!(0, safe_prompt_1.canPrompt)(context.interactive)) {
@@ -612,12 +644,10 @@ async function resolveInclude(include, context, configuredInclude) {
         return 'all';
     }
     choices.push({
-        name: 'all',
-        message: 'All (required and optional)',
+        value: 'all',
+        label: 'All (required and optional)',
     });
-    const { include: selected } = await (0, safe_prompt_1.migratePrompt)({
-        type: 'select',
-        name: 'include',
+    const selected = await (0, safe_prompt_1.migrateChoice)({
         message: 'Which packages would you like to migrate?',
         choices,
     });
@@ -677,6 +707,75 @@ async function parseTargetPackageAndVersion(args) {
     return { targetPackage: args, targetVersion: 'latest' };
 }
 async function parseMigrationsOptions(options, fetch) {
+    // A run recorded or reconciled via `--run-id` is driven by the outer agent;
+    // spawning another agent from it would double-drive the run. Only the
+    // explicit "on" values conflict; the nx.json default is ignored for
+    // `--run-id` invocations instead.
+    if (options.runId !== undefined &&
+        options.agentic !== undefined &&
+        options.agentic !== false) {
+        throw new Error(`Error: '--agentic' cannot be combined with '--run-id'.`);
+    }
+    if (options.runMigration !== undefined) {
+        if (options.runMigration === '') {
+            throw new Error(`Error: '--run-migration' requires a migration id, e.g. '--run-migration=@nx/js:my-migration'.`);
+        }
+        if (options.runId === '') {
+            throw new Error(`Error: '--run-id' requires the id of the migrate run to record into.`);
+        }
+        if (options.stepAction !== undefined) {
+            throw new Error(`Error: '--step-action' cannot be combined with '--run-migration'. It applies to an orchestrated reconcile ('--run-id' without '--run-migration').`);
+        }
+        if (options.runMigrations !== undefined) {
+            throw new Error(`Error: '--run-migration' (run a single migration) cannot be combined with '--run-migrations' (run the whole migrations file).`);
+        }
+        if (options.include) {
+            throw new Error(`Error: '--run-migration' cannot be combined with '--include'.`);
+        }
+        if (options.multiMajorMode) {
+            throw new Error(`Error: '--run-migration' cannot be combined with '--multi-major-mode'.`);
+        }
+        // `--if-exists` only applies to a whole-file run, so an explicit "on"
+        // conflicts. Its yargs default (false) is always present and is tolerated.
+        if (options.ifExists === true) {
+            throw new Error(`Error: '--run-migration' cannot be combined with '--if-exists'.`);
+        }
+        return {
+            type: 'runSingleMigration',
+            runMigration: options.runMigration,
+            runId: options.runId,
+            agentic: options.agentic,
+            validate: options.validate,
+            interactive: options.interactive,
+        };
+    }
+    if (options.runId !== undefined) {
+        // Empty '--run-id' is an error on every path.
+        if (options.runId === '') {
+            throw new Error(`Error: '--run-id' requires the id of the migrate run to record into.`);
+        }
+        if (options.runMigrations !== undefined) {
+            throw new Error(`Error: '--run-id' (reconcile an orchestrated run) cannot be combined with '--run-migrations' (run the whole migrations file).`);
+        }
+        // A bare '--run-id' reconciles the run it names. Ungated, unlike init:
+        // the id has to name a run directory that exists, and only a gated init
+        // ever creates one.
+        // yargs' choices already reject bad CLI values; this guards programmatic
+        // callers, where silently dropping the action would reconcile without it.
+        if (options.stepAction !== undefined && !(0, step_actions_1.isStepAction)(options.stepAction)) {
+            throw new Error(`Error: '--step-action' must be one of ${step_actions_1.STEP_ACTIONS.join(', ')}.`);
+        }
+        return {
+            type: 'orchestratorReconcile',
+            runId: options.runId,
+            ...(options.stepAction !== undefined
+                ? { stepAction: options.stepAction }
+                : {}),
+        };
+    }
+    if (options.stepAction !== undefined) {
+        throw new Error(`Error: '--step-action' requires '--run-id'.`);
+    }
     if (options.runMigrations === '') {
         options.runMigrations = 'migrations.json';
     }
@@ -1053,6 +1152,15 @@ function createFetcher(pmc) {
             migrationsCache[packageName + '-' + packageVersion] = migrations;
         }
         migrations = fetchMigrations(packageName, packageVersion, setCache).then((result) => {
+            // An exact requested version must come back verbatim; a mismatch means
+            // a config surface (registry proxy, override, cooldown gate) silently
+            // substituted another version, which would corrupt the whole plan.
+            if ((0, semver_1.valid)(packageVersion) &&
+                result.version &&
+                result.version !== packageVersion) {
+                throw new Error(`Fetching ${packageName}@${packageVersion} resolved to version ${result.version}. ` +
+                    `Check for registry, override, or minimum-release-age configuration that hides the requested version.`);
+            }
             if (result.schematics) {
                 result.generators = { ...result.schematics, ...result.generators };
                 delete result.schematics;
@@ -1092,8 +1200,30 @@ async function getPackageMigrationsUsingRegistry(packageName, packageVersion) {
     // try to obtain the migrations from the registry directly
     return await downloadPackageMigrationsFromRegistry(packageName, packageVersion, migrationsConfig);
 }
+// Matched exactly: a hostname that merely contains one of these is a different
+// registry. registry.yarnpkg.com is npmjs' CNAME, so it serves the same
+// metadata; the two loopback literals are the spellings of a local registry
+// that the substring below cannot reach, since neither contains "localhost".
+const FULL_METADATA_REGISTRIES = [
+    'registry.npmjs.org',
+    'registry.yarnpkg.com',
+    '127.0.0.1',
+    '[::1]',
+];
+// Matched as substrings, since neither names a single host: a local registry
+// can sit on a subdomain of localhost, and an Artifactory instance is
+// identified only by that word appearing somewhere in its hostname.
+const FULL_METADATA_REGISTRY_MARKERS = [
+    'localhost',
+    'artifactory',
+];
 async function getPackageMigrationsConfigFromRegistry(packageName, packageVersion) {
-    const result = await (0, package_manager_1.packageRegistryView)(packageName, packageVersion, 'nx-migrations ng-update dist --json');
+    const result = await (0, package_manager_1.packageRegistryView)(packageName, packageVersion, [
+        'nx-migrations',
+        'ng-update',
+        'dist',
+        '--json',
+    ]);
     if (!result) {
         return null;
     }
@@ -1101,9 +1231,10 @@ async function getPackageMigrationsConfigFromRegistry(packageName, packageVersio
     if (!json['nx-migrations'] && !json['ng-update']) {
         const registry = new node_url_1.URL('dist' in json ? json.dist.tarball : json.tarball)
             .hostname;
-        // Registries other than npmjs and the local registry may not support full metadata via npm view
-        // so throw error so that fetcher falls back to getting config via install
-        if (!['registry.npmjs.org', 'localhost', 'artifactory'].some((v) => registry.includes(v))) {
+        // Other registries may not support full metadata via npm view; throw to
+        // trigger the install fallback.
+        if (!FULL_METADATA_REGISTRIES.includes(registry) &&
+            !FULL_METADATA_REGISTRY_MARKERS.some((v) => registry.includes(v))) {
             throw new Error(`Getting migration config from registry is not supported from ${registry}`);
         }
     }
@@ -1113,7 +1244,13 @@ async function downloadPackageMigrationsFromRegistry(packageName, packageVersion
     const { dir, cleanup } = (0, package_manager_1.createTempNpmDirectory)();
     let result;
     try {
-        const { tarballPath } = await (0, package_manager_1.packageRegistryPack)(dir, packageName, packageVersion);
+        const { tarballPath } = await (0, package_manager_1.packageRegistryPack)(dir, packageName, packageVersion, 
+        // packageVersion is exact and already resolved through the workspace
+        // package manager's min-release-age policy by the fetcher. In an npm
+        // workspace the pack gate IS that policy, so leave it enforcing; for
+        // other package managers npm's gate is foreign config with no
+        // exclusions and would wrongly re-judge the vetted version.
+        { bypassMinReleaseAge: (0, package_manager_1.detectPackageManager)() !== 'npm' });
         const fullTarballPath = (0, path_1.join)(dir, tarballPath);
         let migrations;
         try {
@@ -1191,7 +1328,7 @@ async function getPackageMigrationsUsingInstallImpl(packageName, packageVersion,
             // as-is by the outer catch instead of being mislabeled as install failures.
             throw new Error(formatCommandFailure(addCommand, e));
         }
-        const { migrations: migrationsFilePath, packageGroup, supportsOptionalMigrations, packageJson, } = readPackageMigrationConfig(packageName, dir);
+        const { migrations: migrationsFilePath, packageGroup, supportsOptionalMigrations, packageJson, } = (0, execute_migration_1.readPackageMigrationConfig)(packageName, dir);
         let migrations = undefined;
         let resolvedPromptFiles;
         if (migrationsFilePath) {
@@ -1218,32 +1355,6 @@ async function getPackageMigrationsUsingInstallImpl(packageName, packageVersion,
     }
     return result;
 }
-function readPackageMigrationConfig(packageName, dir) {
-    const { path: packageJsonPath, packageJson: json } = (0, package_json_1.readModulePackageJson)(packageName, (0, installation_directory_1.getNxRequirePaths)(dir));
-    const config = (0, package_json_1.readNxMigrateConfig)(json);
-    if (!config) {
-        return { packageJson: json, migrations: null, packageGroup: [] };
-    }
-    try {
-        const migrationFile = require.resolve(config.migrations, {
-            paths: [(0, path_1.dirname)(packageJsonPath)],
-        });
-        return {
-            packageJson: json,
-            migrations: migrationFile,
-            packageGroup: config.packageGroup,
-            supportsOptionalMigrations: config.supportsOptionalMigrations,
-        };
-    }
-    catch {
-        return {
-            packageJson: json,
-            migrations: null,
-            packageGroup: config.packageGroup,
-            supportsOptionalMigrations: config.supportsOptionalMigrations,
-        };
-    }
-}
 async function createMigrationsFile(root, migrations) {
     await (0, write_formatted_json_file_1.writeFormattedJsonFile)((0, path_1.join)(root, 'migrations.json'), { migrations });
 }
@@ -1316,7 +1427,7 @@ async function formatCatalogDefinitionFiles(manager, root) {
             content: (0, fs_1.readFileSync)(absolutePath, 'utf-8'),
         };
     });
-    const results = await (0, format_changed_files_with_prettier_if_available_1.formatFilesWithPrettierIfAvailable)(catalogDefinitionFiles.map(({ path, content }) => ({ path, content })), root, { silent: true });
+    const results = await (0, format_changed_files_1.formatFileContents)(catalogDefinitionFiles.map(({ path, content }) => ({ path, content })), root, { silent: true });
     for (const { path, absolutePath, content } of catalogDefinitionFiles) {
         (0, fs_1.writeFileSync)(absolutePath, results.has(path) ? results.get(path) : content, { encoding: 'utf-8' });
     }
@@ -1610,248 +1721,22 @@ function showConnectToCloudMessage() {
         return false;
     }
 }
-function runInstall(nxWorkspaceRoot, phase = 'pre-migration') {
-    const cwd = nxWorkspaceRoot ?? process.cwd();
-    const packageManager = (0, package_manager_1.detectPackageManager)(cwd);
-    const pmCommands = (0, package_manager_1.getPackageManagerCommand)(packageManager, cwd);
-    const installCommand = `${pmCommands.install} ${pmCommands.ignoreScriptsFlag ?? ''}`;
-    output_1.output.log({
-        title: `Running '${installCommand}' to make sure necessary packages are installed`,
-    });
-    return new Promise((resolve, reject) => {
-        // For npm, pipe stderr so we can detect peer dependency errors while still
-        // mirroring it live to the user's terminal. Other package managers inherit
-        // stderr directly since we don't need to inspect their output.
-        const shouldCaptureStderr = packageManager === 'npm';
-        const child = (0, child_process_1.spawn)(installCommand, {
-            shell: true,
-            stdio: ['inherit', 'inherit', shouldCaptureStderr ? 'pipe' : 'inherit'],
-            windowsHide: true,
-            cwd,
-        });
-        const stderrChunks = [];
-        child.stderr?.on('data', (chunk) => {
-            process.stderr.write(chunk);
-            stderrChunks.push(chunk);
-        });
-        child.on('error', reject);
-        child.on('close', (code) => {
-            if (code === 0) {
-                resolve();
-                return;
-            }
-            if (shouldCaptureStderr) {
-                const stderr = Buffer.concat(stderrChunks).toString().trim();
-                if (isNpmPeerDepsError(stderr)) {
-                    // Log the remediation guidance here so every caller of `runInstall`
-                    // (CLI migrate, `nx repair`, single-migration runner, etc.) surfaces
-                    // it consistently. Top-level callers catch `NpmPeerDepsInstallError`
-                    // and return a non-zero exit code without re-logging.
-                    logNpmPeerDepsError(phase);
-                    reject(new NpmPeerDepsInstallError());
-                    return;
-                }
-            }
-            reject(new Error(`Command failed: ${installCommand}`));
-        });
-    });
-}
-class NpmPeerDepsInstallError extends Error {
-    constructor() {
-        super('npm install failed due to peer dependency conflicts.');
-        this.name = 'NpmPeerDepsInstallError';
-    }
-}
-/**
- * Detects npm peer-dependency resolution failures. Keyed on the `ERESOLVE`
- * error code, which npm consistently emits for this class of failure across
- * v7+ (`npm ERR! code ERESOLVE` / `npm error code ERESOLVE`). Falls back to a
- * small set of stable phrases in case the code line is missing from the
- * captured output.
- */
-function isNpmPeerDepsError(stderr) {
-    if (/\bERESOLVE\b/.test(stderr)) {
-        return true;
-    }
-    const lowerStderr = stderr.toLowerCase();
-    return (lowerStderr.includes('unable to resolve dependency tree') ||
-        lowerStderr.includes('could not resolve dependency') ||
-        lowerStderr.includes('conflicting peer dependency'));
-}
-function logNpmPeerDepsError(phase) {
-    const peerDepsResolutionSteps = [
-        'Recommended approaches (in order of preference):',
-        '',
-        '1. Use "overrides" in package.json to force compatible versions across the dependency tree.',
-        '   See https://docs.npmjs.com/cli/configuring-npm/package-json#overrides',
-        '2. Persist legacy peer deps resolution in the project ".npmrc":',
-        '   npm config set legacy-peer-deps=true --location=project',
-        '   (bypasses peer dependency resolution; use with caution)',
-        '3. As a last resort, force the installation by running "npm install --force".',
-        '   (does not persist and may produce broken installs)',
-    ];
-    const manualInstallHint = [
-        'If you installed the dependencies manually, pass "--skip-install" to avoid re-installing them:',
-        '   nx migrate --run-migrations --skip-install',
-    ];
-    if (phase === 'pre-migration') {
-        output_1.output.error({
-            title: 'You need to resolve the peer dependency conflicts before the migration can continue',
-            bodyLines: [
-                ...peerDepsResolutionSteps,
-                '',
-                'Once the conflicts are resolved, re-run the migrations:',
-                '   nx migrate --run-migrations',
-                '',
-                ...manualInstallHint,
-            ],
-        });
-    }
-    else {
-        output_1.output.error({
-            title: 'Some migrations have been applied, but installing the updated dependencies failed',
-            bodyLines: [
-                ...peerDepsResolutionSteps,
-                '',
-                'Once the conflicts are resolved, run "npm install" to install the updated dependencies.',
-                'If the migration was interrupted before completing, re-run the remaining migrations:',
-                '   nx migrate --run-migrations',
-                '',
-                ...manualInstallHint,
-            ],
-        });
-    }
-}
-function resolveAgenticRunId(migrations) {
-    return (0, semver_1.rsort)(migrations.map((m) => (0, version_utils_1.normalizeVersion)(m.version)))[0];
-}
 function formatSkippedPromptsNextStep(skipped) {
     return [
         'Some prompt migrations were skipped. Review and apply each of the following prompt files to the workspace, in the listed order:',
         ...skipped.map((m) => `  - ${m.prompt}`),
     ].join('\n');
 }
-/**
- * Resolves the effective `--create-commits` state once the agentic flow has
- * been resolved. The agent's outer prompt only embeds the impl-phase file list
- * when per-migration commits isolate each migration's diff, so the diff-context
- * flag returned here gates that section.
- */
-function resolveCreateCommits(args) {
-    const { createCommits, agenticKind, isGitRepo, commitPrefixIsCustom } = args;
-    // Explicit `--create-commits` without git is a hard error — the user asked
-    // for something we cannot deliver.
-    if (createCommits === true && !isGitRepo) {
-        return {
-            effective: false,
-            agenticHasDiffContext: false,
-            error: '`--create-commits` requires a git repository. Run `git init` first, or omit the flag.',
-        };
-    }
-    if (agenticKind === 'enabled') {
-        if (createCommits === false) {
-            return {
-                effective: false,
-                agenticHasDiffContext: false,
-                warning: "--no-create-commits was passed alongside --agentic. Without per-migration commits, the agent can't isolate the current migration's changes from earlier migrations in this run. Drop --no-create-commits for accurate per-migration review." +
-                    (commitPrefixIsCustom
-                        ? ' Note: the custom --commit-prefix value will have no effect because commits are disabled.'
-                        : ''),
-            };
-        }
-        // Without git we cannot soft-force commits the user didn't explicitly
-        // opt into. Degrade rather than error: continue the agentic run, but
-        // without per-file diff context (which depends on per-migration commits).
-        if (!isGitRepo) {
-            return {
-                effective: false,
-                agenticHasDiffContext: false,
-                warning: '`--agentic` enables per-migration commits by default, but the workspace is not a git repository. Continuing without commits — the agent will not receive per-file diff context. Run `git init` to enable.' +
-                    (commitPrefixIsCustom
-                        ? ' The custom --commit-prefix value will have no effect.'
-                        : ''),
-            };
-        }
-        return { effective: true, agenticHasDiffContext: true };
-    }
-    // Commits aren't enabled here. A custom prefix only reaches this path via
-    // nx.json (e.g. `migrate.commitPrefix` + `migrate.agentic` when the agentic
-    // flow resolves to disabled); surface that it has no effect rather than
-    // dropping it silently.
-    return {
-        effective: createCommits === true,
-        agenticHasDiffContext: false,
-        warning: commitPrefixIsCustom && createCommits !== true
-            ? 'A custom migrate commit prefix is configured, but commits are not enabled for this run, so it has no effect. Set `migrate.createCommits` to `true` (or pass `--create-commits`) to create a commit per migration.'
-            : undefined,
-    };
-}
-/**
- * Confirms before creating per-migration commits while the user sits on the
- * repository's default branch, so migrations don't silently commit there (most
- * relevant since `--agentic` enables commits by default). Only the default
- * branch triggers a prompt; a detached HEAD, a different branch, or an
- * unresolved default branch all proceed untouched. Callers gate this on
- * commits being effective and prompting being possible, so non-interactive
- * runs (CI, `--no-interactive`) never reach here.
- */
-async function confirmCommitsOnDefaultBranch(args) {
-    const { currentBranch, defaultBranch } = args;
-    if (!currentBranch || !defaultBranch || currentBranch !== defaultBranch) {
-        return true;
-    }
-    const { proceed } = await (0, safe_prompt_1.migratePrompt)([
-        {
-            name: 'proceed',
-            type: 'confirm',
-            message: `You're on the default branch '${currentBranch}'. nx migrate will create a commit for each migration on this branch. Continue?`,
-            initial: false,
-        },
-    ]);
-    return proceed;
-}
-/**
- * Resolves whether the framework-owned generic-validation agent step should run
- * after generator-only migrations.
- *
- * Default-on when the agentic flow resolved to `enabled`; silently ignored
- * otherwise (no warning emitted) — `--validate` requires an active agent
- * session by definition. An explicit `--no-validate` (`validate === false`)
- * opts out even when agentic is enabled.
- */
-function resolveShouldRunValidation(args) {
-    return args.validate !== false && args.agenticKind === 'enabled';
-}
 async function executeMigrations(root, migrations, isVerbose, shouldCreateCommits, commitPrefix, shouldSkipInstall = false, agentic, agenticHasDiffContext = false, shouldRunValidation = false) {
-    const changedDepInstaller = new ChangedDepInstaller(root, shouldSkipInstall);
+    const changedDepInstaller = new execute_migration_1.ChangedDepInstaller(root, shouldSkipInstall);
     const migrationsWithNoChanges = [];
-    const sortedMigrations = migrations.sort((a, b) => {
-        // Under `--agentic`, hoist the v23 migration that ignores
-        // `.nx/migrate-runs` to position 0 so its .gitignore update lands
-        // before any per-migration commit absorbs the run's handoff scratch.
-        // See `agentic/handoff-gitignore.ts` for the full rationale and the
-        // inline-fallback path that covers intra-pre-v23 agentic runs.
-        if (agentic?.kind === 'enabled') {
-            if ((0, handoff_gitignore_1.isHandoffGitignoreMigration)(a))
-                return -1;
-            if ((0, handoff_gitignore_1.isHandoffGitignoreMigration)(b))
-                return 1;
-        }
-        // special case for the split configuration migration to run first
-        if (a.name === '15-7-0-split-configuration-into-project-json-files') {
-            return -1;
-        }
-        if (b.name === '15-7-0-split-configuration-into-project-json-files') {
-            return 1;
-        }
-        return (0, semver_1.lt)((0, version_utils_1.normalizeVersion)(a.version), (0, version_utils_1.normalizeVersion)(b.version))
-            ? -1
-            : 1;
+    const sortedMigrations = (0, sort_migrations_1.sortMigrations)(migrations, {
+        hoistHandoffGitignore: agentic?.kind === 'enabled',
     });
     // Lazy-load the agentic chain so non-agentic runs don't pay its startup cost.
     let agenticRun;
     if (agentic?.kind === 'enabled' && sortedMigrations.length > 0) {
-        const { initRunDir } = require('./agentic/handoff');
+        const { initRunDir, resolveAgenticRunId } = require('./agentic/handoff');
         const { runAgenticPromptStep } = require('./agentic/run-step');
         agenticRun = {
             agentic,
@@ -1939,6 +1824,23 @@ async function executeMigrations(root, migrations, isVerbose, shouldCreateCommit
         // as a commit failure.
         return { kind: 'none' };
     }
+    // Records what a migration's deterministic phase produced. A migration that
+    // changed nothing must not attempt a commit: the absorbing `git add -A`
+    // would build a commit subject naming this no-op migration even though its
+    // content is entirely prior pending diffs, confusing `git log` / `git blame`
+    // attribution. Pending stays pending and the next change-producing migration
+    // absorbs it.
+    async function commitOrRecordNoChanges(m, madeChanges) {
+        if (!madeChanges) {
+            migrationsWithNoChanges.push(m);
+            return { kind: 'none' };
+        }
+        const commit = await attemptMigrationCommit(m);
+        if (commit.kind === 'landed' && commit.sha) {
+            logger_1.logger.info(pc.dim(`Committed as ${commit.sha}`));
+        }
+        return commit;
+    }
     const totalMigrations = sortedMigrations.length;
     let migrationIndex = 0;
     for (const m of sortedMigrations) {
@@ -1959,6 +1861,11 @@ async function executeMigrations(root, migrations, isVerbose, shouldCreateCommit
             const { resolvedCollection, documentationPath } = resolveMigrationForRun(root, m, !!agenticRun);
             let outcome;
             let commit = { kind: 'none' };
+            // Set when the migration returned `skipAgentic: true` and something was
+            // actually waived, so the end-of-run recaps can report it. A hybrid's
+            // prompt is owed in every agentic mode, so waiving it always counts; a
+            // generator-only migration only counts when validation would have run.
+            let waivedAgenticStep = false;
             if ((0, migration_shape_1.isPromptOnlyMigration)(m)) {
                 if (agenticRun) {
                     inAgenticStep = true;
@@ -1983,10 +1890,19 @@ async function executeMigrations(root, migrations, isVerbose, shouldCreateCommit
                 }
             }
             else if ((0, migration_shape_1.isHybridMigration)(m)) {
-                const { changes, nextSteps, agentContext, logs, madeChanges } = await runNxOrAngularMigration(root, m, isVerbose, 
+                const { changes, nextSteps, agentContext, skipAgentic, logs, madeChanges, } = await (0, execute_migration_1.runNxOrAngularMigration)(root, m, isVerbose, 
                 /* captureGeneratorOutput: */ !!agenticRun, resolvedCollection);
                 migrationEmittedNextSteps.push(...nextSteps);
-                if (agenticRun) {
+                if (skipAgentic) {
+                    // The generator reported the prompt half unnecessary, so nothing is
+                    // owed: no agent run, and no next-steps entry telling the user to
+                    // run the prompt themselves. Runs in all three agentic modes.
+                    (0, migrate_output_1.logWaivedAgenticStep)(m, agentContext);
+                    waivedAgenticStep = true;
+                    commit = await commitOrRecordNoChanges(m, madeChanges);
+                    outcome = madeChanges ? 'applied' : 'no-changes';
+                }
+                else if (agenticRun) {
                     // Install any deps the deterministic phase added/bumped before the
                     // agent runs — the prompt half may depend on them being present in
                     // node_modules.
@@ -2025,21 +1941,7 @@ async function executeMigrations(root, migrations, isVerbose, shouldCreateCommit
                         printDroppedAgentContext({ migration: m, agentContext });
                     }
                     skippedPrompts.push(m);
-                    if (!madeChanges) {
-                        migrationsWithNoChanges.push(m);
-                    }
-                    // Only attempt a commit when this migration's deterministic
-                    // phase actually produced changes. Otherwise the absorbing
-                    // `git add -A` would build a commit subject naming this no-op
-                    // migration even though its content is entirely prior pending
-                    // diffs — confusing `git log` / `git blame` attribution. Pending
-                    // stays pending and the next change-producing migration absorbs.
-                    if (madeChanges) {
-                        commit = await attemptMigrationCommit(m);
-                    }
-                    if (commit.kind === 'landed' && commit.sha) {
-                        logger_1.logger.info(pc.dim(`Committed as ${commit.sha}`));
-                    }
+                    commit = await commitOrRecordNoChanges(m, madeChanges);
                     outcome = 'deferred';
                 }
             }
@@ -2047,10 +1949,14 @@ async function executeMigrations(root, migrations, isVerbose, shouldCreateCommit
                 // Defer commit until validation succeeds; failed validation leaves
                 // changes uncommitted in the working tree for the user to review.
                 const validationRun = agenticRun && shouldRunValidation ? agenticRun : undefined;
-                const { changes, nextSteps, agentContext, logs, madeChanges } = await runNxOrAngularMigration(root, m, isVerbose, 
+                const { changes, nextSteps, agentContext, skipAgentic, logs, madeChanges, } = await (0, execute_migration_1.runNxOrAngularMigration)(root, m, isVerbose, 
                 /* captureGeneratorOutput: */ !!validationRun, resolvedCollection);
                 migrationEmittedNextSteps.push(...nextSteps);
-                const canRunValidation = !!validationRun && changes.length > 0;
+                // Whether a validation step was on the table at all. `skipAgentic`
+                // waives nothing when it wasn't, so the whole waived path hangs off
+                // this, not just the log line.
+                const validationApplies = !!validationRun && changes.length > 0;
+                const canRunValidation = validationApplies && !skipAgentic;
                 if (canRunValidation) {
                     // Install any deps the deterministic phase added/bumped before the
                     // validation agent runs — the agent may run tasks that need them.
@@ -2081,22 +1987,17 @@ async function executeMigrations(root, migrations, isVerbose, shouldCreateCommit
                     outcome = 'applied';
                 }
                 else {
-                    // Inner validation step didn't run. Surface `agentContext` under
-                    // `inside-agent` so the outer driving agent can ingest it.
-                    if (printDroppedAgentContext && agentContext.length > 0) {
-                        printDroppedAgentContext({ migration: m, agentContext });
+                    if (skipAgentic && validationApplies) {
+                        (0, migrate_output_1.logWaivedAgenticStep)(m, agentContext);
+                        waivedAgenticStep = true;
                     }
-                    if (!madeChanges) {
-                        migrationsWithNoChanges.push(m);
-                        outcome = 'no-changes';
-                    }
-                    else {
-                        commit = await attemptMigrationCommit(m);
-                        if (commit.kind === 'landed' && commit.sha) {
-                            logger_1.logger.info(pc.dim(`Committed as ${commit.sha}`));
-                        }
-                        outcome = 'applied';
+                    else if (printDroppedAgentContext && agentContext.length > 0) {
+                        // Inner validation step didn't run. Surface `agentContext` under
+                        // `inside-agent` so the outer driving agent can ingest it.
+                        printDroppedAgentContext({ migration: m, agentContext });
                     }
+                    commit = await commitOrRecordNoChanges(m, madeChanges);
+                    outcome = madeChanges ? 'applied' : 'no-changes';
                 }
             }
             outcomes.push({
@@ -2104,6 +2005,7 @@ async function executeMigrations(root, migrations, isVerbose, shouldCreateCommit
                 status: 'completed',
                 kind: outcome,
                 commit,
+                waivedAgenticStep,
             });
             logger_1.logger.info('');
         }
@@ -2124,7 +2026,7 @@ async function executeMigrations(root, migrations, isVerbose, shouldCreateCommit
             // `nx repair` reuses executeMigrations; only record for migrate runs.
             if ((0, migrate_analytics_1.hasMigrateRunStarted)()) {
                 (0, migrate_analytics_1.reportMigrateRunError)({
-                    code: e instanceof NpmPeerDepsInstallError
+                    code: e instanceof execute_migration_1.NpmPeerDepsInstallError
                         ? 'npm_install'
                         : inAgenticStep
                             ? 'agentic'
@@ -2135,7 +2037,7 @@ async function executeMigrations(root, migrations, isVerbose, shouldCreateCommit
                     error: e,
                 });
             }
-            if (!(e instanceof NpmPeerDepsInstallError)) {
+            if (!(e instanceof execute_migration_1.NpmPeerDepsInstallError)) {
                 // `withGeneratorOutputCapture` attaches the generator's `console.*`
                 // output as `capturedLogs` (best-effort; may be absent). Surface it
                 // so the user sees what the generator printed before it crashed.
@@ -2166,7 +2068,7 @@ async function executeMigrations(root, migrations, isVerbose, shouldCreateCommit
         await installDepsIfChanged();
     }
     if (changedDepInstaller.skippedInstall) {
-        logSkippedPostMigrationInstall(root);
+        (0, execute_migration_1.logSkippedPostMigrationInstall)(root);
     }
     // Combined-view next-steps array kept for back-compat with repair.ts, which
     // consumes the single `nextSteps` field.
@@ -2182,6 +2084,7 @@ async function executeMigrations(root, migrations, isVerbose, shouldCreateCommit
         skippedPrompts,
         migrationEmittedNextSteps,
         committedShasCount: (0, migrate_output_1.countLandedCommits)(outcomes),
+        waivedAgenticStepsCount: (0, migrate_output_1.countWaivedAgenticSteps)(outcomes),
         // Migrations whose commits failed and never got absorbed by a later
         // commit. The caller surfaces them so a successful run doesn't claim
         // "up to date" while leaving uncommitted diffs in the working tree.
@@ -2189,106 +2092,27 @@ async function executeMigrations(root, migrations, isVerbose, shouldCreateCommit
         retainedAtSuccess: (0, migrate_output_1.retainedMigrations)(outcomes).map((p) => `${p.package}: ${p.name}`),
     };
 }
-class ChangedDepInstaller {
-    constructor(root, shouldSkipInstall = false) {
-        this.root = root;
-        this.shouldSkipInstall = shouldSkipInstall;
-        this._skippedInstall = false;
-        this.initialDeps = getStringifiedPackageJsonDeps(root);
-    }
-    get skippedInstall() {
-        return this._skippedInstall;
-    }
-    async installDepsIfChanged() {
-        const currentDeps = getStringifiedPackageJsonDeps(this.root);
-        if (this.initialDeps !== currentDeps) {
-            if (this.shouldSkipInstall) {
-                this._skippedInstall = true;
-            }
-            else {
-                await runInstall(this.root, 'post-migration');
-            }
-        }
-        this.initialDeps = currentDeps;
-    }
-}
-exports.ChangedDepInstaller = ChangedDepInstaller;
-function logSkippedPostMigrationInstall(root) {
-    const packageManager = (0, package_manager_1.detectPackageManager)(root);
-    const installCommand = (0, package_manager_1.getPackageManagerCommand)(packageManager, root).install;
-    output_1.output.warn({
-        title: 'Migrations updated your dependencies, but the install was skipped',
-        bodyLines: [`Run "${installCommand}" to install the updated dependencies.`],
-    });
-}
-async function runNxOrAngularMigration(root, migration, isVerbose, captureGeneratorOutput = false, resolvedCollection) {
-    const { collection, collectionPath } = resolvedCollection ?? readMigrationCollection(migration.package, root);
-    let changes = [];
-    let nextSteps = [];
-    let agentContext = [];
-    let logs = '';
-    // Angular's `ngResult.changes` is synthesized from the schematic's
-    // DryRunEvent stream so Nx and Angular paths can share commit/validation
-    // gating via `changes.length > 0`.
-    let madeChanges = false;
-    logger_1.logger.info(pc.dim('→ Running generator…'));
-    if (!isAngularMigration(collection, migration.name)) {
-        ({ nextSteps, changes, agentContext, logs } = await runNxMigration(root, collectionPath, collection, migration.name, migration.version, captureGeneratorOutput));
-        madeChanges = changes.length > 0;
-        logger_1.logger.info(`Ran ${migration.name} from ${migration.package}`);
-        if (migration.description) {
-            logger_1.logger.info(`  ${migration.description}`);
-        }
-        logger_1.logger.info('');
-        if (!madeChanges) {
-            logger_1.logger.info(`No changes were made\n`);
-            return { changes, nextSteps, agentContext, logs, madeChanges };
-        }
-        logger_1.logger.info('Changes:');
-        (0, tree_1.printChanges)(changes, '  ');
-        logger_1.logger.info('');
-    }
-    else {
-        const ngCliAdapter = await getNgCompatLayer();
-        const migrationProjectGraph = await (0, project_graph_1.createProjectGraphAsync)();
-        const ngResult = await ngCliAdapter.runMigration(root, migration.package, migration.name, (0, project_graph_1.readProjectsConfigurationFromProjectGraph)(migrationProjectGraph).projects, isVerbose, migrationProjectGraph);
-        changes = ngResult.changes;
-        madeChanges = ngResult.madeChanges;
-        logs = ngResult.loggingQueue.join('\n');
-        logger_1.logger.info(`Ran ${migration.name} from ${migration.package}`);
-        if (migration.description) {
-            logger_1.logger.info(`  ${migration.description}`);
-        }
-        logger_1.logger.info('');
-        if (!madeChanges) {
-            logger_1.logger.info(`No changes were made\n`);
-            return { changes, nextSteps, agentContext, logs, madeChanges };
-        }
-        logger_1.logger.info('Changes:');
-        ngResult.loggingQueue.forEach((log) => logger_1.logger.info('  ' + log));
-        logger_1.logger.info('');
-    }
-    return { changes, nextSteps, agentContext, logs, madeChanges };
+// nx is located at spawn time, after the gated pre-install, so the child runs
+// the bytes that install put in place.
+function handOffToLocalNx(args) {
+    const exitCode = runOrReturnExitCode(() => (0, child_process_2.runNxArgvSync)(['migrate', ...args], {
+        stdio: ['inherit', 'inherit', 'inherit'],
+        env: {
+            ...process.env,
+            NX_MIGRATE_SKIP_INSTALL: 'true',
+            NX_MIGRATE_USE_LOCAL: 'true',
+        },
+    }));
+    return exitCode !== 0 ? exitCode : undefined;
 }
 async function runMigrations(root, opts, args, isVerbose, shouldCreateCommits, commitPrefix, shouldSkipInstall = false) {
     if (!shouldSkipInstall && !process.env.NX_MIGRATE_SKIP_INSTALL) {
-        await runInstall();
+        await (0, execute_migration_1.runInstall)();
     }
     if (!__dirname.startsWith(workspace_root_1.workspaceRoot)) {
         // we are running from a temp installation with nx latest, switch to running
         // from local installation
-        const exitCode = runOrReturnExitCode(() => (0, child_process_2.runNxSync)(`migrate ${args.join(' ')}`, {
-            stdio: ['inherit', 'inherit', 'inherit'],
-            env: {
-                ...process.env,
-                NX_MIGRATE_SKIP_INSTALL: 'true',
-                NX_MIGRATE_USE_LOCAL: 'true',
-            },
-        }));
-        if (exitCode !== 0) {
-            return exitCode;
-        }
-        return;
+        return handOffToLocalNx(args);
     }
     const migrationsExists = (0, fileutils_1.fileExists)(opts.runMigrations);
     if (opts.ifExists && !migrationsExists) {
@@ -2300,12 +2124,53 @@ async function runMigrations(root, opts, args, isVerbose, shouldCreateCommits, c
     else if (!opts.ifExists && !migrationsExists) {
         throw new Error(`File '${opts.runMigrations}' doesn't exist, can't run migrations. Use flag --if-exists to run migrations only if the file exists`);
     }
-    const migrations = (0, fileutils_1.readJsonFile)((0, path_1.join)(root, opts.runMigrations)).migrations;
+    const migrationsJson = (0, fileutils_1.readJsonFile)((0, path_1.join)(root, opts.runMigrations));
+    const migrations = migrationsJson.migrations;
+    // An outer agent drives the loop, so hand off to the orchestrator instead of
+    // the classic loop: init either starts a fresh run or resumes an already-
+    // active one. `--run-id` reconciles are dispatched separately and never
+    // reach here.
+    if (process.env.NX_MIGRATE_ORCHESTRATOR === 'true' && (0, inception_1.isInsideAgent)()) {
+        // Orchestrated runs are agent-driven, so commits default on exactly as they
+        // do under `--agentic=enabled`; the orchestrator replaces `resolveAgentic`.
+        const { effective: effectiveCreateCommits, warning: createCommitsWarning, error: createCommitsError, } = (0, migrate_commits_1.resolveCreateCommits)({
+            createCommits: shouldCreateCommits,
+            mode: 'orchestrated',
+            isGitRepo: (0, git_utils_1.isGitRepository)(root),
+            commitPrefixIsCustom: commitPrefix !== command_object_1.DEFAULT_MIGRATION_COMMIT_PREFIX,
+        });
+        if (createCommitsError) {
+            throw new Error(createCommitsError);
+        }
+        if (createCommitsWarning) {
+            output_1.output.warn({ title: createCommitsWarning });
+        }
+        // The run commits on the user's behalf across many invocations, so the
+        // default-branch confirmation belongs here, once, before any of them.
+        if (effectiveCreateCommits &&
+            (0, safe_prompt_1.canPrompt)(opts.interactive) &&
+            !(await (0, migrate_commits_1.confirmMigrationCommitsOnDefaultBranch)(root, 'running migrations'))) {
+            return;
+        }
+        const { packageJson: orchestratorNxPackageJson } = (0, package_json_1.readModulePackageJson)('nx', (0, installation_directory_1.getNxRequirePaths)(root));
+        const { runOrchestratorInit } = require('./run');
+        return await runOrchestratorInit({
+            root,
+            migrationsJson,
+            createCommits: effectiveCreateCommits,
+            commitPrefix,
+            // The flag only, never NX_MIGRATE_SKIP_INSTALL: the wrapper's local
+            // re-exec sets that env var for its own hop, and it says nothing about
+            // what the user asked for.
+            skipInstall: shouldSkipInstall,
+            installedNxVersion: orchestratorNxPackageJson.version,
+        });
+    }
     (0, migrate_analytics_1.reportMigrateRunStart)({
         createCommits: shouldCreateCommits ?? false,
         migrationCount: migrations.length,
     });
-    const { resolveAgentic } = require('./agentic/select');
+    const { resolveAgentic, resolveShouldRunValidation } = require('./agentic/select');
     let agentic;
     try {
         agentic = await resolveAgentic({
@@ -2318,9 +2183,9 @@ async function runMigrations(root, opts, args, isVerbose, shouldCreateCommits, c
         (0, migrate_analytics_1.reportMigrateRunError)({ code: 'agentic', error: e });
         throw e;
     }
-    const { effective: effectiveCreateCommits, agenticHasDiffContext, warning: createCommitsWarning, error: createCommitsError, } = resolveCreateCommits({
+    const { effective: effectiveCreateCommits, agenticHasDiffContext, warning: createCommitsWarning, error: createCommitsError, } = (0, migrate_commits_1.resolveCreateCommits)({
         createCommits: shouldCreateCommits,
-        agenticKind: agentic.kind,
+        mode: agentic.kind,
         isGitRepo: (0, git_utils_1.isGitRepository)(root),
         commitPrefixIsCustom: commitPrefix !== command_object_1.DEFAULT_MIGRATION_COMMIT_PREFIX,
     });
@@ -2330,24 +2195,10 @@ async function runMigrations(root, opts, args, isVerbose, shouldCreateCommits, c
     if (createCommitsWarning) {
         output_1.output.warn({ title: createCommitsWarning });
     }
-    if (effectiveCreateCommits && (0, safe_prompt_1.canPrompt)(opts.interactive)) {
-        const currentBranch = (0, git_utils_1.getGitCurrentBranch)(root);
-        // `getBaseRef` may carry an `origin/` prefix (set by the CI-workflow
-        // generator); compare against the local branch name.
-        const defaultBranch = (0, command_line_utils_1.getBaseRef)((0, configuration_1.readNxJson)(root)).replace(/^origin\//, '');
-        const proceed = await confirmCommitsOnDefaultBranch({
-            currentBranch,
-            defaultBranch,
-        });
-        if (!proceed) {
-            output_1.output.log({
-                title: `Skipped running migrations to avoid committing to the default branch '${currentBranch}'.`,
-                bodyLines: [
-                    'Switch to a different branch and re-run, or re-run and confirm to proceed.',
-                ],
-            });
-            return;
-        }
+    if (effectiveCreateCommits &&
+        (0, safe_prompt_1.canPrompt)(opts.interactive) &&
+        !(await (0, migrate_commits_1.confirmMigrationCommitsOnDefaultBranch)(root, 'running migrations'))) {
+        return;
     }
     const shouldRunValidation = resolveShouldRunValidation({
         validate: opts.validate,
@@ -2363,8 +2214,9 @@ async function runMigrations(root, opts, args, isVerbose, shouldCreateCommits, c
         (0, migrate_commits_1.commitCheckpointBeforeMigrations)(root, commitPrefix);
     }
     if (agentic.kind === 'enabled') {
+        const { applyAgenticHandoffGitignoreFallback } = require('./agentic/handoff-gitignore');
         const { packageJson: nxPackageJson } = (0, package_json_1.readModulePackageJson)('nx', (0, installation_directory_1.getNxRequirePaths)(root));
-        await (0, handoff_gitignore_1.applyAgenticHandoffGitignoreFallback)({
+        await applyAgenticHandoffGitignoreFallback({
             migrations,
             installedNxVersion: nxPackageJson.version,
             effectiveCreateCommits,
@@ -2372,7 +2224,7 @@ async function runMigrations(root, opts, args, isVerbose, shouldCreateCommits, c
             root,
         });
     }
-    const { migrationsWithNoChanges, skippedPromptsCount, notRunMigrationsCount, skippedPrompts, migrationEmittedNextSteps, committedShasCount, retainedAtSuccess, } = await executeMigrations(root, migrations, isVerbose, effectiveCreateCommits, commitPrefix, shouldSkipInstall, agentic, agenticHasDiffContext, shouldRunValidation);
+    const { migrationsWithNoChanges, skippedPromptsCount, notRunMigrationsCount, skippedPrompts, migrationEmittedNextSteps, committedShasCount, waivedAgenticStepsCount, retainedAtSuccess, } = await executeMigrations(root, migrations, isVerbose, effectiveCreateCommits, commitPrefix, shouldSkipInstall, agentic, agenticHasDiffContext, shouldRunValidation);
     const ranWithChangesCount = migrations.length - notRunMigrationsCount - migrationsWithNoChanges.length;
     // The "applied" tally counts fully-completed migrations — those that
     // left no deferred work behind. Hybrid migrations whose prompt half was
@@ -2383,6 +2235,7 @@ async function runMigrations(root, opts, args, isVerbose, shouldCreateCommits, c
         appliedCount,
         committedShasCount,
         skippedPromptsCount,
+        waivedAgenticStepsCount,
         insideAgent,
     });
     const tallyBody = tallyLine ? [tallyLine] : undefined;
@@ -2464,71 +2317,30 @@ async function runMigrations(root, opts, args, isVerbose, shouldCreateCommits, c
         appliedCount,
     });
 }
-function getStringifiedPackageJsonDeps(root) {
-    try {
-        const { dependencies, devDependencies } = (0, fileutils_1.readJsonFile)((0, path_1.join)(root, 'package.json'));
-        return JSON.stringify([dependencies, devDependencies]);
-    }
-    catch {
-        // We don't really care if the .nx/installation property changes,
-        // whenever nxw is invoked it will handle the dep updates.
-        return '';
-    }
-}
-async function runNxMigration(root, collectionPath, collection, name, migrationVersion, captureGeneratorOutput) {
-    const { path: implPath, fnSymbol } = getImplementationPath(collection, collectionPath, name, migrationVersion);
-    const fn = require(implPath)[fnSymbol];
-    const host = new tree_1.FsTree(root, process.env.NX_VERBOSE_LOGGING === 'true', `migration ${collection.name}:${name}`);
-    let result;
-    let logs = '';
-    if (captureGeneratorOutput) {
-        const { withGeneratorOutputCapture } = require('./agentic/capture-generator-output');
-        ({ result, logs } = await withGeneratorOutputCapture(() => fn(host, {})));
-    }
-    else {
-        result = await fn(host, {});
-    }
-    const { nextSteps, agentContext } = parseMigrationReturn(result);
-    host.lock();
-    const changes = host.listChanges();
-    (0, tree_1.flushChanges)(root, changes);
-    return { changes, nextSteps, agentContext, logs };
-}
-function parseMigrationReturn(value) {
-    if (Array.isArray(value)) {
-        return { nextSteps: filterStrings(value), agentContext: [] };
-    }
-    if (value && typeof value === 'object') {
-        const obj = value;
-        return {
-            nextSteps: filterStrings(obj.nextSteps),
-            agentContext: filterStrings(obj.agentContext),
-        };
-    }
-    // Catches `void`, mistakenly-returned generator callbacks, malformed values.
-    return { nextSteps: [], agentContext: [] };
-}
-// Bucket-level tolerance: a single non-string entry shouldn't discard the
-// whole `nextSteps` / `agentContext` array. Migration authors occasionally
-// push `null` / `undefined` / a number into the array; we drop the bad entries
-// and keep the rest so end-of-run guidance isn't silently lost.
-function filterStrings(value) {
-    if (!Array.isArray(value))
-        return [];
-    return value.filter((v) => typeof v === 'string');
+function isRunPhaseInvocation(args) {
+    return (args.runMigration !== undefined ||
+        args.runId !== undefined ||
+        args.stepAction !== undefined);
 }
 async function migrate(root, args, rawArgs) {
     await client_1.daemonClient.stop();
     return (0, handle_errors_1.handleErrors)(process.env.NX_VERBOSE_LOGGING === 'true', async () => {
         const mergedArgs = (0, migrate_config_1.applyNxJsonMigrateDefaults)(args, (0, configuration_1.readNxJson)().migrate);
-        (0, migrate_config_1.assertCommitPrefixHasCommits)(mergedArgs);
+        // Run-phase invocations resolve their commit config downstream (run.json
+        // for recorded runs, resolveCreateCommits for standalone), so this assert
+        // must not fire for them; otherwise an nx.json prefix the whole-file run
+        // legitimately uses would wedge every dispensed command.
+        const runPhase = isRunPhaseInvocation(mergedArgs);
+        if (!runPhase) {
+            (0, migrate_config_1.assertCommitPrefixHasCommits)(mergedArgs);
+        }
         // One fetcher (registry-first, install fallback) shared by the `--include`
         // eligibility gate and the migration cascade so package metadata is fetched
         // at most once per package/version.
         const fetch = createFetcher((0, package_manager_1.getPackageManagerCommand)());
-        // `--run-migrations` without a value parses as '' - undefined means the
-        // generate phase.
-        const isGenerateInvocation = mergedArgs['runMigrations'] === undefined;
+        // `--run-migrations` without a value parses as '', so only undefined (and
+        // no run-phase flag) means the generate phase.
+        const isGenerateInvocation = mergedArgs['runMigrations'] === undefined && !runPhase;
         let opts;
         try {
             opts = await parseMigrationsOptions(mergedArgs, fetch);
@@ -2537,36 +2349,320 @@ async function migrate(root, args, rawArgs) {
             if (isGenerateInvocation) {
                 (0, migrate_analytics_1.reportMigrateGenerateError)('resolve_version', e);
             }
+            else if (runPhase) {
+                (0, migrate_analytics_1.reportMigrateRunError)({ code: 'other', error: e });
+            }
             throw e;
         }
-        if (opts.type === 'generateMigrations') {
-            await generateMigrationsJsonAndUpdatePackageJson(root, opts, fetch);
+        switch (opts.type) {
+            case 'generateMigrations':
+                await generateMigrationsJsonAndUpdatePackageJson(root, opts, fetch);
+                return;
+            case 'runSingleMigration':
+                try {
+                    return await runSingleMigrationFromCli(root, opts, rawArgs, mergedArgs);
+                }
+                catch (e) {
+                    // `runInstall` already logged the remediation; returning instead of
+                    // rethrowing keeps `handleErrors` from printing a stack over it.
+                    if (e instanceof execute_migration_1.NpmPeerDepsInstallError) {
+                        (0, migrate_analytics_1.reportMigrateRunError)({ code: 'npm_install', error: e });
+                        return 1;
+                    }
+                    (0, migrate_analytics_1.reportMigrateRunError)({ code: 'other', error: e });
+                    throw e;
+                }
+            case 'orchestratorReconcile':
+                return await runOrchestratorReconcileFromCli(root, opts, rawArgs);
+            case 'runMigrations':
+                try {
+                    return await runMigrations(root, opts, rawArgs, mergedArgs['verbose'], mergedArgs['createCommits'], mergedArgs['commitPrefix'] ?? command_object_1.DEFAULT_MIGRATION_COMMIT_PREFIX, mergedArgs['skipInstall']);
+                }
+                catch (e) {
+                    if (e instanceof execute_migration_1.NpmPeerDepsInstallError) {
+                        (0, migrate_analytics_1.reportMigrateRunError)({ code: 'npm_install', error: e });
+                        return 1;
+                    }
+                    (0, migrate_analytics_1.reportMigrateRunError)({ code: 'other', error: e });
+                    throw e;
+                }
+            default: {
+                // `unhandled: never` makes a new invocation type a compile error here
+                // rather than a silent fall-through.
+                const unhandled = opts;
+                throw new Error(`Unhandled migrate invocation type: ${JSON.stringify(unhandled)}`);
+            }
         }
-        else {
-            try {
-                return await runMigrations(root, opts, rawArgs, mergedArgs['verbose'], mergedArgs['createCommits'], mergedArgs['commitPrefix'] ?? command_object_1.DEFAULT_MIGRATION_COMMIT_PREFIX, mergedArgs['skipInstall']);
+    });
+}
+// Evaluated manifest code can throw any value: a null-prototype object defeats
+// String() (the Object.prototype.toString rung catches it), and a revoked
+// proxy defeats that too. Interpolating either in a catch would throw again
+// and escape the catch.
+function stringifyCaught(e) {
+    try {
+        return String(e);
+    }
+    catch {
+        try {
+            return Object.prototype.toString.call(e);
+        }
+        catch {
+            return '<unprintable value>';
+        }
+    }
+}
+// A resolver-based lookup (including `resolvePackageJsonWithoutCachePollution`,
+// which does defeat Node's package self-reference) is the wrong tool here:
+// resolvers fall back to NODE_PATH after the explicit paths, and NODE_PATH
+// names the temp installation when this runs there. The scan below reads its
+// candidate directories itself, so neither NODE_PATH nor self-reference can
+// reach it; `getNxBin` (utils/child-process.ts), which locates the nx the
+// hand-off spawns, avoids resolvers for the same reason, over a narrower set
+// of directories: it skips `.nx/installation`, declines a root without a
+// package.json, and stops at the nearest install rather than reading past an
+// unusable one. The PnP branch below stays bespoke either way: a resolver
+// cannot see into the zip cache without the PnP runtime.
+function readLocalNxVersion(root) {
+    // A PnP manifest is consulted only when yarn drives the hand-off:
+    // `getRunNxBaseCommand` builds the hand-off command through this same
+    // detectPackageManager call (which answers from nx.json's
+    // cli.packageManager first, before any lockfile), and yarn is the one
+    // package manager that executes the manifest's nx. That mirror alone
+    // cannot see a switch off yarn, because yarn.lock survives one and
+    // outranks all but bun's lockfiles in the detection order, while .pnp.cjs
+    // lingers only on a switch to another package manager (yarn removes it
+    // when moving to node_modules linking). A rival lockfile beside the
+    // manifest is therefore read as evidence of such a switch, though not
+    // proof, since `pnpm install --lockfile-only` writes one without
+    // installing: on a scan miss the manifest still answers rather than
+    // failing the guards, and a rival install over a still-live PnP
+    // workspace is read over the PnP nx the yarn spawn executes, because
+    // preferring the manifest would judge the dead install that a completed
+    // switch leaves behind and refuse persistently. The known misread left
+    // is yarn classic driving a workspace with a leftover Berry manifest
+    // and no other lockfile; telling the two yarns apart from disk is not
+    // worth the fragility, and a `yarn node` runtime probe was rejected
+    // because its stdout is forgeable through an inherited NODE_OPTIONS
+    // preload and a hung descendant holding the output pipe outlives a
+    // subprocess timeout on this synchronous path.
+    const pnpManifest = ['.pnp.cjs', '.pnp.js']
+        .map((f) => (0, path_1.join)(root, f))
+        .find((f) => (0, fs_1.existsSync)(f));
+    if (pnpManifest) {
+        const competingLockfile = [
+            'package-lock.json',
+            'npm-shrinkwrap.json',
+            'pnpm-lock.yaml',
+            'bun.lockb',
+            'bun.lock',
+        ].some((f) => (0, fs_1.existsSync)((0, path_1.join)(root, f)));
+        if (competingLockfile) {
+            const version = scanNodeModulesForNxVersion(root);
+            if (version) {
+                return version;
             }
-            catch (e) {
-                // The remediation guidance is already logged by `runInstall`; swallow
-                // the error here so `handleErrors` doesn't print a noisy stack after
-                // the friendly output.
-                if (e instanceof NpmPeerDepsInstallError) {
-                    (0, migrate_analytics_1.reportMigrateRunError)({ code: 'npm_install', error: e });
-                    return 1;
+        }
+        try {
+            if ((0, package_manager_1.detectPackageManager)(root) === 'yarn') {
+                // Compiled manually rather than required: a require would serve the
+                // stale cached copy the runtime loaded at startup. new Function does
+                // not strip a leading shebang like the CJS loader, so drop it here.
+                const manifestModule = {
+                    exports: {},
+                };
+                new Function('module', 'exports', 'require', '__dirname', '__filename', (0, fs_1.readFileSync)(pnpManifest, 'utf-8').replace(/^#!.*/, ''))(manifestModule, manifestModule.exports, require, root, pnpManifest);
+                const packageJsonPath = manifestModule.exports.resolveRequest('nx/package.json', (0, path_1.join)(root, 'package.json'));
+                if (packageJsonPath) {
+                    // A resolving manifest names the install the yarn spawn runs, so
+                    // every branch below returns rather than falling through to the
+                    // ancestor scan.
+                    try {
+                        const { version } = (0, fileutils_1.readJsonFile)(packageJsonPath);
+                        if (typeof version === 'string') {
+                            logger_1.logger.verbose(`Read the workspace's nx version ${version} from '${packageJsonPath}'.`);
+                            return version;
+                        }
+                        logger_1.logger.verbose(`'${packageJsonPath}' does not declare a usable version.`);
+                        return undefined;
+                    }
+                    catch (readError) {
+                        // A zip-served path (installs with scripts disabled keep nx
+                        // zipped) cannot be read without the PnP runtime's zip fs, but
+                        // the manifest's own locator still names the version (e.g.
+                        // 'virtual:<hash>#npm:23.1.0').
+                        let version;
+                        try {
+                            const reference = manifestModule.exports.findPackageLocator?.(packageJsonPath)?.reference;
+                            version =
+                                typeof reference === 'string'
+                                    ? reference.match(/npm:([^#:]+)/)?.[1]
+                                    : undefined;
+                        }
+                        catch (locatorError) {
+                            logger_1.logger.verbose(`Could not read the nx locator from the PnP manifest '${pnpManifest}': ${stringifyCaught(locatorError)}`);
+                        }
+                        if (version && (0, semver_1.valid)(version)) {
+                            logger_1.logger.verbose(`Read the workspace's nx version ${version} from the locator in the PnP manifest '${pnpManifest}'.`);
+                            return version;
+                        }
+                        logger_1.logger.verbose(`Could not read the workspace's nx version through the PnP manifest '${pnpManifest}': ${stringifyCaught(readError)}`);
+                        return undefined;
+                    }
                 }
-                (0, migrate_analytics_1.reportMigrateRunError)({ code: 'other', error: e });
-                throw e;
             }
         }
+        catch (e) {
+            // Degrade to the full scan: neither a failed detection nor an
+            // unevaluable manifest can name the spawn's nx.
+            logger_1.logger.verbose(`Could not read the workspace's nx version through the PnP manifest '${pnpManifest}': ${stringifyCaught(e)}`);
+        }
+    }
+    return scanNodeModulesForNxVersion(root);
+}
+// The workspace's own install locations first (.nx/installation, root), then
+// ancestor directories: package-manager executable lookup ascends (npx and
+// bun always, pnpm and yarn inside an outer workspace) and hoisted layouts
+// install nx above the workspace root. `getNxBin` ascends too, so an ancestor
+// read here is usually the one the hand-off spawns. They diverge for a
+// `.nx/installation` workspace, which `getNxBin` declines, and where the only
+// nx found sits past the package manager's own lookup boundary and the spawn
+// has fallen back to that manager: yarn then reports "command not found"
+// while pnpm exec lands on an nx on PATH. The version read here is therefore
+// the readable answer, not necessarily the executed one.
+function scanNodeModulesForNxVersion(root) {
+    const searchPaths = [...(0, installation_directory_1.getNxRequirePaths)(root)];
+    for (let dir = (0, path_1.dirname)(root);; dir = (0, path_1.dirname)(dir)) {
+        searchPaths.push(dir);
+        if (dir === (0, path_1.dirname)(dir)) {
+            break;
+        }
+    }
+    return readNxVersionFromNodeModules(searchPaths);
+}
+function readNxVersionFromNodeModules(searchPaths) {
+    for (const searchPath of searchPaths) {
+        const packageJsonPath = (0, path_1.join)(searchPath, 'node_modules', 'nx', 'package.json');
+        try {
+            if ((0, fs_1.existsSync)(packageJsonPath)) {
+                const { version } = (0, fileutils_1.readJsonFile)(packageJsonPath);
+                if (typeof version === 'string') {
+                    logger_1.logger.verbose(`Resolved nx version ${version} from '${packageJsonPath}'.`);
+                    return version;
+                }
+                logger_1.logger.verbose(`'${packageJsonPath}' does not declare a usable version; continuing the search.`);
+            }
+        }
+        catch (e) {
+            logger_1.logger.verbose(`Could not read the workspace's installed nx version from '${packageJsonPath}': ${e}`);
+        }
+    }
+    return undefined;
+}
+// Mirrors the local-nx hand-off of the other run paths so a reconcile always
+// executes against the workspace-local nx that owns the run state, never the
+// temp installation. Reconciles only read state and commit, so no install.
+async function runOrchestratorReconcileFromCli(root, opts, args) {
+    if (!__dirname.startsWith(workspace_root_1.workspaceRoot)) {
+        // The workspace-local nx we are about to hand off to must be new enough to
+        // understand the new flags we forward to it.
+        (0, version_skew_guard_1.assertWorkspaceNxSupportsNewMigrateFlags)({
+            argv: args,
+            readLocalNxVersion: () => readLocalNxVersion(root),
+        });
+        return handOffToLocalNx(args);
+    }
+    const { runOrchestratorReconcile } = require('./run');
+    return runOrchestratorReconcile({
+        root,
+        runId: opts.runId,
+        stepAction: opts.stepAction,
+    });
+}
+// Keeps `--run-migration` behaving like `--run-migrations` when invoked from
+// a temp `nx@latest` install: same pre-install, same local-nx hand-off.
+async function runSingleMigrationFromCli(root, opts, args, mergedArgs) {
+    const shouldSkipInstall = mergedArgs['skipInstall'] ?? false;
+    // A recorded execution skips the pre-install: the run carries its own
+    // install policy and its worker installs what the migration changed, so
+    // paying for a full install ahead of every dispensed command would be
+    // redundant.
+    if (opts.runId === undefined &&
+        !shouldSkipInstall &&
+        !process.env.NX_MIGRATE_SKIP_INSTALL) {
+        await (0, execute_migration_1.runInstall)(undefined, 'pre-migration', (0, execute_migration_1.formatSingleMigrationRerunCommand)(opts.runMigration));
+    }
+    if (!__dirname.startsWith(workspace_root_1.workspaceRoot)) {
+        // Must stay after the pre-install: it reads the version that install may
+        // have just updated, so checking earlier would falsely refuse a workspace
+        // whose package.json bump was not installed yet.
+        (0, version_skew_guard_1.assertWorkspaceNxSupportsNewMigrateFlags)({
+            argv: args,
+            // `workspaceRoot`, not `root`: the migrate flow's `root` is the
+            // invocation directory, which may sit below the workspace the hand-off
+            // resolves nx in.
+            readLocalNxVersion: () => readLocalNxVersion(workspace_root_1.workspaceRoot),
+        });
+        return handOffToLocalNx(args);
+    }
+    // The worker resolves the agentic flow, the effective commit config, and
+    // the default-branch confirmation itself; hand it the raw flags. Recorded
+    // runs (--run-id) take their commit config from run.json instead.
+    // Lazy-load run/ so plain migrate and repair runs don't pay for the agentic
+    // selection chain its barrel pulls in eagerly.
+    const { runSingleMigrationWorker } = require('./run');
+    await runSingleMigrationWorker({
+        root,
+        runMigration: opts.runMigration,
+        runId: opts.runId,
+        agentic: opts.agentic,
+        validate: opts.validate,
+        createCommits: mergedArgs['createCommits'],
+        commitPrefix: mergedArgs['commitPrefix'] ??
+            command_object_1.DEFAULT_MIGRATION_COMMIT_PREFIX,
+        interactive: opts.interactive,
+        skipInstall: shouldSkipInstall,
+        isVerbose: mergedArgs['verbose'] ?? false,
     });
 }
 async function runMigration() {
     return (0, handle_errors_1.handleErrors)(process.env.NX_VERBOSE_LOGGING === 'true', async () => {
-        const runLocalMigrate = () => runOrReturnExitCode(() => (0, child_process_2.runNxSync)(`_migrate ${process.argv.slice(3).join(' ')}`, {
+        // Spawning `nx _migrate` re-resolves the workspace's nx, normally the
+        // very installation running this code: bin/nx.ts delegated the outer
+        // `migrate` command to it, while `_migrate` skips that delegation. A
+        // new-flag invocation reaching this fallback therefore lands on an nx
+        // that parsed the flags, so it needs no capability check. Two lookups
+        // can still diverge from the running install, both properties of the
+        // spawn machinery rather than of this fallback: a `.nx/installation`
+        // beside a root package.json, and, once the spawn falls back to the
+        // package manager, a lookup that misses the workspace install and lands
+        // on an nx on PATH (pnpm exec).
+        const forwardedArgv = process.argv.slice(3);
+        const runLocalMigrate = () => runOrReturnExitCode(() => (0, child_process_2.runNxArgvSync)(['_migrate', ...forwardedArgv], {
             stdio: ['inherit', 'inherit', 'inherit'],
         }));
-        if (process.env.NX_USE_LOCAL !== 'true' &&
+        if (!(0, version_skew_guard_1.targetsExistingRun)(process.argv.slice(3)) &&
+            process.env.NX_USE_LOCAL !== 'true' &&
             process.env.NX_MIGRATE_USE_LOCAL === undefined) {
+            // The version spec mirrors nxCliPath's; keep the two in sync.
+            const cliVersionSpec = process.env.NX_MIGRATE_CLI_VERSION || 'latest';
+            const target = await (0, version_skew_guard_1.resolveNewMigrateFlagsRunTarget)({
+                argv: process.argv.slice(3),
+                cliVersionSpec,
+                fromEnvOverride: !!process.env.NX_MIGRATE_CLI_VERSION,
+                ownNxVersion: versions_1.nxVersion,
+                resolveVersion: (spec) => 
+                // A probe must not prompt, write pnpm excludes, or install; a
+                // minimum-release-age violation surfaces as a rejection and
+                // routes local.
+                (0, resolve_package_version_1.resolvePackageVersionRespectingMinReleaseAge)('nx', spec, {
+                    applySideEffects: false,
+                }),
+                readLocalNxVersion: () => readLocalNxVersion(workspace_root_1.workspaceRoot),
+            });
+            if (target === 'local-nx') {
+                return runLocalMigrate();
+            }
             const p = await nxCliPath();
             if (p === null) {
                 return runLocalMigrate();
@@ -2577,47 +2673,30 @@ async function runMigration() {
                 process.env.npm_config_registry.match(/^https:\/\/registry\.(npmjs\.org|yarnpkg\.com)/)) {
                 delete process.env.npm_config_registry;
             }
-            return runOrReturnExitCode(() => (0, child_process_1.execSync)(`${p} _migrate ${process.argv.slice(3).join(' ')}`, {
-                stdio: ['inherit', 'inherit', 'inherit'],
-                windowsHide: true,
-            }));
+            // Intentionally not the workspace's nx: `p` is an nx CLI freshly
+            // installed into a temp dir by nxCliPath() (latest, or
+            // NX_MIGRATE_CLI_VERSION), so migrations run with an up-to-date migrate
+            // implementation. `p` is <tmpDir>/node_modules/.bin/nx, a shell shim;
+            // spawning the entry point that install's own manifest names instead
+            // keeps the forwarded argv out of a shell. That install declares nx
+            // itself, so it is read without ascending: an nx above the temp dir is
+            // one nothing asked for, and the shim below is the answer instead.
+            const tempNxEntry = (0, child_process_2.readInstalledNxBin)((0, path_1.dirname)((0, path_1.dirname)((0, path_1.dirname)(p))));
+            return runOrReturnExitCode(() => tempNxEntry
+                ? (0, child_process_2.runNxArgvSync)(['_migrate', ...forwardedArgv], {
+                    stdio: ['inherit', 'inherit', 'inherit'],
+                    nxBin: tempNxEntry,
+                })
+                : (0, child_process_1.execSync)(`${(0, shell_quoting_1.quoteShellArg)(p)} _migrate ${forwardedArgv
+                    .map(shell_quoting_1.quoteShellArg)
+                    .join(' ')}`, {
+                    stdio: ['inherit', 'inherit', 'inherit'],
+                    windowsHide: true,
+                }));
         }
         return runLocalMigrate();
     });
 }
-function readMigrationCollection(packageName, root) {
-    const collectionPath = readPackageMigrationConfig(packageName, root).migrations;
-    const collection = (0, fileutils_1.readJsonFile)(collectionPath);
-    collection.name ??= packageName;
-    return {
-        collection,
-        collectionPath,
-    };
-}
-function getImplementationPath(collection, collectionPath, name, migrationVersion) {
-    const g = collection.generators?.[name] || collection.schematics?.[name];
-    if (!g) {
-        throw new MigrationImplementationMissingError(`Unable to determine implementation path for "${collectionPath}:${name}"`, collectionPath, migrationVersion);
-    }
-    const implRelativePathAndMaybeSymbol = g.implementation || g.factory;
-    const [implRelativePath, fnSymbol = 'default'] = implRelativePathAndMaybeSymbol.split('#');
-    let implPath;
-    try {
-        implPath = require.resolve(implRelativePath, {
-            paths: [(0, path_1.dirname)(collectionPath)],
-        });
-    }
-    catch (e) {
-        try {
-            // workaround for a bug in node 12
-            implPath = require.resolve(`${(0, path_1.dirname)(collectionPath)}/${implRelativePath}`);
-        }
-        catch {
-            throw new MigrationImplementationMissingError(`Could not resolve implementation for migration "${name}" from "${collectionPath}"`, collectionPath, migrationVersion ?? g.version);
-        }
-    }
-    return { path: implPath, fnSymbol };
-}
 /**
  * Resolves a migration's collection once and derives everything the run loop
  * needs from that single read: the implementation context (`collection` +
@@ -2636,11 +2715,11 @@ function getImplementationPath(collection, collectionPath, name, migrationVersio
 function resolveMigrationForRun(root, migration, resolveDocumentation) {
     let resolvedCollection;
     if (!(0, migration_shape_1.isPromptOnlyMigration)(migration)) {
-        resolvedCollection = readMigrationCollection(migration.package, root);
+        resolvedCollection = (0, execute_migration_1.readMigrationCollection)(migration.package, root);
     }
     else if (resolveDocumentation && migration.documentation) {
         try {
-            resolvedCollection = readMigrationCollection(migration.package, root);
+            resolvedCollection = (0, execute_migration_1.readMigrationCollection)(migration.package, root);
         }
         catch {
             // Non-fatal: documentation is supplementary; the warning below fires.
@@ -2649,7 +2728,7 @@ function resolveMigrationForRun(root, migration, resolveDocumentation) {
     let documentationPath;
     if (resolveDocumentation && migration.documentation) {
         documentationPath = resolvedCollection
-            ? resolveDocumentationFileToWorkspacePath(root, (0, path_1.dirname)(resolvedCollection.collectionPath), migration.documentation)
+            ? (0, execute_migration_1.resolveDocumentationFileToWorkspacePath)(root, (0, path_1.dirname)(resolvedCollection.collectionPath), migration.documentation)
             : undefined;
         if (!documentationPath) {
             logger_1.logger.warn(`Could not resolve the "documentation" file "${migration.documentation}" declared for migration "${migration.package}: ${migration.name}". It will be skipped as additional context for the AI agent.`);
@@ -2657,70 +2736,6 @@ function resolveMigrationForRun(root, migration, resolveDocumentation) {
     }
     return { resolvedCollection, documentationPath };
 }
-// Resolves a `documentation` path (relative to the package's migrations dir) to
-// a workspace-relative path - or the absolute path when it resolves outside the
-// workspace (unusual hoisted/symlinked layouts). The agent runs with cwd =
-// workspace root, so the workspace-relative form is preferred. Returns
-// undefined when the file can't be resolved.
-function resolveDocumentationFileToWorkspacePath(root, migrationsDir, documentation) {
-    let documentationFile;
-    try {
-        documentationFile = require.resolve(documentation, {
-            paths: [migrationsDir],
-        });
-    }
-    catch {
-        return undefined;
-    }
-    const relativePath = (0, path_1.relative)(root, documentationFile);
-    return relativePath.startsWith('..') ? documentationFile : relativePath;
-}
-class MigrationImplementationMissingError extends Error {
-    constructor(baseMessage, collectionPath, migrationVersion) {
-        super(buildMigrationMissingMessage(baseMessage, collectionPath, migrationVersion));
-        this.name = 'MigrationImplementationMissingError';
-    }
-}
-function buildMigrationMissingMessage(baseMessage, collectionPath, migrationVersion) {
-    if (!migrationVersion) {
-        return baseMessage;
-    }
-    try {
-        const packageJsonPath = (0, path_1.join)((0, path_1.dirname)(collectionPath), 'package.json');
-        if (!(0, fs_1.existsSync)(packageJsonPath)) {
-            return baseMessage;
-        }
-        const packageJson = (0, fileutils_1.readJsonFile)(packageJsonPath);
-        const installedVersion = packageJson.version;
-        if (installedVersion &&
-            (0, semver_1.lt)((0, version_utils_1.normalizeVersion)(installedVersion), (0, version_utils_1.normalizeVersion)(migrationVersion))) {
-            const packageManager = (0, package_manager_1.detectPackageManager)();
-            const pmc = (0, package_manager_1.getPackageManagerCommand)(packageManager);
-            const overrideFieldName = getOverrideFieldName(packageManager);
-            return (`${baseMessage}\n\n` +
-                `The installed version of "${packageJson.name}" is ${installedVersion}, ` +
-                `but this migration requires version ${migrationVersion}. ` +
-                `This likely means the package version is being held back by an ${overrideFieldName} ` +
-                `in your package.json. ` +
-                `Remove the ${overrideFieldName} and run "${pmc.install}" to install the correct version.`);
-        }
-    }
-    catch {
-        // Fall through to return the base message if we can't read package info
-    }
-    return baseMessage;
-}
-function getOverrideFieldName(packageManager) {
-    switch (packageManager) {
-        case 'pnpm':
-            return '"pnpm.overrides"';
-        case 'yarn':
-            return '"resolutions"';
-        case 'npm':
-        case 'bun':
-            return '"overrides"';
-    }
-}
 async function nxCliPath(nxWorkspaceRoot) {
     const version = process.env.NX_MIGRATE_CLI_VERSION || 'latest';
     const isVerbose = process.env.NX_VERBOSE_LOGGING === 'true';
@@ -2771,7 +2786,7 @@ async function nxCliPath(nxWorkspaceRoot) {
         return (0, path_1.join)(tmpDir, `node_modules`, '.bin', 'nx');
     }
     catch (e) {
-        console.error(`Failed to install the ${version} version of the migration script. Using the current version.`);
+        console.error(`Failed to install the ${version} version of the migration script. Falling back to the workspace's installed nx.`);
         if (isVerbose) {
             console.error(e);
         }
@@ -2790,16 +2805,3 @@ function addToNodePath(dir) {
     // Update the env variable.
     process.env.NODE_PATH = paths.join(delimiter);
 }
-function isAngularMigration(collection, name) {
-    return !collection.generators?.[name] && collection.schematics?.[name];
-}
-const getNgCompatLayer = (() => {
-    let _ngCliAdapter;
-    return async function getNgCompatLayer() {
-        if (!_ngCliAdapter) {
-            _ngCliAdapter = await (0, handle_import_1.handleImport)('../../adapter/ngcli-adapter.js', __dirname);
-            require('../../adapter/compat');
-        }
-        return _ngCliAdapter;
-    };
-})();