@depup/nx 23.1.3-depup.0 → 23.2.0-depup.0

package/dist/src/command-line/init/init-v2.js

@@ -5,7 +5,7 @@ exports.getPluginReason = getPluginReason;
 exports.detectPlugins = detectPlugins;
 const fs_1 = require("fs");
 const path_1 = require("path");
-const enquirer_1 = require("enquirer");
+const prompt_helpers_1 = require("../../utils/prompt-helpers");
 const semver_1 = require("semver");
 const nx_json_1 = require("../../config/nx-json");
 const fileutils_1 = require("../../utils/fileutils");
@@ -20,6 +20,7 @@ const configure_plugins_1 = require("./configure-plugins");
 const ai_agent_prompts_1 = require("./ai-agent-prompts");
 const set_up_ai_agents_1 = require("../../ai/set-up-ai-agents/set-up-ai-agents");
 const tree_1 = require("../../generators/tree");
+const format_1 = require("./implementation/format");
 const add_nx_to_monorepo_1 = require("./implementation/add-nx-to-monorepo");
 const add_nx_to_npm_repo_1 = require("./implementation/add-nx-to-npm-repo");
 const add_nx_to_turborepo_1 = require("./implementation/add-nx-to-turborepo");
@@ -29,11 +30,14 @@ const utils_1 = require("./implementation/utils");
 const provenance_1 = require("../../utils/provenance");
 const handle_import_1 = require("../../utils/handle-import");
 const native_1 = require("../../native");
+const utils_2 = require("../../ai/utils");
+const permission_errors_1 = require("../../utils/permission-errors");
 const detect_ai_agent_1 = require("../../ai/detect-ai-agent");
 const ab_testing_1 = require("../../utils/ab-testing");
 const analytics_prompt_1 = require("../../utils/analytics-prompt");
 const is_ci_1 = require("../../utils/is-ci");
 const ai_output_1 = require("./utils/ai-output");
