nx 23.2.0-beta.0 → 23.2.0-beta.10

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

@@ -1,6 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isHandoffGitignoreMigration = isHandoffGitignoreMigration;
 exports.applyAgenticHandoffGitignoreFallback = applyAgenticHandoffGitignoreFallback;
 const tslib_1 = require("tslib");
 const semver_1 = require("semver");
@@ -9,50 +8,42 @@ const add_migrate_runs_to_git_ignore_1 = tslib_1.__importDefault(require("../../
 const tree_1 = require("../../../generators/tree");
 const git_utils_1 = require("../../../utils/git-utils");
 const logger_1 = require("../../../utils/logger");
+const types_1 = require("./types");
 /**
- * Composite identity of the v23 migration that adds `.nx/migrate-runs` to
- * `.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.
- */
-const HANDOFF_GITIGNORE_MIGRATION_PACKAGE = 'nx';
-const HANDOFF_GITIGNORE_MIGRATION_NAME = '23-0-0-add-migrate-runs-to-git-ignore';
-function isHandoffGitignoreMigration(m) {
-    return (m.package === HANDOFF_GITIGNORE_MIGRATION_PACKAGE &&
-        m.name === HANDOFF_GITIGNORE_MIGRATION_NAME);
-}
-/**
- * Under `--agentic`, the runner writes per-run scratch under
- * `.nx/migrate-runs/<run-id>/`. The v23 migration
+ * Both the agentic runner and the orchestrator write per-run scratch under
+ * `.nx/migrate-runs/<run-id>/`: handoff 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`; without intervention it would run in its declared slot
- * (typically late), so earlier per-migration commits would absorb the
- * scratch into the user-visible diff.
+ * `.gitignore`; in its declared slot (typically late) earlier per-migration
+ * commits would absorb the scratch into the user-visible diff.
  *
  * Two paths cover the leak, with no overlap:
  *
- *   1. HOIST — handled by the sort comparator in `executeMigrations`. When
- *      the v23 migration is in the queue, it sorts to position 0 and runs
- *      first via the normal migration runner (with its own log line and
- *      commit). Fully traceable in `git log`.
+ *   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. INLINE FALLBACK — this function. When the migration is NOT in the
- *      queue AND the highest target version is < v23 (intra-pre-v23
- *      `--agentic` run), the migration won't run at all. Apply its body
- *      inline against an `FsTree` and commit it as a standalone preflight
- *      commit (or leave 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`).
  *
- * When the migration is not in the queue AND target >= v23, the user is
- * past v23 already. They had the entry historically; if it's gone, that's
- * a conscious removal we respect.
+ * 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.
  */
-async function applyAgenticHandoffGitignoreFallback({ migrations, installedNxVersion, effectiveCreateCommits, commitPrefix, root, }) {
-    if (migrations.some(isHandoffGitignoreMigration)) {
-        // The hoist path handles this via the sort comparator.
-        return;
+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.
+            return;
+        }
     }
-    if ((0, semver_1.major)(installedNxVersion) >= 23) {
+    else if ((0, semver_1.major)(installedNxVersion) >= 23) {
         // User is past v23. Respect their `.gitignore` state — if the entry
         // is missing, that's a conscious removal.
         return;
@@ -66,13 +57,13 @@ async function applyAgenticHandoffGitignoreFallback({ migrations, installedNxVer
         return;
     }
     (0, tree_1.flushChanges)(root, changes);
-    logger_1.logger.info(pc.dim(`- Added .nx/migrate-runs to .gitignore so this --agentic run's handoff scratch is ignored.`));
-    if (!effectiveCreateCommits)
+    logger_1.logger.info(pc.dim(`- Added ${types_1.MIGRATE_RUNS_RELATIVE_DIR} to .gitignore so this run's scratch state is ignored.`));
+    if (!effectiveCreateCommits || !commitStandalone)
         return;
     if (!(0, git_utils_1.hasUncommittedChanges)(root))
         return;
     try {
-        const sha = (0, git_utils_1.tryCommitChanges)(`${commitPrefix}add .nx/migrate-runs to .gitignore`, root);
+        const sha = (0, git_utils_1.tryCommitChanges)(`${commitPrefix}add ${types_1.MIGRATE_RUNS_RELATIVE_DIR} to .gitignore`, root, [types_1.MIGRATE_RUNS_RELATIVE_DIR]);
         if (sha) {
             logger_1.logger.info(pc.dim(`  Commit: ${sha}`));
         }

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

@@ -1,12 +1,10 @@
 import { HandoffFile } from './types';
-/**
- * Workspace-relative directory holding all migrate-run scratch (handoff
- * files). Shared with the agent permission rules in `definitions.ts` so the
- * pre-authorized write scope can't drift from the actual layout.
- */
-export declare const MIGRATE_RUNS_RELATIVE_DIR = ".nx/migrate-runs";
 /** Returns the run directory for a given workspace + run id (target version). */
 export declare function runDirPath(workspaceRoot: string, runId: string): string;
+/** The version-derived run id: the highest target version in the plan. */
+export declare function resolveAgenticRunId(migrations: ReadonlyArray<{
+    version: string;
+}>): string;
 /**
  * `mkdir -p` with a contextual error wrapper. Without this, the raw
  * ENOSPC/EACCES/EROFS surfaces with no indication of which directory the
@@ -22,7 +20,9 @@ export declare function mkdirSafely(dir: string, purpose: string): void;
  */
 export declare function initRunDir(workspaceRoot: string, runId: string): string;
 /**
- * Absolute path of the handoff file for a migration step within a run.
+ * Absolute path of the handoff file for a migration step within a run, under
+ * the run directory's `handoffs/` subtree: the pre-authorized write scope
+ * stops there, so a handoff placed anywhere else costs an approval prompt.
  * The package's scope (if any) becomes a real subdirectory so the package name
  * stays readable; two packages can ship a migration with the same name without
  * colliding because they land in different package subdirectories. Each

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

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MIGRATE_RUNS_RELATIVE_DIR = void 0;
 exports.runDirPath = runDirPath;
+exports.resolveAgenticRunId = resolveAgenticRunId;
 exports.mkdirSafely = mkdirSafely;
 exports.initRunDir = initRunDir;
 exports.stepHandoffPath = stepHandoffPath;
@@ -10,15 +10,16 @@ exports.readHandoff = readHandoff;
 exports.waitForValidHandoff = waitForValidHandoff;
 const fs_1 = require("fs");
 const path_1 = require("path");
-/**
- * Workspace-relative directory holding all migrate-run scratch (handoff
- * files). Shared with the agent permission rules in `definitions.ts` so the
- * pre-authorized write scope can't drift from the actual layout.
- */
-exports.MIGRATE_RUNS_RELATIVE_DIR = '.nx/migrate-runs';
+const semver_1 = require("semver");
+const version_utils_1 = require("../version-utils");
+const types_1 = require("./types");
 /** Returns the run directory for a given workspace + run id (target version). */
 function runDirPath(workspaceRoot, runId) {
-    return (0, path_1.join)(workspaceRoot, exports.MIGRATE_RUNS_RELATIVE_DIR, runId);
+    return (0, path_1.join)(workspaceRoot, types_1.MIGRATE_RUNS_RELATIVE_DIR, runId);
+}
+/** The version-derived run id: the highest target version in the plan. */
+function resolveAgenticRunId(migrations) {
+    return (0, semver_1.rsort)(migrations.map((m) => (0, version_utils_1.normalizeVersion)(m.version)))[0];
 }
 /**
  * `mkdir -p` with a contextual error wrapper. Without this, the raw
@@ -71,14 +72,16 @@ function sanitizeSegment(value) {
     return sanitized || '_';
 }
 /**
- * Absolute path of the handoff file for a migration step within a run.
+ * Absolute path of the handoff file for a migration step within a run, under
+ * the run directory's `handoffs/` subtree: the pre-authorized write scope
+ * stops there, so a handoff placed anywhere else costs an approval prompt.
  * The package's scope (if any) becomes a real subdirectory so the package name
  * stays readable; two packages can ship a migration with the same name without
  * colliding because they land in different package subdirectories. Each
  * segment is sanitized so the path is always writable on every platform.
  */
 function stepHandoffPath(runDir, migration) {
-    return (0, path_1.join)(runDir, ...migration.package.split('/').map(sanitizeSegment), `${sanitizeSegment(migration.name)}.json`);
+    return (0, path_1.join)(runDir, types_1.HANDOFFS_DIR_NAME, ...migration.package.split('/').map(sanitizeSegment), `${sanitizeSegment(migration.name)}.json`);
 }
 /**
  * Reads and validates a handoff file written by an agent. Returns a tagged

package/dist/src/command-line/migrate/agentic/print-dropped-agent-context.d.ts

@@ -1,15 +1,3 @@
-/**
- * Surfaces a migration's `agentContext` to stdout in an XML-tagged block so an
- * outer AI agent driving `nx migrate` can ingest the hints when no inner agent
- * step ran to consume them.
- *
- * Used only when `agentic.kind === 'inside-agent'`. Under `enabled`, the inner
- * step consumes `agentContext` via the prompt builders. Under `disabled` the
- * run is human-driven and printing agent-targeted context would only add noise.
- *
- * The label format is unambiguous so the outer agent can locate the block
- * within the mixed stdout stream (logger output, migration progress, etc.).
- */
 export interface DroppedAgentContextInput {
     migration: {
         package: string;
@@ -19,4 +7,11 @@ export interface DroppedAgentContextInput {
     agentContext: string[];
 }
 export declare function formatDroppedAgentContextForOuterAgent(input: DroppedAgentContextInput): string;
+export declare function escapeXmlAttr(value: string): string;
+/**
+ * Both the classic loop and the single-migration worker call this only under
+ * `agentic.kind === 'inside-agent'`. Under `enabled` the inner agent step
+ * consumes `agentContext` through the prompt builders; under `disabled` the
+ * run is human-driven and agent-targeted context is only noise.
+ */
 export declare function printDroppedAgentContextForOuterAgent(input: DroppedAgentContextInput): void;

package/dist/src/command-line/migrate/agentic/print-dropped-agent-context.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatDroppedAgentContextForOuterAgent = formatDroppedAgentContextForOuterAgent;
+exports.escapeXmlAttr = escapeXmlAttr;
 exports.printDroppedAgentContextForOuterAgent = printDroppedAgentContextForOuterAgent;
 const shared_rendering_1 = require("./prompts/shared-rendering");
 function formatDroppedAgentContextForOuterAgent(input) {
@@ -40,6 +41,12 @@ function escapeXmlAttr(value) {
         .replace(/"/g, '"')
         .replace(/'/g, ''');
 }
+/**
+ * Both the classic loop and the single-migration worker call this only under
+ * `agentic.kind === 'inside-agent'`. Under `enabled` the inner agent step
+ * consumes `agentContext` through the prompt builders; under `disabled` the
+ * run is human-driven and agent-targeted context is only noise.
+ */
 function printDroppedAgentContextForOuterAgent(input) {
     const block = formatDroppedAgentContextForOuterAgent(input);
     if (block) {

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

@@ -22,6 +22,16 @@ export interface AgenticStepResult {
      */
     ambiguous: boolean;
 }
+/**
+ * `runStep` travels in the context rather than being imported by its call
+ * sites, so this module loads only where the context is built, behind an
+ * agentic-enabled gate.
+ */
+export interface AgenticRunContext {
+    agentic: EnabledResolvedAgentic;
+    runDir: string;
+    runStep: typeof runAgenticPromptStep;
+}
 export interface RunAgenticPromptStepInput {
     root: string;
     migration: {

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

@@ -83,6 +83,7 @@ async function runAgenticPromptStep(input) {
             systemContext,
             userPrompt,
             workspaceRoot: root,
+            runDirName: (0, path_1.basename)(runDir),
         },
         handoffFilePath,
     });

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

@@ -41,10 +41,11 @@ async function runAgentic(args) {
         });
     }
     // Counts SIGINTs while the agent runs. Non-zero after exit means the
-    // user pressed Ctrl+C → skip the ambiguous abort/continue prompt, because
-    // enquirer misbehaves in the TTY state left by a SIGINT-killed child
-    // (ERR_USE_AFTER_CLOSE, setRawMode EIO) and the errors surface from async
-    // chains that `await` cannot catch.
+    // user pressed Ctrl+C → skip the ambiguous abort/continue prompt. Prompting
+    // in the TTY state left by a SIGINT-killed child misbehaved under enquirer
+    // (ERR_USE_AFTER_CLOSE, setRawMode EIO) from async chains `await` could not
+    // catch. Whether @clack/prompts shares that fault is unverified, so the skip
+    // stays; reproducing it needs a real terminal.
     let userInterruptCount = 0;
     const swallowSigint = () => {
         userInterruptCount++;
@@ -279,9 +280,10 @@ async function resolveFromHandoffOrPrompt(handoffFilePath, userInterrupted = fal
     };
     if (userInterrupted) {
         // User pressed Ctrl+C. Don't show the abort/continue prompt — they
-        // already told us what they want, and the TTY state after a
-        // SIGINT-killed child trips enquirer's setRawMode-EIO and
-        // ERR_USE_AFTER_CLOSE bugs. The orchestrator's standard failure
+        // already told us what they want. Prompting in the TTY state left by a
+        // SIGINT-killed child also tripped enquirer's setRawMode-EIO and
+        // ERR_USE_AFTER_CLOSE bugs; whether @clack/prompts shares that fault is
+        // unverified, so the skip stays. The orchestrator's standard failure
         // cascade surfaces the abort outcome.
         //
         // Forward the underlying cause as pre-rendered summary lines so the
@@ -357,13 +359,14 @@ function escapeCmdCommand(arg) {
 }
 async function promptAmbiguous(cause) {
     // stderr blank line so the spacer lands in the same stream as output.warn
-    // and the enquirer prompt — buffered stdout could otherwise reorder it
-    // and glue the prompt to the agent's trailing exit message.
+    // and the prompt — buffered stdout could otherwise reorder it and glue the
+    // prompt to the agent's trailing exit message.
     process.stderr.write('\n');
-    // Cause rendered ABOVE the prompt rather than inlined into prompt.message:
-    // enquirer's select redraw uses different math for clear (wrap-aware) vs
-    // restore (raw \n-split count), so a multi-line message can leave orphaned
-    // cells on arrow-key re-renders. Keeping message single-line sidesteps it.
+    // Cause rendered ABOVE the prompt rather than inlined into its message:
+    // enquirer's select redraw used different math for clear (wrap-aware) vs
+    // restore (raw \n-split count), so a multi-line message could leave orphaned
+    // cells on arrow-key re-renders. Kept single-line because that constraint is
+    // unverified under @clack/prompts, not because the cause still applies.
     const causeLines = describeAmbiguousCause(cause);
     if (causeLines.length > 0) {
         output_1.output.warn({
@@ -371,24 +374,21 @@ async function promptAmbiguous(cause) {
             bodyLines: causeLines,
         });
     }
-    // `migratePrompt` injects `options.cancel` so Ctrl+C and Esc exit cleanly
-    // via `process.exit(130)` before enquirer's broken cancel cleanup runs.
-    // Any other rejection we treat as abort.
+    // Cancelling exits 130 from inside the prompt; any other rejection is an
+    // abort.
     try {
-        const response = await (0, safe_prompt_1.migratePrompt)({
-            name: 'choice',
-            type: 'select',
+        const choice = await (0, safe_prompt_1.migrateChoice)({
             message: 'How should nx migrate proceed?',
             choices: [
-                { name: 'abort', message: 'Treat as failed — abort the run' },
+                { value: 'abort', label: 'Treat as failed — abort the run' },
                 {
-                    name: 'continue',
-                    message: 'Treat as completed — mark done and continue',
+                    value: 'continue',
+                    label: 'Treat as completed — mark done and continue',
                 },
             ],
         });
-        (0, migrate_analytics_1.reportMigratePrompt)('ambiguous_agent_outcome', response.choice);
-        return response.choice === 'continue'
+        (0, migrate_analytics_1.reportMigratePrompt)('ambiguous_agent_outcome', choice);
+        return choice === 'continue'
             ? { kind: 'ambiguous-continue' }
             : { kind: 'ambiguous-abort' };
     }

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

@@ -10,7 +10,15 @@ export interface ResolveAgenticInput {
     interactive?: boolean;
 }
 /**
- * Resolves the agentic state for a `--run-migrations` invocation. Runs once,
- * before the migration loop, and its result is cached for every entry.
+ * Callers resolve this once per run-phase invocation and reuse the result for
+ * every migration it covers.
  */
 export declare function resolveAgentic(input: ResolveAgenticInput): Promise<ResolvedAgentic>;
+/**
+ * No warning when `--validate` is passed with the agentic flow off: validation
+ * requires an active agent session by definition.
+ */
+export declare function resolveShouldRunValidation(args: {
+    validate: boolean | undefined;
+    agenticKind: ResolvedAgentic['kind'];
+}): boolean;

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

@@ -1,11 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveAgentic = resolveAgentic;
-const tslib_1 = require("tslib");
+exports.resolveShouldRunValidation = resolveShouldRunValidation;
 const fs_1 = require("fs");
 const jsonc_parser_1 = require("jsonc-parser");
 const path_1 = require("path");
-const pc = tslib_1.__importStar(require("picocolors"));
 const output_1 = require("../../../utils/output");
 const workspace_root_1 = require("../../../utils/workspace-root");
 const migrate_analytics_1 = require("../migrate-analytics");
@@ -18,8 +17,8 @@ const INSTALL_SUPPORTED_AGENTS_HINT = [
     ...definitions_1.AGENT_DEFINITIONS.map((def) => `  - ${def.displayName}`),
 ];
 /**
- * Resolves the agentic state for a `--run-migrations` invocation. Runs once,
- * before the migration loop, and its result is cached for every entry.
+ * Callers resolve this once per run-phase invocation and reuse the result for
+ * every migration it covers.
  */
 async function resolveAgentic(input) {
     if ((0, inception_1.isInsideAgent)()) {
@@ -57,6 +56,13 @@ async function resolveAgentic(input) {
     }
     return { kind: 'enabled', selectedAgent: selected };
 }
+/**
+ * No warning when `--validate` is passed with the agentic flow off: validation
+ * requires an active agent session by definition.
+ */
+function resolveShouldRunValidation(args) {
+    return args.validate !== false && args.agenticKind === 'enabled';
+}
 async function resolveFlag(input, isInteractive, detected) {
     if (input.agentic === true) {
         if (!isInteractive) {
@@ -121,46 +127,40 @@ async function firePromptForAgentic(migrations, detected) {
     const pinChoice = multipleAgents
         ? [
             {
-                name: 'yes-pin',
-                message: 'Yes, always with the same agent',
-                description: rememberHint,
+                value: 'yes-pin',
+                label: 'Yes, always with the same agent',
+                hint: rememberHint,
             },
         ]
         : [];
     const choices = [
         {
-            name: 'yes-once',
-            message: 'Yes, just this time',
-            description: applyHint,
+            value: 'yes-once',
+            label: 'Yes, just this time',
+            hint: applyHint,
         },
         {
-            name: 'yes-flex',
-            message: multipleAgents
+            value: 'yes-flex',
+            label: multipleAgents
                 ? "Yes, always (I'll pick the agent each run)"
                 : 'Yes, always',
-            description: rememberHint,
+            hint: rememberHint,
         },
         ...pinChoice,
-        { name: 'no-once', message: 'No, just this time', description: skipHint },
-        { name: 'no-never', message: 'No, never', description: rememberHint },
+        { value: 'no-once', label: 'No, just this time', hint: skipHint },
+        { value: 'no-never', label: 'No, never', hint: rememberHint },
     ];
     // Blank line keeps the prompt from gluing to the previous `npm install`
     // output or any earlier orchestrator line.
     console.log();
-    // `as any`: `footer` and per-choice `description` aren't in enquirer's .d.ts.
-    const response = await (0, safe_prompt_1.migratePrompt)({
-        name: 'choice',
-        type: 'select',
+    // Each choice's hint renders beside it, so the description no longer needs a
+    // footer that tracks the cursor.
+    const choice = await (0, safe_prompt_1.migrateChoice)({
         message: 'Enable the agentic flow?',
         choices,
-        initial: 0,
-        footer: function () {
-            const focused = this.focused;
-            return focused?.description ? pc.dim(`  ${focused.description}`) : '';
-        },
     });
-    (0, migrate_analytics_1.reportMigratePrompt)('agentic', response.choice);
-    switch (response.choice) {
+    (0, migrate_analytics_1.reportMigratePrompt)('agentic', choice);
+    switch (choice) {
         case 'yes-once':
             return { enabled: true };
         case 'yes-flex':
@@ -242,12 +242,10 @@ async function selectAgent(detected, explicitId, isInteractive) {
     requireInteractiveOrAbort(isInteractive);
     // Blank line keeps the prompt from gluing to the preceding output.
     console.log();
-    const response = await (0, safe_prompt_1.migratePrompt)({
-        name: 'id',
-        type: 'select',
+    const id = await (0, safe_prompt_1.migrateChoice)({
         message: 'Multiple AI agents detected. Which one should Nx use?',
-        choices: detected.map((d) => ({ name: d.id, message: d.displayName })),
+        choices: detected.map((d) => ({ value: d.id, label: d.displayName })),
     });
-    (0, migrate_analytics_1.reportMigratePrompt)('agent_select', response.id);
-    return detected.find((d) => d.id === response.id);
+    (0, migrate_analytics_1.reportMigratePrompt)('agent_select', id);
+    return detected.find((d) => d.id === id);
 }

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

@@ -1,5 +1,27 @@
 import type { AgentId } from './cli-args';
 export type { AgentId };
+/**
+ * Workspace-relative directory holding all migrate-run scratch: a run
+ * directory per run id. Shared by the run-dir layout in `handoff.ts` and the
+ * agent permission rules in `definitions.ts` so the pre-authorized write scope
+ * can't drift from the actual layout. It lives here so `definitions.ts`,
+ * loaded whenever the agentic flow is resolved, doesn't pull in the handoff
+ * runtime for the path alone.
+ */
+export declare const MIGRATE_RUNS_RELATIVE_DIR = ".nx/migrate-runs";
+/**
+ * The one subtree of a run directory an agent writes: its handoff files.
+ * Everything beside it is state Nx owns and reads back, the orchestrator's
+ * run state and plan snapshots included, so the pre-authorized write scope
+ * stops at this segment. Package names make up the rest of a handoff path,
+ * so without it they would occupy the run directory's top level and leave Nx
+ * no name it could add there safely.
+ */
+export declare const HANDOFFS_DIR_NAME = "handoffs";
+export declare function isHandoffGitignoreMigration(m: {
+    package: string;
+    name: string;
+}): boolean;
 /**
  * A coding agent that was found on the user's machine, ready to be spawned.
  *
@@ -21,6 +43,13 @@ export interface InvocationContext {
     systemContext: string;
     userPrompt: string;
     workspaceRoot: string;
+    /**
+     * Name of the run directory under `MIGRATE_RUNS_RELATIVE_DIR` holding this
+     * invocation's handoff. A workspace can carry several run directories at
+     * once, so a definition that pre-authorizes the handoff write narrows it to
+     * this one: the others belong to runs this invocation is not executing.
+     */
+    runDirName: string;
 }
 /**
  * What an agent definition returns from `buildInteractive`. The runner combines
@@ -78,11 +107,12 @@ export type HandoffOutcome = {
     causeSummary?: string[];
 };
 /**
- * Result of the up-front resolution phase that runs once per `--run-migrations`
- * invocation, before the migration loop. Cached and consulted for every entry.
+ * Result of the up-front resolution phase, run once per run-phase invocation
+ * and applied to every migration it covers.
  *
  * - `inside-agent`: nx detected it is itself running inside another agent;
- *   every agentic step is skipped and prompt migrations go to `nextSteps`.
+ *   every agentic step is skipped and prompt migrations are surfaced for the
+ *   outer agent to apply.
  * - `disabled`: the user opted out (explicit `--agentic=false`, declined the
  *   up-front prompt, or non-TTY without the flag).
  * - `enabled`: the agentic flow runs and `selectedAgent` is the agent it

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

@@ -1,2 +1,37 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.HANDOFFS_DIR_NAME = exports.MIGRATE_RUNS_RELATIVE_DIR = void 0;
+exports.isHandoffGitignoreMigration = isHandoffGitignoreMigration;
+/**
+ * Workspace-relative directory holding all migrate-run scratch: a run
+ * directory per run id. Shared by the run-dir layout in `handoff.ts` and the
+ * agent permission rules in `definitions.ts` so the pre-authorized write scope
+ * can't drift from the actual layout. It lives here so `definitions.ts`,
+ * loaded whenever the agentic flow is resolved, doesn't pull in the handoff
+ * runtime for the path alone.
+ */
+exports.MIGRATE_RUNS_RELATIVE_DIR = '.nx/migrate-runs';
+/**
+ * The one subtree of a run directory an agent writes: its handoff files.
+ * Everything beside it is state Nx owns and reads back, the orchestrator's
+ * run state and plan snapshots included, so the pre-authorized write scope
+ * stops at this segment. Package names make up the rest of a handoff path,
+ * so without it they would occupy the run directory's top level and leave Nx
+ * no name it could add there safely.
+ */
+exports.HANDOFFS_DIR_NAME = 'handoffs';
+/**
+ * Composite identity of the v23 migration that adds `.nx/migrate-runs` to
+ * `.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.
+ */
+const HANDOFF_GITIGNORE_MIGRATION_PACKAGE = 'nx';
+const HANDOFF_GITIGNORE_MIGRATION_NAME = '23-0-0-add-migrate-runs-to-git-ignore';
+function isHandoffGitignoreMigration(m) {
+    return (m.package === HANDOFF_GITIGNORE_MIGRATION_PACKAGE &&
+        m.name === HANDOFF_GITIGNORE_MIGRATION_NAME);
+}

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

@@ -1,5 +1,6 @@
 import { CommandModule } from 'yargs';
 import type { AgenticArg } from './agentic/select';
+import { type StepAction } from './step-actions';
 export declare const yargsMigrateCommand: CommandModule;
 export declare const yargsInternalMigrateCommand: CommandModule;
 export declare const DEFAULT_MIGRATION_COMMIT_PREFIX = "chore: [nx migration] ";
@@ -17,6 +18,9 @@ export type MultiMajorMode = (typeof MULTI_MAJOR_MODES)[number];
 export interface MigrateArgs {
     packageAndVersion?: string;
     runMigrations?: string;
+    runMigration?: string;
+    runId?: string;
+    stepAction?: StepAction;
     include?: MigrateInclude;
     /**
      * nx.json `migrate.include` default. Consumed by `resolveInclude` only when the
@@ -30,6 +34,8 @@ export interface MigrateArgs {
     commitPrefix?: string;
     agentic?: AgenticArg;
     validate?: boolean;
+    ifExists?: boolean;
+    interactive?: boolean;
     [key: string]: any;
 }
 /**

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

@@ -6,11 +6,13 @@ const handle_import_1 = require("../../utils/handle-import");
 const documentation_1 = require("../yargs-utils/documentation");
 const shared_options_1 = require("../yargs-utils/shared-options");
 const cli_args_1 = require("./agentic/cli-args");
+const step_actions_1 = require("./step-actions");
 exports.yargsMigrateCommand = {
     command: 'migrate [packageAndVersion]',
     describe: `Creates a migrations file or runs migrations from the migrations file.
   - Migrate packages and create migrations.json (e.g., nx migrate @nx/workspace@latest)
-  - Run migrations (e.g., nx migrate --run-migrations=migrations.json). Use flag --if-exists to run migrations only if the migrations file exists.`,
+  - Run migrations (e.g., nx migrate --run-migrations=migrations.json). Use flag --if-exists to run migrations only if the migrations file exists.
+  - Run a single migration from migrations.json by id (e.g., nx migrate --run-migration=@nx/js:my-migration).`,
     builder: (yargs) => (0, documentation_1.linkToNxDevAndExamples)(withMigrationOptions(yargs), 'migrate'),
     handler: async () => process.exit(await (await (0, handle_import_1.handleImport)('./migrate.js', __dirname)).runMigration()),
 };
@@ -51,6 +53,22 @@ function withMigrationOptions(yargs) {
         .option('runMigrations', {
         describe: `Execute migrations from a file (when the file isn't provided, execute migrations from migrations.json).`,
         type: 'string',
+    })
+        .option('runMigration', {
+        describe: "Run a single migration from migrations.json by id. The id is '<package>:<name>'; a bare '<name>' is accepted when it matches exactly one migration. A name that contains ':' must use the full '<package>:<name>' form.",
+        type: 'string',
+    })
+        .option('runId', {
+        // Hidden with the orchestrator itself.
+        describe: 'The orchestrated migrate run to record a single migration into, or to reconcile when given without --run-migration.',
+        type: 'string',
+        hidden: true,
+    })
+        .option('stepAction', {
+        describe: 'How an orchestrated reconcile resolves its single failed or died step.',
+        choices: step_actions_1.STEP_ACTIONS,
+        type: 'string',
+        hidden: true,
     })
         .option('ifExists', {
         describe: `Run migrations only if the migrations file exists, if not continues successfully.`,