nx 23.0.0-beta.2 → 23.0.0-beta.21

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

@@ -1,12 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Migrator = void 0;
+exports.ChangedDepInstaller = exports.isHybridMigration = exports.isPromptOnlyMigration = exports.filterDowngradedUpdates = exports.Migrator = exports.normalizeVersion = void 0;
 exports.formatCommandFailure = formatCommandFailure;
-exports.normalizeVersion = normalizeVersion;
+exports.resolveCanonicalNxPackage = resolveCanonicalNxPackage;
+exports.resolveMode = resolveMode;
 exports.parseMigrationsOptions = parseMigrationsOptions;
 exports.isNpmPeerDepsError = isNpmPeerDepsError;
+exports.resolveAgenticRunId = resolveAgenticRunId;
+exports.formatSkippedPromptsNextStep = formatSkippedPromptsNextStep;
+exports.resolveCreateCommits = resolveCreateCommits;
+exports.resolveShouldRunValidation = resolveShouldRunValidation;
 exports.executeMigrations = executeMigrations;
 exports.runNxOrAngularMigration = runNxOrAngularMigration;
+exports.parseMigrationReturn = parseMigrationReturn;
 exports.migrate = migrate;
 exports.runMigration = runMigration;
 exports.readMigrationCollection = readMigrationCollection;
@@ -15,7 +21,7 @@ exports.nxCliPath = nxCliPath;
 const tslib_1 = require("tslib");
 const pc = tslib_1.__importStar(require("picocolors"));
 const child_process_1 = require("child_process");
-const enquirer_1 = require("enquirer");
+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");
@@ -25,6 +31,7 @@ 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 logger_1 = require("../../utils/logger");
 const git_utils_1 = require("../../utils/git-utils");
@@ -37,6 +44,7 @@ const fs_1 = require("fs");
 const workspace_root_1 = require("../../utils/workspace-root");
 const is_ci_1 = require("../../utils/is-ci");
 const installation_directory_1 = require("../../utils/installation-directory");
+const installed_nx_version_1 = require("../../utils/installed-nx-version");
 const configuration_1 = require("../../config/configuration");
 const child_process_2 = require("../../utils/child-process");
 const client_1 = require("../../daemon/client/client");
@@ -45,6 +53,19 @@ 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 provenance_1 = require("../../utils/provenance");
 const catalog_1 = require("../../utils/catalog");