+const is_sandbox_1 = require("../../utils/is-sandbox");
 async function initHandler(options, inner = false) {
     // Use environment variable to force local execution
     if (process.env.NX_USE_LOCAL === 'true' || inner) {
@@ -118,8 +122,15 @@ async function runInit(options, baseMeta) {
     }
     // AI agent mode: apply defaults for non-interactive operation
     const aiMode = (0, native_1.isAiAgent)();
+    const isSandboxed = (0, is_sandbox_1.isSandbox)();
     if (aiMode) {
         options.interactive = false; // Force non-interactive
+        if (isSandboxed) {
+            // During init, before configuring AI agents, the daemon and
+            // plugin socket connections are not available
+            process.env.NX_DAEMON = 'false';
+            process.env.NX_ISOLATE_PLUGINS = 'false';
+        }
         if (options.nxCloud === undefined) {
             options.nxCloud = false; // Default to skip Nx Cloud
         }
@@ -148,6 +159,7 @@ async function runInit(options, baseMeta) {
             ...options,
             integrated: !!options.integrated,
         });
+        await (0, format_1.formatInitWrites)(process.cwd());
         (0, utils_1.printFinalMessage)({
             learnMoreLink: 'https://nx.dev/technologies/angular/migration/angular',
         });
@@ -161,21 +173,17 @@ async function runInit(options, baseMeta) {
         options.interactive &&
         !aiMode &&
         process.stdin.isTTY) {
-        const setupMode = await (0, enquirer_1.prompt)([
-            {
-                type: 'select',
-                name: 'setupMode',
-                message: 'How would you like to set up Nx in this directory?',
-                choices: [
-                    {
-                        name: '.nx installation (recommended for non-JavaScript projects)',
-                    },
-                    {
-                        name: 'package.json installation (recommended for JavaScript/TypeScript projects)',
-                    },
-                ],
-            },
-        ]).then((r) => r.setupMode);
+        const setupMode = await (0, prompt_helpers_1.selectPrompt)({
+            message: 'How would you like to set up Nx in this directory?',
+            choices: [
+                {
+                    value: '.nx installation (recommended for non-JavaScript projects)',
+                },
+                {
+                    value: 'package.json installation (recommended for JavaScript/TypeScript projects)',
+                },
+            ],
+        });
         if (setupMode.startsWith('package.json')) {
             // Create a minimal package.json so the JS/TS workflow takes over
             const workspaceName = (0, path_1.basename)(process.cwd());
@@ -184,6 +192,7 @@ async function runInit(options, baseMeta) {
                 version: '0.0.0',
                 private: true,
             });
+            (0, format_1.recordInitWrite)('package.json');
         }
         else {
             options.useDotNxInstallation = true;
@@ -198,14 +207,10 @@ async function runInit(options, baseMeta) {
     // AI mode defaults to minimum setup, humans can choose
     let guided = !aiMode; // Default to minimum (false) for AI, guided (true) for humans
     if (options.interactive && !(_isTurborepo || _isNonJs)) {
-        const setupType = await (0, enquirer_1.prompt)([
-            {
-                type: 'select',
-                name: 'setupPreference',
-                message: 'Would you like a minimum or guided setup?',
-                choices: [{ name: 'Minimum' }, { name: 'Guided' }],
-            },
-        ]).then((r) => r.setupPreference);
+        const setupType = await (0, prompt_helpers_1.selectPrompt)({
+            message: 'Would you like a minimum or guided setup?',
+            choices: [{ value: 'Minimum' }, { value: 'Guided' }],
+        });
         guided = setupType === 'Guided';
     }
     /**
@@ -221,6 +226,7 @@ async function runInit(options, baseMeta) {
         await (0, add_nx_to_turborepo_1.addNxToTurborepo)({
             interactive: options.interactive,
         });
+        await (0, format_1.formatInitWrites)(process.cwd());
         (0, utils_1.printFinalMessage)({
             learnMoreLink: 'https://nx.dev/recipes/adopting-nx/from-turborepo',
         });
@@ -295,6 +301,9 @@ async function runInit(options, baseMeta) {
                     reason: getPluginReason(name),
                 }));
                 (0, ai_output_1.logProgress)('detecting', `Detected ${detectedPluginNames.length} plugin(s): ${detectedPluginNames.join(', ')}`);
+                // This path exits without reaching the drain below, and `nx.json` has
+                // already been written by now.
+                await (0, format_1.formatInitWrites)(repoRoot);
                 (0, ai_output_1.writeAiOutput)((0, ai_output_1.buildNeedsInputResult)(detectedPlugins));
                 process.exit(0);
             }
@@ -321,21 +330,38 @@ async function runInit(options, baseMeta) {
             await (0, configure_plugins_1.configurePlugins)(pluginsToInstall, updatePackageScripts, pmc, repoRoot, options.verbose);
         }
     }
-    const selectedAgents = await (0, ai_agent_prompts_1.determineAiAgents)(options.aiAgents, options.interactive && guided);
+    // AI agent mode configures the detected agent automatically (aiAgents is
+    // pre-filled above); interactive humans are always prompted — even in the
+    // minimum setup — since agent configuration also writes the sandbox
+    // allowances the Nx daemon needs when driven by an agent later.
+    const selectedAgents = await (0, ai_agent_prompts_1.determineAiAgents)(options.aiAgents, options.interactive);
     if (selectedAgents && selectedAgents.length > 0) {
-        const tree = new tree_1.FsTree(repoRoot, false);
-        const aiAgentsCallback = await (0, set_up_ai_agents_1.setupAiAgentsGenerator)(tree, {
-            directory: '.',
-            writeNxCloudRules: options.nxCloud !== false,
-            packageVersion: 'latest',
-            agents: [...selectedAgents],
-        });
-        const changes = tree.listChanges();
-        (0, tree_1.flushChanges)(repoRoot, changes);
-        if (aiAgentsCallback) {
-            const results = await aiAgentsCallback();
-            results.messages.forEach((m) => output_1.output.log(m));
-            results.errors.forEach((e) => output_1.output.error(e));
+        try {
+            const tree = new tree_1.FsTree(repoRoot, false);
+            const aiAgentsCallback = await (0, set_up_ai_agents_1.setupAiAgentsGenerator)(tree, {
+                directory: '.',
+                writeNxCloudRules: options.nxCloud !== false,
+                packageVersion: 'latest',
+                agents: [...selectedAgents],
+            });
+            const changes = tree.listChanges();
+            (0, tree_1.flushChanges)(repoRoot, changes);
+            if (aiAgentsCallback) {
+                const results = await aiAgentsCallback();
+                results.messages.forEach((m) => output_1.output.log(m));
+                results.errors.forEach((e) => output_1.output.error(e));
+            }
+        }
+        catch (e) {
+            if (!(0, permission_errors_1.isPermissionDenied)(e)) {
+                throw e;
+            }
+            // Don't fail the whole init over this — everything else succeeded.
+            // Warned rather than thrown so the rest of the init result still stands.
+            output_1.output.warn({
+                title: 'AI agent configuration could not be written from this process',
+                bodyLines: (0, utils_2.agentConfigWriteBlockedLines)(e),
+            });
         }
     }
     let nxCloudChoice;
@@ -373,6 +399,10 @@ async function runInit(options, baseMeta) {
             pluginsInstalled: pluginsToInstall.join(','),
         },
     });
+    // Before the AI record, not after: the formatters write to stdout
+    // (`--list-different`, oxfmt's summary), which would otherwise land after the
+    // NDJSON result and corrupt the tail an agent parses.
+    await (0, format_1.formatInitWrites)(repoRoot);
     // Output success result for AI agents
     if (aiMode) {
         (0, ai_output_1.writeAiOutput)((0, ai_output_1.buildSuccessResult)({
@@ -400,6 +430,7 @@ async function runInit(options, baseMeta) {
 function getPluginReason(plugin) {
     const reasonMap = {
         '@nx/eslint': 'eslint detected in dependencies',
+        '@nx/oxlint': 'oxlint detected in dependencies',
         '@nx/storybook': 'storybook detected in dependencies',
         '@nx/vite': 'vite detected in dependencies',
         '@nx/vitest': 'vitest detected in dependencies',
@@ -447,6 +478,7 @@ function parsePluginsFlag(value) {
 const npmPackageToPluginMap = {
     // Generic JS tools
     eslint: '@nx/eslint',
+    oxlint: '@nx/oxlint',
     storybook: '@nx/storybook',
     // Bundlers
     vite: '@nx/vite',
@@ -573,39 +605,18 @@ async function detectPlugins(nxJson, packageJson, interactive, includeAngularCli
             `Add these Nx plugins to integrate with the tools used in your workspace.`,
         ],
     });
-    const pluginsToInstall = await (0, enquirer_1.prompt)([
-        {
-            name: 'plugins',
-            type: 'multiselect',
-            message: `Which plugins would you like to add? Press <Space> to select and <Enter> to submit.`,
-            choices: plugins.map((p) => ({ name: p, value: p })),
-            /**
-             * limit is missing from the interface but it limits the amount of options shown
-             */
-            limit: process.stdout.rows - 4, // 4 leaves room for the header above, the prompt and some whitespace
-        },
-    ]).then((r) => r.plugins);
+    const pluginsToInstall = await (0, prompt_helpers_1.multiselectPrompt)({
+        message: `Which plugins would you like to add? Press <Space> to select and <Enter> to submit.`,
+        choices: plugins,
+    });
     if (pluginsToInstall?.length === 0)
         return {
             plugins: [],
             updatePackageScripts: false,
         };
     const updatePackageScripts = (0, fs_1.existsSync)('package.json') &&
-        (await (0, enquirer_1.prompt)([
-            {
-                name: 'updatePackageScripts',
-                type: 'autocomplete',
-                message: `Do you want to start using Nx in your package.json scripts?`,
-                choices: [
-                    {
-                        name: 'Yes',
-                    },
-                    {
-                        name: 'No',
-                    },
-                ],
-                initial: 0,
-            },
-        ]).then((r) => r.updatePackageScripts === 'Yes'));
+        (await (0, prompt_helpers_1.confirmationPrompt)({
+            message: `Do you want to start using Nx in your package.json scripts?`,
+        }));
     return { plugins: pluginsToInstall, updatePackageScripts };
 }

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

