nx 23.3.0-beta.7 → 23.3.0-beta.9

package/README.md

@@ -12,7 +12,7 @@
 [![Semantic Release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg?style=flat-square)](<>)
 [![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
 [![Join us on the Official Nx Discord Server](https://img.shields.io/discord/1143497901675401286?label=discord)](https://go.nx.dev/community)
-[![Nx Sandboxing](https://staging.nx.app/workspaces/62d013ea0852fe0a2df74438/sandbox-badge.svg)](https://nx.dev/docs/features/ci-features/sandboxing)
+[![Hours saved](https://img.shields.io/endpoint?url=https%3A%2F%2Fstaging.nx.app%2Fnx-cloud%2Fbadge%2F62d013ea0852fe0a2df74438%2Fhours-saved.json)](https://nx.dev/nx-cloud)
 
 </div>
 

package/dist/nx-cloud-internals.d.ts

@@ -1 +1 @@
-export { importIoSnapshots, openIoSnapshots } from './src/io-snapshots/store';
+export { importUltracacheConfigurations, openUltracacheConfigurations, } from './src/ultracache/store';

package/dist/nx-cloud-internals.js

@@ -3,7 +3,7 @@
 // a public API. The client probes these exports to tell what this nx supports,
 // so keep them stable.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.openIoSnapshots = exports.importIoSnapshots = void 0;
-var store_1 = require("./src/io-snapshots/store");
-Object.defineProperty(exports, "importIoSnapshots", { enumerable: true, get: function () { return store_1.importIoSnapshots; } });
-Object.defineProperty(exports, "openIoSnapshots", { enumerable: true, get: function () { return store_1.openIoSnapshots; } });
+exports.openUltracacheConfigurations = exports.importUltracacheConfigurations = void 0;
+var store_1 = require("./src/ultracache/store");
+Object.defineProperty(exports, "importUltracacheConfigurations", { enumerable: true, get: function () { return store_1.importUltracacheConfigurations; } });
+Object.defineProperty(exports, "openUltracacheConfigurations", { enumerable: true, get: function () { return store_1.openUltracacheConfigurations; } });

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

@@ -15,6 +15,8 @@ const configuration_1 = require("../../config/configuration");
 const find_matching_projects_1 = require("../../utils/find-matching-projects");
 const graph_1 = require("../graph/graph");
 const affected_tasks_1 = require("../../project-graph/affected/affected-tasks");
+const affected_reasons_1 = require("../../project-graph/affected/affected-reasons");
+const print_explanation_1 = require("../../project-graph/affected/print-explanation");
 async function affected(command, args, extraTargetDependencies = {}, extraOptions = {
     excludeTaskDependencies: args.excludeTaskDependencies,
     loadDotEnvFiles: process.env.NX_LOAD_DOT_ENV_FILES !== 'false',
@@ -31,12 +33,19 @@ async function affected(command, args, extraTargetDependencies = {}, extraOption
     const useTasks = (0, affected_tasks_1.selectsAffectedTasks)() &&
         command === 'affected' &&
         !!nxArgs.targets?.length;
+    if ((0, affected_reasons_1.isExplaining)(nxArgs.explain) && !useTasks) {
+        throw new Error((0, affected_reasons_1.explainUnavailable)([
+            !(0, affected_tasks_1.selectsAffectedTasks)() && 'NX_LEGACY_AFFECTED=false',
+            !nxArgs.targets?.length && 'targets passed with --targets (-t)',
+        ].filter(Boolean)));
+    }
     // Outside the try so errors reach handleErrors, as they did from inside runCommand.
     let projectGraph;
     let taskSelection;
     let projects = [];
     if (useTasks) {
-        ({ projectGraph, taskSelection } = await (0, affected_tasks_1.computeAffectedTasks)({
+        let explanation;
+        ({ projectGraph, taskSelection, explanation } = await (0, affected_tasks_1.computeAffectedTasks)({
             nxJson,
             targets: nxArgs.targets,
             touchedFiles: (0, file_utils_1.calculateFileChanges)((0, command_line_utils_1.parseFiles)(nxArgs).files, nxArgs),
@@ -50,8 +59,18 @@ async function affected(command, args, extraTargetDependencies = {}, extraOption
             extraTargetDependencies,
             excludeTaskDependencies: extraOptions.excludeTaskDependencies,
             exclude: nxArgs.exclude,
+            explain: (0, affected_reasons_1.isExplaining)(nxArgs.explain),
             ...(await (0, run_command_1.runnerInputsForSelection)(nxArgs, nxJson)),
         }));
+        // --explain reports the selection rather than acting on it: someone asking
+        // why a task is affected does not also want it to run.
+        if ((0, affected_reasons_1.isExplaining)(nxArgs.explain)) {
+            (0, print_explanation_1.printAffectedExplanation)(explanation, 'Affected tasks', nxArgs.explain, {
+                verbose: args.verbose,
+            });
+            await output_1.output.drain();
+            process.exit(0);
+        }
     }
     else {
         projectGraph = await (0, project_graph_1.createProjectGraphAsync)({ exitOnError: true });

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

@@ -8,7 +8,7 @@ const shared_options_1 = require("../yargs-utils/shared-options");
 exports.yargsAffectedCommand = {
     command: 'affected',
     describe: 'Run target for affected projects. Affected projects are projects that have been changed and projects that depend on the changed projects. See https://nx.dev/ci/features/affected for more details.',
-    builder: (yargs) => (0, documentation_1.linkToNxDevAndExamples)((0, shared_options_1.withAffectedOptions)((0, shared_options_1.withTuiOptions)((0, shared_options_1.withRunOptions)((0, shared_options_1.withOutputStyleOption)((0, shared_options_1.withTargetAndConfigurationOption)((0, shared_options_1.withBatch)(yargs))))))
+    builder: (yargs) => (0, documentation_1.linkToNxDevAndExamples)((0, shared_options_1.withAffectedOptions)((0, shared_options_1.withTuiOptions)((0, shared_options_1.withRunOptions)((0, shared_options_1.withOutputStyleOption)((0, shared_options_1.withTargetAndConfigurationOption)((0, shared_options_1.withBatch)((0, shared_options_1.withExplainOption)(yargs)))))))
         .option('all', {
         type: 'boolean',
         deprecated: 'Use `nx run-many` instead',

package/dist/src/command-line/migrate/agentic/master/run-master-session.d.ts

@@ -1,10 +1,14 @@
 import { type RunOrchestratorInitInput } from '../../run';
 import type { DetectedInstalledAgent } from '../types';
-export interface RunMasterSessionInput extends Omit<RunOrchestratorInitInput, 'emitAgentInstructions'> {
+export interface RunMasterSessionInput extends Omit<RunOrchestratorInitInput, 'emitAgentInstructions' | 'onExistingRun'> {
     agent: DetectedInstalledAgent;
+    interactive?: boolean;
+    runId?: string;
+    startFresh?: boolean;
+    confirmStart: () => Promise<boolean>;
 }
 /**
- * Starts (or resumes) an orchestrated run and hands it to one agent session
+ * Starts (or continues) an orchestrated run and hands it to one agent session
  * that drives it through `--run-id` reconciles. Run state is the only
  * authority on the outcome: the exit code follows what run.json says once the
  * session ends, not what the agent process returned.

package/dist/src/command-line/migrate/agentic/master/run-master-session.js

@@ -4,26 +4,65 @@ exports.runMasterSession = runMasterSession;
 const output_1 = require("../../../../utils/output");
 const migrate_analytics_1 = require("../../migrate-analytics");
 const run_1 = require("../../run");
+const safe_prompt_1 = require("../../safe-prompt");
 const spawn_master_1 = require("./spawn-master");
 /**
- * Starts (or resumes) an orchestrated run and hands it to one agent session
+ * Starts (or continues) an orchestrated run and hands it to one agent session
  * that drives it through `--run-id` reconciles. Run state is the only
  * authority on the outcome: the exit code follows what run.json says once the
  * session ends, not what the agent process returned.
  */
 async function runMasterSession(input) {
-    const { agent, ...init } = input;
-    const ready = await (0, run_1.runOrchestratorInit)({
+    const { agent, interactive, runId: requestedRunId, startFresh, ...init } = input;
+    // The invocation's policy; an interactive continue adopts the run's recorded
+    // one instead, shown in the report and the choice, so resume, broker and
+    // the resume hint agree with the run.
+    let policy = {
+        createCommits: init.createCommits,
+        skipInstall: init.skipInstall,
+    };
+    const resume = (runId) => (0, run_1.runOrchestratorResume)({
+        root: init.root,
+        runId,
+        policy,
+        emitAgentInstructions: false,
+    });
+    // With `replaceRunId`, starts fresh over that run only; the consent covers
+    // the run the user saw, and any other active run is reported instead.
+    const start = (replaceRunId) => (0, run_1.runOrchestratorInit)({
         ...init,
         emitAgentInstructions: false,
+        onExistingRun: replaceRunId === undefined ? 'report' : 'start-fresh',
+        replaceRunId,
     });
+    let ready = requestedRunId !== undefined && !startFresh
+        ? resume(requestedRunId)
+        : await start(startFresh ? requestedRunId : undefined);
+    if (ready.kind === 'existing-run' && (0, safe_prompt_1.canPrompt)(interactive)) {
+        const decision = await decideExistingRun(ready, init.root);
+        if (decision === 'abort') {
+            output_1.output.log({
+                title: `Leaving migrate run ${ready.runId} as it is. ${continueHint(init.root, agent.id, ready.runId, ready.facts.policy)}`,
+            });
+            return;
+        }
+        if (decision === 'continue') {
+            policy = ready.facts.policy;
+            ready = resume(ready.runId);
+        }
+        else {
+            ready = await start(ready.runId);
+        }
+    }
+    if (ready.kind === 'existing-run') {
+        output_1.output.warn((0, run_1.renderExistingRunReport)(ready.facts, (0, run_1.renderExistingRunCommands)(init.root, ready.facts, init.migrationsPath, agent.id)));
+        return 1;
+    }
     if (ready.kind === 'refused') {
         return;
     }
     const { runId, runRoot, runbookPath, reconcileCommand } = ready;
-    // Not rendered: the gate env var and the migrations path would have to be
-    // reproduced, and the same command carries both.
-    const resumeHint = 'Run the same nx migrate command again to resume it.';
+    const resumeHint = continueHint(init.root, agent.id, runId, policy);
     output_1.output.log({
         title: `Starting ${agent.displayName} to drive migrate run ${runId}.`,
     });
@@ -33,10 +72,7 @@ async function runMasterSession(input) {
         runId,
         runbookPath,
         reconcileCommand,
-        policy: {
-            createCommits: init.createCommits,
-            skipInstall: init.skipInstall,
-        },
+        policy,
     });
     if (session.kind === 'spawn-failed') {
         output_1.output.error({
@@ -69,16 +105,19 @@ async function runMasterSession(input) {
     }
     switch (state.status) {
         case 'active':
+            (0, migrate_analytics_1.reportMigrateOrchestratorAbandoned)({
+                ...(0, run_1.runTallies)(state),
+                agentUsed: agent.id,
+            });
             output_1.output.warn({
                 title: `Migrate run ${runId} is still active. ${resumeHint}`,
             });
             return 1;
         case 'completed': {
-            const applied = state.steps.filter((s) => s.status === 'succeeded').length;
-            const skipped = state.steps.filter((s) => s.status === 'skipped').length;
+            const tally = (0, run_1.tallySteps)(state);
             output_1.output.log({
                 title: `Migrate run ${runId} is complete.`,
-                bodyLines: [`  applied: ${applied}`, `  skipped: ${skipped}`],
+                bodyLines: (0, run_1.completionSummaryLines)(state),
             });
             for (const lines of (0, run_1.completionWarnings)(runRoot, runId, state)) {
                 output_1.output.warn({ title: lines[0], bodyLines: lines.slice(1) });
@@ -87,8 +126,14 @@ async function runMasterSession(input) {
                 agenticOutcome: 'enabled',
                 agentUsed: agent.id,
                 migrationCount: state.steps.length,
-                appliedCount: applied,
+                appliedCount: tally.applied + tally.adopted,
             });
+            if (tally.unresolved.length > 0 || (0, run_1.hasUnresolvedIssues)(state)) {
+                output_1.output.warn({
+                    title: `Migrate run ${runId} left work unresolved; exiting with code 1.`,
+                });
+                return 1;
+            }
             return;
         }
         default: {
@@ -97,3 +142,32 @@ async function runMasterSession(input) {
         }
     }
 }
+function continueHint(root, agentId, runId, policy) {
+    return `Run ${(0, run_1.renderContinueCommand)(root, runId, policy, agentId)}, with NX_MIGRATE_ORCHESTRATOR=true set in the environment, to continue it.`;
+}
+async function decideExistingRun(found, root) {
+    output_1.output.log((0, run_1.renderExistingRunReport)(found.facts));
+    // A held run leaves nothing to ask: continue would open a second session
+    // over the live one, and start fresh refuses. The continue's own gate
+    // throws the refusal; a holder gone since the report lets the prompt run.
+    if (found.facts.otherHolders === 'unknown' ||
+        found.facts.otherHolders.length > 0) {
+        (0, run_1.holdRunToContinue)(root, found.runId);
+    }
+    return (0, safe_prompt_1.migrateChoice)({
+        message: 'What do you want to do with the active migrate run?',
+        choices: [
+            {
+                value: 'continue',
+                label: 'Continue it',
+                hint: 'picks the run up where it stopped, keeping its recorded commit and install policy',
+            },
+            {
+                value: 'start-fresh',
+                label: 'Start fresh',
+                hint: 'deletes the run record only; the whole plan runs again',
+            },
+            { value: 'abort', label: 'Abort', hint: 'leaves the run as it is' },
+        ],
+    });
+}

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

@@ -21,6 +21,7 @@ export interface MigrateArgs {
     runMigration?: string;
     runId?: string;
     stepAction?: StepAction;
+    startFresh?: boolean;
     include?: MigrateInclude;
     /**
      * nx.json `migrate.include` default. Consumed by `resolveInclude` only when the

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

@@ -60,7 +60,7 @@ function withMigrationOptions(yargs) {
     })
         .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.',
+        describe: 'The orchestrated migrate run to record a single migration into, to continue with --run-migrations, or to reconcile when given alone.',
         type: 'string',
         hidden: true,
     })
@@ -69,6 +69,11 @@ function withMigrationOptions(yargs) {
         choices: step_actions_1.STEP_ACTIONS,
         type: 'string',
         hidden: true,
+    })
+        .option('startFresh', {
+        describe: 'With --run-migrations and --run-id=<id> under the orchestrator: delete the record of the active migrate run the id names and start a new run over the whole plan. Migrations the deleted run applied stay applied.',
+        type: 'boolean',
+        hidden: true,
     })
         .option('ifExists', {
         describe: `Run migrations only if the migrations file exists, if not continues successfully.`,

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

@@ -72,23 +72,48 @@ export declare function reportMigrateOrchestratorInit(opts: {
     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.
+ * One event per dispense response, repeated on every reconcile until the
+ * step moves. 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 and `ordinal` (the run's dispense count) the
+ * task-count one.
  */
 export declare function reportMigrateOrchestratorDispense(opts: {
     action: string;
     attempt: number;
+    ordinal?: 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: {
+/** Once per durable dispense transition. */
+export declare function reportMigrateOrchestratorStepDispensed(opts: {
+    attempt: number;
+    ordinal: number;
+}): void;
+export interface MigrateOrchestratorTallies {
     completed: number;
     skipped: number;
+    unresolved: number;
     dispenseCount: number;
+}
+export declare function reportMigrateOrchestratorComplete(opts: MigrateOrchestratorTallies): void;
+/** The agent session nx spawned ended with the run still active. */
+export declare function reportMigrateOrchestratorAbandoned(opts: MigrateOrchestratorTallies & {
+    agentUsed: string;
+}): void;
+/**
+ * An explicit continue (`--run-migrations --run-id`, or "continue" at the
+ * master prompt) took up an active run; every resume reports. A bare
+ * `--run-id` reconcile is not a resume: nothing in run state marks the first
+ * call after a lost session.
+ */
+export declare function reportMigrateOrchestratorResume(opts: MigrateOrchestratorTallies): void;
+/**
+ * An invocation found an active run and started nothing. `activity` says
+ * whether another nx migrate process held the run; 'unknown' where nx cannot
+ * tell.
+ */
+export declare function reportMigrateOrchestratorExistingRun(opts: MigrateOrchestratorTallies & {
+    activity: 'idle' | 'held' | 'unknown';
 }): void;
 /**
  * Counts invocations, not completions: emitted as soon as the migration id

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

@@ -13,7 +13,11 @@ exports.reportMigrateRunComplete = reportMigrateRunComplete;
 exports.reportMigrateRunError = reportMigrateRunError;
 exports.reportMigrateOrchestratorInit = reportMigrateOrchestratorInit;
 exports.reportMigrateOrchestratorDispense = reportMigrateOrchestratorDispense;
+exports.reportMigrateOrchestratorStepDispensed = reportMigrateOrchestratorStepDispensed;
 exports.reportMigrateOrchestratorComplete = reportMigrateOrchestratorComplete;
+exports.reportMigrateOrchestratorAbandoned = reportMigrateOrchestratorAbandoned;
+exports.reportMigrateOrchestratorResume = reportMigrateOrchestratorResume;
+exports.reportMigrateOrchestratorExistingRun = reportMigrateOrchestratorExistingRun;
 exports.reportMigrateSingleMigrationInvocation = reportMigrateSingleMigrationInvocation;
 exports.computeMajorsCrossed = computeMajorsCrossed;
 exports.safeReport = safeReport;
@@ -195,10 +199,12 @@ function reportMigrateOrchestratorInit(opts) {
     });
 }
 /**
- * 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.
+ * One event per dispense response, repeated on every reconcile until the
+ * step moves. 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 and `ordinal` (the run's dispense count) the
+ * task-count one.
  */
 function reportMigrateOrchestratorDispense(opts) {
     safeReport(() => {
@@ -207,21 +213,76 @@ function reportMigrateOrchestratorDispense(opts) {
         (0, analytics_1.reportEvent)('migrate_orchestrator_dispense', {
             [analytics_1.customDimensions.promptChoice]: opts.action,
             [analytics_1.customDimensions.migrationCount]: opts.attempt,
+            [analytics_1.customDimensions.taskCount]: opts.ordinal,
+        });
+    });
+}
+/** Once per durable dispense transition. */
+function reportMigrateOrchestratorStepDispensed(opts) {
+    safeReport(() => {
+        if (!analytics_1.customDimensions)
+            return;
+        (0, analytics_1.reportEvent)('migrate_orchestrator_step_dispensed', {
+            [analytics_1.customDimensions.migrationCount]: opts.attempt,
+            [analytics_1.customDimensions.taskCount]: opts.ordinal,
         });
     });
 }
 /**
- * Terminal funnel event. The two step tallies and the total dispense count
- * ride reused numeric dimensions, read conditioned on the event name.
+ * The three step tallies and the total dispense count ride reused numeric
+ * dimensions, read conditioned on the event name.
  */
+function orchestratorTallyParams(tallies) {
+    return {
+        [analytics_1.customDimensions.appliedCount]: tallies.completed,
+        [analytics_1.customDimensions.taskCount]: tallies.skipped,
+        [analytics_1.customDimensions.majorsCrossed]: tallies.unresolved,
+        [analytics_1.customDimensions.migrationCount]: tallies.dispenseCount,
+    };
+}
 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,
+        (0, analytics_1.reportEvent)('migrate_orchestrator_complete', orchestratorTallyParams(opts));
+    });
+}
+/** The agent session nx spawned ended with the run still active. */
+function reportMigrateOrchestratorAbandoned(opts) {
+    safeReport(() => {
+        if (!analytics_1.customDimensions)
+            return;
+        (0, analytics_1.reportEvent)('migrate_orchestrator_abandoned', {
+            ...orchestratorTallyParams(opts),
+            [analytics_1.customDimensions.agentUsed]: opts.agentUsed,
+        });
+    });
+}
+/**
+ * An explicit continue (`--run-migrations --run-id`, or "continue" at the
+ * master prompt) took up an active run; every resume reports. A bare
+ * `--run-id` reconcile is not a resume: nothing in run state marks the first
+ * call after a lost session.
+ */
+function reportMigrateOrchestratorResume(opts) {
+    safeReport(() => {
+        if (!analytics_1.customDimensions)
+            return;
+        (0, analytics_1.reportEvent)('migrate_orchestrator_resume', orchestratorTallyParams(opts));
+    });
+}
+/**
+ * An invocation found an active run and started nothing. `activity` says
+ * whether another nx migrate process held the run; 'unknown' where nx cannot
+ * tell.
+ */
+function reportMigrateOrchestratorExistingRun(opts) {
+    safeReport(() => {
+        if (!analytics_1.customDimensions)
+            return;
+        (0, analytics_1.reportEvent)('migrate_orchestrator_existing_run', {
+            ...orchestratorTallyParams(opts),
+            [analytics_1.customDimensions.promptChoice]: opts.activity,
         });
     });
 }

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

@@ -10,8 +10,11 @@ import { type MigrateArgs } from './command-object';
  * `parseMigrationsOptions`: `include` and `multiMajorMode` in the generate
  * 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.
+ * `--run-id` reconcile or recorded worker takes none of them: a recorded run
+ * takes its commit config from run.json and is driven by the outer agent. A
+ * `--run-migrations --run-id` continue takes `agentic` only, to select the
+ * agent of the new session. A `--start-fresh` starts a new run and takes all
+ * four.
  *
  * `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

@@ -15,8 +15,11 @@ const MULTI_MAJOR_MODE_ENV = 'NX_MULTI_MAJOR_MODE';
  * `parseMigrationsOptions`: `include` and `multiMajorMode` in the generate
  * 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.
+ * `--run-id` reconcile or recorded worker takes none of them: a recorded run
+ * takes its commit config from run.json and is driven by the outer agent. A
+ * `--run-migrations --run-id` continue takes `agentic` only, to select the
+ * agent of the new session. A `--start-fresh` starts a new run and takes all
+ * four.
  *
  * `include` is carried as `includeFromConfig` so it is never mistaken for an
  * explicit `--include`: `resolveInclude` applies it only when the resolved
@@ -33,11 +36,12 @@ function applyNxJsonMigrateDefaults(args, migrateConfig, env = process.env) {
     // 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) {
+    // These overlays are for an invocation that decides the options for itself,
+    // which a `--run-id` invocation only does when it starts fresh: the recorded
+    // worker and the reconcile both read the commit config from run.json.
+    const startsRun = (isRunMigrations || isSingleMigration) &&
+        (merged.runId === undefined || merged.startFresh === true);
+    if (startsRun) {
         if (merged.createCommits === undefined &&
             migrateConfig.createCommits !== undefined) {
             assertType(migrateConfig.createCommits, 'boolean', 'createCommits');
@@ -52,15 +56,19 @@ function applyNxJsonMigrateDefaults(args, migrateConfig, env = process.env) {
             assertType(migrateConfig.commitPrefix, 'string', 'commitPrefix');
             merged.commitPrefix = migrateConfig.commitPrefix;
         }
-        if (merged.agentic === undefined && migrateConfig.agentic !== undefined) {
-            assertValidAgentic(migrateConfig.agentic);
-            merged.agentic = (0, cli_args_1.coerceAgenticArg)(migrateConfig.agentic);
-        }
         if (merged.validate === undefined && migrateConfig.validate !== undefined) {
             assertType(migrateConfig.validate, 'boolean', 'validate');
             merged.validate = migrateConfig.validate;
         }
     }
+    // A continue takes `agentic` too; the reconcile and the worker must not:
+    // there it trips the `--agentic`/`--run-id` parse conflict.
+    if ((startsRun || isRunMigrations) &&
+        merged.agentic === undefined &&
+        migrateConfig.agentic !== undefined) {
+        assertValidAgentic(migrateConfig.agentic);
+        merged.agentic = (0, cli_args_1.coerceAgenticArg)(migrateConfig.agentic);
+    }
     if (!isRunMigrations && !isSingleMigration) {
         if (merged.include === undefined && migrateConfig.include !== undefined) {
             assertOneOf(migrateConfig.include, command_object_1.MIGRATE_INCLUDE_VALUES, 'include');

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

@@ -171,6 +171,8 @@ type RunMigrations = {
     agentic: AgenticArg;
     validate?: boolean;
     interactive?: boolean;
+    runId?: string;
+    startFresh?: boolean;
 };
 type RunSingleMigration = {
     type: 'runSingleMigration';