nx 24.0.0-beta.0 → 24.0.0-beta.2

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

@@ -1 +1,2 @@
 export { importUltracacheConfigurations, openUltracacheConfigurations, } from './src/ultracache/store';
+export declare const TASK_GRAPH_FORMAT = 2;

package/dist/nx-cloud-internals.js

@@ -3,7 +3,13 @@
 // a public API. The client probes these exports to tell what this nx supports,
 // so keep them stable.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.openUltracacheConfigurations = exports.importUltracacheConfigurations = void 0;
+exports.TASK_GRAPH_FORMAT = exports.openUltracacheConfigurations = exports.importUltracacheConfigurations = void 0;
 var store_1 = require("./src/ultracache/store");
 Object.defineProperty(exports, "importUltracacheConfigurations", { enumerable: true, get: function () { return store_1.importUltracacheConfigurations; } });
 Object.defineProperty(exports, "openUltracacheConfigurations", { enumerable: true, get: function () { return store_1.openUltracacheConfigurations; } });
+// Nx Cloud reads it to pick the task-graph shape it hands this nx. Bump it when
+// the shape changes in a way Cloud must handle.
+//   1: `dependencies` and `continuousDependencies` edges are task ids (implied
+//      when the export is absent)
+//   2: edges are objects (`{ id, waitFor?, inputs? }`)
+exports.TASK_GRAPH_FORMAT = 2;

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

@@ -967,7 +967,8 @@ function expandInputs(inputs, project, allWorkspaceFiles, depGraphClientResponse
         }
     });
     const workspaceRootsExpanded = getExpandedWorkspaceRoots(workspaceRootInputs, allWorkspaceFiles);
