@depup/nx 23.2.1-depup.7 → 23.3.0-depup.0

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

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.commitMigrationIfRequested = commitMigrationIfRequested;
 exports.commitCheckpointBeforeMigrations = commitCheckpointBeforeMigrations;
 exports.resolveCreateCommits = resolveCreateCommits;
+exports.currentBranchIfDefault = currentBranchIfDefault;
 exports.confirmMigrationCommitsOnDefaultBranch = confirmMigrationCommitsOnDefaultBranch;
 exports.confirmCommitsOnDefaultBranch = confirmCommitsOnDefaultBranch;
 const tslib_1 = require("tslib");
@@ -14,6 +15,7 @@ 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");
+const deferred_output_1 = require("./deferred-output");
 // `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).
@@ -27,7 +29,7 @@ const MIGRATE_COMMIT_EXCLUDES = [types_1.MIGRATE_RUNS_RELATIVE_DIR];
  * behavior; a caller with no later commit or recap to absorb the diff (the
  * standalone single-migration worker) passes its own.
  */
-async function commitMigrationIfRequested(root, migration, shouldCreateCommits, commitPrefix, installDepsIfChanged, pendingMigrations = [], failureGuidance = 'The next successful commit will absorb it and reference this migration in its body; if no later commit lands, the end-of-run output will list this migration so you can commit or revert manually.') {
+async function commitMigrationIfRequested(root, migration, shouldCreateCommits, commitPrefix, installDepsIfChanged, pendingMigrations = [], failureGuidance = 'Any uncommitted changes will be included in the next successful commit, which will reference this migration; if they remain uncommitted, the end-of-run output will list this migration so you can commit or revert them manually.', out = deferred_output_1.terminalOutput) {
     if (!shouldCreateCommits)
         return { status: 'disabled' };
     await installDepsIfChanged();
@@ -35,22 +37,22 @@ async function commitMigrationIfRequested(root, migration, shouldCreateCommits,
     // 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}.`));
+        out.line('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, MIGRATE_COMMIT_EXCLUDES);
+        const sha = await (0, git_utils_1.tryCommitChangesAsync)(commitMessage, root, MIGRATE_COMMIT_EXCLUDES);
         if (sha)
             return { status: 'committed', sha };
         // null = commit landed but `git rev-parse HEAD` failed (see
-        // `tryCommitChanges`). Degraded-but-correct — log yellow, not red.
-        logger_1.logger.info(pc.yellow(`The commit for ${migration.name} was created, but its sha could not be resolved (\`git rev-parse HEAD\` failed transiently). Continuing without recording the sha for this step.`));
+        // `tryCommitChangesAsync`). Degraded-but-correct — log yellow, not red.
+        out.line('yellow', `The commit for ${migration.name} was created, but its sha could not be resolved (\`git rev-parse HEAD\` failed transiently). Continuing without recording the sha for this step.`);
         return { status: 'committed', sha: null };
     }
     catch (err) {
         const reason = err instanceof Error ? err.message : String(err);
-        logger_1.logger.info(pc.red(`Could not create a commit for ${migration.name}:\n${reason}\nThe migration's diff remains in the working tree; inspect with \`git status\` / \`git diff\` to review. ${failureGuidance}`));
+        out.line('red', `The commit for ${migration.name} failed:\n${reason}\nCheck \`git status\` and \`git log\`; the commit may have landed despite this error. ${failureGuidance}`);
         return { status: 'failed', reason };
     }
 }
@@ -180,6 +182,14 @@ function defaultBranchToCompare(baseRef, currentBranch, root) {
         .sort((a, b) => b.length - a.length)[0];
     return remote ? baseRef.slice(remote.length + 1) : baseRef;
 }
+function currentBranchIfDefault(root) {
+    const currentBranch = (0, git_utils_1.getGitCurrentBranch)(root);
+    if (!currentBranch) {
+        return null;
+    }
+    const defaultBranch = defaultBranchToCompare((0, command_line_utils_1.getBaseRef)((0, configuration_1.readNxJson)(root)), currentBranch, root);
+    return currentBranch === defaultBranch ? currentBranch : null;
+}
 /**
  * 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.

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-output.d.ts

@@ -24,13 +24,9 @@ export declare function logMigrationBoundary(index: number, total: number, pkg:
  */
 export declare function logAgenticSuccessOutcome(label: string, sha: string | null, summary: string): void;
 /**
- * Logs the skip line for a migration that waived its AI step through
- * `skipAgentic`, plus a verbose note for any `agentContext` the waiver
- * dropped. A hybrid waives its paired prompt; a generator-only migration
- * waives the validation pass, so callers must reach here only once they know
- * one was on the table. Under `inside-agent` only a hybrid can, so the
- * hand-off dropped alongside is always a prompt's; a waived generator-only
- * migration keeps its own. The note is author-facing, hence `--verbose`.
+ * Callers must already know an agentic step was owed; this only picks which one
+ * the waiver dropped. The dropped-`agentContext` note is aimed at the migration
+ * author, hence `--verbose`.
  */
 export declare function logWaivedAgenticStep(migration: {
     package: string;

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

@@ -52,13 +52,9 @@ function logAgenticSuccessOutcome(label, sha, summary) {
     logger_1.logger.info(`${pc.green('✓')} ${label}${shaPart}: ${summary}`);
 }
 /**
- * Logs the skip line for a migration that waived its AI step through
- * `skipAgentic`, plus a verbose note for any `agentContext` the waiver
- * dropped. A hybrid waives its paired prompt; a generator-only migration
- * waives the validation pass, so callers must reach here only once they know
- * one was on the table. Under `inside-agent` only a hybrid can, so the
- * hand-off dropped alongside is always a prompt's; a waived generator-only
- * migration keeps its own. The note is author-facing, hence `--verbose`.
+ * Callers must already know an agentic step was owed; this only picks which one
+ * the waiver dropped. The dropped-`agentContext` note is aimed at the migration
+ * author, hence `--verbose`.
  */
 function logWaivedAgenticStep(migration, agentContext) {
     logger_1.logger.info(pc.dim((0, migration_shape_1.isHybridMigration)(migration)

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

@@ -170,7 +170,10 @@ type RunMigrations = {
     ifExists: boolean;
     agentic: AgenticArg;
     validate?: boolean;
+    finalValidation?: boolean;
     interactive?: boolean;
+    runId?: string;
+    startFresh?: boolean;
 };
 type RunSingleMigration = {
     type: 'runSingleMigration';

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

@@ -30,6 +30,7 @@ const tar_1 = require("../../utils/tar");
 const write_formatted_json_file_1 = require("../../utils/write-formatted-json-file");
 const shell_quoting_1 = require("../../utils/shell-quoting");
 const logger_1 = require("../../utils/logger");
+const native_1 = require("../../native");
 const git_utils_1 = require("../../utils/git-utils");
 const package_json_1 = require("../../utils/package-json");
 const package_manager_1 = require("../../utils/package-manager");
@@ -709,13 +710,24 @@ async function parseTargetPackageAndVersion(args) {
 async function parseMigrationsOptions(options, fetch) {
     // A run recorded or reconciled via `--run-id` is driven by the outer agent;
     // spawning another agent from it would double-drive the run. Only the
-    // explicit "on" values conflict; the nx.json default is ignored for
-    // `--run-id` invocations instead.
+    // explicit "on" values conflict; the nx.json default is not applied to
+    // those invocations instead. The `--run-migrations` shape is the
+    // exception: there `--run-id` names the run a continue re-enters, or the
+    // one a `--start-fresh` replaces.
     if (options.runId !== undefined &&
         options.agentic !== undefined &&
-        options.agentic !== false) {
+        options.agentic !== false &&
+        options.runMigrations === undefined) {
         throw new Error(`Error: '--agentic' cannot be combined with '--run-id'.`);
     }
+    if (options.startFresh === true) {
+        if (options.runMigrations === undefined) {
+            throw new Error(`Error: '--start-fresh' requires '--run-migrations'.`);
+        }
+        if (options.runId === undefined) {
+            throw new Error(`Error: '--start-fresh' requires '--run-id=<id>' naming the run to replace; the report prints it.`);
+        }
+    }
     if (options.runMigration !== undefined) {
         if (options.runMigration === '') {
             throw new Error(`Error: '--run-migration' requires a migration id, e.g. '--run-migration=@nx/js:my-migration'.`);
@@ -754,8 +766,16 @@ async function parseMigrationsOptions(options, fetch) {
         if (options.runId === '') {
             throw new Error(`Error: '--run-id' requires the id of the migrate run to record into.`);
         }
-        if (options.runMigrations !== undefined) {
-            throw new Error(`Error: '--run-id' (reconcile an orchestrated run) cannot be combined with '--run-migrations' (run the whole migrations file).`);
+        // With `--run-migrations`, `--run-id` continues the named run, which needs
+        // `--agentic`; a start-fresh names the run it replaces instead.
+        if (options.runMigrations !== undefined &&
+            options.startFresh !== true &&
+            (options.agentic === undefined || options.agentic === false)) {
+            throw new Error(`Error: '--run-id' (reconcile an orchestrated run) cannot be combined with '--run-migrations' (run the whole migrations file). To continue the run, pass '--agentic' (or '--agentic=<agent>') as well.`);
+        }
+        if (options.runMigrations !== undefined &&
+            options.stepAction !== undefined) {
+            throw new Error(`Error: '--step-action' cannot be combined with '--run-migrations'.`);
         }
         // A bare '--run-id' reconciles the run it names. Ungated, unlike init:
         // the id has to name a run directory that exists, and only a gated init
@@ -765,13 +785,15 @@ async function parseMigrationsOptions(options, fetch) {
         if (options.stepAction !== undefined && !(0, step_actions_1.isStepAction)(options.stepAction)) {
             throw new Error(`Error: '--step-action' must be one of ${step_actions_1.STEP_ACTIONS.join(', ')}.`);
         }
-        return {
-            type: 'orchestratorReconcile',
-            runId: options.runId,
-            ...(options.stepAction !== undefined
-                ? { stepAction: options.stepAction }
-                : {}),
-        };
+        if (options.runMigrations === undefined) {
+            return {
+                type: 'orchestratorReconcile',
+                runId: options.runId,
+                ...(options.stepAction !== undefined
+                    ? { stepAction: options.stepAction }
+                    : {}),
+            };
+        }
     }
     if (options.stepAction !== undefined) {
         throw new Error(`Error: '--step-action' requires '--run-id'.`);
@@ -792,7 +814,10 @@ async function parseMigrationsOptions(options, fetch) {
             ifExists: options.ifExists,
             agentic: options.agentic,
             validate: options.validate,
+            finalValidation: options.finalValidation,
             interactive: options.interactive,
+            ...(options.runId !== undefined ? { runId: options.runId } : {}),
+            ...(options.startFresh === true ? { startFresh: true } : {}),
         };
     }
     assertOptionalIncludeFlagCompatibility(options);
@@ -1227,7 +1252,7 @@ async function getPackageMigrationsConfigFromRegistry(packageName, packageVersio
     if (!result) {
         return null;
     }
-    const json = JSON.parse(result);
+    const json = (0, package_manager_1.parseRegistryViewJson)(result);
     if (!json['nx-migrations'] && !json['ng-update']) {
         const registry = new node_url_1.URL('dist' in json ? json.dist.tarball : json.tarball)
             .hostname;
@@ -2092,6 +2117,9 @@ async function executeMigrations(root, migrations, isVerbose, shouldCreateCommit
         retainedAtSuccess: (0, migrate_output_1.retainedMigrations)(outcomes).map((p) => `${p.package}: ${p.name}`),
     };
 }
+function orchestratorFlagNeedsOrchestrator(flag) {
+    return `'${flag}' acts on an orchestrated migrate run (NX_MIGRATE_ORCHESTRATOR=true with an enabled agent), and this invocation is not orchestrated.`;
+}
 // nx is located at spawn time, after the gated pre-install, so the child runs
 // the bytes that install put in place.
 function handOffToLocalNx(args) {
@@ -2106,31 +2134,92 @@ function handOffToLocalNx(args) {
     return exitCode !== 0 ? exitCode : undefined;
 }
 async function runMigrations(root, opts, args, isVerbose, shouldCreateCommits, commitPrefix, shouldSkipInstall = false) {
+    // Both flags act on an orchestrated run: refuse them where none can run
+    // (an explicit --agentic=false outside an agent cannot reach one either),
+    // before the install and before --if-exists could return silently.
+    const orchestratorFlag = opts.startFresh === true
+        ? '--start-fresh'
+        : opts.runId !== undefined
+            ? '--run-id'
+            : undefined;
+    if (orchestratorFlag !== undefined &&
+        (process.env.NX_MIGRATE_ORCHESTRATOR !== 'true' ||
+            (opts.agentic === false && !(0, inception_1.isInsideAgent)()))) {
+        throw new Error(orchestratorFlagNeedsOrchestrator(orchestratorFlag));
+    }
+    const isContinue = opts.runId !== undefined && opts.startFresh !== true;
+    let continued;
+    if (isContinue) {
+        // Before the install: a concurrent start-fresh must not delete the run
+        // this command is about to continue.
+        const { holdRunToContinue } = require('./run');
+        continued = holdRunToContinue(root, opts.runId);
+    }
+    else if (opts.startFresh === true) {
+        // Before the install too: with no active run there is nothing to replace.
+        const { activeRunToReplace } = require('./run');
+        activeRunToReplace(root, opts.runId);
+    }
     if (!shouldSkipInstall && !process.env.NX_MIGRATE_SKIP_INSTALL) {
         await (0, execute_migration_1.runInstall)();
     }
     if (!__dirname.startsWith(workspace_root_1.workspaceRoot)) {
         // we are running from a temp installation with nx latest, switch to running
         // from local installation
+        if (isContinue) {
+            // The child holds the run itself and refuses while this process does.
+            const { releaseRunToHandOff } = require('./run');
+            releaseRunToHandOff(root, opts.runId);
+        }
         return handOffToLocalNx(args);
     }
-    const migrationsExists = (0, fileutils_1.fileExists)(opts.runMigrations);
-    if (opts.ifExists && !migrationsExists) {
-        output_1.output.log({
-            title: `Migrations file '${opts.runMigrations}' doesn't exist`,
-        });
-        return;
+    let migrationsJson;
+    if (isContinue) {
+        // A continue runs the plan the run recorded, not whatever the workspace's
+        // migrations file holds now (it may be gone, or belong to another plan).
+        const { latestRound, runDir } = require('./run');
+        const round = latestRound(continued);
+        if (!round) {
+            throw new Error(`Migrate run '${opts.runId}' records no plan.`);
+        }
+        migrationsJson = (0, fileutils_1.readJsonFile)((0, path_1.join)(runDir(root, opts.runId), round.planSnapshot));
     }
-    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`);
+    else {
+        const migrationsExists = (0, fileutils_1.fileExists)(opts.runMigrations);
+        if (opts.ifExists && !migrationsExists) {
+            output_1.output.log({
+                title: `Migrations file '${opts.runMigrations}' doesn't exist`,
+            });
+            return;
+        }
+        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`);
+        }
+        migrationsJson = (0, fileutils_1.readJsonFile)((0, path_1.join)(root, opts.runMigrations));
     }
-    const migrationsJson = (0, fileutils_1.readJsonFile)((0, path_1.join)(root, opts.runMigrations));
     const migrations = migrationsJson.migrations;
+    // Defer the nx package lookup until an orchestrated branch needs this payload.
+    const orchestratorInitInput = (createCommits) => ({
+        root,
+        migrationsJson,
+        migrationsPath: opts.runMigrations,
+        createCommits,
+        commitPrefix,
+        // The flag only, never NX_MIGRATE_SKIP_INSTALL: the wrapper's local
+        // re-exec sets that env var for its own hop, and it says nothing about
+        // what the user asked for.
+        skipInstall: shouldSkipInstall,
+        installedNxVersion: (0, package_json_1.readModulePackageJson)('nx', (0, installation_directory_1.getNxRequirePaths)(root))
+            .packageJson.version,
+        validate: opts.validate,
+        finalValidation: opts.finalValidation,
+    });
     // An outer agent drives the loop, so hand off to the orchestrator instead of
-    // the classic loop: init either starts a fresh run or resumes an already-
-    // active one. `--run-id` reconciles are dispatched separately and never
-    // reach here.
+    // the classic loop: init starts a fresh run or reports an already-active
+    // one; `--run-id` continues that run. Bare `--run-id` reconciles are
+    // dispatched separately and never reach here.
     if (process.env.NX_MIGRATE_ORCHESTRATOR === 'true' && (0, inception_1.isInsideAgent)()) {
+        const { runOrchestratorInit, runOrchestratorResume } = require('./run');
         // Orchestrated runs are agent-driven, so commits default on exactly as they
         // do under `--agentic=enabled`; the orchestrator replaces `resolveAgentic`.
         const { effective: effectiveCreateCommits, warning: createCommitsWarning, error: createCommitsError, } = (0, migrate_commits_1.resolveCreateCommits)({
@@ -2145,26 +2234,50 @@ async function runMigrations(root, opts, args, isVerbose, shouldCreateCommits, c
         if (createCommitsWarning) {
             output_1.output.warn({ title: createCommitsWarning });
         }
-        // The run commits on the user's behalf across many invocations, so the
-        // default-branch confirmation belongs here, once, before any of them.
-        if (effectiveCreateCommits &&
-            (0, safe_prompt_1.canPrompt)(opts.interactive) &&
-            !(await (0, migrate_commits_1.confirmMigrationCommitsOnDefaultBranch)(root, 'running migrations'))) {
+        if (isContinue) {
+            runOrchestratorResume({
+                root,
+                runId: opts.runId,
+                policy: {
+                    createCommits: effectiveCreateCommits,
+                    skipInstall: shouldSkipInstall,
+                },
+            });
             return;
         }
-        const { packageJson: orchestratorNxPackageJson } = (0, package_json_1.readModulePackageJson)('nx', (0, installation_directory_1.getNxRequirePaths)(root));
-        const { runOrchestratorInit } = require('./run');
-        return await runOrchestratorInit({
-            root,
-            migrationsJson,
-            createCommits: effectiveCreateCommits,
-            commitPrefix,
-            // The flag only, never NX_MIGRATE_SKIP_INSTALL: the wrapper's local
-            // re-exec sets that env var for its own hop, and it says nothing about
-            // what the user asked for.
-            skipInstall: shouldSkipInstall,
-            installedNxVersion: orchestratorNxPackageJson.version,
+        // The run commits on the user's behalf across many invocations and the
+        // agent driving it cannot answer a terminal prompt, so a commit policy the
+        // user never asked for stops the run on the default branch before any of
+        // them. `--create-commits` or nx.json `migrate.createCommits` is that ask.
+        // Asked by init only once it is about to start a run: an active run is
+        // reported instead, and keeps its own policy.
+        const refuseCommitsOnDefaultBranch = async () => {
+            if (!effectiveCreateCommits || shouldCreateCommits !== undefined) {
+                return true;
+            }
+            const defaultBranch = (0, migrate_commits_1.currentBranchIfDefault)(root);
+            if (!defaultBranch) {
+                return true;
+            }
+            output_1.output.log({
+                title: `Not starting the run: you are on the default branch '${defaultBranch}' and nx migrate would create a commit for each migration on it.`,
+                bodyLines: [
+                    'Ask the user how to proceed, then either:',
+                    '- re-run with --create-commits to commit on this branch for this run,',
+                    '- set "migrate": { "createCommits": true } in nx.json to always allow it, then re-run,',
+                    '- or switch to another branch and re-run.',
+                ],
+            });
+            return false;
+        };
+        const init = orchestratorInitInput(effectiveCreateCommits);
+        await runOrchestratorInit({
+            ...init,
+            onExistingRun: opts.startFresh === true ? 'start-fresh' : 'report',
+            ...(opts.startFresh === true ? { replaceRunId: opts.runId } : {}),
+            confirmStart: refuseCommitsOnDefaultBranch,
         });
+        return;
     }
     (0, migrate_analytics_1.reportMigrateRunStart)({
         createCommits: shouldCreateCommits ?? false,
@@ -2195,9 +2308,33 @@ async function runMigrations(root, opts, args, isVerbose, shouldCreateCommits, c
     if (createCommitsWarning) {
         output_1.output.warn({ title: createCommitsWarning });
     }
-    if (effectiveCreateCommits &&
-        (0, safe_prompt_1.canPrompt)(opts.interactive) &&
-        !(await (0, migrate_commits_1.confirmMigrationCommitsOnDefaultBranch)(root, 'running migrations'))) {
+    // Asked only for a run this invocation starts: the master session hands it
+    // to init, which asks once it is about to start one; a continued run keeps
+    // the policy it was started with.
+    const confirmNewRunCommits = async () => !effectiveCreateCommits ||
+        !(0, safe_prompt_1.canPrompt)(opts.interactive) ||
+        (0, migrate_commits_1.confirmMigrationCommitsOnDefaultBranch)(root, 'running migrations');
+    // Dark: with the env var set, the agent drives the whole run through the
+    // orchestrator from one session instead of being spawned per step. Not
+    // under WASM, where the broker has no native lock to detect a dead parent.
+    if (agentic.kind === 'enabled' &&
+        process.env.NX_MIGRATE_ORCHESTRATOR === 'true' &&
+        !native_1.IS_WASM) {
+        const init = orchestratorInitInput(effectiveCreateCommits);
+        const { runMasterSession } = require('./agentic/master/run-master-session');
+        return await runMasterSession({
+            ...init,
+            agent: agentic.selectedAgent,
+            interactive: opts.interactive,
+            runId: opts.runId,
+            startFresh: opts.startFresh,
+            confirmStart: confirmNewRunCommits,
+        });
+    }
+    if (orchestratorFlag !== undefined) {
+        throw new Error(orchestratorFlagNeedsOrchestrator(orchestratorFlag));
+    }
+    if (!(await confirmNewRunCommits())) {
         return;
     }
     const shouldRunValidation = resolveShouldRunValidation({
@@ -2412,7 +2549,7 @@ function stringifyCaught(e) {
         }
     }
 }
-// A resolver-based lookup (including `resolvePackageJsonWithoutCachePollution`,
+// A resolver-based lookup (including `resolveWithoutCachePollution`,
 // which does defeat Node's package self-reference) is the wrong tool here:
 // resolvers fall back to NODE_PATH after the explicit paths, and NODE_PATH
 // names the temp installation when this runs there. The scan below reads its

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

@@ -15,6 +15,7 @@ const policy_1 = require("../../utils/min-release-age/policy");
 const pnpm_exclude_writer_1 = require("../../utils/min-release-age/pnpm-exclude-writer");
 const resolve_1 = require("../../utils/min-release-age/resolve");
 const safe_prompt_1 = require("./safe-prompt");
+const text_1 = require("./text");
 /**
  * Whether nx migrate should resolve versions via the npm registry (fast) rather
  * than via a real package-manager install. Precedence, highest first:
@@ -195,7 +196,7 @@ async function handleViolation(packageName, error, policy) {
     // sorted newest-first, so the resolver's pick is the last entry. Mirror the
     // loose path: prompt for, exclude, and return that one version.
     const resolved = error.blocked[error.blocked.length - 1];
-    const blockedLine = `  ${packageName}@${resolved.version} (published ${formatPublishAge(resolved.publishedAt)})`;
+    const blockedLine = `  ${packageName}@${resolved.version} (published ${(0, text_1.formatAge)(resolved.publishedAt)})`;
     // pnpm prompts once for the whole run; remember an approval for later picks.
     if (!strictApprovalGranted) {
         const approved = await (0, safe_prompt_1.migrateConfirm)({
@@ -225,21 +226,3 @@ async function handleViolation(packageName, error, policy) {
     ]);
     return resolved.version;
 }
-// Renders a registry ISO publish timestamp as a human age for the strict prompt
-// (e.g. "6 hours ago"), falling back to the raw value when it is not parseable.
-function formatPublishAge(publishedAt) {
-    const elapsedMs = Date.now() - Date.parse(publishedAt);
-    if (!Number.isFinite(elapsedMs) || elapsedMs < 0) {
-        return publishedAt;
-    }
-    const minutes = Math.floor(elapsedMs / 60_000);
-    if (minutes < 60) {
-        return `${minutes} minute${minutes === 1 ? '' : 's'} ago`;
-    }
-    const hours = Math.floor(elapsedMs / 3_600_000);
-    if (hours < 48) {
-        return `${hours} hour${hours === 1 ? '' : 's'} ago`;
-    }
-    const days = Math.floor(elapsedMs / 86_400_000);
-    return `${days} day${days === 1 ? '' : 's'} ago`;
-}

package/dist/src/command-line/migrate/run/agent-output.d.ts

@@ -18,3 +18,14 @@ export declare function logToAgent(message: AgentMessage): void;
 export declare function warnToAgent(message: AgentMessage): void;
 export declare function emitStepBlock(runId: string, stepId: string, action: string, payload: object): void;
 export declare function emitPromptBlock(migrationId: string, payload: object): void;
+export declare function emitStepPromptBlock(stepId: string, payload: object): void;
+/**
+ * Markdown, not JSON: the block carries the runbook file's bytes, so the agent
+ * reads what a resume re-emits from disk. Every `<` opening or closing an
+ * `<nx_migrate_*>` tag is neutralized wherever it sits: a positional check
+ * (line starts plus a blank-character class) can be sidestepped by characters
+ * that render as nothing but match no enumerable class. The renderer never
+ * emits the literal sequence (runbook.spec pins that), so only tampered bytes
+ * change.
+ */
+export declare function emitRunbookBlock(runId: string, content: string): void;

package/dist/src/command-line/migrate/run/agent-output.js

@@ -15,6 +15,8 @@ exports.logToAgent = logToAgent;
 exports.warnToAgent = warnToAgent;
 exports.emitStepBlock = emitStepBlock;
 exports.emitPromptBlock = emitPromptBlock;
+exports.emitStepPromptBlock = emitStepPromptBlock;
+exports.emitRunbookBlock = emitRunbookBlock;
 const output_1 = require("../../../utils/output");
 const print_dropped_agent_context_1 = require("../agentic/print-dropped-agent-context");
 const text_1 = require("../text");
@@ -47,11 +49,11 @@ function blockPayload(payload) {
     return JSON.stringify(payload, null, 2).replace(/</g, '\\u003c');
 }
 // A bare newline pair frames the block so adjacent stdout cannot run into it.
-function writeBlock(tag, attrs, json) {
+function writeBlock(tag, attrs, body) {
     const attrText = attrs
         .map(([name, value]) => ` ${name}="${(0, print_dropped_agent_context_1.escapeXmlAttr)((0, text_1.singleLine)(value))}"`)
         .join('');
-    process.stdout.write(`\n<${tag}${attrText}>\n${json}\n</${tag}>\n\n`);
+    process.stdout.write(`\n<${tag}${attrText}>\n${body}\n</${tag}>\n\n`);
 }
 function emitStepBlock(runId, stepId, action, payload) {
     writeBlock('nx_migrate_step', [
@@ -63,3 +65,20 @@ function emitStepBlock(runId, stepId, action, payload) {
 function emitPromptBlock(migrationId, payload) {
     writeBlock('nx_migrate_prompt', [['migration', migrationId]], blockPayload(payload));
 }
+// For work that belongs to no migration (the final-validation step).
+function emitStepPromptBlock(stepId, payload) {
+    writeBlock('nx_migrate_prompt', [['step', stepId]], blockPayload(payload));
+}
+/**
+ * Markdown, not JSON: the block carries the runbook file's bytes, so the agent
+ * reads what a resume re-emits from disk. Every `<` opening or closing an
+ * `<nx_migrate_*>` tag is neutralized wherever it sits: a positional check
+ * (line starts plus a blank-character class) can be sidestepped by characters
+ * that render as nothing but match no enumerable class. The renderer never
+ * emits the literal sequence (runbook.spec pins that), so only tampered bytes
+ * change.
+ */
+function emitRunbookBlock(runId, content) {
+    const neutralized = content.replace(/<(?=\/?nx_migrate_)/gi, '\\u003c');
+    writeBlock('nx_migrate_runbook', [['run-id', runId]], neutralized);
+}