@ohos-ports/nx 23.3.0-beta.2 → 24.0.2-beta.0

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"));
@@ -37,6 +36,7 @@ const package_manager_1 = require("../../utils/package-manager");
 const errors_1 = require("../../utils/min-release-age/errors");
 const resolve_package_version_1 = require("./resolve-package-version");
 const handle_errors_1 = require("../../utils/handle-errors");
+const exit_codes_1 = require("../../utils/exit-codes");
 const connect_to_nx_cloud_1 = require("../nx-cloud/connect/connect-to-nx-cloud");
 const output_1 = require("../../utils/output");
 const fs_1 = require("fs");
@@ -56,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");
@@ -68,6 +69,7 @@ Object.defineProperty(exports, "normalizeVersion", { enumerable: true, get: func
 const execute_migration_1 = require("./execute-migration");
 const step_actions_1 = require("./step-actions");
 const sort_migrations_1 = require("./sort-migrations");
+const text_1 = require("./text");
 const inception_1 = require("./agentic/inception");
 const version_skew_guard_1 = require("./version-skew-guard");
 const versions_1 = require("../../utils/versions");
@@ -88,20 +90,27 @@ function formatCommandFailure(command, error) {
             .trim();
     return [`Command failed: ${command}`, ...(details ? [details] : [])].join('\n');
 }
+// Ctrl+C is left to the child. Killed by it, this process would hand the
+// terminal back to the shell while the child still runs.
 function runOrReturnExitCode(run) {
+    const leaveSigintToChild = () => { };
+    process.on('SIGINT', leaveSigintToChild);
     try {
         run();
         return 0;
     }
     catch (e) {
-        if (typeof e === 'object' &&
-            e !== null &&
-            'status' in e &&
-            typeof e.status === 'number') {
+        if (typeof e !== 'object' || e === null)
+            throw e;
+        if ('signal' in e && e.signal === 'SIGINT')
+            (0, exit_codes_1.exitAsInterrupted)();
+        if ('status' in e && typeof e.status === 'number')
             return e.status;
-        }
         throw e;
     }
+    finally {
+        process.removeListener('SIGINT', leaveSigintToChild);
+    }
 }
 function cleanSemver(version) {
     return (0, semver_1.clean)(version) ?? (0, semver_1.coerce)(version);
@@ -144,8 +153,8 @@ class Migrator {
             addToPackageJson: false,
         });
         await this.applyPendingPackageJsonUpdates();
-        this.applyIncludeFilter();
-        const { migrations, promptContents } = await this.createMigrateJson();
+        const requiredPackageUpdates = this.applyIncludeFilter();
+        const { migrations, promptContents } = await this.createMigrateJson(requiredPackageUpdates);
         return {
             packageUpdates: this.packageUpdates,
             migrations,
@@ -153,17 +162,10 @@ class Migrator {
             minVersionWithSkippedUpdates: this.minVersionWithSkippedUpdates,
         };
     }
-    async createMigrateJson() {
+    async createMigrateJson(requiredPackageUpdates) {
         const promptContents = {};
-        const migrations = await Promise.all(Object.keys(this.packageUpdates).map(async (packageName) => {
-            if (this.packageUpdates[packageName].ignoreMigrations) {
-                return [];
-            }
-            const currentVersion = this.getPkgVersion(packageName);
-            if (currentVersion === null)
-                return [];
-            const { version } = this.packageUpdates[packageName];
-            const { generators: migrationEntries, resolvedPromptFiles } = await this.fetchMigrationConfig(packageName, version);
+        const collect = async (packageName, metadataVersion, fromVersion, toVersion) => {
+            const { generators: migrationEntries, resolvedPromptFiles } = await this.fetchMigrationConfig(packageName, metadataVersion);
             if (!migrationEntries)
                 return [];
             if (resolvedPromptFiles) {
@@ -173,15 +175,34 @@ class Migrator {
             }
             return Object.entries(migrationEntries)
                 .filter(([, migration]) => migration.version &&
-                this.gt(migration.version, currentVersion) &&
-                this.lte(migration.version, version) &&
-                this.areMigrationRequirementsMet(packageName, migration))
+                this.gt(migration.version, fromVersion) &&
+                this.lte(migration.version, toVersion) &&
+                this.shouldCollectMigration(packageName, migration))
                 .map(([migrationName, migration]) => ({
                 ...migration,
                 package: packageName,
                 name: migrationName,
             }));
-        }));
+        };
+        const migrations = await Promise.all([
+            ...Object.entries(this.packageUpdates).map(async ([packageName, { version, ignoreMigrations }]) => {
+                if (ignoreMigrations)
+                    return [];
+                const currentVersion = this.getPkgVersion(packageName);
+                if (currentVersion === null)
+                    return [];
+                return collect(packageName, version, currentVersion, version);
+            }),
+            // The optional pass keeps required packages at their installed version,
+            // and the runner resolves migrations from there. An older target caps the
+            // range.
+            ...Object.entries(requiredPackageUpdates).map(async ([packageName, { version, ignoreMigrations }]) => {
+                const installedVersion = this.getInstalledPackageVersion(packageName);
+                if (ignoreMigrations || !installedVersion)
+                    return [];
+                return collect(packageName, installedVersion, '0.0.0', this.lt(version, installedVersion) ? version : installedVersion);
+            }),
+        ]);
         return { migrations: migrations.flat(), promptContents };
     }
     async buildPackageJsonUpdates(targetPackage, target) {
@@ -423,8 +444,9 @@ class Migrator {
         return false;
     }
     applyIncludeFilter() {
+        const requiredPackageUpdates = {};
         if (this.include !== 'optional') {
-            return;
+            return requiredPackageUpdates;
         }
         // Cascade walks through the required packages so cross-plugin optional
         // deps (e.g. typescript managed by @nx/js but used by @nx/angular) get
@@ -432,9 +454,11 @@ class Migrator {
         // optional updates land in package.json.
         for (const name of Object.keys(this.packageUpdates)) {
             if (this.requiredPackages.has(name)) {
+                requiredPackageUpdates[name] = this.packageUpdates[name];
                 delete this.packageUpdates[name];
             }
         }
+        return requiredPackageUpdates;
     }
     shouldApplyPackageUpdate(packageUpdate, packageName, dependencies) {
         return ((!packageUpdate.ifPackageInstalled ||
@@ -484,6 +508,35 @@ class Migrator {
                 }));
         });
     }
+    shouldCollectMigration(packageName, migration) {
+        if (this.include === 'required') {
+            return (migration.optionalUpdate !== true &&
+                this.areMigrationRequirementsMet(packageName, migration));
+        }
+        if (this.include === 'optional' &&
+            this.requiredPackages.has(packageName)) {
+            // Every past migration of a required package is in range here. Collect
+            // only those that apply an optional update or were skipped.
+            return ((migration.optionalUpdate === true ||
+                this.wasMigrationSkipped(migration.requires)) &&
+                this.areRequirementsMetAfterUpdates(migration.requires));
+        }
+        return this.areMigrationRequirementsMet(packageName, migration);
+    }
+    // Counts only updates above the installed version. The optional walk also
+    // collects stale pins below it, which are never written.
+    areRequirementsMetAfterUpdates(requirements) {
+        return Object.entries(requirements ?? {}).every(([pkgName, versionRange]) => {
+            const installedVersion = this.getInstalledPackageVersion(pkgName);
+            const update = this.packageUpdates[pkgName];
+            const version = update &&
+                (!installedVersion || this.gt(update.version, installedVersion))
+                ? cleanSemver(update.version)
+                : installedVersion;
+            return (!!version &&
+                (0, semver_1.satisfies)(version, versionRange, { includePrerelease: true }));
+        });
+    }
     areMigrationRequirementsMet(packageName, migration) {
         if (!this.excludeAppliedMigrations) {
             return this.areRequirementsMet(migration.requires);
@@ -777,9 +830,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)) {
@@ -1752,23 +1803,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;
@@ -1803,12 +1843,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'`
@@ -1841,8 +1875,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
@@ -1875,89 +1908,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.
@@ -1971,59 +1951,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 },
@@ -2053,9 +1990,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,
@@ -2117,8 +2052,66 @@ 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.`;
+// 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, isHeld, 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 = isHeld(facts.otherHolders);
+    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.
@@ -2134,20 +2127,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
@@ -2160,8 +2151,42 @@ async function runMigrations(root, opts, args, isVerbose, shouldCreateCommits, c
         const { activeRunToReplace } = require('./run');
         activeRunToReplace(root, opts.runId);
     }
+    else {
+        // Before the install as well: it would act on the in-progress edits of a
+        // live run that init wouldn't report.
+        const { refuseNewRunAlongsideLiveRun } = require('./run');
+        refuseNewRunAlongsideLiveRun(root);
+    }
     if (!shouldSkipInstall && !process.env.NX_MIGRATE_SKIP_INSTALL) {
-        await (0, execute_migration_1.runInstall)();
+        // The run must resume while the cause of a step's failed install persists.
+        const failedInstallSteps = continued?.steps.filter((s) => s.installFailed === true) ?? [];
+        if (failedInstallSteps.length > 0) {
+            const { pmInstallCommand, stepLabel, TERMINAL_STEP_STATUSES } = require('./run');
+            // A settled step keeps its mark, but no step action can retry it.
+            const settled = failedInstallSteps.filter((s) => TERMINAL_STEP_STATUSES.has(s.status));
+            const retryable = failedInstallSteps.filter((s) => !settled.includes(s));
+            const notCompleted = (steps) => `The dependency install of ${steps
+                .map(stepLabel)
+                .join(', ')} did not complete earlier in this run.`;
+            output_1.output.warn({
+                title: 'Skipping the dependency install',
+                bodyLines: [
+                    ...(retryable.length > 0
+                        ? [
+                            `${notCompleted(retryable)} Retrying that step installs again; any other choice leaves the install to you.`,
+                        ]
+                        : []),
+                    ...(settled.length > 0
+                        ? [
+                            `${notCompleted(settled)} Run \`${pmInstallCommand(root)}\` once the cause of the failed install is fixed.`,
+                        ]
+                        : []),
+                ].map(text_1.singleLine),
+            });
+        }
+        else {
+            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
@@ -2214,11 +2239,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 { dropUnsupportedAgent, idProblemLines, resolveAgentic } = require('./agentic/select');
     // 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`.
@@ -2279,11 +2312,19 @@ 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(idProblems),
+                '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');
     let agentic;
     try {
         agentic = await resolveAgentic({
@@ -2296,7 +2337,9 @@ 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.
+    agentic = dropUnsupportedAgent(agentic, idProblems);
+    const { effective: effectiveCreateCommits, warning: createCommitsWarning, error: createCommitsError, } = (0, migrate_commits_1.resolveCreateCommits)({
         createCommits: shouldCreateCommits,
         mode: agentic.kind,
         isGitRepo: (0, git_utils_1.isGitRepository)(root),
@@ -2314,12 +2357,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({
@@ -2331,16 +2370,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
@@ -2350,18 +2395,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
@@ -2391,9 +2425,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,
@@ -2449,7 +2487,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,
     });
@@ -2727,6 +2764,10 @@ async function runSingleMigrationFromCli(root, opts, args, mergedArgs) {
     if (opts.runId === undefined &&
         !shouldSkipInstall &&
         !process.env.NX_MIGRATE_SKIP_INSTALL) {
+        // The worker's refusals come after the install, which would act on the
+        // in-progress edits of a run another process works on.
+        const { checkRunsForSingleMigration } = require('./run');
+        checkRunsForSingleMigration(root);
         await (0, execute_migration_1.runInstall)(undefined, 'pre-migration', (0, execute_migration_1.formatSingleMigrationRerunCommand)(opts.runMigration));
     }
     if (!__dirname.startsWith(workspace_root_1.workspaceRoot)) {
@@ -2748,7 +2789,7 @@ async function runSingleMigrationFromCli(root, opts, args, mergedArgs) {
     // Lazy-load run/ so plain migrate and repair runs don't pay for the agentic
     // selection chain its barrel pulls in eagerly.
     const { runSingleMigrationWorker } = require('./run');
-    await runSingleMigrationWorker({
+    return await runSingleMigrationWorker({
         root,
         runMigration: opts.runMigration,
         runId: opts.runId,
@@ -2834,45 +2875,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';