nx 23.2.0-beta.7 → 23.2.0-beta.8

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

@@ -1,16 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MIGRATE_RUNS_RELATIVE_DIR = void 0;
+exports.HANDOFFS_DIR_NAME = exports.MIGRATE_RUNS_RELATIVE_DIR = void 0;
 exports.isHandoffGitignoreMigration = isHandoffGitignoreMigration;
 /**
- * Workspace-relative directory holding all migrate-run scratch (handoff
- * files). Shared by the run-dir layout in `handoff.ts` and the agent
- * permission rules in `definitions.ts` so the pre-authorized write scope
+ * Workspace-relative directory holding all migrate-run scratch: a run
+ * directory per run id. Shared by the run-dir layout in `handoff.ts` and the
+ * agent permission rules in `definitions.ts` so the pre-authorized write scope
  * can't drift from the actual layout. It lives here so `definitions.ts`,
  * loaded whenever the agentic flow is resolved, doesn't pull in the handoff
  * runtime for the path alone.
  */
 exports.MIGRATE_RUNS_RELATIVE_DIR = '.nx/migrate-runs';
+/**
+ * The one subtree of a run directory an agent writes: its handoff files.
+ * Everything beside it is state Nx owns and reads back, the orchestrator's
+ * run state and plan snapshots included, so the pre-authorized write scope
+ * stops at this segment. Package names make up the rest of a handoff path,
+ * so without it they would occupy the run directory's top level and leave Nx
+ * no name it could add there safely.
+ */
+exports.HANDOFFS_DIR_NAME = 'handoffs';
 /**
  * Composite identity of the v23 migration that adds `.nx/migrate-runs` to
  * `.gitignore`. Hard-coded because the agentic preflight is a deliberate

package/dist/src/command-line/migrate/command-object.d.ts

@@ -1,5 +1,6 @@
 import { CommandModule } from 'yargs';
 import type { AgenticArg } from './agentic/select';
+import { type StepAction } from './step-actions';
 export declare const yargsMigrateCommand: CommandModule;
 export declare const yargsInternalMigrateCommand: CommandModule;
 export declare const DEFAULT_MIGRATION_COMMIT_PREFIX = "chore: [nx migration] ";
@@ -18,6 +19,8 @@ export interface MigrateArgs {
     packageAndVersion?: string;
     runMigrations?: string;
     runMigration?: string;
+    runId?: string;
+    stepAction?: StepAction;
     include?: MigrateInclude;
     /**
      * nx.json `migrate.include` default. Consumed by `resolveInclude` only when the

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

@@ -6,6 +6,7 @@ const handle_import_1 = require("../../utils/handle-import");
 const documentation_1 = require("../yargs-utils/documentation");
 const shared_options_1 = require("../yargs-utils/shared-options");
 const cli_args_1 = require("./agentic/cli-args");
+const step_actions_1 = require("./step-actions");
 exports.yargsMigrateCommand = {
     command: 'migrate [packageAndVersion]',
     describe: `Creates a migrations file or runs migrations from the migrations file.
@@ -56,6 +57,18 @@ function withMigrationOptions(yargs) {
         .option('runMigration', {
         describe: "Run a single migration from migrations.json by id. The id is '<package>:<name>'; a bare '<name>' is accepted when it matches exactly one migration. A name that contains ':' must use the full '<package>:<name>' form.",
         type: 'string',
+    })
+        .option('runId', {
+        // Hidden with the orchestrator itself.
+        describe: 'The orchestrated migrate run to record a single migration into, or to reconcile when given without --run-migration.',
+        type: 'string',
+        hidden: true,
+    })
+        .option('stepAction', {
+        describe: 'How an orchestrated reconcile resolves its single failed or died step.',
+        choices: step_actions_1.STEP_ACTIONS,
+        type: 'string',
+        hidden: true,
     })
         .option('ifExists', {
         describe: `Run migrations only if the migrations file exists, if not continues successfully.`,

package/dist/src/command-line/migrate/execute-migration.d.ts

@@ -28,8 +28,15 @@ export declare class ChangedDepInstaller {
     private readonly rerunCommand?;
     private initialDeps;
     private _skippedInstall;
+    private _installed;
     constructor(root: string, shouldSkipInstall?: boolean, rerunCommand?: string);
     get skippedInstall(): boolean;
+    /**
+     * Whether an install actually ran. Distinct from `!skippedInstall`, which is
+     * only about the skip-install flag: dependencies that never changed leave
+     * both false.
+     */
+    get installed(): boolean;
     installDepsIfChanged(): Promise<void>;
 }
 export declare function runNxOrAngularMigration(root: string, migration: {
@@ -45,6 +52,13 @@ export declare function runNxOrAngularMigration(root: string, migration: {
     logs: string;
     madeChanges: boolean;
 }>;
+/**
+ * The workspace's declared dependencies, serialized for equality comparison,
+ * or `null` when package.json could not be read or parsed. Callers that
+ * persist the value across processes need that distinction: an unreadable
+ * package.json is not an empty dependency set.
+ */
+export declare function readPackageJsonDeps(root: string): string | null;
 export declare function getStringifiedPackageJsonDeps(root: string): string;
 export declare function runNxMigration(root: string, collectionPath: string, collection: MigrationsJson, name: string, migrationVersion: string | undefined, captureGeneratorOutput: boolean): Promise<{
     changes: FileChange[];

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

@@ -8,6 +8,7 @@ exports.formatSingleMigrationRerunCommand = formatSingleMigrationRerunCommand;
 exports.logNpmPeerDepsError = logNpmPeerDepsError;
 exports.logSkippedPostMigrationInstall = logSkippedPostMigrationInstall;
 exports.runNxOrAngularMigration = runNxOrAngularMigration;
+exports.readPackageJsonDeps = readPackageJsonDeps;
 exports.getStringifiedPackageJsonDeps = getStringifiedPackageJsonDeps;
 exports.runNxMigration = runNxMigration;
 exports.parseMigrationReturn = parseMigrationReturn;
@@ -25,6 +26,7 @@ const handle_import_1 = require("../../utils/handle-import");
 const tree_1 = require("../../generators/tree");
 const fileutils_1 = require("../../utils/fileutils");
 const logger_1 = require("../../utils/logger");
+const text_1 = require("./text");
 const package_json_1 = require("../../utils/package-json");
 const package_manager_1 = require("../../utils/package-manager");
 const output_1 = require("../../utils/output");
@@ -199,11 +201,20 @@ class ChangedDepInstaller {
         this.shouldSkipInstall = shouldSkipInstall;
         this.rerunCommand = rerunCommand;
         this._skippedInstall = false;
+        this._installed = false;
         this.initialDeps = getStringifiedPackageJsonDeps(root);
     }
     get skippedInstall() {
         return this._skippedInstall;
     }
+    /**
+     * Whether an install actually ran. Distinct from `!skippedInstall`, which is
+     * only about the skip-install flag: dependencies that never changed leave
+     * both false.
+     */
+    get installed() {
+        return this._installed;
+    }
     async installDepsIfChanged() {
         const currentDeps = getStringifiedPackageJsonDeps(this.root);
         if (this.initialDeps !== currentDeps) {
@@ -212,6 +223,7 @@ class ChangedDepInstaller {
             }
             else {
                 await runInstall(this.root, 'post-migration', this.rerunCommand);
+                this._installed = true;
             }
         }
         this.initialDeps = currentDeps;
@@ -235,9 +247,9 @@ async function runNxOrAngularMigration(root, migration, isVerbose, captureGenera
         ({ nextSteps, changes, agentContext, skipAgentic, 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((0, text_1.singleLine)(`Ran ${migration.name} from ${migration.package}`));
         if (migration.description) {
-            logger_1.logger.info(`  ${migration.description}`);
+            logger_1.logger.info((0, text_1.singleLine)(`  ${migration.description}`));
         }
         logger_1.logger.info('');
         if (!madeChanges) {
@@ -262,9 +274,9 @@ async function runNxOrAngularMigration(root, migration, isVerbose, captureGenera
         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((0, text_1.singleLine)(`Ran ${migration.name} from ${migration.package}`));
         if (migration.description) {
-            logger_1.logger.info(`  ${migration.description}`);
+            logger_1.logger.info((0, text_1.singleLine)(`  ${migration.description}`));
         }
         logger_1.logger.info('');
         if (!madeChanges) {
@@ -279,22 +291,31 @@ async function runNxOrAngularMigration(root, migration, isVerbose, captureGenera
             };
         }
         logger_1.logger.info('Changes:');
-        ngResult.loggingQueue.forEach((log) => logger_1.logger.info('  ' + log));
+        ngResult.loggingQueue.forEach((log) => logger_1.logger.info((0, text_1.singleLine)('  ' + log)));
         logger_1.logger.info('');
     }
     return { changes, nextSteps, agentContext, skipAgentic, logs, madeChanges };
 }
-function getStringifiedPackageJsonDeps(root) {
+/**
+ * The workspace's declared dependencies, serialized for equality comparison,
+ * or `null` when package.json could not be read or parsed. Callers that
+ * persist the value across processes need that distinction: an unreadable
+ * package.json is not an empty dependency set.
+ */
+function readPackageJsonDeps(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 '';
+        return null;
     }
 }
+function getStringifiedPackageJsonDeps(root) {
+    // We don't really care if the .nx/installation property changes,
+    // whenever nxw is invoked it will handle the dep updates.
+    return readPackageJsonDeps(root) ?? '';
+}
 async function runNxMigration(root, collectionPath, collection, name, migrationVersion, captureGeneratorOutput) {
     const { path: implPath, fnSymbol } = getImplementationPath(collection, collectionPath, name, migrationVersion);
     const fn = require(implPath)[fnSymbol];

package/dist/src/command-line/migrate/migrate-analytics.d.ts

@@ -67,12 +67,40 @@ export declare function reportMigrateRunError(opts: {
     migrationCount?: number;
     error?: unknown;
 }): void;
+export declare function reportMigrateOrchestratorInit(opts: {
+    migrationCount: number;
+    createCommits: boolean;
+}): void;
+/**
+ * One event per orchestrator dispense. The `action` (dispense case) is a
+ * closed enum carried on a reused dimension, read conditioned on the event
+ * name (the same multiplexing pattern as {@link reportMigratePrompt});
+ * `attempt` rides the migration-count dimension.
+ */
+export declare function reportMigrateOrchestratorDispense(opts: {
+    action: string;
+    attempt: number;
+}): void;
+/**
+ * Terminal funnel event. The two step tallies and the total dispense count
+ * ride reused numeric dimensions, read conditioned on the event name.
+ */
+export declare function reportMigrateOrchestratorComplete(opts: {
+    completed: number;
+    skipped: number;
+    dispenseCount: number;
+}): void;
 /**
  * Counts invocations, not completions: emitted as soon as the migration id
  * resolves, while the worker can still stop before running anything.
+ *
+ * An invocation recorded into an orchestrated run (`--run-id`) gets its own
+ * event name. Every other one keeps the name `--run-migration` shipped with,
+ * so that series stays continuous for users who never enable the orchestrator.
  */
 export declare function reportMigrateSingleMigrationInvocation(opts: {
     migrationType: 'generator' | 'prompt' | 'hybrid';
+    orchestrated: boolean;
 }): void;
 export declare function computeMajorsCrossed(installed: string | null | undefined, target: string | null | undefined): number | undefined;
 export declare function safeReport(emit: () => void): void;

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

@@ -11,6 +11,9 @@ exports.reportMigrateRunStart = reportMigrateRunStart;
 exports.hasMigrateRunStarted = hasMigrateRunStarted;
 exports.reportMigrateRunComplete = reportMigrateRunComplete;
 exports.reportMigrateRunError = reportMigrateRunError;
+exports.reportMigrateOrchestratorInit = reportMigrateOrchestratorInit;
+exports.reportMigrateOrchestratorDispense = reportMigrateOrchestratorDispense;
+exports.reportMigrateOrchestratorComplete = reportMigrateOrchestratorComplete;
 exports.reportMigrateSingleMigrationInvocation = reportMigrateSingleMigrationInvocation;
 exports.computeMajorsCrossed = computeMajorsCrossed;
 exports.safeReport = safeReport;
@@ -181,15 +184,62 @@ function reportMigrateRunError(opts) {
         });
     });
 }
+function reportMigrateOrchestratorInit(opts) {
+    safeReport(() => {
+        if (!analytics_1.customDimensions)
+            return;
+        (0, analytics_1.reportEvent)('migrate_orchestrator_init', {
+            [analytics_1.customDimensions.createCommits]: opts.createCommits,
+            [analytics_1.customDimensions.migrationCount]: opts.migrationCount,
+        });
+    });
+}
+/**
+ * One event per orchestrator dispense. The `action` (dispense case) is a
+ * closed enum carried on a reused dimension, read conditioned on the event
+ * name (the same multiplexing pattern as {@link reportMigratePrompt});
+ * `attempt` rides the migration-count dimension.
+ */
+function reportMigrateOrchestratorDispense(opts) {
+    safeReport(() => {
+        if (!analytics_1.customDimensions)
+            return;
+        (0, analytics_1.reportEvent)('migrate_orchestrator_dispense', {
+            [analytics_1.customDimensions.promptChoice]: opts.action,
+            [analytics_1.customDimensions.migrationCount]: opts.attempt,
+        });
+    });
+}
+/**
+ * Terminal funnel event. The two step tallies and the total dispense count
+ * ride reused numeric dimensions, read conditioned on the event name.
+ */
+function reportMigrateOrchestratorComplete(opts) {
+    safeReport(() => {
+        if (!analytics_1.customDimensions)
+            return;
+        (0, analytics_1.reportEvent)('migrate_orchestrator_complete', {
+            [analytics_1.customDimensions.appliedCount]: opts.completed,
+            [analytics_1.customDimensions.taskCount]: opts.skipped,
+            [analytics_1.customDimensions.migrationCount]: opts.dispenseCount,
+        });
+    });
+}
 /**
  * Counts invocations, not completions: emitted as soon as the migration id
  * resolves, while the worker can still stop before running anything.
+ *
+ * An invocation recorded into an orchestrated run (`--run-id`) gets its own
+ * event name. Every other one keeps the name `--run-migration` shipped with,
+ * so that series stays continuous for users who never enable the orchestrator.
  */
 function reportMigrateSingleMigrationInvocation(opts) {
     safeReport(() => {
         if (!analytics_1.customDimensions)
             return;
-        (0, analytics_1.reportEvent)('migrate_single_migration_invocation', {
+        (0, analytics_1.reportEvent)(opts.orchestrated
+            ? 'migrate_single_migration_recorded'
+            : 'migrate_single_migration_invocation', {
             [analytics_1.customDimensions.promptChoice]: opts.migrationType,
         });
     });

package/dist/src/command-line/migrate/migrate-commits.d.ts

@@ -55,7 +55,7 @@ export declare function commitCheckpointBeforeMigrations(root: string, commitPre
  */
 export declare function resolveCreateCommits(args: {
     createCommits: boolean | undefined;
-    agenticKind: ResolvedAgentic['kind'];
+    mode: ResolvedAgentic['kind'] | 'orchestrated';
     isGitRepo: boolean;
     commitPrefixIsCustom?: boolean;
 }): {
@@ -65,9 +65,15 @@ export declare function resolveCreateCommits(args: {
     error?: string;
 };
 /**
+ * Asks before a run starts committing on the workspace's default branch, and
+ * reports the decision when the answer is no. Returns whether to proceed.
+ *
  * Callers gate this on commits being effective and on prompting being
- * possible, so non-interactive runs (CI, `--no-interactive`) never reach here.
+ * possible, so non-interactive runs (CI, `--no-interactive`) never reach here;
+ * `confirmCommitsOnDefaultBranch` has no guard of its own and would block on a
+ * prompt nobody can answer.
  */
+export declare function confirmMigrationCommitsOnDefaultBranch(root: string, whatWouldRun: 'running migrations' | 'running the migration'): Promise<boolean>;
 export declare function confirmCommitsOnDefaultBranch(args: {
     currentBranch: string | null;
     defaultBranch: string | null;

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

@@ -3,13 +3,21 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.commitMigrationIfRequested = commitMigrationIfRequested;
 exports.commitCheckpointBeforeMigrations = commitCheckpointBeforeMigrations;
 exports.resolveCreateCommits = resolveCreateCommits;
+exports.confirmMigrationCommitsOnDefaultBranch = confirmMigrationCommitsOnDefaultBranch;
 exports.confirmCommitsOnDefaultBranch = confirmCommitsOnDefaultBranch;
 const tslib_1 = require("tslib");
 const pc = tslib_1.__importStar(require("picocolors"));
+const configuration_1 = require("../../config/configuration");
+const command_line_utils_1 = require("../../utils/command-line-utils");
 const git_utils_1 = require("../../utils/git-utils");
 const logger_1 = require("../../utils/logger");
 const output_1 = require("../../utils/output");
+const types_1 = require("./agentic/types");
 const safe_prompt_1 = require("./safe-prompt");
+// `git add -A` captures an orchestrated run's scratch state whenever the
+// ignore rule that normally hides it goes missing mid-run (a checkout, a
+// .gitignore edit, or the migration's own changes).
+const MIGRATE_COMMIT_EXCLUDES = [types_1.MIGRATE_RUNS_RELATIVE_DIR];
 /**
  * `pendingMigrations` are listed in the commit body so a `git log -p` reader
  * can see which earlier migrations' diffs this commit absorbed (their own
@@ -23,15 +31,16 @@ async function commitMigrationIfRequested(root, migration, shouldCreateCommits,
     if (!shouldCreateCommits)
         return { status: 'disabled' };
     await installDepsIfChanged();
-    // Generator may have only touched gitignored paths, or the prompt half
-    // made no change — log neutrally instead of as an error.
-    if (!(0, git_utils_1.hasUncommittedChanges)(root)) {
+    // Generator may have only touched gitignored paths or the excluded scratch
+    // dir, or the prompt half made no change: log neutrally, not as an error.
+    // The probe excludes what the commit excludes, else the commit fails empty.
+    if (!(0, git_utils_1.hasUncommittedChanges)(root, MIGRATE_COMMIT_EXCLUDES)) {
         logger_1.logger.info(pc.dim(`- No changes to commit for ${migration.name}.`));
         return { status: 'no-changes' };
     }
     const commitMessage = buildCommitMessage(`${commitPrefix}${migration.name}`, pendingMigrations);
     try {
-        const sha = (0, git_utils_1.tryCommitChanges)(commitMessage, root);
+        const sha = (0, git_utils_1.tryCommitChanges)(commitMessage, root, MIGRATE_COMMIT_EXCLUDES);
         if (sha)
             return { status: 'committed', sha };
         // null = commit landed but `git rev-parse HEAD` failed (see
@@ -74,10 +83,10 @@ function buildCommitMessage(subject, pendingMigrations) {
  * the working tree is already clean.
  */
 function commitCheckpointBeforeMigrations(root, commitPrefix) {
-    if (!(0, git_utils_1.hasUncommittedChanges)(root))
+    if (!(0, git_utils_1.hasUncommittedChanges)(root, MIGRATE_COMMIT_EXCLUDES))
         return;
     try {
-        const sha = (0, git_utils_1.tryCommitChanges)(`${commitPrefix}checkpoint before running migrations`, root);
+        const sha = (0, git_utils_1.tryCommitChanges)(`${commitPrefix}checkpoint before running migrations`, root, MIGRATE_COMMIT_EXCLUDES);
         if (sha) {
             logger_1.logger.info(pc.dim(`- Checkpoint commit created: ${sha}`));
             return;
@@ -108,7 +117,11 @@ function commitCheckpointBeforeMigrations(root, commitPrefix) {
  * pointing at git.
  */
 function resolveCreateCommits(args) {
-    const { createCommits, agenticKind, isGitRepo, commitPrefixIsCustom } = args;
+    const { createCommits, mode, isGitRepo, commitPrefixIsCustom } = args;
+    // The orchestrator forces the agentic defaults without the `--agentic` flag,
+    // so its warnings must not name a flag the user never passed.
+    const orchestrated = mode === 'orchestrated';
+    const agenticKind = orchestrated ? 'enabled' : mode;
     if (createCommits === true && !isGitRepo) {
         return {
             effective: false,
@@ -121,7 +134,9 @@ function resolveCreateCommits(args) {
             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." +
+                warning: (orchestrated
+                    ? "--no-create-commits was passed, but orchestrated migrate runs create per-migration commits by default. Without them, 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."
+                    : "--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.'
                         : ''),
@@ -133,7 +148,9 @@ function resolveCreateCommits(args) {
             return {
                 effective: false,
                 agenticHasDiffContext: false,
-                warning: '`--agentic` enables per-migration commits by default, but the workspace is not a git repository. Continuing without commits, so the agent will not receive per-file diff context. Run `git init` to enable.' +
+                warning: (orchestrated
+                    ? 'Orchestrated migrate runs create per-migration commits by default, but the workspace is not a git repository. Continuing without commits, so the agent will not receive per-file diff context. Run `git init` to enable.'
+                    : '`--agentic` enables per-migration commits by default, but the workspace is not a git repository. Continuing without commits, so the agent will not receive per-file diff context. Run `git init` to enable.') +
                     (commitPrefixIsCustom
                         ? ' The custom --commit-prefix value will have no effect.'
                         : ''),
@@ -149,22 +166,52 @@ function resolveCreateCommits(args) {
             : undefined,
     };
 }
+// The branch to hold `getBaseRef`'s value against. It may name a remote-tracking
+// ref whose local counterpart drops the remote (the CI-workflow generator writes
+// `origin/<branch>`), yet a local branch can be named `up/feature` while `up` is
+// a remote, so an exact match wins before any stripping and the longest matching
+// remote wins after. `origin` counts even undeclared: the generator assumes it.
+function defaultBranchToCompare(baseRef, currentBranch, root) {
+    if (currentBranch === baseRef) {
+        return baseRef;
+    }
+    const remote = [...(0, git_utils_1.getGitRemoteNames)(root), 'origin']
+        .filter((name) => baseRef.startsWith(`${name}/`))
+        .sort((a, b) => b.length - a.length)[0];
+    return remote ? baseRef.slice(remote.length + 1) : baseRef;
+}
 /**
+ * Asks before a run starts committing on the workspace's default branch, and
+ * reports the decision when the answer is no. Returns whether to proceed.
+ *
  * Callers gate this on commits being effective and on prompting being
- * possible, so non-interactive runs (CI, `--no-interactive`) never reach here.
+ * possible, so non-interactive runs (CI, `--no-interactive`) never reach here;
+ * `confirmCommitsOnDefaultBranch` has no guard of its own and would block on a
+ * prompt nobody can answer.
  */
+async function confirmMigrationCommitsOnDefaultBranch(root, whatWouldRun) {
+    const currentBranch = (0, git_utils_1.getGitCurrentBranch)(root);
+    const proceed = await confirmCommitsOnDefaultBranch({
+        currentBranch,
+        defaultBranch: defaultBranchToCompare((0, command_line_utils_1.getBaseRef)((0, configuration_1.readNxJson)(root)), currentBranch, root),
+    });
+    if (!proceed) {
+        output_1.output.log({
+            title: `Skipped ${whatWouldRun} 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 proceed;
+}
 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;
+    return (0, safe_prompt_1.migrateConfirm)({
+        message: `You're on the default branch '${currentBranch}'. nx migrate will create a commit for each migration on this branch. Continue?`,
+        initial: false,
+    });
 }

package/dist/src/command-line/migrate/migrate-config.d.ts

@@ -8,8 +8,10 @@ import { type MigrateArgs } from './command-object';
  * Phase-aware so each option is only filled where it is consumed, and so a
  * config value never trips the mutually-exclusive-flag guards in
  * `parseMigrationsOptions`: `include` and `multiMajorMode` in the generate
- * phase only, `agentic` / `validate` / `createCommits` / `commitPrefix` when
- * running the whole migrations file or a single migration.
+ * phase only; `createCommits` / `commitPrefix` and `agentic` / `validate` when
+ * running the whole migrations file or a standalone single migration. A
+ * `--run-id` invocation takes none of them: a recorded run takes its commit
+ * config from run.json and is driven by the outer agent.
  *
  * `include` is carried as `includeFromConfig` so it is never mistaken for an
  * explicit `--include`: `resolveInclude` applies it only when the resolved

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

@@ -13,8 +13,10 @@ const MULTI_MAJOR_MODE_ENV = 'NX_MULTI_MAJOR_MODE';
  * Phase-aware so each option is only filled where it is consumed, and so a
  * config value never trips the mutually-exclusive-flag guards in
  * `parseMigrationsOptions`: `include` and `multiMajorMode` in the generate
- * phase only, `agentic` / `validate` / `createCommits` / `commitPrefix` when
- * running the whole migrations file or a single migration.
+ * phase only; `createCommits` / `commitPrefix` and `agentic` / `validate` when
+ * running the whole migrations file or a standalone single migration. A
+ * `--run-id` invocation takes none of them: a recorded run takes its commit
+ * config from run.json and is driven by the outer agent.
  *
  * `include` is carried as `includeFromConfig` so it is never mistaken for an
  * explicit `--include`: `resolveInclude` applies it only when the resolved
@@ -28,8 +30,14 @@ function applyNxJsonMigrateDefaults(args, migrateConfig, env = process.env) {
     // `--run-migrations` with no value is normalized to '' by yargs, so a defined
     // (even empty-string) value means we're in the run-migrations phase.
     const isRunMigrations = merged.runMigrations !== undefined;
-    const isSingleMigration = merged.runMigration !== undefined;
-    if (isRunMigrations || isSingleMigration) {
+    // A bare `--run-id` (orchestrated reconcile) must never take the
+    // generate-options overlay, which would leak `include` etc. from nx.json.
+    const isSingleMigration = merged.runMigration !== undefined || merged.runId !== undefined;
+    // Both overlays are for an invocation that decides these options for
+    // itself, which a `--run-id` invocation never does: the recorded worker and
+    // the reconcile both read the commit config from run.json, and overlaying
+    // `agentic` would trip the `--agentic`/`--run-id` parse conflict.
+    if ((isRunMigrations || isSingleMigration) && merged.runId === undefined) {
         if (merged.createCommits === undefined &&
             migrateConfig.createCommits !== undefined) {
             assertType(migrateConfig.createCommits, 'boolean', 'createCommits');

package/dist/src/command-line/migrate/migrate.d.ts

@@ -10,6 +10,7 @@ import type { ResolvedAgentic } from './agentic/types';
 import { isHybridMigration, isPromptOnlyMigration, type PlannedMigration } from './migration-shape';
 import { filterDowngradedUpdates } from './update-filters';
 import { normalizeVersion } from './version-utils';
+import { type StepAction } from './step-actions';
 export * from './execute-migration';
 export { normalizeVersion };
 export interface ResolvedMigrationConfiguration extends MigrationsJson {
@@ -170,11 +171,17 @@ type RunMigrations = {
 type RunSingleMigration = {
     type: 'runSingleMigration';
     runMigration: string;
+    runId?: string;
     agentic: AgenticArg;
     validate?: boolean;
     interactive?: boolean;
 };
-export declare function parseMigrationsOptions(options: MigrateArgs, fetch?: MigratorOptions['fetch']): Promise<GenerateMigrations | RunMigrations | RunSingleMigration>;
+type OrchestratorReconcile = {
+    type: 'orchestratorReconcile';
+    runId: string;
+    stepAction?: StepAction;
+};
+export declare function parseMigrationsOptions(options: MigrateArgs, fetch?: MigratorOptions['fetch']): Promise<GenerateMigrations | RunMigrations | RunSingleMigration | OrchestratorReconcile>;
 export declare function createFetcher(pmc: PackageManagerCommands): ((pkg: string, version: string) => Promise<ResolvedMigrationConfiguration>) & {
     stats?: MigrateFetchStats;
 };
@@ -193,7 +200,7 @@ export declare function executeMigrations(root: string, migrations: PlannedMigra
     waivedAgenticStepsCount: number;
     retainedAtSuccess: string[];
 }>;
-export declare function isSingleMigrationInvocation(args: Pick<MigrateArgs, 'runMigration'>): boolean;
+export declare function isRunPhaseInvocation(args: Pick<MigrateArgs, 'runMigration' | 'runId' | 'stepAction'>): boolean;
 export declare function migrate(root: string, args: {
     [k: string]: any;
 }, rawArgs: string[]): Promise<number>;