@@ -4,7 +4,7 @@ exports.AGENT_DEFINITIONS = exports.opencodeDefinition = exports.codexDefinition
 exports.getAgentDefinition = getAgentDefinition;
 const os_1 = require("os");
 const path_1 = require("path");
-const handoff_1 = require("./handoff");
+const types_1 = require("./types");
 // --- Claude Code ---------------------------------------------------------
 function claudeCodeWellKnownPaths() {
     if (process.platform === 'win32') {
@@ -13,21 +13,48 @@ function claudeCodeWellKnownPaths() {
     }
     return [(0, path_1.join)((0, os_1.homedir)(), '.claude', 'local', 'claude')];
 }
-// Pre-authorizes the handoff write: Claude Code's default permission mode
-// asks before file writes it has no allow rule for, so without this each step
-// ends with an approval prompt for nx's own handoff scratch. Prefix-less
-// patterns resolve against the session cwd (pinned to the workspace root
-// below); `Edit` covers corrections to an already-written handoff.
-const CLAUDE_CODE_HANDOFF_ALLOWED_TOOLS = `Write(${handoff_1.MIGRATE_RUNS_RELATIVE_DIR}/**),Edit(${handoff_1.MIGRATE_RUNS_RELATIVE_DIR}/**)`;
+/**
+ * The run directory names Nx will interpolate into a permission rule. A rule
+ * is a gitignore pattern, which reads `*?[]\` as syntax, and `--allowedTools`
+ * splits its value on commas and spaces, so a name carrying any of those
+ * would change what the rule authorizes rather than what it names. Run
+ * directory names derive from a migration's own version string, which nothing
+ * upstream constrains to this alphabet. The leading character rejects `.`
+ * and `..`.
+ */
+const RULE_SAFE_RUN_DIR_NAME = /^[A-Za-z0-9][A-Za-z0-9._+-]*$/;
+/**
+ * Pre-authorizes the handoff write. Claude Code's default permission mode
+ * asks before a file write it has no allow rule for, so without this every
+ * step ends on an approval prompt for Nx's own handoff scratch.
+ *
+ * The rule reaches one run's handoffs and nothing else. Its own run
+ * directory also holds state Nx wrote and reads back, and the sibling
+ * directories belong to other runs, including an orchestrated run whose
+ * handoffs decide how its steps settle. `Edit` is the only tool name file
+ * rules are matched against, and it covers creating the file as well as
+ * correcting one already written. Prefix-less patterns resolve against the
+ * session cwd, pinned to the workspace root below.
+ *
+ * Returns null for a name it cannot express, which costs the approval prompt
+ * this exists to avoid. That beats widening the rule, and nothing narrower is
+ * available: Claude Code has no escape for a literal path.
+ */
+function claudeCodeHandoffAllowedTools(runDirName) {
+    if (!RULE_SAFE_RUN_DIR_NAME.test(runDirName)) {
+        return null;
+    }
+    return `Edit(${types_1.MIGRATE_RUNS_RELATIVE_DIR}/${runDirName}/${types_1.HANDOFFS_DIR_NAME}/**)`;
+}
 function claudeCodeBuildInteractive(ctx) {
+    const allowedTools = claudeCodeHandoffAllowedTools(ctx.runDirName);
     return {
         // `--allowedTools` is variadic (space/comma separated): a positional
         // placed right after its value gets swallowed as another rule. The rules
         // must stay in one comma-joined element with a non-variadic flag
         // (`--system-prompt`) between them and the user prompt.
         args: [
-            '--allowedTools',
-            CLAUDE_CODE_HANDOFF_ALLOWED_TOOLS,
+            ...(allowedTools ? ['--allowedTools', allowedTools] : []),
             '--system-prompt',
             ctx.systemContext,
             ctx.userPrompt,

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

@@ -1,33 +1,30 @@
-export declare function isHandoffGitignoreMigration(m: {
-    package: string;
-    name: string;
-}): boolean;
 /**
- * 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.
  */
-export declare function applyAgenticHandoffGitignoreFallback({ migrations, installedNxVersion, effectiveCreateCommits, commitPrefix, root, }: {
+export declare function applyAgenticHandoffGitignoreFallback({ migrations, installedNxVersion, effectiveCreateCommits, commitPrefix, root, applyWhenPlanned, commitStandalone, }: {
     migrations: ReadonlyArray<{
         package: string;
         name: string;
@@ -43,4 +40,22 @@ export declare function applyAgenticHandoffGitignoreFallback({ migrations, insta
     effectiveCreateCommits: boolean;
     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.
+     */
+    applyWhenPlanned?: boolean;
+    /**
+     * Commit the applied entry as its own preflight commit (the default). The
+     * orchestrator suppresses this: it applies the fallback before its init
+     * checkpoint so the checkpoint's `git add -A` cannot sweep in older
+     * scratch, and in that ordering a standalone commit here would carry the
+     * user's pre-existing changes along with the entry. The checkpoint that
+     * follows captures both instead.
+     */
+    commitStandalone?: boolean;
 }): Promise<void>;

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) {