nx 24.0.0-beta.1 → 24.0.0-beta.2

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

@@ -13,7 +13,6 @@ exports.isRunPhaseInvocation = isRunPhaseInvocation;
 exports.migrate = migrate;
 exports.readLocalNxVersion = readLocalNxVersion;
 exports.runMigration = runMigration;
-exports.resolveMigrationForRun = resolveMigrationForRun;
 exports.nxCliPath = nxCliPath;
 const tslib_1 = require("tslib");
 const pc = tslib_1.__importStar(require("picocolors"));
@@ -57,6 +56,7 @@ const multi_major_1 = require("./multi-major");
 const prompt_files_1 = require("./prompt-files");
 const command_object_1 = require("./command-object");
 const migrate_config_1 = require("./migrate-config");
+const types_1 = require("./agentic/types");
 const migrate_commits_1 = require("./migrate-commits");
 const migrate_output_1 = require("./migrate-output");
 const migration_shape_1 = require("./migration-shape");
@@ -786,9 +786,7 @@ async function parseMigrationsOptions(options, fetch) {
             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
-        // ever creates one.
+        // A bare '--run-id' reconciles the run it names.
         // yargs' choices already reject bad CLI values; this guards programmatic
         // callers, where silently dropping the action would reconcile without it.
         if (options.stepAction !== undefined && !(0, step_actions_1.isStepAction)(options.stepAction)) {
@@ -1761,23 +1759,12 @@ function formatSkippedPromptsNextStep(skipped) {
         ...skipped.map((m) => `  - ${m.prompt}`),
     ].join('\n');
 }
-async function executeMigrations(root, migrations, isVerbose, shouldCreateCommits, commitPrefix, shouldSkipInstall = false, agentic, agenticHasDiffContext = false, shouldRunValidation = false) {
+async function executeMigrations(root, migrations, isVerbose, shouldCreateCommits, commitPrefix, shouldSkipInstall = false, 
+// An enabled agent drives the whole run from one session instead.
+agentic) {
     const changedDepInstaller = new execute_migration_1.ChangedDepInstaller(root, shouldSkipInstall);
     const migrationsWithNoChanges = [];
-    const sortedMigrations = (0, sort_migrations_1.sortMigrations)(migrations, {
-        hoistHandoffGitignore: agentic?.kind === 'enabled',
-    });
-    // Lazy-load the agentic chain so non-agentic runs don't pay its startup cost.
-    let agenticRun;
-    if (agentic?.kind === 'enabled' && sortedMigrations.length > 0) {
-        const { initRunDir, resolveAgenticRunId } = require('./agentic/handoff');
-        const { runAgenticPromptStep } = require('./agentic/run-step');
-        agenticRun = {
-            agentic,
-            runDir: initRunDir(root, resolveAgenticRunId(sortedMigrations)),
-            runStep: runAgenticPromptStep,
-        };
-    }
+    const sortedMigrations = (0, sort_migrations_1.sortMigrations)(migrations);
     const printDroppedAgentContext = agentic?.kind === 'inside-agent'
         ? require('./agentic/print-dropped-agent-context').printDroppedAgentContextForOuterAgent
         : undefined;
@@ -1812,12 +1799,6 @@ async function executeMigrations(root, migrations, isVerbose, shouldCreateCommit
     const pendingForCommitBody = () => outcomes
         .filter((o) => o.commit.kind === 'failed')
         .map((o) => ({ package: o.migration.package, name: o.migration.name }));
-    // True while at least one prior migration's commit has failed and its
-    // diff hasn't been absorbed yet. While true, the working tree carries
-    // prior-migration state, so the `hasDiffContext` flag in the hybrid-
-    // agentic and validation-agentic prompt branches is suppressed (the
-    // prompt-only-with-agentic branch doesn't use `hasDiffContext`).
-    const hasPendingCommitDebt = () => outcomes.some((o) => o.commit.kind === 'failed');
     // Single funnel for per-migration commit attempts. Returns the
     // `CommitState` to record on the migration's outcome. On `committed`,
     // back-annotates any prior failed-commit outcomes to `kind: 'absorbed'`
@@ -1850,8 +1831,7 @@ async function executeMigrations(root, migrations, isVerbose, shouldCreateCommit
             return { kind: 'landed', sha: result.sha };
         }
         if (result.status === 'failed') {
-            // Diff is still in WT. Subsequent prompts cannot claim git-isolation
-            // until a later commit absorbs the backlog.
+            // The diff stays in the working tree until a later commit absorbs it.
             return { kind: 'failed' };
         }
         // `no-changes` and `disabled` — no commit attempted, nothing to record
@@ -1884,89 +1864,36 @@ async function executeMigrations(root, migrations, isVerbose, shouldCreateCommit
         // Content-sensitive so a dirty→dirty case (this migration mutating an
         // already-dirty shared file like `package.json`) doesn't collapse.
         const baselineWorkingTreeSnapshot = (0, git_utils_1.getUncommittedChangesSnapshot)(root);
-        // Tracks whether a failure originated in the agentic step so the error
-        // event classifies it as 'agentic' rather than 'migration_exec'.
-        let inAgenticStep = false;
         try {
-            // Read this migration's collection once and derive everything from it:
-            // the implementation context (passed to runNxOrAngularMigration) and the
-            // documentation path (passed to the agent). Read fresh per iteration so a
-            // prior migration's reinstall is reflected.
-            const { resolvedCollection, documentationPath } = resolveMigrationForRun(root, m, !!agenticRun);
+            // Read fresh per migration so a prior migration's reinstall is reflected.
+            const resolvedCollection = (0, migration_shape_1.isPromptOnlyMigration)(m)
+                ? undefined
+                : (0, execute_migration_1.readMigrationCollection)(m.package, root);
             let outcome;
             let commit = { kind: 'none' };
-            // Set when the migration returned `skipAgentic: true` and something was
-            // actually waived, so the end-of-run recaps can report it. A hybrid's
-            // prompt is owed in every agentic mode, so waiving it always counts; a
-            // generator-only migration only counts when validation would have run.
+            // Set when a hybrid returned `skipAgentic: true`, so the end-of-run
+            // recaps can report the waived prompt.
             let waivedAgenticStep = false;
             if ((0, migration_shape_1.isPromptOnlyMigration)(m)) {
-                if (agenticRun) {
-                    inAgenticStep = true;
-                    const stepResult = await agenticRun.runStep({
-                        root,
-                        migration: m,
-                        agentic: agenticRun.agentic,
-                        runDir: agenticRun.runDir,
-                        installDepsIfChanged,
-                        documentationPath,
-                    });
-                    inAgenticStep = false;
-                    commit = await attemptMigrationCommit(m);
-                    (0, migrate_output_1.logAgenticSuccessOutcome)(stepResult.ambiguous ? 'Marked complete by user' : 'Applied', commit.kind === 'landed' ? commit.sha : null, stepResult.summary);
-                    outcome = 'applied';
-                }
-                else {
-                    logger_1.logger.info(pc.dim(`↷ Skipped — ${skipReason}. Listed in next steps.`));
-                    skippedPrompts.push(m);
-                    notRunMigrationsCount++;
-                    outcome = 'deferred';
-                }
+                logger_1.logger.info(pc.dim(`↷ Skipped — ${skipReason}. Listed in next steps.`));
+                skippedPrompts.push(m);
+                notRunMigrationsCount++;
+                outcome = 'deferred';
             }
             else if ((0, migration_shape_1.isHybridMigration)(m)) {
-                const { changes, nextSteps, agentContext, skipAgentic, logs, madeChanges, } = await (0, execute_migration_1.runNxOrAngularMigration)(root, m, isVerbose, 
-                /* captureGeneratorOutput: */ !!agenticRun, resolvedCollection);
+                const { nextSteps, agentContext, skipAgentic, madeChanges } = await (0, execute_migration_1.runNxOrAngularMigration)(root, m, isVerbose, 
+                /* captureGeneratorOutput: */ false, resolvedCollection);
                 migrationEmittedNextSteps.push(...nextSteps);
                 if (skipAgentic) {
                     // The generator reported the prompt half unnecessary, so nothing is
-                    // owed: no agent run, and no next-steps entry telling the user to
-                    // run the prompt themselves. Runs in all three agentic modes.
+                    // owed: no next-steps entry telling anyone to run the prompt.
                     (0, migrate_output_1.logWaivedAgenticStep)(m, agentContext);
                     waivedAgenticStep = true;
                     commit = await commitOrRecordNoChanges(m, madeChanges);
                     outcome = madeChanges ? 'applied' : 'no-changes';
                 }
-                else if (agenticRun) {
-                    // Install any deps the deterministic phase added/bumped before the
-                    // agent runs — the prompt half may depend on them being present in
-                    // node_modules.
-                    await installDepsIfChanged();
-                    inAgenticStep = true;
-                    const stepResult = await agenticRun.runStep({
-                        root,
-                        migration: m,
-                        agentic: agenticRun.agentic,
-                        runDir: agenticRun.runDir,
-                        installDepsIfChanged,
-                        documentationPath,
-                        implContext: {
-                            logs,
-                            changes,
-                            agentContext,
-                            // When prior commits failed, the working tree carries their
-                            // diff. The git-inspect path of the prompt would mislead the
-                            // agent in that case; fall back to embedded `<files_changed>`.
-                            hasDiffContext: agenticHasDiffContext && !hasPendingCommitDebt(),
-                        },
-                    });
-                    inAgenticStep = false;
-                    commit = await attemptMigrationCommit(m);
-                    (0, migrate_output_1.logAgenticSuccessOutcome)(stepResult.ambiguous ? 'Marked complete by user' : 'Applied', commit.kind === 'landed' ? commit.sha : null, stepResult.summary);
-                    outcome = 'applied';
-                }
                 else {
-                    // The inner prompt step doesn't run here (agentic disabled, or
-                    // running inside an outer agent). Under `inside-agent`, surface the
+                    // The prompt half is deferred. Under `inside-agent`, surface the
                     // generator-emitted `agentContext` to stdout so the outer driving
                     // agent can ingest it. Under `disabled` the run is human-driven;
                     // agent-targeted context would only add noise — drop.
@@ -1980,59 +1907,16 @@ async function executeMigrations(root, migrations, isVerbose, shouldCreateCommit
                 }
             }
             else {
-                // Defer commit until validation succeeds; failed validation leaves
-                // changes uncommitted in the working tree for the user to review.
-                const validationRun = agenticRun && shouldRunValidation ? agenticRun : undefined;
-                const { changes, nextSteps, agentContext, skipAgentic, logs, madeChanges, } = await (0, execute_migration_1.runNxOrAngularMigration)(root, m, isVerbose, 
-                /* captureGeneratorOutput: */ !!validationRun, resolvedCollection);
+                const { nextSteps, agentContext, madeChanges } = await (0, execute_migration_1.runNxOrAngularMigration)(root, m, isVerbose, 
+                /* captureGeneratorOutput: */ false, resolvedCollection);
                 migrationEmittedNextSteps.push(...nextSteps);
-                // Whether a validation step was on the table at all. `skipAgentic`
-                // waives nothing when it wasn't, so the whole waived path hangs off
-                // this, not just the log line.
-                const validationApplies = !!validationRun && changes.length > 0;
-                const canRunValidation = validationApplies && !skipAgentic;
-                if (canRunValidation) {
-                    // Install any deps the deterministic phase added/bumped before the
-                    // validation agent runs — the agent may run tasks that need them.
-                    await installDepsIfChanged();
-                    inAgenticStep = true;
-                    const stepResult = await validationRun.runStep({
-                        root,
-                        migration: m,
-                        agentic: validationRun.agentic,
-                        runDir: validationRun.runDir,
-                        installDepsIfChanged,
-                        documentationPath,
-                        implContext: {
-                            logs,
-                            changes,
-                            agentContext,
-                            // See the hybrid agentic branch above for the rationale on
-                            // why pending commit debt gates git-inspect context.
-                            hasDiffContext: agenticHasDiffContext && !hasPendingCommitDebt(),
-                        },
-                        mode: 'generic-validation',
-                    });
-                    inAgenticStep = false;
-                    commit = await attemptMigrationCommit(m);
-                    (0, migrate_output_1.logAgenticSuccessOutcome)(stepResult.ambiguous
-                        ? 'Marked complete by user'
-                        : 'Validation passed', commit.kind === 'landed' ? commit.sha : null, stepResult.summary);
-                    outcome = 'applied';
-                }
-                else {
-                    if (skipAgentic && validationApplies) {
-                        (0, migrate_output_1.logWaivedAgenticStep)(m, agentContext);
-                        waivedAgenticStep = true;
-                    }
-                    else if (printDroppedAgentContext && agentContext.length > 0) {
-                        // Inner validation step didn't run. Surface `agentContext` under
-                        // `inside-agent` so the outer driving agent can ingest it.
-                        printDroppedAgentContext({ migration: m, agentContext });
-                    }
-                    commit = await commitOrRecordNoChanges(m, madeChanges);
-                    outcome = madeChanges ? 'applied' : 'no-changes';
+                if (printDroppedAgentContext && agentContext.length > 0) {
+                    // Surface `agentContext` under `inside-agent` so the outer driving
+                    // agent can ingest it.
+                    printDroppedAgentContext({ migration: m, agentContext });
                 }
+                commit = await commitOrRecordNoChanges(m, madeChanges);
+                outcome = madeChanges ? 'applied' : 'no-changes';
             }
             outcomes.push({
                 migration: { package: m.package, name: m.name },
@@ -2062,9 +1946,7 @@ async function executeMigrations(root, migrations, isVerbose, shouldCreateCommit
                 (0, migrate_analytics_1.reportMigrateRunError)({
                     code: e instanceof execute_migration_1.NpmPeerDepsInstallError
                         ? 'npm_install'
-                        : inAgenticStep
-                            ? 'agentic'
-                            : 'migration_exec',
+                        : 'migration_exec',
                     migrationPackage: m.package,
                     migrationName: m.name,
                     migrationCount: totalMigrations,
@@ -2126,8 +2008,70 @@ 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.`;
+const CONTINUE_NEEDS_ORCHESTRATION = `'--run-id' continues an orchestrated migrate run, and this invocation is not orchestrated. Orchestration needs an enabled agent, or an AI agent running nx outside CI; --agentic=false and the WASM build turn it off.`;
+const ID_PROBLEM_LABELS = {
+    'not-shell-safe': 'not shell-safe',
+    duplicate: 'listed more than once',
+};
+// The classic loop records no run, so it must not run over an active one. The
+// run is reported or asked about before the default-branch prompt; a start
+// fresh is checked there too, and the caller deletes the run only after it.
+async function settleActiveRunForClassic(root, opts, migrations) {
+    const { activeRunForClassic, checkRunForStartFresh, renderContinueCommand, renderExistingRunCommands, renderExistingRunReport, } = require('./run');
+    const active = activeRunForClassic(root, migrations.map((m) => `${m.package}:${m.name}`));
+    // With no active run left, the check refuses as init does: the run
+    // completed after the pre-install check, so its plan already ran.
+    if (opts.startFresh === true &&
+        (active === null || active.runId === opts.runId)) {
+        checkRunForStartFresh(root, opts.runId);
+        return { kind: 'run', replaceRunId: opts.runId };
+    }
+    if (!active) {
+        return { kind: 'run' };
+    }
+    const { runId, facts } = active;
+    // Start fresh refuses while another process holds the run, so a held run
+    // leaves nothing to ask; an agent cannot answer a prompt.
+    const held = facts.otherHolders === 'unknown' || facts.otherHolders.length > 0;
+    if (opts.startFresh !== true &&
+        !held &&
+        (0, safe_prompt_1.canPrompt)(opts.interactive) &&
+        !(0, inception_1.isInsideAgent)()) {
+        output_1.output.log(renderExistingRunReport(facts));
+        const choice = await (0, safe_prompt_1.migrateChoice)({
+            message: 'What do you want to do with the active migrate run?',
+            choices: [
+                {
+                    value: 'start-fresh',
+                    label: 'Start fresh',
+                    hint: 'deletes the run record, then runs the whole plan without an agent',
+                },
+                { value: 'abort', label: 'Abort', hint: 'leaves the run as it is' },
+            ],
+        });
+        switch (choice) {
+            case 'start-fresh':
+                checkRunForStartFresh(root, runId);
+                return { kind: 'run', replaceRunId: runId };
+            case 'abort':
+                output_1.output.log({
+                    title: `Leaving migrate run ${runId} as it is. To continue it with an agent, run ${renderContinueCommand(root, runId, facts.policy)}.`,
+                });
+                (0, migrate_analytics_1.reportMigrateRunStopped)('aborted');
+                return { kind: 'stop', exitCode: undefined };
+            default: {
+                const unhandled = choice;
+                throw new Error(`Unhandled choice: ${unhandled}`);
+            }
+        }
+    }
+    const report = renderExistingRunReport(facts, renderExistingRunCommands(root, facts, opts.runMigrations, opts.agentic === false ? false : undefined));
+    if (native_1.IS_WASM) {
+        report.bodyLines.push(`The WASM build can run neither command. Continue the run with the native nx binary, or make sure no nx migrate process is acting on it, remove ${types_1.MIGRATE_RUNS_RELATIVE_DIR}/${runId}, then run the plan again.`);
+    }
+    output_1.output.warn(report);
+    (0, migrate_analytics_1.reportMigrateRunStopped)('existing_run');
+    return { kind: 'stop', exitCode: 1 };
 }
 // nx is located at spawn time, after the gated pre-install, so the child runs
 // the bytes that install put in place.
@@ -2143,20 +2087,18 @@ 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));
-    }
+    // The WASM build lacks the native locks a durable run relies on.
+    const outerAgentDrivesRun = (0, inception_1.isInsideAgent)() && opts.agentic !== false && !(0, is_ci_1.isCI)() && !native_1.IS_WASM;
     const isContinue = opts.runId !== undefined && opts.startFresh !== true;
+    // Refused before the install, and before --if-exists could return silently,
+    // when neither the outer agent nor a master session (an agent enabled
+    // outside one, off WASM) can continue the run. A start fresh may reach the
+    // classic loop, which deletes the run's record and runs the plan.
+    if (isContinue &&
+        !outerAgentDrivesRun &&
+        ((0, inception_1.isInsideAgent)() || opts.agentic === false || native_1.IS_WASM)) {
+        throw new Error(CONTINUE_NEEDS_ORCHESTRATION);
+    }
     let continued;
     if (isContinue) {
         // Before the install: a concurrent start-fresh must not delete the run
@@ -2251,11 +2193,19 @@ async function runMigrations(root, opts, args, isVerbose, shouldCreateCommits, c
         validate: opts.validate,
         finalValidation: opts.finalValidation,
     });
+    // Orchestration refuses ids it cannot dispense verbatim or resolve to one
+    // step, so a new run with one falls back to the classic loop. A continue
+    // has no classic fallback, since it runs the plan its run recorded, and a
+    // start fresh still reaches init's refusal.
+    const idProblems = isContinue || opts.startFresh === true
+        ? []
+        : require('./run').migrationIdProblems(migrations);
+    const idProblemLines = idProblems.map(({ id, problem }) => `- ${(0, text_1.singleLine)(id)} (${ID_PROBLEM_LABELS[problem]})`);
     // An outer agent drives the loop, so hand off to the orchestrator instead of
     // 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)()) {
+    if (outerAgentDrivesRun && idProblems.length === 0) {
         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`.
@@ -2316,11 +2266,20 @@ async function runMigrations(root, opts, args, isVerbose, shouldCreateCommits, c
         });
         return;
     }
+    if (outerAgentDrivesRun) {
+        output_1.output.warn({
+            title: 'Running the migrations without an orchestrated run: orchestrated runs need each migration id to be shell-safe (letters, digits and @/:._-) and listed once, and these are not:',
+            bodyLines: [
+                ...idProblemLines,
+                'No run is recorded, so --run-id cannot continue this one. Prompt work is listed as next steps for the AI agent driving this run, and no validation runs.',
+            ],
+        });
+    }
     (0, migrate_analytics_1.reportMigrateRunStart)({
         createCommits: shouldCreateCommits ?? false,
         migrationCount: migrations.length,
     });
-    const { resolveAgentic, resolveShouldRunValidation } = require('./agentic/select');
+    const { resolveAgentic } = require('./agentic/select');
     let agentic;
     try {
         agentic = await resolveAgentic({
@@ -2333,7 +2292,25 @@ async function runMigrations(root, opts, args, isVerbose, shouldCreateCommits, c
         (0, migrate_analytics_1.reportMigrateRunError)({ code: 'agentic', error: e });
         throw e;
     }
-    const { effective: effectiveCreateCommits, agenticHasDiffContext, warning: createCommitsWarning, error: createCommitsError, } = (0, migrate_commits_1.resolveCreateCommits)({
+    // Resolved before the commit policy, which defaults on only for an agent.
+    if (agentic.kind === 'enabled' && native_1.IS_WASM) {
+        output_1.output.warn({
+            title: 'Skipping the agentic flow: it needs the native nx binary, and this run loaded the WASM build.',
+            bodyLines: ['Continuing the migration without the agentic flow.'],
+        });
+        agentic = { kind: 'disabled' };
+    }
+    if (agentic.kind === 'enabled' && idProblems.length > 0) {
+        output_1.output.warn({
+            title: 'Skipping the agentic flow: it needs each migration id to be shell-safe (letters, digits and @/:._-) and listed once, and these are not:',
+            bodyLines: [
+                ...idProblemLines,
+                'Continuing the migration without the agentic flow. Generators still run. Prompt-only migrations and the prompt part of hybrid migrations are skipped and listed as next steps, and no AI validation runs.',
+            ],
+        });
+        agentic = { kind: 'disabled' };
+    }
+    const { effective: effectiveCreateCommits, warning: createCommitsWarning, error: createCommitsError, } = (0, migrate_commits_1.resolveCreateCommits)({
         createCommits: shouldCreateCommits,
         mode: agentic.kind,
         isGitRepo: (0, git_utils_1.isGitRepository)(root),
@@ -2351,12 +2328,8 @@ async function runMigrations(root, opts, args, isVerbose, shouldCreateCommits, c
     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) {
+    // The agent drives the whole run through the orchestrator from one session.
+    if (agentic.kind === 'enabled') {
         const init = orchestratorInitInput(effectiveCreateCommits);
         const { runMasterSession } = require('./agentic/master/run-master-session');
         return await runMasterSession({
@@ -2368,16 +2341,22 @@ async function runMigrations(root, opts, args, isVerbose, shouldCreateCommits, c
             confirmStart: confirmNewRunCommits,
         });
     }
-    if (orchestratorFlag !== undefined) {
-        throw new Error(orchestratorFlagNeedsOrchestrator(orchestratorFlag));
+    if (isContinue) {
+        throw new Error(CONTINUE_NEEDS_ORCHESTRATION);
+    }
+    const classicGate = await settleActiveRunForClassic(root, opts, migrations);
+    if (classicGate.kind === 'stop') {
+        return classicGate.exitCode;
     }
     if (!(await confirmNewRunCommits())) {
+        (0, migrate_analytics_1.reportMigrateRunStopped)('declined_commits');
         return;
     }
-    const shouldRunValidation = resolveShouldRunValidation({
-        validate: opts.validate,
-        agenticKind: agentic.kind,
-    });
+    // After the prompt, so declining it keeps the run.
+    if (classicGate.replaceRunId !== undefined) {
+        const { deleteRunForStartFresh } = require('./run');
+        deleteRunForStartFresh(root, classicGate.replaceRunId);
+    }
     output_1.output.log({
         title: `Running migrations from '${opts.runMigrations}'` +
             (effectiveCreateCommits
@@ -2387,18 +2366,7 @@ async function runMigrations(root, opts, args, isVerbose, shouldCreateCommits, c
     if (effectiveCreateCommits) {
         (0, migrate_commits_1.commitCheckpointBeforeMigrations)(root, commitPrefix);
     }
-    if (agentic.kind === 'enabled') {
-        const { applyAgenticHandoffGitignoreFallback } = require('./agentic/handoff-gitignore');
-        const { packageJson: nxPackageJson } = (0, package_json_1.readModulePackageJson)('nx', (0, installation_directory_1.getNxRequirePaths)(root));
-        await applyAgenticHandoffGitignoreFallback({
-            migrations,
-            installedNxVersion: nxPackageJson.version,
-            effectiveCreateCommits,
-            commitPrefix,
-            root,
-        });
-    }
-    const { migrationsWithNoChanges, skippedPromptsCount, notRunMigrationsCount, skippedPrompts, migrationEmittedNextSteps, committedShasCount, waivedAgenticStepsCount, retainedAtSuccess, } = await executeMigrations(root, migrations, isVerbose, effectiveCreateCommits, commitPrefix, shouldSkipInstall, agentic, agenticHasDiffContext, shouldRunValidation);
+    const { migrationsWithNoChanges, skippedPromptsCount, notRunMigrationsCount, skippedPrompts, migrationEmittedNextSteps, committedShasCount, waivedAgenticStepsCount, retainedAtSuccess, } = await executeMigrations(root, migrations, isVerbose, effectiveCreateCommits, commitPrefix, shouldSkipInstall, agentic);
     const ranWithChangesCount = migrations.length - notRunMigrationsCount - migrationsWithNoChanges.length;
     // The "applied" tally counts fully-completed migrations — those that
     // left no deferred work behind. Hybrid migrations whose prompt half was
@@ -2428,9 +2396,13 @@ async function runMigrations(root, opts, args, isVerbose, shouldCreateCommits, c
         ? 'Finished running migrations with uncommitted state retained'
         : 'Successfully finished running migrations';
     if (notRunMigrationsCount === migrations.length && migrations.length > 0) {
+        // Under WASM or with ids orchestration refuses, an --agentic re-run lands
+        // here again.
         const remediation = insideAgent
             ? 'The AI agent driving this run should apply each prompt — see next steps below.'
-            : 'Re-run with --agentic to apply them. See next steps below.';
+            : native_1.IS_WASM || idProblems.length > 0
+                ? 'Apply each prompt yourself. See next steps below.'
+                : 'Re-run with --agentic to apply them. See next steps below.';
         output_1.output.warn({
             title: `No migrations from '${opts.runMigrations}' were applied — every entry is a prompt-only migration. ${remediation}`,
             bodyLines: tallyBody,
@@ -2486,7 +2458,6 @@ async function runMigrations(root, opts, args, isVerbose, shouldCreateCommits, c
     }
     (0, migrate_analytics_1.reportMigrateRunComplete)({
         agenticOutcome: agentic.kind,
-        agentUsed: agentic.kind === 'enabled' ? agentic.selectedAgent.id : undefined,
         migrationCount: migrations.length,
         appliedCount,
     });
@@ -2871,45 +2842,6 @@ async function runMigration() {
         return runLocalMigrate();
     });
 }
-/**
- * Resolves a migration's collection once and derives everything the run loop
- * needs from that single read: the implementation context (`collection` +
- * `collectionPath`, handed to `runNxOrAngularMigration`) and, for agentic runs,
- * the workspace-relative documentation path handed to the agent.
- *
- * Read fresh per migration (not cached across the loop) so a prior migration's
- * reinstall is reflected, exactly as before. Error handling matches each field's
- * role:
- * - Migrations that run an implementation REQUIRE the collection; an unreadable
- *   collection throws and aborts that migration (caught by the run loop).
- * - Prompt-only migrations don't run an implementation, so the collection is
- *   read only to resolve documentation - a failure there is non-fatal: the
- *   prompt still runs and the supplementary doc is skipped with a warning.
- */
-function resolveMigrationForRun(root, migration, resolveDocumentation) {
-    let resolvedCollection;
-    if (!(0, migration_shape_1.isPromptOnlyMigration)(migration)) {
-        resolvedCollection = (0, execute_migration_1.readMigrationCollection)(migration.package, root);
-    }
-    else if (resolveDocumentation && migration.documentation) {
-        try {
-            resolvedCollection = (0, execute_migration_1.readMigrationCollection)(migration.package, root);
-        }
-        catch {
-            // Non-fatal: documentation is supplementary; the warning below fires.
-        }
-    }
-    let documentationPath;
-    if (resolveDocumentation && migration.documentation) {
-        documentationPath = resolvedCollection
-            ? (0, execute_migration_1.resolveDocumentationFileToWorkspacePath)(root, (0, path_1.dirname)(resolvedCollection.collectionPath), migration.documentation)
-            : undefined;
-        if (!documentationPath) {
-            logger_1.logger.warn(`Could not resolve the "documentation" file "${migration.documentation}" declared for migration "${migration.package}: ${migration.name}". It will be skipped as additional context for the AI agent.`);
-        }
-    }
-    return { resolvedCollection, documentationPath };
-}
 async function nxCliPath(nxWorkspaceRoot) {
     const version = process.env.NX_MIGRATE_CLI_VERSION || 'latest';
     const isVerbose = process.env.NX_VERBOSE_LOGGING === 'true';

package/dist/src/command-line/migrate/run/existing-run-report.d.ts

@@ -41,7 +41,7 @@ export interface ExistingRunCommands {
         migrationsPath: string;
     };
 }
-export declare function renderExistingRunCommands(root: string, facts: ExistingRunFacts, migrationsPath: string | undefined, agentId?: string): ExistingRunCommands;
+export declare function renderExistingRunCommands(root: string, facts: ExistingRunFacts, migrationsPath: string | undefined, agentic?: string | false): ExistingRunCommands;
 /**
  * Title plus body lines, in the shape the agent-output writers take. Every
  * body line goes through `singleLine`: branch names and timestamps came from

package/dist/src/command-line/migrate/run/existing-run-report.js

@@ -108,16 +108,18 @@ function otherActiveRuns(root, runId) {
 function renderContinueCommand(root, runId, policy, agentId) {
     return `${(0, util_1.pmExecPrefix)(root)} nx migrate --run-migrations --agentic${agentId === undefined ? '' : `=${agentId}`} --run-id=${runId} ${policy.createCommits ? '--create-commits' : '--no-create-commits'}${policy.skipInstall ? ' --skip-install' : ''}`;
 }
-function renderExistingRunCommands(root, facts, migrationsPath, agentId) {
+// `agentic` echoes the invocation's choice into the start-fresh command; the
+// continue command needs an agent, so it takes only an agent id.
+function renderExistingRunCommands(root, facts, migrationsPath, agentic) {
     const flag = migrationsPath === undefined
         ? '--run-migrations'
         : (0, util_1.runMigrationsFlag)(migrationsPath);
     return {
-        continueCommand: renderContinueCommand(root, facts.runId, facts.policy, agentId),
+        continueCommand: renderContinueCommand(root, facts.runId, facts.policy, agentic === false ? undefined : agentic),
         startFresh: flag === null
             ? { migrationsPath }
             : {
-                command: `${(0, util_1.pmExecPrefix)(root)} nx migrate ${flag}${agentId === undefined ? '' : ` --agentic=${agentId}`} --start-fresh --run-id=${facts.runId}`,
+                command: `${(0, util_1.pmExecPrefix)(root)} nx migrate ${flag}${agentic === undefined ? '' : ` --agentic=${agentic}`} --start-fresh --run-id=${facts.runId}`,
             },
     };
 }
@@ -153,12 +155,12 @@ function renderExistingRunReport(facts, commands) {
         lines.push(`  other active runs on disk: ${facts.otherActiveRuns.join(', ')}`);
     }
     if (facts.appliedStillPlanned !== undefined) {
-        lines.push(`  plan overlap: ${facts.appliedStillPlanned} of the applied migrations ${facts.appliedStillPlanned === 1 ? 'is' : 'are'} still in the plan; a new run applies ${facts.appliedStillPlanned === 1 ? 'it' : 'them'} again`);
+        lines.push(`  plan overlap: ${facts.appliedStillPlanned} of the applied migrations ${facts.appliedStillPlanned === 1 ? 'is' : 'are'} still in the plan; running the plan applies ${facts.appliedStillPlanned === 1 ? 'it' : 'them'} again`);
     }
     if (commands) {
         lines.push(``, `To continue the run: ${commands.continueCommand}`, `To start fresh (deletes the run record, then runs the whole plan again): ${'command' in commands.startFresh
             ? commands.startFresh.command
-            : `re-run this command with --start-fresh --run-id=${facts.runId}, keeping the --run-migrations argument, which names ${displayPath(commands.startFresh.migrationsPath)}; that path cannot be rendered as a command for this shell`}`, `Run either command with NX_MIGRATE_ORCHESTRATOR=true set in the environment.`);
+            : `re-run this command with --start-fresh --run-id=${facts.runId}, keeping the --run-migrations argument, which names ${displayPath(commands.startFresh.migrationsPath)}; that path cannot be rendered as a command for this shell`}`);
     }
     return {
         title: `A migrate run is already active: ${facts.runId}`,

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

@@ -1,5 +1,5 @@
-export { CURRENT_RUN_STATE_FORMAT_VERSION, NewerRunStateFormatError, migrateRunsDir, runDir, runHandoffsDir, readRunState, writeRunState, findActiveRun, createRun, TERMINAL_STEP_STATUSES, } from './run-state';
-export type { MigrateRunStatus, MigrateRunRound, MigrateStepStatus, PromptOutcomeStatus, MigrateStepAwaitingKind, MigrateStepOutcome, MigrateStepPromptOutcome, MigrateStep, MigrateCommitKind, MigrateCommitLedgerEntry, MigrateIssueDisposition, MigrateRunIssue, MigrateRunAnalytics, MigrateRunNoProgress, MigrateRunPolicy, MigrateRunState, } from './run-state';
+export { CURRENT_RUN_STATE_FORMAT_VERSION, NewerRunStateFormatError, migrateRunsDir, runDir, runHandoffsDir, readRunState, writeRunState, findActiveRun, createRun, TERMINAL_STEP_STATUSES, migrationIdProblems, } from './run-state';
+export type { MigrateRunStatus, MigrateRunRound, MigrateStepStatus, PromptOutcomeStatus, MigrateStepAwaitingKind, MigrateStepOutcome, MigrateStepPromptOutcome, MigrateStep, MigrateCommitKind, MigrateCommitLedgerEntry, MigrateIssueDisposition, MigrateRunIssue, MigrateRunAnalytics, MigrateRunNoProgress, MigrateRunPolicy, MigrateRunState, MigrationIdProblem, } from './run-state';
 export { applyStepEvent, completionSummaryLines, hasPendingCommitDebt, latestRound, runTallies, stepLabel, tallySteps, } from './state-machine';
 export { hasUnresolvedIssues } from './issues';
 export type { StepAction, StepEvent, ApplyStepEventResult, } from './state-machine';
@@ -7,7 +7,7 @@ export { createRunId } from './run-id';
 export { pmInstallCommand } from './util';
 export { runSingleMigrationWorker } from './worker';
 export type { RunSingleMigrationWorkerInput } from './worker';
-export { activeRunToReplace, completionWarnings, holdRunToContinue, releaseRunToHandOff, runOrchestratorInit, runOrchestratorReconcile, runOrchestratorResume, } from './orchestrator';
+export { activeRunForClassic, activeRunToReplace, checkRunForStartFresh, completionWarnings, deleteRunForStartFresh, holdRunToContinue, releaseRunToHandOff, runOrchestratorInit, runOrchestratorReconcile, runOrchestratorResume, } from './orchestrator';
 export type { OrchestratorInitResult, RunOrchestratorInitInput, RunOrchestratorReconcileInput, } from './orchestrator';
 export { renderContinueCommand, renderExistingRunCommands, renderExistingRunReport, } from './existing-run-report';
 export { BROKER_ENV_VAR, COMMIT_INSTALLS_FIRST, formatElapsed, MigrateCommitBroker, commitsStep, treeOperationLabel, } from './broker';