-    const filesExpanded = filesInputs.flatMap((globs) => (0, native_1.expandFilesInput)(workspace_root_1.workspaceRoot, globs));
+    const projectRoots = depGraphClientResponse.projects.map((p) => p.data.root);
+    const filesExpanded = filesInputs.flatMap((globs) => (0, native_1.expandFilesInput)(workspace_root_1.workspaceRoot, globs, projectRoots));
     const otherInputsExpanded = otherInputs.map((input) => {
         if (input === 'TsConfig') {
             return (0, node_path_1.relative)(workspace_root_1.workspaceRoot, (0, typescript_1.getRootTsConfigPath)());

package/dist/src/command-line/migrate/agentic/close-agent-session.d.ts

@@ -18,4 +18,4 @@ export declare function waitForExit(child: ChildProcess): Promise<ExitInfo>;
  * orphan the agent. `taskkill` failures are swallowed.
  */
 export declare function closeAgentSession(child: ChildProcess, exitPromise: Promise<ExitInfo>, gracefulExitMs: number, forceKillWaitMs: number): Promise<void>;
-export declare function raceWithTimeout(promise: Promise<unknown>, timeoutMs: number): Promise<void>;
+export declare function raceWithTimeout(promise: Promise<unknown>, timeoutMs: number): Promise<boolean>;

package/dist/src/command-line/migrate/agentic/close-agent-session.js

@@ -109,13 +109,14 @@ async function forceKillWindowsTree(child, exitPromise, forceKillWaitMs) {
     }
     await raceWithTimeout(exitPromise, forceKillWaitMs);
 }
+// True when `promise` resolves before the timeout.
 async function raceWithTimeout(promise, timeoutMs) {
     let timer;
     try {
-        await Promise.race([
-            promise,
+        return await Promise.race([
+            promise.then(() => true),
             new Promise((resolve) => {
-                timer = setTimeout(resolve, timeoutMs);
+                timer = setTimeout(() => resolve(false), timeoutMs);
             }),
         ]);
     }

package/dist/src/command-line/migrate/agentic/handoff-gitignore.d.ts

@@ -3,26 +3,23 @@
  * `.nx/migrate-runs/<run-id>/`: handoff and prompt files in both cases, plus
  * the durable run state and its plan snapshots for the orchestrator. The v23
  * migration `23-0-0-add-migrate-runs-to-git-ignore` adds `.nx/migrate-runs` to
- * `.gitignore`; in its declared slot (typically late) earlier per-migration
- * commits would absorb the scratch into the user-visible diff.
+ * `.gitignore`, but the scratch exists before that migration runs, so earlier
+ * commits would absorb it into the user-visible diff. Its two callers use this
+ * function to add the entry before that can happen:
  *
- * Two paths cover the leak, with no overlap:
+ *   1. Orchestrator init calls it with `applyWhenPlanned` and no standalone
+ *      commit, before it creates the run dir. Its checkpoint commit carries the
+ *      edit when commits are on and the checkpoint succeeds. A planned v23
+ *      migration then changes nothing in its own step.
  *
- *   1. HOIST: `sortMigrations`, which `executeMigrations` applies, sorts the
- *      v23 migration to position 0 when it is in the queue, so it runs first
- *      through the normal runner with its own log line and commit. A
- *      single-migration worker run needs no hoisting: the requested migration
- *      is the entire queue.
+ *   2. A single-migration worker run with an agent defers to the requested
+ *      migration when it is the v23 one. Otherwise, below v23, it applies the
+ *      entry and commits it as a standalone preflight commit (or leaves it in
+ *      the working tree under `--no-create-commits`).
  *
- *   2. INLINE FALLBACK, this function. When the migration is NOT in the queue
- *      AND the highest target version is < v23 (intra-pre-v23 `--agentic`
- *      run) it will never run, so apply its body inline against an `FsTree`
- *      and commit it as a standalone preflight commit (or leave it in the
- *      working tree under `--no-create-commits`).
- *
- * Not in the queue AND target >= v23 means the user is already past v23. They
- * had the entry historically; if it is gone, that is a conscious removal we
- * respect.
+ * When the v23 migration is not planned and nx is at v23 or later, the user is
+ * already past v23. They had the entry historically; if it is gone, that is a
+ * conscious removal we respect.
  */
 export declare function applyAgenticHandoffGitignoreFallback({ migrations, installedNxVersion, effectiveCreateCommits, commitPrefix, root, applyWhenPlanned, commitStandalone, }: {
     migrations: ReadonlyArray<{
@@ -41,12 +38,11 @@ export declare function applyAgenticHandoffGitignoreFallback({ migrations, insta
     commitPrefix: string;
     root: string;
     /**
-     * Apply the entry even when the hoisted migration is in the plan. The
-     * classic loop can defer to that migration because its run scratch appears
-     * only after migration 1 has run; the orchestrator creates its run dir at
-     * init, before any migration, so it needs the entry immediately. A planned
-     * migration also means the missing entry is not a conscious removal, so the
-     * v23 cutoff does not apply.
+     * Apply the entry even when the v23 migration is in the plan. The
+     * orchestrator creates its run dir at init, before any migration runs, so
+     * it can't defer to that migration. A planned migration also means the
+     * missing entry is not a conscious removal, so the v23 cutoff does not
+     * apply.
      */
     applyWhenPlanned?: boolean;
     /**

package/dist/src/command-line/migrate/agentic/handoff-gitignore.js

@@ -14,32 +14,29 @@ const types_1 = require("./types");
  * `.nx/migrate-runs/<run-id>/`: handoff and prompt files in both cases, plus
  * the durable run state and its plan snapshots for the orchestrator. The v23
  * migration `23-0-0-add-migrate-runs-to-git-ignore` adds `.nx/migrate-runs` to
- * `.gitignore`; in its declared slot (typically late) earlier per-migration
- * commits would absorb the scratch into the user-visible diff.
+ * `.gitignore`, but the scratch exists before that migration runs, so earlier
+ * commits would absorb it into the user-visible diff. Its two callers use this
+ * function to add the entry before that can happen:
  *
- * Two paths cover the leak, with no overlap:
+ *   1. Orchestrator init calls it with `applyWhenPlanned` and no standalone
+ *      commit, before it creates the run dir. Its checkpoint commit carries the
+ *      edit when commits are on and the checkpoint succeeds. A planned v23
+ *      migration then changes nothing in its own step.
  *
- *   1. HOIST: `sortMigrations`, which `executeMigrations` applies, sorts the
- *      v23 migration to position 0 when it is in the queue, so it runs first
- *      through the normal runner with its own log line and commit. A
- *      single-migration worker run needs no hoisting: the requested migration
- *      is the entire queue.
+ *   2. A single-migration worker run with an agent defers to the requested
+ *      migration when it is the v23 one. Otherwise, below v23, it applies the
+ *      entry and commits it as a standalone preflight commit (or leaves it in
+ *      the working tree under `--no-create-commits`).
  *
- *   2. INLINE FALLBACK, this function. When the migration is NOT in the queue
- *      AND the highest target version is < v23 (intra-pre-v23 `--agentic`
- *      run) it will never run, so apply its body inline against an `FsTree`
- *      and commit it as a standalone preflight commit (or leave it in the
- *      working tree under `--no-create-commits`).
- *
- * Not in the queue AND target >= v23 means the user is already past v23. They
- * had the entry historically; if it is gone, that is a conscious removal we
- * respect.
+ * When the v23 migration is not planned and nx is at v23 or later, the user is
+ * already past v23. They had the entry historically; if it is gone, that is a
+ * conscious removal we respect.
  */
 async function applyAgenticHandoffGitignoreFallback({ migrations, installedNxVersion, effectiveCreateCommits, commitPrefix, root, applyWhenPlanned = false, commitStandalone = true, }) {
     if (migrations.some(types_1.isHandoffGitignoreMigration)) {
         if (!applyWhenPlanned) {
-            // The queue runs it itself: hoisted to the front by the sort comparator
-            // in a full run, or as the single requested migration in a worker run.
+            // The single-migration worker run is that migration, and it adds the
+            // entry itself.
             return;
         }
     }

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

@@ -21,20 +21,29 @@ async function runMasterSession(input) {
         createCommits: init.createCommits,
         skipInstall: init.skipInstall,
     };
-    const resume = (runId) => (0, run_1.runOrchestratorResume)({
-        root: init.root,
-        runId,
-        policy,
-        emitAgentInstructions: false,
-    });
+    // A resume refuses when it cannot restore the run's missing runbook; a
+    // start refuses when the default-branch commit confirmation is declined.
+    let refusal = 'declined_commits';
+    const resume = (runId) => {
+        refusal = 'runbook_missing';
+        return (0, run_1.runOrchestratorResume)({
+            root: init.root,
+            runId,
+            policy,
+            emitAgentInstructions: false,
+        });
+    };
     // With `replaceRunId`, starts fresh over that run only; the consent covers
     // the run the user saw, and any other active run is reported instead.
-    const start = (replaceRunId) => (0, run_1.runOrchestratorInit)({
-        ...init,
-        emitAgentInstructions: false,
-        onExistingRun: replaceRunId === undefined ? 'report' : 'start-fresh',
-        replaceRunId,
-    });
+    const start = (replaceRunId) => {
+        refusal = 'declined_commits';
+        return (0, run_1.runOrchestratorInit)({
+            ...init,
+            emitAgentInstructions: false,
+            onExistingRun: replaceRunId === undefined ? 'report' : 'start-fresh',
+            replaceRunId,
+        });
+    };
     let ready = requestedRunId !== undefined && !startFresh
         ? resume(requestedRunId)
         : await start(startFresh ? requestedRunId : undefined);
@@ -44,6 +53,7 @@ async function runMasterSession(input) {
             output_1.output.log({
                 title: `Leaving migrate run ${ready.runId} as it is. ${continueHint(init.root, agent.id, ready.runId, ready.facts.policy)}`,
             });
+            (0, migrate_analytics_1.reportMigrateRunStopped)('aborted');
             return;
         }
         if (decision === 'continue') {
@@ -56,9 +66,11 @@ async function runMasterSession(input) {
     }
     if (ready.kind === 'existing-run') {
         output_1.output.warn((0, run_1.renderExistingRunReport)(ready.facts, (0, run_1.renderExistingRunCommands)(init.root, ready.facts, init.migrationsPath, agent.id)));
+        (0, migrate_analytics_1.reportMigrateRunStopped)('existing_run');
         return 1;
     }
     if (ready.kind === 'refused') {
+        (0, migrate_analytics_1.reportMigrateRunStopped)(refusal);
         return;
     }
     const { runId, runRoot, runbookPath, reconcileCommand } = ready;
@@ -145,7 +157,7 @@ async function runMasterSession(input) {
     }
 }
 function continueHint(root, agentId, runId, policy) {
-    return `Run ${(0, run_1.renderContinueCommand)(root, runId, policy, agentId)}, with NX_MIGRATE_ORCHESTRATOR=true set in the environment, to continue it.`;
+    return `Run ${(0, run_1.renderContinueCommand)(root, runId, policy, agentId)} to continue it.`;
 }
 async function decideExistingRun(found, root) {
     output_1.output.log((0, run_1.renderExistingRunReport)(found.facts));

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

@@ -2,10 +2,13 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.spawnMasterSession = spawnMasterSession;
 const child_process_1 = require("child_process");
+const events_1 = require("events");
 const fs_1 = require("fs");
 const path_1 = require("path");
+const exit_codes_1 = require("../../../../utils/exit-codes");
 const logger_1 = require("../../../../utils/logger");
 const output_1 = require("../../../../utils/output");
+const spawn_without_terminal_1 = require("../../../../utils/spawn-without-terminal");
 const migrate_output_1 = require("../../migrate-output");
 const run_1 = require("../../run");
 const close_agent_session_1 = require("../close-agent-session");
@@ -13,16 +16,21 @@ const handoff_1 = require("../handoff");
 const terminal_repair_1 = require("../terminal-repair");
 const windows_cmd_1 = require("../windows-cmd");
 const invocations_1 = require("./invocations");
-// The wrapper's local re-exec sets the first two for its own hop and the user
-// sets the third to reach this path; inherited, they would change install or
-// routing behavior for every `nx migrate` the agent runs. CI exports the last
-// two for its own `nx affected` runs; inherited, they would replace the base
-// the run names and drop uncommitted files from the pass's selection. The
-// workspace's env files can still set them: every nx command loads those.
+// How long a second Ctrl+C waits for the killed operation to settle before nx
+// stops waiting on it: only a process that left its group can hold it open.
+const OPERATION_KILL_WAIT_MS = 2_000;
+// SIGINTs this close together are one Ctrl+C: `npx` and the package managers
+// pass on to nx the SIGINT the terminal already sent it.
+const SAME_PRESS_MS = 500;
+// The wrapper's local re-exec sets the first two for its own hop; inherited,
+// they would change install or routing behavior for every `nx migrate` the
+// agent runs. CI exports the last two for its own `nx affected` runs;
+// inherited, they would replace the base the run names and drop uncommitted
+// files from the pass's selection. The workspace's env files can still set
+// them: every nx command loads those.
 const STRIPPED_ENV_VARS = [
     'NX_MIGRATE_SKIP_INSTALL',
     'NX_MIGRATE_USE_LOCAL',
-    'NX_MIGRATE_ORCHESTRATOR',
     'NX_BASE',
     'NX_HEAD',
 ];
@@ -80,9 +88,26 @@ async function spawnMasterSession(input) {
         broker?.close();
         return { kind: 'spawn-failed', error: toError(error) };
     }
-    // Ctrl+C belongs to the agent from the moment it exists.
-    const swallowSigint = () => { };
-    process.on('SIGINT', swallowSigint);
+    // Ctrl+C belongs to the agent from the moment it exists. The operations the
+    // broker runs have no terminal, so nx passes on what would have reached them
+    // through it, and ends them when it goes away itself.
+    const ctrlC = new events_1.EventEmitter();
+    let lastPressAt = -Infinity;
+    const forwardSigint = () => {
+        const now = Date.now();
+        if (now - lastPressAt < SAME_PRESS_MS)
+            return;
+        lastPressAt = now;
+        (0, spawn_without_terminal_1.signalCommandsWithoutTerminal)('SIGINT');
+        ctrlC.emit('press');
+    };
+    const exitOnSignal = (signal) => {
+        (0, spawn_without_terminal_1.signalCommandsWithoutTerminal)(signal);
+        process.exit((0, exit_codes_1.signalToCode)(signal));
+    };
+    process.on('SIGINT', forwardSigint);
+    process.on('SIGHUP', exitOnSignal);
+    process.on('SIGTERM', exitOnSignal);
     const sentinelWatch = new AbortController();
     let brokerFailure;
     // Settles when the poll aborts and the request in flight is answered, or
@@ -133,17 +158,33 @@ async function spawnMasterSession(input) {
     finally {
         sentinelWatch.abort();
         // With the agent gone, the terminal is restored before the wait: an
-        // agent that left it raw would keep a Ctrl+C from reaching the operation
-        // in flight as a signal.
+        // agent that left it raw would keep a Ctrl+C from reaching nx as a signal.
         const exited = child.exitCode !== null || child.signalCode !== null;
+        let stoppedWaiting = false;
         if (started && exited) {
             restoreTerminal();
-            warnOperationInFlight(broker);
+            const inFlight = warnOperationInFlight(broker);
+            if (inFlight && (await interruptedTwice(brokerDone, ctrlC))) {
+                (0, spawn_without_terminal_1.signalCommandsWithoutTerminal)('SIGKILL');
+                if (!(await (0, close_agent_session_1.raceWithTimeout)(brokerDone, OPERATION_KILL_WAIT_MS))) {
+                    stoppedWaiting = true;
+                    output_1.output.warn({
+                        title: `Stopped waiting for ${(0, run_1.treeOperationLabel)(inFlight.request, inFlight.stepName)}.`,
+                        bodyLines: [
+                            'A process it started may still be running. Resume the run once it has exited.',
+                        ],
+                    });
+                }
+            }
         }
-        // The request in flight settles before the lock is released.
-        await brokerDone;
+        // The request in flight settles before the lock is released, unless nx
+        // stopped waiting on it above.
+        if (!stoppedWaiting)
+            await brokerDone;
         broker.close();
-        process.removeListener('SIGINT', swallowSigint);
+        process.removeListener('SIGINT', forwardSigint);
+        process.removeListener('SIGHUP', exitOnSignal);
+        process.removeListener('SIGTERM', exitOnSignal);
         if (started && !exited)
             restoreTerminal();
     }
@@ -155,15 +196,34 @@ function restoreTerminal() {
     (0, terminal_repair_1.restoreTermiosAfterAgent)();
     (0, migrate_output_1.resetSgrAfterAgent)();
 }
-// With the agent gone a Ctrl+C reaches the operation's child process, and
-// nothing else tells the user one is still running.
+// With the agent gone nothing else tells the user an operation still runs.
 function warnOperationInFlight(broker) {
-    const request = broker.requestInFlight;
-    if (!request)
-        return;
+    const inFlight = broker.requestInFlight;
+    if (!inFlight)
+        return null;
     output_1.output.warn({
-        title: `Still running ${(0, run_1.treeOperationLabel)(request)} for this migrate run. Press Ctrl+C to end it; the run can be resumed afterwards.`,
+        title: `Still running ${(0, run_1.treeOperationLabel)(inFlight.request, inFlight.stepName)} for this migrate run (${(0, run_1.formatElapsed)(Date.now() - inFlight.startedAt)} so far).${(0, run_1.commitsStep)(inFlight.request.kind) ? ` ${run_1.COMMIT_INSTALLS_FIRST}` : ''} Press Ctrl+C to end it, and again to stop everything it started. The run can be resumed afterwards.`,
+    });
+    return inFlight;
+}
+// The first Ctrl+C reaches the operation as usual; the second ends whatever
+// outlived it.
+async function interruptedTwice(done, ctrlC) {
+    let countPress;
+    const secondPress = new Promise((resolve) => {
+        let presses = 0;
+        countPress = () => {
+            if (++presses === 2)
+                resolve(true);
+        };
     });
+    ctrlC.on('press', countPress);
+    try {
+        return await Promise.race([done.then(() => false), secondPress]);
+    }
+    finally {
+        ctrlC.removeListener('press', countPress);
+    }
 }
 async function serviceBrokerUntilAborted(broker, intervalMs, signal) {
     while (!signal.aborted) {

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

@@ -97,7 +97,7 @@ function requireInteractiveOrAbort(isInteractive) {
     if (isInteractive)
         return;
     output_1.output.error({
-        title: 'The agentic flow is interactive-only in this release.',
+        title: 'The agentic flow needs an interactive terminal.',
         bodyLines: [
             'Re-run in an interactive terminal, or pass `--agentic=false` to skip the agentic flow.',
         ],
@@ -106,9 +106,9 @@ function requireInteractiveOrAbort(isInteractive) {
 }
 function warnAgenticInteractiveOnly() {
     output_1.output.warn({
-        title: 'Skipping the agentic flow: it is interactive-only in this release and this run is non-interactive.',
+        title: 'Skipping the agentic flow: the agent session needs an interactive terminal, and this run is non-interactive.',
         bodyLines: [
-            'Continuing the migration without the agentic flow. Re-run in an interactive terminal to use it.',
+            'Continuing without the agentic flow. Generators still run, prompt-based changes are left for you to apply, and no AI validation runs. Re-run in an interactive terminal to use the agentic flow.',
         ],
     });
 }

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

@@ -28,9 +28,7 @@ exports.PROMPTS_DIR_NAME = 'prompts';
  * `.gitignore`. Hard-coded because the agentic preflight is a deliberate
  * one-off coupling: this exact migration owns the entry that keeps
  * `.nx/migrate-runs/<run-id>/...` scratch out of per-migration commits. If
- * the migration is ever renamed, this entry must move with it. It lives here
- * rather than in `handoff-gitignore.ts` so `sortMigrations`' hoist check
- * doesn't load that module's migration-execution machinery.
+ * the migration is ever renamed, this entry must move with it.
  */
 const HANDOFF_GITIGNORE_MIGRATION_PACKAGE = 'nx';
 const HANDOFF_GITIGNORE_MIGRATION_NAME = '23-0-0-add-migrate-runs-to-git-ignore';

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

@@ -59,10 +59,8 @@ function withMigrationOptions(yargs) {
         type: 'string',
     })
         .option('runId', {
-        // Hidden with the orchestrator itself.
-        describe: 'The orchestrated migrate run to record a single migration into, to continue with --run-migrations, or to reconcile when given alone.',
+        describe: "The id of a migrate run, as nx prints it. With --run-migrations: continue that run, or replace it with --start-fresh. The AI agent driving a run also passes it with --run-migration to record a migration into the run, and alone to record a step's outcome and get the next step.",
         type: 'string',
-        hidden: true,
     })
         .option('stepAction', {
         describe: 'How an orchestrated reconcile resolves its single failed or died step.',
@@ -71,9 +69,8 @@ function withMigrationOptions(yargs) {
         hidden: true,
     })
         .option('startFresh', {
-        describe: 'With --run-migrations and --run-id=<id> under the orchestrator: delete the record of the active migrate run the id names and start a new run over the whole plan. Migrations the deleted run applied stay applied.',
+        describe: 'With --run-migrations and --run-id=<id>: delete the record of the active migrate run the id names, then run the whole plan again, as a new run when orchestrated. Migrations the deleted run applied stay applied.',
         type: 'boolean',
-        hidden: true,
     })
         .option('ifExists', {
         describe: `Run migrations only if the migrations file exists, if not continues successfully.`,
@@ -123,17 +120,16 @@ function withMigrationOptions(yargs) {
         choices: exports.MULTI_MAJOR_MODES,
     })
         .option('agentic', {
-        describe: 'Enable the agentic flow for prompt-based migrations and AI-driven review. Pass `--agentic=<agent>` to pin a specific agent (claude-code, codex, or opencode). Pass `--agentic=false` or `--no-agentic` to disable.',
+        describe: 'Use an AI agent to apply prompt-based migrations and review the results. With --run-migrations, one agent session drives the whole run. Pass `--agentic=<agent>` to pin a specific agent (claude-code, codex, or opencode). Pass `--agentic=false` or `--no-agentic` to disable it, including when nx migrate runs inside an AI agent.',
         coerce: cli_args_1.coerceAgenticArg,
     })
         .option('validate', {
-        describe: 'When `--agentic` resolves to an enabled agent, run agent-driven validation after generator-only migrations that have no `prompt:` field. Defaults to on; pass `--no-validate` to opt out. Has no effect when `--agentic` is disabled, when running inside an outer agent, or when running non-interactively without an explicit agent.',
+        describe: 'Have the AI agent driving the run review the changes of generator-only migrations (those with no `prompt:` field). On by default; pass `--no-validate` to opt out. A continued run keeps the setting it started with. Has no effect when no agent drives the run, or with --run-migration inside an AI agent.',
         type: 'boolean',
     })
         .option('finalValidation', {
-        describe: 'With --run-migrations under the orchestrator: end the run with an agent validation pass over the whole workspace once every migration has run. On by default; pass --no-final-validation to opt out.',
+        describe: 'With --run-migrations, when an AI agent drives the run: once every migration has run, the agent checks that the projects the run touched still lint, build, and pass their unit tests. On by default; pass --no-final-validation to opt out. A continued run keeps the setting it started with.',
         type: 'boolean',
-        hidden: true,
     })
         .check(({ createCommits, commitPrefix, from, excludeAppliedMigrations, include, agentic, }) => {
         // Only an explicit `--no-create-commits` is decidable here, before the

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

@@ -9,8 +9,8 @@ interface PackageMigrationConfig extends NxMigrationsConfiguration {
 export declare function readPackageMigrationConfig(packageName: string, dir: string): PackageMigrationConfig;
 /**
  * With a `sink`, stdin is ignored and stdout and stderr are collected for a
- * caller sharing the terminal. On POSIX the child stays in nx's process
- * group. Without a sink, the install owns the terminal.
+ * caller sharing the terminal, and the install runs without the terminal (see
+ * `spawnWithoutTerminal`). Without a sink, the install owns the terminal.
  */
 export declare function runInstall(nxWorkspaceRoot?: string, phase?: MigrationInstallPhase, rerunCommand?: string, sink?: MigrateOutputSink): Promise<void>;
 export type MigrationInstallPhase = 'pre-migration' | 'post-migration';

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

@@ -33,6 +33,7 @@ const package_manager_1 = require("../../utils/package-manager");
 const fs_1 = require("fs");
 const installation_directory_1 = require("../../utils/installation-directory");
 const shell_quoting_1 = require("../../utils/shell-quoting");
+const spawn_without_terminal_1 = require("../../utils/spawn-without-terminal");
 const project_graph_1 = require("../../project-graph/project-graph");
 const version_utils_1 = require("./version-utils");
 const deferred_output_1 = require("./deferred-output");
@@ -64,8 +65,8 @@ function readPackageMigrationConfig(packageName, dir) {
 }
 /**
  * With a `sink`, stdin is ignored and stdout and stderr are collected for a
- * caller sharing the terminal. On POSIX the child stays in nx's process
- * group. Without a sink, the install owns the terminal.
+ * caller sharing the terminal, and the install runs without the terminal (see
+ * `spawnWithoutTerminal`). Without a sink, the install owns the terminal.
  */
 function runInstall(nxWorkspaceRoot, phase = 'pre-migration', rerunCommand, sink) {
     const cwd = nxWorkspaceRoot ?? process.cwd();
@@ -81,14 +82,21 @@ function runInstall(nxWorkspaceRoot, phase = 'pre-migration', rerunCommand, sink
         // Without a sink it is mirrored live and other package managers inherit
         // stderr directly, since their output is not inspected.
         const shouldCaptureStderr = packageManager === 'npm';
-        const child = (0, child_process_1.spawn)(installCommand, {
-            shell: true,
-            stdio: sink
-                ? ['ignore', 'pipe', 'pipe']
-                : ['inherit', 'inherit', shouldCaptureStderr ? 'pipe' : 'inherit'],
-            windowsHide: true,
-            cwd,
-        });
+        const child = sink
+            ? (0, spawn_without_terminal_1.spawnWithoutTerminal)(installCommand, {
+                stdio: ['ignore', 'pipe', 'pipe'],
+                cwd,
+            })
+            : (0, child_process_1.spawn)(installCommand, {
+                shell: true,
+                stdio: [
+                    'inherit',
+                    'inherit',
+                    shouldCaptureStderr ? 'pipe' : 'inherit',
+                ],
+                windowsHide: true,
+                cwd,
+            });
         // Decoded per stream: a chunk boundary can split a multi-byte character,
         // and a sequence still incomplete at the end is what `end()` returns.
         const stdoutText = new string_decoder_1.StringDecoder('utf8');

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

@@ -18,6 +18,7 @@ export type MigratePromptChoices = {
 export type MigratePromptName = keyof MigratePromptChoices;
 export type MigrateGenerateErrorCode = 'resolve_version' | 'fetch_migrations' | 'package_updates';
 export type MigrateRunErrorCode = 'npm_install' | 'migration_exec' | 'agentic' | 'other';
+export type MigrateRunStopReason = 'existing_run' | 'declined_commits' | 'aborted' | 'runbook_missing';
 export declare function setMigrateInclude(include: MigrateInclude): void;
 export declare function setMigrateIncludeSource(source: MigrateIncludeSource): void;
 export declare function classifyMigrateFetchFallback(error: unknown): MigrateFetchFallbackReason;
@@ -60,6 +61,11 @@ export declare function reportMigrateRunComplete(opts: {
     migrationCount: number;
     appliedCount: number;
 }): void;
+/**
+ * Closes a `migrate_run_start` whose invocation stopped before running any
+ * migration.
+ */
+export declare function reportMigrateRunStopped(reason: MigrateRunStopReason): void;
 export declare function reportMigrateRunError(opts: {
     code: MigrateRunErrorCode;
     migrationPackage?: string;

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

@@ -10,6 +10,7 @@ exports.reportMigrateGenerateError = reportMigrateGenerateError;
 exports.reportMigrateRunStart = reportMigrateRunStart;
 exports.hasMigrateRunStarted = hasMigrateRunStarted;
 exports.reportMigrateRunComplete = reportMigrateRunComplete;
+exports.reportMigrateRunStopped = reportMigrateRunStopped;
 exports.reportMigrateRunError = reportMigrateRunError;
 exports.reportMigrateOrchestratorInit = reportMigrateOrchestratorInit;
 exports.reportMigrateOrchestratorDispense = reportMigrateOrchestratorDispense;
@@ -165,6 +166,17 @@ function reportMigrateRunComplete(opts) {
         });
     });
 }
+/**
+ * Closes a `migrate_run_start` whose invocation stopped before running any
+ * migration.
+ */
+function reportMigrateRunStopped(reason) {
+    safeReport(() => {
+        if (!analytics_1.customDimensions)
+            return;
+        (0, analytics_1.reportEvent)(`migrate_run_stopped_${reason}`);
+    });
+}
 function reportMigrateRunError(opts) {
     safeReport(() => {
         if (!analytics_1.customDimensions || runErrorRecorded)

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

@@ -31,13 +31,16 @@ export type CommitResult = {
  * The default `failureGuidance` describes the classic loop's absorb-and-recap
  * behavior; a caller with no later commit or recap to absorb the diff (the
  * standalone single-migration worker) passes its own.
+ *
+ * A `sink` collects the output for a caller sharing the terminal with an
+ * agent, and the commit then runs without the terminal.
  */
 export declare function commitMigrationIfRequested(root: string, migration: {
     name: string;
 }, shouldCreateCommits: boolean, commitPrefix: string, installDepsIfChanged: () => Promise<void>, pendingMigrations?: ReadonlyArray<{
     package: string;
     name: string;
-}>, failureGuidance?: string, out?: MigrateOutputSink): Promise<CommitResult>;
+}>, failureGuidance?: string, sink?: MigrateOutputSink): Promise<CommitResult>;
 /**
  * Commits any pre-existing working-tree state into a dedicated "checkpoint"
  * commit before the first migration runs. Without this, the first migration's