+const multi_major_1 = require("./multi-major");
+const prompt_files_1 = require("./prompt-files");
+const command_object_1 = require("./command-object");
+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");
+Object.defineProperty(exports, "isHybridMigration", { enumerable: true, get: function () { return migration_shape_1.isHybridMigration; } });
+Object.defineProperty(exports, "isPromptOnlyMigration", { enumerable: true, get: function () { return migration_shape_1.isPromptOnlyMigration; } });
+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 execAsync = (0, util_1.promisify)(child_process_1.exec);
 function formatCommandFailure(command, error) {
     const normalizeCommandOutput = (output) => {
@@ -76,33 +97,6 @@ function runOrReturnExitCode(run) {
         throw e;
     }
 }
-function normalizeVersion(version) {
-    const [semver, ...prereleaseTagParts] = version.split('-');
-    // Handle versions like 1.0.0-beta-next.2
-    const prereleaseTag = prereleaseTagParts.join('-');
-    const [major, minor, patch] = semver.split('.');
-    const newSemver = `${major || 0}.${minor || 0}.${patch || 0}`;
-    const newVersion = prereleaseTag
-        ? `${newSemver}-${prereleaseTag}`
-        : newSemver;
-    const withoutPatch = `${major || 0}.${minor || 0}.0`;
-    const withoutPatchAndMinor = `${major || 0}.0.0`;
-    const variationsToCheck = [
-        newVersion,
-        newSemver,
-        withoutPatch,
-        withoutPatchAndMinor,
-    ];
-    for (const variation of variationsToCheck) {
-        try {
-            if ((0, semver_1.gt)(variation, '0.0.0')) {
-                return variation;
-            }
-        }
-        catch { }
-    }
-    return '0.0.0';
-}
 function cleanSemver(version) {
     return (0, semver_1.clean)(version) ?? (0, semver_1.coerce)(version);
 }
@@ -114,6 +108,10 @@ class Migrator {
         this.packageUpdates = {};
         this.collectedVersions = {};
         this.promptAnswers = {};
+        if ((opts.mode === 'first-party' || opts.mode === 'third-party') &&
+            !opts.firstPartyPackages) {
+            throw new Error(`Error: 'firstPartyPackages' is required when 'mode' is '${opts.mode}'.`);
+        }
         this.packageJson = opts.packageJson;
         this.nxInstallation = opts.nxInstallation;
         this.getInstalledPackageVersion = opts.getInstalledPackageVersion;
@@ -122,6 +120,8 @@ class Migrator {
         this.to = opts.to;
         this.interactive = opts.interactive;
         this.excludeAppliedMigrations = opts.excludeAppliedMigrations;
+        this.mode = opts.mode;
+        this.firstPartyPackages = opts.firstPartyPackages;
     }
     async fetchMigrationConfig(packageName, packageVersion) {
         const migrationConfig = await this.fetch(packageName, packageVersion);
@@ -135,14 +135,17 @@ class Migrator {
             version: targetVersion,
             addToPackageJson: false,
         });
-        const migrations = await this.createMigrateJson();
+        this.applyModeFilter();
+        const { migrations, promptContents } = await this.createMigrateJson();
         return {
             packageUpdates: this.packageUpdates,
             migrations,
+            ...(Object.keys(promptContents).length > 0 ? { promptContents } : {}),
             minVersionWithSkippedUpdates: this.minVersionWithSkippedUpdates,
         };
     }
     async createMigrateJson() {
+        const promptContents = {};
         const migrations = await Promise.all(Object.keys(this.packageUpdates).map(async (packageName) => {
             if (this.packageUpdates[packageName].ignoreMigrations) {
                 return [];
@@ -151,10 +154,15 @@ class Migrator {
             if (currentVersion === null)
                 return [];
             const { version } = this.packageUpdates[packageName];
-            const { generators } = await this.fetchMigrationConfig(packageName, version);
-            if (!generators)
+            const { generators: migrationEntries, resolvedPromptFiles } = await this.fetchMigrationConfig(packageName, version);
+            if (!migrationEntries)
                 return [];
-            return Object.entries(generators)
+            if (resolvedPromptFiles) {
+                for (const [promptPath, content] of Object.entries(resolvedPromptFiles)) {
+                    promptContents[(0, prompt_files_1.promptContentKey)(packageName, promptPath)] = content;
+                }
+            }
+            return Object.entries(migrationEntries)
                 .filter(([, migration]) => migration.version &&
                 this.gt(migration.version, currentVersion) &&
                 this.lte(migration.version, version) &&
@@ -165,7 +173,7 @@ class Migrator {
                 name: migrationName,
             }));
         }));
-        return migrations.flat();
+        return { migrations: migrations.flat(), promptContents };
     }
     async buildPackageJsonUpdates(targetPackage, target) {
         const packagesToCheck = await this.populatePackageJsonUpdatesAndGetPackagesToCheck(targetPackage, target);
@@ -263,7 +271,7 @@ class Migrator {
         if (ignorePackageGroup) {
             return [];
         }
-        const packageGroup = packageName === '@nrwl/workspace' && (0, semver_1.lt)(targetVersion, '14.0.0-beta.0')
+        const packageGroup = packageName === '@nrwl/workspace' && (0, version_utils_1.isLegacyEra)(targetVersion)
             ? LEGACY_NRWL_PACKAGE_GROUP
             : (migrationConfig.packageGroup ?? []);
         let packageGroupOrder = [];
@@ -307,6 +315,9 @@ class Migrator {
             };
             const filtered = {};
             for (const [packageName, packageUpdate] of Object.entries(packageJsonUpdate.packages)) {
+                if (this.shouldExcludePackage(packageName)) {
+                    continue;
+                }
                 if (this.shouldApplyPackageUpdate(packageUpdate, packageName, dependencies)) {
                     filtered[packageName] = {
                         version: packageUpdate.version,
@@ -331,6 +342,29 @@ class Migrator {
         }
         return filteredPackageJsonUpdates;
     }
+    shouldExcludePackage(packageName) {
+        if (!this.firstPartyPackages) {
+            return false;
+        }
+        if (this.mode === 'first-party') {
+            return !this.firstPartyPackages.has(packageName);
+        }
+        return false;
+    }
+    applyModeFilter() {
+        if (this.mode !== 'third-party') {
+            return;
+        }
+        // Cascade walks through first-party packages so cross-plugin third-party
+        // deps (e.g. typescript managed by @nx/js but used by @nx/angular) get
+        // surfaced. Drop the first-party set from the final result here so only
+        // third-party updates land in package.json.
+        for (const name of Object.keys(this.packageUpdates)) {
+            if (this.firstPartyPackages.has(name)) {
+                delete this.packageUpdates[name];
+            }
+        }
+    }
     shouldApplyPackageUpdate(packageUpdate, packageName, dependencies) {
         return ((!packageUpdate.ifPackageInstalled ||
             this.getPkgVersion(packageUpdate.ifPackageInstalled)) &&
@@ -423,7 +457,7 @@ class Migrator {
             // @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, enquirer_1.prompt)([promptConfig]).then(({ shouldApply }) => {
+        return await (0, safe_prompt_1.migratePrompt)([promptConfig]).then(({ shouldApply }) => {
             this.promptAnswers[promptKey] = shouldApply;
             if (!shouldApply &&
                 (!this.minVersionWithSkippedUpdates ||
@@ -442,13 +476,13 @@ class Migrator {
         return this.getInstalledPackageVersion(pkg, this.installedPkgVersionOverrides);
     }
     gt(v1, v2) {
-        return (0, semver_1.gt)(normalizeVersion(v1), normalizeVersion(v2));
+        return (0, semver_1.gt)((0, version_utils_1.normalizeVersion)(v1), (0, version_utils_1.normalizeVersion)(v2));
     }
     lt(v1, v2) {
-        return (0, semver_1.lt)(normalizeVersion(v1), normalizeVersion(v2));
+        return (0, semver_1.lt)((0, version_utils_1.normalizeVersion)(v1), (0, version_utils_1.normalizeVersion)(v2));
     }
     lte(v1, v2) {
-        return (0, semver_1.lte)(normalizeVersion(v1), normalizeVersion(v2));
+        return (0, semver_1.lte)((0, version_utils_1.normalizeVersion)(v1), (0, version_utils_1.normalizeVersion)(v2));
     }
 }
 exports.Migrator = Migrator;
@@ -475,17 +509,59 @@ const LEGACY_NRWL_PACKAGE_GROUP = [
     { package: '@nrwl/expo', version: '*' },
     { package: '@nrwl/tao', version: '*' },
 ];
-async function normalizeVersionWithTagCheck(pkg, version) {
-    // This doesn't seem like a valid version, lets check if its a tag on the registry.
-    if (version && !(0, semver_1.parse)(version)) {
-        try {
-            return (0, package_manager_1.resolvePackageVersionUsingRegistry)(pkg, version);
-        }
-        catch {
-            // fall through to old logic
-        }
+function resolveFirstPartyPackages(targetPackage, packageGroup) {
+    const set = new Set([targetPackage]);
+    for (const { package: name } of packageGroup ?? []) {
+        set.add(name);
+    }
+    return set;
+}
+/**
+ * The canonical Nx package for a given target version: `@nrwl/workspace` for
+ * legacy (`< 14.0.0-beta.0`), `nx` otherwise. Non-semver inputs (e.g. the
+ * literal `'latest'` sentinel before tag resolution) resolve to modern era.
+ * Used by `--mode=third-party` to silently swap `@nx/workspace` → `nx` when
+ * walking the cascade.
+ */
+function resolveCanonicalNxPackage(targetVersion) {
+    return (0, version_utils_1.isLegacyEra)(targetVersion) ? '@nrwl/workspace' : 'nx';
+}
+async function resolveMode(mode, targetPackage, targetVersion, context = {
+    hasFrom: false,
+    hasExcludeAppliedMigrations: false,
+}) {
+    if (mode) {
+        return mode;
+    }
+    if (!(0, version_utils_1.isNxEquivalentTarget)(targetPackage, targetVersion)) {
+        return 'all';
+    }
+    if (!process.stdin.isTTY || (0, is_ci_1.isCI)()) {
+        return 'all';
+    }
+    const choices = [
+        {
+            name: 'first-party',
+            message: 'First-party only (Nx and its official packages)',
+        },
+    ];
+    if (!context.hasFrom && !context.hasExcludeAppliedMigrations) {
+        choices.push({
+            name: 'third-party',
+            message: 'Third-party only (deps managed by Nx)',
+        });
     }
-    return normalizeVersion(version);
+    choices.push({
+        name: 'all',
+        message: 'All (first-party and third-party)',
+    });
+    const { mode: selected } = await (0, safe_prompt_1.migratePrompt)({
+        type: 'select',
+        name: 'mode',
+        message: 'Which packages would you like to migrate?',
+        choices,
+    });
+    return selected;
 }
 async function versionOverrides(overrides, param) {
     const res = {};
@@ -499,7 +575,7 @@ async function versionOverrides(overrides, param) {
         if (!selectedPackage || !selectedVersion) {
             throw new Error(`Incorrect '${param}' section. Use --${param}="package@version"`);
         }
-        return normalizeVersionWithTagCheck(selectedPackage, selectedVersion).then((version) => {
+        return (0, version_utils_1.normalizeVersionWithTagCheck)(selectedPackage, selectedVersion).then((version) => {
             res[normalizeSlashes(selectedPackage)] = version;
         });
     });
@@ -513,78 +589,219 @@ async function parseTargetPackageAndVersion(args) {
     if (args.indexOf('@') > -1) {
         const i = args.lastIndexOf('@');
         if (i === 0) {
-            const targetPackage = args.trim();
-            const targetVersion = 'latest';
-            return { targetPackage, targetVersion };
-        }
-        else {
-            const targetPackage = args.substring(0, i);
-            const maybeVersion = args.substring(i + 1);
-            if (!targetPackage || !maybeVersion) {
-                throw new Error(`Provide the correct package name and version. E.g., my-package@9.0.0.`);
-            }
-            const targetVersion = await normalizeVersionWithTagCheck(targetPackage, maybeVersion);
-            return { targetPackage, targetVersion };
-        }
-    }
-    else {
-        if (args === 'latest' ||
-            args === 'next' ||
-            args === 'canary' ||
-            (0, semver_1.valid)(args) ||
-            args.match(/^\d+(?:\.\d+)?(?:\.\d+)?$/)) {
-            // Passing `nx` here may seem wrong, but nx and @nrwl/workspace are synced in version.
-            // We could duplicate the ternary below, but its not necessary since they are equivalent
-            // on the registry
-            const targetVersion = await normalizeVersionWithTagCheck('nx', args);
-            const targetPackage = !['latest', 'next', 'canary'].includes(args) &&
-                (0, semver_1.lt)(targetVersion, '14.0.0-beta.0')
-                ? '@nrwl/workspace'
-                : 'nx';
-            return {
-                targetPackage,
-                targetVersion,
-            };
-        }
-        else {
-            return {
-                targetPackage: args,
-                targetVersion: 'latest',
-            };
-        }
-    }
+            return { targetPackage: args.trim(), targetVersion: 'latest' };
+        }
+        const targetPackage = args.substring(0, i);
+        const maybeVersion = args.substring(i + 1);
+        if (!targetPackage || !maybeVersion) {
+            throw new Error(`Provide the correct package name and version. E.g., my-package@9.0.0.`);
+        }
+        const targetVersion = await (0, version_utils_1.normalizeVersionWithTagCheck)(targetPackage, maybeVersion);
+        return { targetPackage, targetVersion };
+    }
+    if (version_utils_1.DIST_TAGS.includes(args) ||
+        (0, semver_1.valid)(args) ||
+        args.match(/^\d+(?:\.\d+)?(?:\.\d+)?$/)) {
+        // Passing `nx` here may seem wrong, but nx and @nrwl/workspace are synced in version.
+        // We could duplicate the ternary below, but its not necessary since they are equivalent
+        // on the registry
+        const targetVersion = await (0, version_utils_1.normalizeVersionWithTagCheck)('nx', args);
+        const isDistTag = version_utils_1.DIST_TAGS.includes(args);
+        const targetPackage = isDistTag
+            ? 'nx'
+            : resolveCanonicalNxPackage(targetVersion);
+        return { targetPackage, targetVersion };
+    }
+    return { targetPackage: args, targetVersion: 'latest' };
 }
 async function parseMigrationsOptions(options) {
     if (options.runMigrations === '') {
         options.runMigrations = 'migrations.json';
     }
-    if (!options.runMigrations) {
-        const [from, to] = await Promise.all([
-            options.from
-                ? versionOverrides(options.from, 'from')
-                : Promise.resolve({}),
-            options.to
-                ? await versionOverrides(options.to, 'to')
-                : Promise.resolve({}),
-        ]);
-        const { targetPackage, targetVersion } = await parseTargetPackageAndVersion(options['packageAndVersion']);
-        return {
-            type: 'generateMigrations',
-            targetPackage: normalizeSlashes(targetPackage),
-            targetVersion,
-            from,
-            to,
-            interactive: options.interactive,
-            excludeAppliedMigrations: options.excludeAppliedMigrations,
-        };
+    if (options.mode && options.runMigrations) {
+        throw new Error(`Error: '--mode' cannot be combined with '--run-migrations'.`);
     }
-    else {
+    if (options.multiMajorMode && options.runMigrations) {
+        throw new Error(`Error: '--multi-major-mode' cannot be combined with '--run-migrations'.`);
+    }
+    if (options.runMigrations) {
         return {
             type: 'runMigrations',
             runMigrations: options.runMigrations,
             ifExists: options.ifExists,
+            agentic: options.agentic,
+            validate: options.validate,
         };
     }
+    assertThirdPartyModeFlagCompatibility(options);
+    const [from, to] = await Promise.all([
+        options.from
+            ? versionOverrides(options.from, 'from')
+            : Promise.resolve({}),
+        options.to
+            ? await versionOverrides(options.to, 'to')
+            : Promise.resolve({}),
+    ]);
+    const positional = options['packageAndVersion'];
+    const resolved = await resolveTargetAndMode({ positional, from, options });
+    const { mode, installedNxVersion } = resolved;
+    let { targetPackage, targetVersion } = resolved;
+    // Crossing more than one major can silently skip migrations: each
+    // major's metadata may have pruned entries from much-older versions.
+    const multiMajorResult = await (0, multi_major_1.maybePromptOrWarnMultiMajorMigration)({
+        mode,
+        options,
+        targetPackage,
+        targetVersion,
+    });
+    targetVersion = multiMajorResult.chosen;
+    if (mode === 'third-party') {
+        assertThirdPartyTargetBounds({
+            targetPackage,
+            targetVersion,
+            to,
+            installedNxVersion,
+        });
+    }
+    return {
+        type: 'generateMigrations',
+        targetPackage,
+        targetVersion,
+        from,
+        to,
+        interactive: options.interactive,
+        excludeAppliedMigrations: options.excludeAppliedMigrations,
+        mode,
+        originalTargetVersion: multiMajorResult.originalTarget,
+        multiMajorMode: multiMajorResult.gradual ? 'gradual' : undefined,
+    };
+}
+function assertThirdPartyModeFlagCompatibility(options) {
+    if (options.mode !== 'third-party')
+        return;
+    if (options.from) {
+        throw new Error(`Error: '--mode=third-party' cannot be combined with '--from'.`);
+    }
+    if (options.excludeAppliedMigrations === true) {
+        throw new Error(`Error: '--mode=third-party' cannot be combined with '--exclude-applied-migrations'.`);
+    }
+}
+// Defaults target package/version mode-aware (third-party → installed
+// canonical, otherwise nx@latest) and enforces the era gate when --mode
+// is explicit.
+async function resolveTargetAndMode(args) {
+    const { positional, from, options } = args;
+    let targetPackage;
+    let targetVersion;
+    if (positional) {
+        const parsed = await parseTargetPackageAndVersion(positional);
+        targetPackage = normalizeSlashes(parsed.targetPackage);
+        targetVersion = parsed.targetVersion;
+    }
+    // Resolve mode before defaulting target so the default can depend on the
+    // resolved mode (third-party defaults to nx@<installed>; otherwise nx@latest).
+    // For bare invocation, `targetPackage='nx'` and `targetVersion='latest'` are
+    // safe sentinels: `isNxEquivalentTarget` treats the literal `'latest'` as
+    // modern era (semver `lt('latest', '14.0.0-beta.0')` is false).
+    const mode = await resolveMode(options.mode, targetPackage ?? 'nx', targetVersion ?? 'latest', {
+        hasFrom: Object.keys(from).length > 0,
+        hasExcludeAppliedMigrations: options.excludeAppliedMigrations === true,
+    });
+    let installedNxVersion;
+    // For third-party, anchor `targetPackage`/`targetVersion` to the installed
+    // canonical when the positional was either omitted or a bare package name
+    // (no semver). This keeps the era gate accepting legacy workspaces, the
+    // upper-bound gate meaningful, and downstream semver comparisons safe from
+    // the literal `'latest'` that `parseTargetPackageAndVersion` emits for bare
+    // package names.
+    if (mode === 'third-party' && (!positional || !(0, semver_1.valid)(targetVersion))) {
+        const installed = resolveInstalledCanonical();
+        if (!installed) {
+            throw new Error(`Error: '--mode=third-party' requires 'nx' (or '@nrwl/workspace' on Nx <14) to be installed in your workspace. Install dependencies first, then re-run.`);
+        }
+        installedNxVersion = installed.version;
+        targetPackage = installed.canonical;
+        targetVersion = installed.version;
+    }
+    else if (!positional) {
+        // Bare invocation: default to `nx@latest` as a literal sentinel rather
+        // than resolving via the registry here. Multi-major resolves the dist-tag
+        // when needed (and bails gracefully on registry failure), and the cascade
+        // resolves it for the walk (honouring `NX_MIGRATE_SKIP_REGISTRY_FETCH`).
+        // This matches the resilience of `nx migrate nx`.
+        targetPackage = 'nx';
+        targetVersion = 'latest';
+    }
+    if (options.mode && !(0, version_utils_1.isNxEquivalentTarget)(targetPackage, targetVersion)) {
+        const isLegacy = (0, version_utils_1.isLegacyEra)(targetVersion);
+        const validTargets = isLegacy
+            ? `'@nrwl/workspace'`
+            : `'nx' or '@nx/workspace'`;
+        const eraNote = isLegacy ? ' for Nx <14.0.0' : '';
+        throw new Error(`Error: '--mode' requires the target to be ${validTargets}${eraNote}. Got '${targetPackage}@${targetVersion}'.`);
+    }
+    return {
+        targetPackage: targetPackage,
+        targetVersion: targetVersion,
+        mode,
+        installedNxVersion,
+    };
+}
+// `--mode=third-party` upper-bound gate. The third-party walk follows nx's
+// `packageGroup`; a target or `--to` above the installed version would
+// expand the walk past it and surface third-party bumps that only exist in
+// the newer plugin's history. The first-party set is sourced from the
+// installed nx package's declared `packageGroup` (authoritative for the
+// user's current Nx universe). Legacy era falls back to the hardcoded
+// `LEGACY_NRWL_PACKAGE_GROUP`.
+function assertThirdPartyTargetBounds(args) {
+    const { targetPackage, targetVersion, to, installedNxVersion } = args;
+    const canonical = resolveCanonicalNxPackage(targetVersion);
+    const isLegacy = canonical === '@nrwl/workspace';
+    // Reuse the resolved installed version from `resolveTargetAndMode` when
+    // present (it's already era-aware via `resolveInstalledCanonical`).
+    // Otherwise fall back to the era-specific reader.
+    const installed = installedNxVersion ??
+        (isLegacy
+            ? (0, installed_nx_version_1.getInstalledLegacyNrwlWorkspaceVersion)()
+            : (0, installed_nx_version_1.getInstalledNxVersion)());
+    if (!installed) {
+        throw new Error(`Error: '--mode=third-party' requires '${canonical}' to be installed in your workspace. Install dependencies first, then re-run.`);
+    }
+    if ((0, semver_1.gt)(targetVersion, installed)) {
+        throw new Error(`Error: '--mode=third-party' cannot migrate to a version higher than what is currently installed (got '${targetPackage}@${targetVersion}', installed '${canonical}@${installed}'). Either drop '--mode=third-party' or lower the target.`);
+    }
+    const firstPartySet = isLegacy
+        ? new Set([
+            '@nrwl/workspace',
+            ...LEGACY_NRWL_PACKAGE_GROUP.map((p) => p.package),
+        ])
+        : (0, installed_nx_version_1.getInstalledNxPackageGroup)();
+    for (const [pkg, version] of Object.entries(to)) {
+        if (firstPartySet.has(pkg) && (0, semver_1.gt)(version, installed)) {
+            throw new Error(`Error: '--mode=third-party' cannot migrate to a version higher than what is currently installed (got '--to ${pkg}@${version}', installed '${canonical}@${installed}'). Either drop '--mode=third-party' or lower the '--to' value.`);
+        }
+    }
+}
+/**
+ * Pick the canonical Nx package + version for `--mode=third-party` when the
+ * user didn't supply an explicit version. Returns `'nx'` for modern era,
+ * falls back to `'@nrwl/workspace'` (legacy era) when only that is installed
+ * or when the installed `nx` itself is `<14`.
+ */
+function resolveInstalledCanonical() {
+    const installedNx = (0, installed_nx_version_1.getInstalledNxVersion)();
+    if (installedNx) {
+        return {
+            canonical: resolveCanonicalNxPackage(installedNx),
+            version: installedNx,
+        };
+    }
+    const installedLegacy = (0, installed_nx_version_1.getInstalledLegacyNrwlWorkspaceVersion)();
+    if (installedLegacy) {
+        return { canonical: '@nrwl/workspace', version: installedLegacy };
+    }
+    return null;
 }
 function createInstalledPackageVersionsResolver(root) {
     const cache = {};
@@ -731,11 +948,22 @@ async function downloadPackageMigrationsFromRegistry(packageName, packageVersion
     let result;
     try {
         const { tarballPath } = await (0, package_manager_1.packageRegistryPack)(dir, packageName, packageVersion);
-        const migrations = await (0, fileutils_1.extractFileFromTarball)((0, path_1.join)(dir, tarballPath), (0, path_2.joinPathFragments)('package', migrationsFilePath), (0, path_1.join)(dir, migrationsFilePath)).then((path) => (0, fileutils_1.readJsonFile)(path));
-        result = { ...migrations, packageGroup, version: packageVersion };
-    }
-    catch {
-        throw new Error(`Failed to find migrations file "${migrationsFilePath}" in package "${packageName}@${packageVersion}".`);
+        const fullTarballPath = (0, path_1.join)(dir, tarballPath);
+        let migrations;
+        try {
+            migrations = await (0, tar_1.extractFileFromTarball)(fullTarballPath, (0, path_2.joinPathFragments)('package', migrationsFilePath), (0, path_1.join)(dir, migrationsFilePath)).then((path) => (0, fileutils_1.readJsonFile)(path));
+        }
+        catch {
+            throw new Error(`Failed to find migrations file "${migrationsFilePath}" in package "${packageName}@${packageVersion}".`);
+        }
+        (0, prompt_files_1.validateMigrationEntries)(packageName, packageVersion, migrations);
+        const resolvedPromptFiles = await (0, prompt_files_1.extractPromptFilesFromTarball)(packageName, packageVersion, migrations, migrationsFilePath, fullTarballPath, dir);
+        result = {
+            ...migrations,
+            packageGroup,
+            version: packageVersion,
+            ...(resolvedPromptFiles ? { resolvedPromptFiles } : {}),
+        };
     }
     finally {
         await cleanup();
@@ -789,10 +1017,18 @@ async function getPackageMigrationsUsingInstallImpl(packageName, packageVersion)
         });
         const { migrations: migrationsFilePath, packageGroup, packageJson, } = readPackageMigrationConfig(packageName, dir);
         let migrations = undefined;
+        let resolvedPromptFiles;
         if (migrationsFilePath) {
             migrations = (0, fileutils_1.readJsonFile)(migrationsFilePath);
-        }
-        result = { ...migrations, packageGroup, version: packageJson.version };
+            (0, prompt_files_1.validateMigrationEntries)(packageName, packageVersion, migrations);
+            resolvedPromptFiles = await (0, prompt_files_1.readPromptFilesFromInstall)(packageName, packageVersion, migrations, migrationsFilePath);
+        }
+        result = {
+            ...migrations,
+            packageGroup,
+            version: packageJson.version,
+            ...(resolvedPromptFiles ? { resolvedPromptFiles } : {}),
+        };
     }
     catch (e) {
         const pmc = (0, package_manager_1.getPackageManagerCommand)((0, package_manager_1.detectPackageManager)(dir), dir);
@@ -836,12 +1072,13 @@ async function createMigrationsFile(root, migrations) {
 async function updatePackageJson(root, updatedPackages) {
     const packageJsonPath = (0, path_1.join)(root, 'package.json');
     if (!(0, fs_1.existsSync)(packageJsonPath)) {
-        return;
+        return false;
     }
     const parseOptions = {};
     const json = (0, fileutils_1.readJsonFile)(packageJsonPath, parseOptions);
     const manager = (0, catalog_1.getCatalogManager)(root);
     const catalogUpdates = [];
+    let modified = false;
     Object.keys(updatedPackages).forEach((p) => {
         const existingVersion = json.dependencies?.[p] ?? json.devDependencies?.[p];
         if (existingVersion && manager?.isCatalogReference(existingVersion)) {
@@ -856,28 +1093,40 @@ async function updatePackageJson(root, updatedPackages) {
         }
         // Update non-catalog packages in package.json
         if (json.devDependencies?.[p]) {
-            json.devDependencies[p] = updatedPackages[p].version;
+            if (json.devDependencies[p] !== updatedPackages[p].version) {
+                json.devDependencies[p] = updatedPackages[p].version;
+                modified = true;
+            }
             return;
         }
         if (json.dependencies?.[p]) {
-            json.dependencies[p] = updatedPackages[p].version;
+            if (json.dependencies[p] !== updatedPackages[p].version) {
+                json.dependencies[p] = updatedPackages[p].version;
+                modified = true;
+            }
             return;
         }
         const dependencyType = updatedPackages[p].addToPackageJson;
         if (typeof dependencyType === 'string') {
             json[dependencyType] ??= {};
-            json[dependencyType][p] = updatedPackages[p].version;
+            if (json[dependencyType][p] !== updatedPackages[p].version) {
+                json[dependencyType][p] = updatedPackages[p].version;
+                modified = true;
+            }
         }
     });
-    await (0, write_formatted_json_file_1.writeFormattedJsonFile)(packageJsonPath, json, {
-        appendNewLine: parseOptions.endsWithNewline,
-    });
+    if (modified) {
+        await (0, write_formatted_json_file_1.writeFormattedJsonFile)(packageJsonPath, json, {
+            appendNewLine: parseOptions.endsWithNewline,
+        });
+    }
     // Update catalog definitions
     if (catalogUpdates.length) {
         // manager is guaranteed to be defined when there are catalog updates
         manager.updateCatalogVersions(root, catalogUpdates);
         await formatCatalogDefinitionFiles(manager, root);
     }
+    return modified || catalogUpdates.length > 0;
 }
 async function formatCatalogDefinitionFiles(manager, root) {
     const catalogDefinitionFilePaths = manager.getCatalogDefinitionFilePaths();
@@ -899,29 +1148,38 @@ async function updateInstallationDetails(root, updatedPackages) {
     const parseOptions = {};
     const nxJson = (0, fileutils_1.readJsonFile)(nxJsonPath, parseOptions);
     if (!nxJson.installation) {
-        return;
+        return false;
     }
+    let modified = false;
     const nxVersion = updatedPackages.nx?.version;
-    if (nxVersion) {
+    if (nxVersion && nxJson.installation.version !== nxVersion) {
         nxJson.installation.version = nxVersion;
+        modified = true;
     }
     if (nxJson.installation.plugins) {
         for (const dep in nxJson.installation.plugins) {
             const update = updatedPackages[dep];
             if (update) {
-                nxJson.installation.plugins[dep] = (0, semver_1.valid)(update.version)
+                const newVersion = (0, semver_1.valid)(update.version)
                     ? update.version
                     : await (0, package_manager_1.resolvePackageVersionUsingRegistry)(dep, update.version);
+                if (nxJson.installation.plugins[dep] !== newVersion) {
+                    nxJson.installation.plugins[dep] = newVersion;
+                    modified = true;
+                }
             }
         }
     }
-    await (0, write_formatted_json_file_1.writeFormattedJsonFile)(nxJsonPath, nxJson, {
-        appendNewLine: parseOptions.endsWithNewline,
-    });
+    if (modified) {
+        await (0, write_formatted_json_file_1.writeFormattedJsonFile)(nxJsonPath, nxJson, {
+            appendNewLine: parseOptions.endsWithNewline,
+        });
+    }
+    return modified;
 }
 async function isMigratingToNewMajor(from, to) {
-    from = normalizeVersion(from);
-    to = ['latest', 'next', 'canary'].includes(to) ? to : normalizeVersion(to);
+    from = (0, version_utils_1.normalizeVersion)(from);
+    to = ['latest', 'next', 'canary'].includes(to) ? to : (0, version_utils_1.normalizeVersion)(to);
     if (!(0, semver_1.valid)(from)) {
         from = await (0, package_manager_1.resolvePackageVersionUsingRegistry)('nx', from);
     }
@@ -945,34 +1203,107 @@ async function generateMigrationsJsonAndUpdatePackageJson(root, opts) {
         const originalNxJson = (0, configuration_1.readNxJson)();
         const from = originalNxJson.installation?.version ??
             readNxVersion(originalPackageJson, root);
+        const mode = opts.mode;
+        let walkedTargetPackage = opts.targetPackage;
+        let fromOverrides = opts.from;
+        let excludeApplied = opts.excludeAppliedMigrations;
+        if (mode === 'third-party') {
+            // For third-party, walk the canonical Nx target so cross-plugin
+            // third-party dependencies (e.g. typescript managed by @nx/js but
+            // used by @nx/angular) stay consistent.
+            const canonical = resolveCanonicalNxPackage(opts.targetVersion);
+            walkedTargetPackage = canonical;
+            fromOverrides = { [canonical]: '0.0.0' };
+            excludeApplied = true;
+        }
         logger_1.logger.info(`Fetching meta data about packages.`);
         logger_1.logger.info(`It may take a few minutes.`);
+        const fetch = createFetcher();
+        let firstPartyPackages;
+        if (mode === 'first-party' || mode === 'third-party') {
+            // `@nx/workspace` is version-synced with `nx` and declares an
+            // intentionally narrow `packageGroup` ({ nx, nx-cloud }) via its
+            // `ng-update` field, whereas `nx` declares the full @nx/* plugin
+            // fan-out. Their transitive first-party closures are equivalent.
+            const sourcePackage = walkedTargetPackage === '@nx/workspace' ? 'nx' : walkedTargetPackage;
+            const rootMetadata = await fetch(sourcePackage, opts.targetVersion);
+            // Legacy `@nrwl/workspace<14` doesn't ship a complete `packageGroup`
+            // in its metadata; the Migrator's cascade injects
+            // `LEGACY_NRWL_PACKAGE_GROUP` for that case, and the post-build
+            // third-party filter must mirror that set or first-party `@nrwl/*`
+            // plugins slip past it.
+            const packageGroup = sourcePackage === '@nrwl/workspace' && (0, version_utils_1.isLegacyEra)(opts.targetVersion)
+                ? LEGACY_NRWL_PACKAGE_GROUP
+                : rootMetadata.packageGroup;
+            firstPartyPackages = resolveFirstPartyPackages(sourcePackage, packageGroup);
+        }
+        const installedPackageVersions = createInstalledPackageVersionsResolver(root);
         const migrator = new Migrator({
             packageJson: originalPackageJson,
             nxInstallation: originalNxJson.installation,
-            getInstalledPackageVersion: createInstalledPackageVersionsResolver(root),
-            fetch: createFetcher(),
-            from: opts.from,
+            getInstalledPackageVersion: installedPackageVersions,
+            fetch,
+            from: fromOverrides,
             to: opts.to,
             interactive: opts.interactive && !(0, is_ci_1.isCI)(),
-            excludeAppliedMigrations: opts.excludeAppliedMigrations,
+            excludeAppliedMigrations: excludeApplied,
+            mode,
+            firstPartyPackages,
         });
-        const { migrations, packageUpdates, minVersionWithSkippedUpdates } = await migrator.migrate(opts.targetPackage, opts.targetVersion);
-        await updatePackageJson(root, packageUpdates);
-        await updateInstallationDetails(root, packageUpdates);
+        const { migrations, packageUpdates, promptContents, minVersionWithSkippedUpdates, } = await migrator.migrate(walkedTargetPackage, opts.targetVersion);
+        // The cascade collects packageJsonUpdates entries against the cascade
+        // root's installed version, but inner per-package pins are only gated
+        // against the in-flight cascade tally — not against each inner package's
+        // installed version. A from-zero walk (e.g. `--mode=third-party`) can
+        // surface a stale historical pin that would write a lower version than
+        // the user already has. Drop those before writing; nx migrate is
+        // forward-only, never a downgrade.
+        const writableUpdates = (0, update_filters_1.filterDowngradedUpdates)(packageUpdates, originalPackageJson, installedPackageVersions);
+        const wrotePackageJson = await updatePackageJson(root, writableUpdates);
+        const wroteNxJsonInstallation = await updateInstallationDetails(root, writableUpdates);
+        const promptMigrationFiles = (0, prompt_files_1.writePromptMigrationFiles)(root, migrations, promptContents ?? {}, packageUpdates[walkedTargetPackage].version);
         if (migrations.length > 0) {
             await createMigrationsFile(root, [
-                ...addSplitConfigurationMigrationIfAvailable(from, packageUpdates),
+                ...addSplitConfigurationMigrationIfAvailable(from, writableUpdates),
                 ...migrations,
             ]);
         }
+        const modeLine = mode === 'first-party'
+            ? `- Processed Nx first-party packages only (skipped third-party dependency bumps).`
+            : mode === 'third-party'
+                ? `- Processed third-party dependencies only (skipped Nx first-party package updates).`
+                : null;
+        const noChanges = !wrotePackageJson && !wroteNxJsonInstallation && migrations.length === 0;
+        if (noChanges) {
+            output_1.output.success({
+                title: `No updates were applied.`,
+                bodyLines: [
+                    ...(modeLine ? [modeLine] : []),
+                    mode === 'third-party'
+                        ? `- No third-party dependency bumps were found for the installed Nx version. Either your dependencies are already up to date, or this workspace doesn't manage them in a place 'nx migrate' writes to (e.g. non-JS workspaces only track Nx and its plugins).`
+                        : `- No package updates or migrations were found.`,
+                ],
+            });
+            // Nothing was applied; skip the "Next steps" guidance below — it would
+            // tell the user to inspect package.json changes that don't exist.
+            return;
+        }
         output_1.output.success({
             title: `The migrate command has run successfully.`,
             bodyLines: [
-                `- package.json has been updated.`,
+                ...(modeLine ? [modeLine] : []),
+                ...(wrotePackageJson ? [`- package.json has been updated.`] : []),
+                ...(wroteNxJsonInstallation
+                    ? [`- nx.json (installation) has been updated.`]
+                    : []),
                 migrations.length > 0
                     ? `- migrations.json has been generated.`
                     : `- There are no migrations to run, so migrations.json has not been created.`,
+                ...(promptMigrationFiles.length > 0
+                    ? [
+                        `- ${promptMigrationFiles.length} AI migration prompt(s) have been written to ${prompt_files_1.AI_MIGRATIONS_DIR}/.`,
+                    ]
+                    : []),
             ],
         });
         try {
@@ -1006,9 +1337,21 @@ async function generateMigrationsJsonAndUpdatePackageJson(root, opts) {
             ]
             : [
                 `- Make sure package.json changes make sense and then run '${pmc.install}',`,
+                ...(promptMigrationFiles.length > 0
+                    ? [
+                        `- Review and tweak the AI migration prompts in ${prompt_files_1.AI_MIGRATIONS_DIR}/ as needed.`,
+                    ]
+                    : []),
                 ...(migrations.length > 0
                     ? [`- Run '${pmc.exec} nx migrate --run-migrations'`]
                     : []),
+                ...(opts.originalTargetVersion
+                    ? [
+                        `- After applying these migrations, run '${pmc.exec} nx migrate ${opts.targetPackage}@${opts.originalTargetVersion} --mode=${opts.mode}${opts.multiMajorMode === 'gradual'
+                            ? ` ${multi_major_1.MULTI_MAJOR_MODE_FLAG}=gradual`
+                            : ''}' to continue toward your original target.`,
+                    ]
+                    : []),
                 ...(opts.interactive && minVersionWithSkippedUpdates
                     ? [
                         `- You opted out of some migrations for now. Write the following command down somewhere to apply these migrations later:`,
@@ -1040,7 +1383,7 @@ function addSplitConfigurationMigrationIfAvailable(from, packageJson) {
     if (!packageJson['@nrwl/workspace'])
         return [];
     if ((0, semver_1.gte)(packageJson['@nrwl/workspace'].version, '15.7.0-beta.0') &&
-        (0, semver_1.lt)(normalizeVersion(from), '15.7.0-beta.0')) {
+        (0, semver_1.lt)((0, version_utils_1.normalizeVersion)(from), '15.7.0-beta.0')) {
         return [
             {
                 version: '15.7.0-beta.0',
@@ -1177,10 +1520,90 @@ function logNpmPeerDepsError(phase) {
         });
     }
 }
-async function executeMigrations(root, migrations, isVerbose, shouldCreateCommits, commitPrefix, shouldSkipInstall = false) {
+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 };
+    }
+    return {
+        effective: createCommits === true,
+        agenticHasDiffContext: false,
+    };
+}
+/**
+ * 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 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;
@@ -1188,40 +1611,319 @@ async function executeMigrations(root, migrations, isVerbose, shouldCreateCommit
         if (b.name === '15-7-0-split-configuration-into-project-json-files') {
             return 1;
         }
-        return (0, semver_1.lt)(normalizeVersion(a.version), normalizeVersion(b.version))
+        return (0, semver_1.lt)((0, version_utils_1.normalizeVersion)(a.version), (0, version_utils_1.normalizeVersion)(b.version))
             ? -1
             : 1;
     });
+    // 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 { runAgenticPromptStep } = require('./agentic/run-step');
+        agenticRun = {
+            agentic,
+            runDir: initRunDir(root, resolveAgenticRunId(sortedMigrations)),
+            runStep: runAgenticPromptStep,
+        };
+    }
+    const printDroppedAgentContext = agentic?.kind === 'inside-agent'
+        ? require('./agentic/print-dropped-agent-context').printDroppedAgentContextForOuterAgent
+        : undefined;
     logger_1.logger.info(`Running the following migrations:`);
-    sortedMigrations.forEach((m) => logger_1.logger.info(`- ${m.package}: ${m.name} (${m.description})`));
-    logger_1.logger.info(`---------------------------------------------------------\n`);
-    const allNextSteps = [];
+    sortedMigrations.forEach((m) => logger_1.logger.info(m.description
+        ? `- ${m.package}: ${m.name} — ${m.description}`
+        : `- ${m.package}: ${m.name}`));
+    logger_1.logger.info('');
+    // Tracked separately from `skippedPrompts` so the end-of-run logic can
+    // render them distinctly per resolution mode.
+    const migrationEmittedNextSteps = [];
+    const skippedPrompts = [];
+    // One record per migration the loop touched. `status: 'completed'` records
+    // are pushed at the end of each successful iteration; `status: 'aborted'`
+    // is pushed by the catch block when a migration throws mid-iteration, so
+    // `outcomes` is the single source of truth for the recap and tally — no
+    // parallel "pending" list. `outcomes.length` always equals `migrationIndex`
+    // after the loop body runs.
+    const outcomes = [];
+    // Prompt-only migrations whose agent never ran. Hybrid migrations with a
+    // skipped prompt are NOT counted here — their deterministic half still ran.
+    let notRunMigrationsCount = 0;
+    const skipReason = agentic?.kind === 'inside-agent'
+        ? 'deferred to the AI agent driving this run'
+        : 'agentic flow disabled';
+    const installDepsIfChanged = () => changedDepInstaller.installDepsIfChanged();
+    // Returns the migrations whose own commits failed and whose diffs are
+    // still sitting in the working tree — derived live from `outcomes`. The
+    // next successful commit absorbs them via `git add -A`; its commit body
+    // lists them so a reader of `git log -p` can see which prior migrations'
+    // diffs got pulled in.
+    const pendingForCommitBody = () => outcomes
+        .filter((o) => o.commit.kind === 'failed')
+        .map((o) => ({ package: o.migration.package, name: o.migration.name }));
+    // True while at least one prior migration's commit has failed and its
+    // diff hasn't been absorbed yet. While true, the working tree carries
+    // prior-migration state, so the `hasDiffContext` flag in the hybrid-
+    // agentic and validation-agentic prompt branches is suppressed (the
+    // prompt-only-with-agentic branch doesn't use `hasDiffContext`).
+    const hasPendingCommitDebt = () => outcomes.some((o) => o.commit.kind === 'failed');
+    // Single funnel for per-migration commit attempts. Returns the
+    // `CommitState` to record on the migration's outcome. On `committed`,
+    // back-annotates any prior failed-commit outcomes to `kind: 'absorbed'`
+    // (their diffs were just rolled into this commit via `git add -A`).
+    async function attemptMigrationCommit(m) {
+        const pending = pendingForCommitBody();
+        const result = await (0, migrate_commits_1.commitMigrationIfRequested)(root, m, shouldCreateCommits, commitPrefix, installDepsIfChanged, pending);
+        if (result.status === 'committed') {
+            // This commit absorbed every pending failed-commit migration's diff.
+            // Transition their `commit.kind: 'failed'` records to `'absorbed'` so
+            // the failure recap (if a later migration throws) can anchor them
+            // and the retained-state filter no longer counts them as
+            // uncommitted.
+            //
+            // The key is `package:name`; matching on `name` alone would conflate
+            // across packages. Guard the kind check so a subsequent absorption-
+            // of-same-name cannot overwrite an earlier annotation.
+            if (pending.length > 0) {
+                const absorbedKeys = new Set(pending.map((p) => `${p.package}:${p.name}`));
+                for (const o of outcomes) {
+                    const key = `${o.migration.package}:${o.migration.name}`;
+                    if (absorbedKeys.has(key) && o.commit.kind === 'failed') {
+                        o.commit = {
+                            kind: 'absorbed',
+                            into: { name: m.name, sha: result.sha },
+                        };
+                    }
+                }
+            }
+            return { kind: 'landed', sha: result.sha };
+        }
+        if (result.status === 'failed') {
+            // Diff is still in WT. Subsequent prompts cannot claim git-isolation
+            // until a later commit absorbs the backlog.
+            return { kind: 'failed' };
+        }
+        // `no-changes` and `disabled` — no commit attempted, nothing to record
+        // as a commit failure.
+        return { kind: 'none' };
+    }
+    const totalMigrations = sortedMigrations.length;
+    let migrationIndex = 0;
     for (const m of sortedMigrations) {
-        logger_1.logger.info(`Running migration ${m.package}: ${m.name}`);
+        migrationIndex++;
+        (0, migrate_output_1.logMigrationBoundary)(migrationIndex, totalMigrations, m.package, m.name);
+        // Snapshot the WT for before/after comparison in the catch block.
+        // Content-sensitive so a dirty→dirty case (this migration mutating an
+        // already-dirty shared file like `package.json`) doesn't collapse.
+        const baselineWorkingTreeSnapshot = (0, git_utils_1.getUncommittedChangesSnapshot)(root);
         try {
-            const { changes, nextSteps } = await runNxOrAngularMigration(root, m, isVerbose, shouldCreateCommits, commitPrefix, () => changedDepInstaller.installDepsIfChanged());
-            allNextSteps.push(...nextSteps);
-            if (changes.length === 0) {
-                migrationsWithNoChanges.push(m);
+            let outcome;
+            let commit = { kind: 'none' };
+            if ((0, migration_shape_1.isPromptOnlyMigration)(m)) {
+                if (agenticRun) {
+                    const stepResult = await agenticRun.runStep({
+                        root,
+                        migration: m,
+                        agentic: agenticRun.agentic,
+                        runDir: agenticRun.runDir,
+                        installDepsIfChanged,
+                    });
+                    commit = await attemptMigrationCommit(m);
+                    (0, migrate_output_1.logAgenticSuccessOutcome)(stepResult.ambiguous ? 'Marked complete by user' : 'Applied', commit.kind === 'landed' ? commit.sha : null, stepResult.summary);
+                    outcome = 'applied';
+                }
+                else {
+                    logger_1.logger.info(pc.dim(`↷ Skipped — ${skipReason}. Listed in next steps.`));
+                    skippedPrompts.push(m);
+                    notRunMigrationsCount++;
+                    outcome = 'deferred';
+                }
+            }
+            else if ((0, migration_shape_1.isHybridMigration)(m)) {
+                const { changes, nextSteps, agentContext, logs, madeChanges } = await runNxOrAngularMigration(root, m, isVerbose, 
+                /* captureGeneratorOutput: */ !!agenticRun);
+                migrationEmittedNextSteps.push(...nextSteps);
+                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.
+                    await installDepsIfChanged();
+                    const stepResult = await agenticRun.runStep({
+                        root,
+                        migration: m,
+                        agentic: agenticRun.agentic,
+                        runDir: agenticRun.runDir,
+                        installDepsIfChanged,
+                        implContext: {
+                            logs,
+                            changes,
+                            agentContext,
+                            // When prior commits failed, the working tree carries their
+                            // diff. The git-inspect path of the prompt would mislead the
+                            // agent in that case; fall back to embedded `<files_changed>`.
+                            hasDiffContext: agenticHasDiffContext && !hasPendingCommitDebt(),
+                        },
+                    });
+                    commit = await attemptMigrationCommit(m);
+                    (0, migrate_output_1.logAgenticSuccessOutcome)(stepResult.ambiguous ? 'Marked complete by user' : 'Applied', commit.kind === 'landed' ? commit.sha : null, stepResult.summary);
+                    outcome = 'applied';
+                }
+                else {
+                    // The inner prompt step doesn't run here (agentic disabled, or
+                    // running inside an outer agent). Under `inside-agent`, surface the
+                    // generator-emitted `agentContext` to stdout so the outer driving
+                    // agent can ingest it. Under `disabled` the run is human-driven;
+                    // agent-targeted context would only add noise — drop.
+                    logger_1.logger.info(pc.dim(`↷ Prompt phase skipped — ${skipReason}. Listed in next steps.`));
+                    if (printDroppedAgentContext && agentContext.length > 0) {
+                        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}`));
+                    }
+                    outcome = 'deferred';
+                }
             }
-            logger_1.logger.info(`---------------------------------------------------------`);
+            else {
+                // 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, 
+                /* captureGeneratorOutput: */ !!validationRun);
+                migrationEmittedNextSteps.push(...nextSteps);
+                const canRunValidation = !!validationRun && changes.length > 0;
+                if (canRunValidation) {
+                    // Install any deps the deterministic phase added/bumped before the
+                    // validation agent runs — the agent may run tasks that need them.
+                    await installDepsIfChanged();
+                    const stepResult = await validationRun.runStep({
+                        root,
+                        migration: m,
+                        agentic: validationRun.agentic,
+                        runDir: validationRun.runDir,
+                        installDepsIfChanged,
+                        implContext: {
+                            logs,
+                            changes,
+                            agentContext,
+                            // See the hybrid agentic branch above for the rationale on
+                            // why pending commit debt gates git-inspect context.
+                            hasDiffContext: agenticHasDiffContext && !hasPendingCommitDebt(),
+                        },
+                        mode: 'generic-validation',
+                    });
+                    commit = await attemptMigrationCommit(m);
+                    (0, migrate_output_1.logAgenticSuccessOutcome)(stepResult.ambiguous
+                        ? 'Marked complete by user'
+                        : 'Validation passed', commit.kind === 'landed' ? commit.sha : null, stepResult.summary);
+                    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 (!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';
+                    }
+                }
+            }
+            outcomes.push({
+                migration: { package: m.package, name: m.name },
+                status: 'completed',
+                kind: outcome,
+                commit,
+            });
+            logger_1.logger.info('');
         }
         catch (e) {
+            // Record the in-flight migration as `aborted` so the recap and tally
+            // see it. `commit: 'failed'` requires both: (1) commits were
+            // requested — otherwise the "could not be created" recap line is
+            // false; (2) the WT snapshot diverged from the iteration baseline —
+            // net-new state, not the pre-existing pending diff. Else `'none'`.
+            const leftNewDiff = (0, git_utils_1.getUncommittedChangesSnapshot)(root) !== baselineWorkingTreeSnapshot;
+            outcomes.push({
+                migration: { package: m.package, name: m.name },
+                status: 'aborted',
+                commit: shouldCreateCommits && leftNewDiff
+                    ? { kind: 'failed' }
+                    : { kind: 'none' },
+            });
             if (!(e instanceof 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.
+                const capturedLogs = e?.capturedLogs;
+                const bodyLines = typeof capturedLogs === 'string' && capturedLogs.length > 0
+                    ? [
+                        'Output from the generator before it failed:',
+                        '',
+                        ...capturedLogs.split('\n'),
+                    ]
+                    : undefined;
                 output_1.output.error({
                     title: `Failed to run ${m.name} from ${m.package}. This workspace is NOT up to date!`,
+                    bodyLines,
+                });
+                (0, migrate_output_1.logFailureRecap)({
+                    migrationIndex,
+                    totalMigrations,
+                    outcomes,
+                    migrationEmittedNextSteps,
+                    insideAgent: agentic?.kind === 'inside-agent',
                 });
             }
             throw e;
         }
     }
     if (!shouldCreateCommits) {
-        await changedDepInstaller.installDepsIfChanged();
+        await installDepsIfChanged();
     }
     if (changedDepInstaller.skippedInstall) {
         logSkippedPostMigrationInstall(root);
     }
-    return { migrationsWithNoChanges, nextSteps: allNextSteps };
+    // Combined-view next-steps array kept for back-compat with repair.ts, which
+    // consumes the single `nextSteps` field.
+    const combinedNextSteps = [...migrationEmittedNextSteps];
+    if (skippedPrompts.length > 0) {
+        combinedNextSteps.push(formatSkippedPromptsNextStep(skippedPrompts));
+    }
+    return {
+        migrationsWithNoChanges,
+        skippedPromptsCount: skippedPrompts.length,
+        notRunMigrationsCount,
+        nextSteps: combinedNextSteps,
+        skippedPrompts,
+        migrationEmittedNextSteps,
+        committedShasCount: (0, migrate_output_1.countLandedCommits)(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.
+        // Formatted as `package: name` for direct display.
+        retainedAtSuccess: (0, migrate_output_1.retainedMigrations)(outcomes).map((p) => `${p.package}: ${p.name}`),
+    };
 }
 class ChangedDepInstaller {
     constructor(root, shouldSkipInstall = false) {
@@ -1246,6 +1948,7 @@ class ChangedDepInstaller {
         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;
@@ -1254,21 +1957,28 @@ function logSkippedPostMigrationInstall(root) {
         bodyLines: [`Run "${installCommand}" to install the updated dependencies.`],
     });
 }
-async function runNxOrAngularMigration(root, migration, isVerbose, shouldCreateCommits, commitPrefix, installDepsIfChanged, handleInstallDeps = false) {
-    if (!installDepsIfChanged) {
-        const changedDepInstaller = new ChangedDepInstaller(root);
-        installDepsIfChanged = () => changedDepInstaller.installDepsIfChanged();
-    }
+async function runNxOrAngularMigration(root, migration, isVerbose, captureGeneratorOutput = false) {
     const { collection, collectionPath } = 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 } = await runNxMigration(root, collectionPath, collection, migration.name, migration.version));
+        ({ 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}`);
-        logger_1.logger.info(`  ${migration.description}\n`);
-        if (changes.length < 1) {
+        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 };
+            return { changes, nextSteps, agentContext, logs, madeChanges };
         }
         logger_1.logger.info('Changes:');
         (0, tree_1.printChanges)(changes, '  ');
@@ -1277,40 +1987,26 @@ async function runNxOrAngularMigration(root, migration, isVerbose, shouldCreateC
     else {
         const ngCliAdapter = await getNgCompatLayer();
         const migrationProjectGraph = await (0, project_graph_1.createProjectGraphAsync)();
-        const { madeChanges, loggingQueue } = await ngCliAdapter.runMigration(root, migration.package, migration.name, (0, project_graph_1.readProjectsConfigurationFromProjectGraph)(migrationProjectGraph).projects, isVerbose, migrationProjectGraph);
+        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}`);
-        logger_1.logger.info(`  ${migration.description}\n`);
+        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 };
+            return { changes, nextSteps, agentContext, logs, madeChanges };
         }
         logger_1.logger.info('Changes:');
-        loggingQueue.forEach((log) => logger_1.logger.info('  ' + log));
+        ngResult.loggingQueue.forEach((log) => logger_1.logger.info('  ' + log));
         logger_1.logger.info('');
     }
-    if (shouldCreateCommits) {
-        await installDepsIfChanged();
-        const commitMessage = `${commitPrefix}${migration.name}`;
-        try {
-            const committedSha = (0, git_utils_1.commitChanges)(commitMessage, root);
-            if (committedSha) {
-                logger_1.logger.info(pc.dim(`- Commit created for changes: ${committedSha}`));
-            }
-            else {
-                logger_1.logger.info(pc.red(`- A commit could not be created/retrieved for an unknown reason`));
-            }
-        }
-        catch (e) {
-            logger_1.logger.info(pc.red(`- ${e.message}`));
-        }
-        // if we are running this function alone, we need to install deps internally
-    }
-    else if (handleInstallDeps) {
-        await installDepsIfChanged();
-    }
-    return { changes, nextSteps };
+    return { changes, nextSteps, agentContext, logs, madeChanges };
 }
-async function runMigrations(root, opts, args, isVerbose, shouldCreateCommits = false, commitPrefix, shouldSkipInstall = false) {
+async function runMigrations(root, opts, args, isVerbose, shouldCreateCommits, commitPrefix, shouldSkipInstall = false) {
     if (!shouldSkipInstall && !process.env.NX_MIGRATE_SKIP_INSTALL) {
         await runInstall();
     }
@@ -1340,26 +2036,130 @@ async function runMigrations(root, opts, args, isVerbose, shouldCreateCommits =
     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 { resolveAgentic } = require('./agentic/select');
+    const agentic = await resolveAgentic({
+        agentic: opts.agentic,
+        migrations,
+    });
+    const { effective: effectiveCreateCommits, agenticHasDiffContext, warning: createCommitsWarning, error: createCommitsError, } = resolveCreateCommits({
+        createCommits: shouldCreateCommits,
+        agenticKind: agentic.kind,
+        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 });
+    }
+    const shouldRunValidation = resolveShouldRunValidation({
+        validate: opts.validate,
+        agenticKind: agentic.kind,
+    });
     output_1.output.log({
         title: `Running migrations from '${opts.runMigrations}'` +
-            (shouldCreateCommits ? ', with each applied in a dedicated commit' : ''),
+            (effectiveCreateCommits
+                ? ', with each applied in a dedicated commit'
+                : ''),
     });
-    const migrations = (0, fileutils_1.readJsonFile)((0, path_1.join)(root, opts.runMigrations)).migrations;
-    const { migrationsWithNoChanges, nextSteps } = await executeMigrations(root, migrations, isVerbose, shouldCreateCommits, commitPrefix, shouldSkipInstall);
-    if (migrationsWithNoChanges.length < migrations.length) {
-        output_1.output.success({
-            title: `Successfully finished running migrations from '${opts.runMigrations}'. This workspace is up to date!`,
+    if (effectiveCreateCommits) {
+        (0, migrate_commits_1.commitCheckpointBeforeMigrations)(root, commitPrefix);
+    }
+    if (agentic.kind === 'enabled') {
+        const { packageJson: nxPackageJson } = (0, package_json_1.readModulePackageJson)('nx', (0, installation_directory_1.getNxRequirePaths)(root));
+        await (0, handoff_gitignore_1.applyAgenticHandoffGitignoreFallback)({
+            migrations,
+            installedNxVersion: nxPackageJson.version,
+            effectiveCreateCommits,
+            commitPrefix,
+            root,
+        });
+    }
+    const { migrationsWithNoChanges, skippedPromptsCount, notRunMigrationsCount, skippedPrompts, migrationEmittedNextSteps, committedShasCount, 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
+    // deferred count as "deferred", not "applied".
+    const appliedCount = migrations.length - skippedPrompts.length;
+    const insideAgent = agentic.kind === 'inside-agent';
+    const tallyLine = (0, migrate_output_1.buildTallyBodyLine)({
+        appliedCount,
+        committedShasCount,
+        skippedPromptsCount,
+        insideAgent,
+    });
+    const tallyBody = tallyLine ? [tallyLine] : undefined;
+    // Only claim "up to date" when there's nothing pending: no deferred
+    // prompts AND no migrations whose commits failed without being absorbed.
+    const upToDateSuffix = skippedPromptsCount > 0 || retainedAtSuccess.length > 0
+        ? ''
+        : ' This workspace is up to date!';
+    // Demote `output.success` to `output.warn` when there's uncommitted state
+    // retained from failed commits — the run did its work, but it would be
+    // misleading to lead with a green "Successfully finished" before the
+    // retained-state block. `.bind(output)` is required: assigning the method
+    // reference to a local would otherwise call it with `this === undefined`.
+    const completionLog = (retainedAtSuccess.length > 0 ? output_1.output.warn : output_1.output.success).bind(output_1.output);
+    const completionTitlePrefix = retainedAtSuccess.length > 0
+        ? 'Finished running migrations with uncommitted state retained'
+        : 'Successfully finished running migrations';
+    if (notRunMigrationsCount === migrations.length && migrations.length > 0) {
+        const remediation = insideAgent
+            ? 'The AI agent driving this run should apply each prompt — see next steps below.'
+            : 'Re-run with --agentic to apply them. See next steps below.';
+        output_1.output.warn({
+            title: `No migrations from '${opts.runMigrations}' were applied — every entry is a prompt-only migration. ${remediation}`,
+            bodyLines: tallyBody,
+        });
+    }
+    else if (ranWithChangesCount > 0) {
+        completionLog({
+            title: `${completionTitlePrefix} from '${opts.runMigrations}'.${upToDateSuffix}`,
+            bodyLines: tallyBody,
         });
     }
     else {
-        output_1.output.success({
-            title: `No changes were made from running '${opts.runMigrations}'. This workspace is up to date!`,
+        // Pathological-but-possible: a no-op run that still has retained state
+        // (e.g. pre-existing pending diffs that no commit absorbed). Demote
+        // explicitly rather than rely on the implicit invariant.
+        completionLog({
+            title: `No changes were made from running '${opts.runMigrations}'.${upToDateSuffix}`,
+            bodyLines: tallyBody,
+        });
+    }
+    if (retainedAtSuccess.length > 0) {
+        output_1.output.warn({
+            title: `Working-tree state retained from ${retainedAtSuccess.length} migration${retainedAtSuccess.length === 1 ? '' : 's'} whose commits could not be created`,
+            bodyLines: (0, migrate_output_1.buildRetainedAtSuccessBody)(retainedAtSuccess),
         });
     }
-    if (nextSteps.length > 0) {
+    if (insideAgent) {
+        // Under inside-agent, emit a directive block so the outer agent has
+        // explicit instructions to act on, not just relay.
+        const directiveLines = (0, migrate_output_1.buildDirectiveBlockBodyLines)({
+            skippedPrompts,
+            migrationEmittedNextSteps,
+        });
+        if (directiveLines.length > 0) {
+            output_1.output.log({
+                title: 'Next steps for the AI agent driving this run',
+                bodyLines: directiveLines,
+            });
+        }
+    }
+    else if (skippedPromptsCount > 0 || migrationEmittedNextSteps.length > 0) {
+        // Non-inside-agent path keeps the legacy "additional information" shape —
+        // the consumer is the human user.
+        const bodyLines = [];
+        if (skippedPromptsCount > 0) {
+            bodyLines.push(formatSkippedPromptsNextStep(skippedPrompts));
+        }
+        bodyLines.push(...migrationEmittedNextSteps);
         output_1.output.log({
             title: `Some migrations have additional information, see below.`,
-            bodyLines: nextSteps.map((line) => `- ${line}`),
+            bodyLines: bodyLines.map((line) => `- ${line}`),
         });
     }
 }
@@ -1374,22 +2174,47 @@ function getStringifiedPackageJsonDeps(root) {
         return '';
     }
 }
-async function runNxMigration(root, collectionPath, collection, name, migrationVersion) {
+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 nextSteps = await fn(host, {});
-    // This accounts for migrations that mistakenly return a generator callback
-    // from a migration. We've never executed these, so its not a breaking change that
-    // we don't call them now... but currently shipping a migration with one wouldn't break
-    // the migrate flow, so we are being cautious.
-    if (!isStringArray(nextSteps)) {
-        nextSteps = [];
+    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 };
+    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');
 }
 async function migrate(root, args, rawArgs) {
     await client_1.daemonClient.stop();
@@ -1490,7 +2315,7 @@ function buildMigrationMissingMessage(baseMessage, collectionPath, migrationVers
         const packageJson = (0, fileutils_1.readJsonFile)(packageJsonPath);
         const installedVersion = packageJson.version;
         if (installedVersion &&
-            (0, semver_1.lt)(normalizeVersion(installedVersion), normalizeVersion(migrationVersion))) {
+            (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);
@@ -1600,9 +2425,3 @@ const getNgCompatLayer = (() => {
         return _ngCliAdapter;
     };
 })();
-function isStringArray(value) {
-    if (!Array.isArray(value)) {
-        return false;
-    }
-    return value.every((v) => typeof v === 'string');
-}