nx 23.2.1 → 23.3.0-beta.1

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

@@ -1,9 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.WINDOWS_COMMAND_LINE_BUDGET = void 0;
 exports.runAgentic = runAgentic;
 exports.adaptSpawnForWindowsShim = adaptSpawnForWindowsShim;
+const tslib_1 = require("tslib");
 const child_process_1 = require("child_process");
 const path_1 = require("path");
+const pc = tslib_1.__importStar(require("picocolors"));
+const logger_1 = require("../../../utils/logger");
 const output_1 = require("../../../utils/output");
 const migrate_analytics_1 = require("../migrate-analytics");
 const safe_prompt_1 = require("../safe-prompt");
@@ -11,7 +15,7 @@ const handoff_1 = require("./handoff");
 // How long to wait for the agent to exit gracefully after sending SIGINT once
 // a valid handoff has been written. Long enough for an interactive agent to
 // finish its current render and clean up; short enough that a frozen child
-// still gets escalated to SIGTERM in a sensible time.
+// still gets escalated to SIGKILL in a sensible time.
 const AGENT_GRACEFUL_EXIT_MS = 5_000;
 /**
  * Spawns the selected agent with `stdio: 'inherit'`, swallows SIGINT while the
@@ -19,14 +23,8 @@ const AGENT_GRACEFUL_EXIT_MS = 5_000;
  * the handoff file (or the user when the file is missing).
  */
 async function runAgentic(args) {
-    const { detected, definition, invocationContext, handoffFilePath, handoffPollIntervalMs, gracefulExitMs = AGENT_GRACEFUL_EXIT_MS, forceKillWaitMs = FORCE_KILL_WAIT_MS, } = args;
-    const spec = definition.buildInteractive(invocationContext);
-    const adapted = adaptSpawnForWindowsShim(detected.binary, spec.args, {
-        stdio: 'inherit',
-        cwd: spec.cwd ?? invocationContext.workspaceRoot,
-        env: spec.env ? { ...process.env, ...spec.env } : process.env,
-        windowsHide: true,
-    });
+    const { detected, definition, invocationContext, handoffFilePath, handoffsDir, handoffPollIntervalMs, gracefulExitMs = AGENT_GRACEFUL_EXIT_MS, forceKillWaitMs = FORCE_KILL_WAIT_MS, } = args;
+    const adapted = adaptWithinCommandLineBudget(detected, definition, invocationContext);
     let child;
     // Local alias so `@nx/workspace-require-windows-hide` recognizes the
     // options arg as a tracked Identifier rather than giving up on a
@@ -36,7 +34,7 @@ async function runAgentic(args) {
         child = (0, child_process_1.spawn)(adapted.binary, adapted.args, spawnOptions);
     }
     catch (err) {
-        return resolveFromHandoffOrPrompt(handoffFilePath, false, {
+        return resolveFromHandoffOrPrompt(handoffFilePath, handoffsDir, false, {
             spawnError: err instanceof Error ? err.message : String(err),
         });
     }
@@ -53,7 +51,7 @@ async function runAgentic(args) {
     process.on('SIGINT', swallowSigint);
     const handoffWatchAbort = new AbortController();
     const exitPromise = waitForExit(child);
-    const handoffPromise = (0, handoff_1.waitForValidHandoff)(handoffFilePath, {
+    const handoffPromise = (0, handoff_1.waitForValidHandoff)(handoffFilePath, handoffsDir, {
         signal: handoffWatchAbort.signal,
         intervalMs: handoffPollIntervalMs,
     });
@@ -82,7 +80,56 @@ async function runAgentic(args) {
         process.removeListener('SIGINT', swallowSigint);
         restoreTermiosAfterAgent();
     }
-    return resolveFromHandoffOrPrompt(handoffFilePath, userInterruptCount > 0, exitInfoToCause(exitInfo));
+    return resolveFromHandoffOrPrompt(handoffFilePath, handoffsDir, userInterruptCount > 0, exitInfoToCause(exitInfo));
+}
+// "The maximum length of the string that you can use at the command prompt is
+// 8191 characters".
+// https://learn.microsoft.com/troubleshoot/windows-client/shell-experience/command-line-string-limitation
+const WINDOWS_COMMAND_LINE_LIMIT = 8191;
+// Deliberate headroom below the documented limit for argument growth.
+const WINDOWS_COMMAND_LINE_RESERVE = 1000;
+exports.WINDOWS_COMMAND_LINE_BUDGET = WINDOWS_COMMAND_LINE_LIMIT - WINDOWS_COMMAND_LINE_RESERVE;
+/**
+ * Builds Windows shim arguments within budget, trying the shorter context
+ * before aborting. Rejects overflow to avoid truncated instructions.
+ * Leaves command lines unmeasured off the shim path.
+ */
+function adaptWithinCommandLineBudget(detected, definition, invocationContext) {
+    const adapt = (ctx) => {
+        const spec = definition.buildInteractive(ctx);
+        return adaptSpawnForWindowsShim(detected.binary, spec.args, {
+            stdio: 'inherit',
+            cwd: spec.cwd ?? ctx.workspaceRoot,
+            env: spec.env ? { ...process.env, ...spec.env } : process.env,
+            windowsHide: true,
+        });
+    };
+    const adapted = adapt(invocationContext);
+    if (withinCommandLineBudget(adapted)) {
+        return adapted;
+    }
+    const reduced = adapt({
+        ...invocationContext,
+        inlineSystemContext: invocationContext.inlineSystemContextFallback,
+    });
+    if (withinCommandLineBudget(reduced)) {
+        logger_1.logger.info(pc.dim(`  Passing the agent a reduced system context. The full one does not fit on a Windows command line alongside these paths.`));
+        return reduced;
+    }
+    output_1.output.error({
+        title: `${detected.displayName} cannot be started for this migration step`,
+        bodyLines: [
+            `Launching it needs a ${reduced.commandLineLength}-character command line. cmd.exe runs at most ${WINDOWS_COMMAND_LINE_LIMIT} characters, and nx stops at ${exports.WINDOWS_COMMAND_LINE_BUDGET} to leave room for what it cannot measure from here.`,
+            `The length is paths: the workspace root, at ${invocationContext.workspaceRoot.length} characters, and the migration's package and name, each repeated across several of them.`,
+            ``,
+            `Re-run with \`--agentic=false\` to apply the remaining migrations yourself. Moving the workspace to a shorter path can help too, but only for agents that put it on the command line.`,
+        ],
+    });
+    throw new Error(`Cannot start ${detected.displayName}: the command line exceeds the Windows limit.`);
+}
+function withinCommandLineBudget(adapted) {
+    return (adapted.commandLineLength === undefined ||
+        adapted.commandLineLength <= exports.WINDOWS_COMMAND_LINE_BUDGET);
 }
 function exitInfoToCause(info) {
     const cause = {};
@@ -130,23 +177,14 @@ function restoreTermiosAfterAgent() {
 // before the process actually exits.
 const FORCE_KILL_WAIT_MS = 500;
 /**
- * Stops the agent process after a successful handoff. Platform-branched:
+ * Stops the agent process after a successful handoff.
  *
- * - POSIX: SIGINT (graceful, equivalent to user Ctrl+C) → wait
- *   `gracefulExitMs` for the child to exit → SIGKILL → wait
- *   `FORCE_KILL_WAIT_MS` (bounded) → return. SIGTERM is intentionally
- *   skipped: a process that ignores SIGINT for 5s will hit the same
- *   handler on SIGTERM, the extra step only delays the inevitable.
+ * POSIX: SIGINT, then SIGKILL after a bounded wait. SIGTERM is skipped so a
+ * child that ignored the first graceful signal does not get a second one.
  *
- * - Windows: skip SIGINT entirely. `child.kill('*')` on Windows is a
- *   `TerminateProcess` call regardless of the signal name (Windows has
- *   no POSIX signals), and on the `cmd.exe /d /s /c "..."` shim path it
- *   would terminate cmd.exe while leaving the agent orphaned (parent
- *   death doesn't cascade to children on Windows). `taskkill /T /F`
- *   walks the process tree and kills cmd.exe AND the agent atomically;
- *   that's the only reliable shutdown path here. `taskkill` failures
- *   (binary missing, race with already-dead pid) are swallowed; the
- *   safety bound returns regardless.
+ * Windows: `taskkill /T /F`. `child.kill` is a `TerminateProcess` call whatever
+ * the signal name, which on the `cmd.exe` shim path would kill the shim and
+ * orphan the agent. `taskkill` failures are swallowed.
  */
 async function closeAgentSession(child, exitPromise, gracefulExitMs, forceKillWaitMs) {
     if (child.exitCode !== null || child.signalCode !== null)
@@ -265,8 +303,8 @@ function waitForExit(child) {
         });
     });
 }
-async function resolveFromHandoffOrPrompt(handoffFilePath, userInterrupted = false, cause = {}) {
-    const read = (0, handoff_1.readHandoffWithReason)(handoffFilePath);
+async function resolveFromHandoffOrPrompt(handoffFilePath, handoffsDir, userInterrupted = false, cause = {}) {
+    const read = (0, handoff_1.readHandoffWithReason)(handoffFilePath, handoffsDir);
     if (read.ok === true) {
         return {
             kind: read.handoff.status,
@@ -286,18 +324,8 @@ async function resolveFromHandoffOrPrompt(handoffFilePath, userInterrupted = fal
         // 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
-        // caller can log it before "Aborted by user" — a Ctrl+C that masked
-        // a SEPARATE crash still needs to show the user what crashed. Scrub
-        // fields that are just the Ctrl+C itself reverberating: exit code
-        // 130 (SIGINT) / 143 (SIGTERM from our escalation) and signals
-        // SIGINT / SIGTERM reflect the user's own keystroke (and our
-        // graceful-exit handling of it); surfacing them as "agent crashed"
-        // would be noise. Anything else — code 1, code 137 (OOM), an
-        // unrelated signal — is a separate diagnostic worth keeping. Note
-        // that `spawnError` is structurally impossible here: the spawn-throw
-        // path returns directly without registering the SIGINT listener, so
-        // `userInterrupted` can never be true on that branch.
+        // After user interruption, suppress conventional stop statuses and retain
+        // independent failure diagnostics for the caller to display.
         const exitWasCtrlC = cause.exitCode === 130 ||
             cause.exitCode === 143 ||
             cause.exitSignal === 'SIGINT' ||
@@ -321,8 +349,8 @@ async function resolveFromHandoffOrPrompt(handoffFilePath, userInterrupted = fal
 /**
  * Node's `spawn` cannot directly execute `.cmd` / `.bat` shims on Windows;
  * `which` resolves to those when an agent was installed via npm. Wrap them in
- * a `cmd.exe /d /s /c` invocation with `windowsVerbatimArguments` so quoting
- * follows the cmd.exe convention rather than Node's default cooking.
+ * a `cmd.exe /c` invocation with `windowsVerbatimArguments` so quoting follows
+ * the cmd.exe convention rather than Node's default cooking.
  *
  * On non-Windows or for non-shim binaries this is a passthrough.
  */
@@ -334,28 +362,55 @@ function adaptSpawnForWindowsShim(binary, args, options) {
     if (ext !== '.cmd' && ext !== '.bat') {
         return { binary, args: [...args], options };
     }
+    assertNoLineBreaks(binary, args);
     const cmdLine = [escapeCmdCommand(binary), ...args.map(escapeCmdArg)].join(' ');
+    const comspec = process.env.comspec || 'cmd.exe';
+    // Both modes are set rather than inherited, since a machine-wide registry
+    // setting can flip either: `/e:on` for the `%cd:~,%` substring, `/v:off` so a
+    // `!` stays literal. The outer quotes stop `cmd.exe /c` stripping the inner
+    // ones around the binary path.
+    const cmdArgs = ['/e:on', '/v:off', '/d', '/s', '/c', `"${cmdLine}"`];
     return {
-        binary: process.env.comspec || 'cmd.exe',
-        // Outer pair of quotes is required so cmd.exe /c does not strip the inner
-        // quotes around the binary path.
-        args: ['/d', '/s', '/c', `"${cmdLine}"`],
+        binary: comspec,
+        args: cmdArgs,
         options: { ...options, windowsVerbatimArguments: true },
+        // `windowsVerbatimArguments` makes the command line the argv joined by
+        // single spaces, so this is what CreateProcess and then cmd.exe see.
+        commandLineLength: [comspec, ...cmdArgs].join(' ').length,
     };
 }
-const CMD_META_CHARS = /([()\][%!^"`<>&|;, ])/g;
-// Backslash-escape embedded quotes per MS C runtime convention, wrap in
-// quotes, then caret-escape cmd.exe metacharacters.
+/** Rejects line breaks in shim commands to avoid truncated instructions. */
+function assertNoLineBreaks(binary, args) {
+    const offending = [binary, ...args].find((value) => /[\r\n]/.test(value));
+    if (offending !== undefined) {
+        throw new Error(`Cannot pass a multi-line argument to "${binary}" on Windows: cmd.exe truncates the command line at the line break. Offending argument: ${JSON.stringify(offending.slice(0, 120))}`);
+    }
+}
+const CMD_META_CHARS = /([()\][!^"`<>&|;, ])/g;
 function escapeCmdArg(arg) {
-    const quoted = `"${arg
-        .replace(/(\\*)"/g, '$1$1\\"')
-        .replace(/(\\*)$/, '$1$1')}"`;
-    return quoted.replace(CMD_META_CHARS, '^$1');
+    return neutralizePercent(caretEscape(quoteCmdArg(arg)));
 }
 function escapeCmdCommand(arg) {
     // cmd.exe interprets the command portion through an extra parsing pass;
     // apply the caret-escape twice so the .cmd shim sees the original.
-    return escapeCmdArg(arg).replace(CMD_META_CHARS, '^$1');
+    return neutralizePercent(caretEscape(caretEscape(quoteCmdArg(arg))));
+}
+// Double backslashes before quotes for the MS C runtime argv parser.
+function quoteCmdArg(arg) {
+    return `"${arg.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\*)$/, '$1$1')}"`;
+}
+function caretEscape(quoted) {
+    return quoted.replace(CMD_META_CHARS, '^$1');
+}
+/**
+ * Stops cmd.exe expanding `%VAR%` inside an argument. A caret cannot escape
+ * `%`, since expansion runs before caret processing, so each `%` becomes
+ * `%%cd:~,%`: `%cd:~,%` is a zero-length substring of a built-in and expands to
+ * nothing, leaving the leading `%`. Runs after the caret passes so the `,` it
+ * introduces stays uncareted, which the substring syntax requires.
+ */
+function neutralizePercent(escaped) {
+    return escaped.replace(/%/g, '%%cd:~,%');
 }
 async function promptAmbiguous(cause) {
     // stderr blank line so the spacer lands in the same stream as output.warn

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

@@ -10,14 +10,17 @@ export type { AgentId };
  */
 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.
+ * The one subtree of a run directory an agent writes; everything beside it is
+ * state Nx owns, so the pre-authorized write scope stops here. Handoff names
+ * derive from step ids or package and migration names, so flattening them into
+ * the run dir would leave Nx no name it could safely add.
  */
 export declare const HANDOFFS_DIR_NAME = "handoffs";
+/**
+ * Sibling subtree holding the per-step prompt files Nx writes for the agent
+ * to read. They stay out of `handoffs/`, which is the agent's to write.
+ */
+export declare const PROMPTS_DIR_NAME = "prompts";
 export declare function isHandoffGitignoreMigration(m: {
     package: string;
     name: string;
@@ -38,10 +41,22 @@ export interface DetectedInstalledAgent {
  * Inputs the runner provides when asking an agent definition to build its
  * spawn arguments. Kept minimal — agent-specific quirks (e.g. transient agent
  * name for OpenCode) are encoded inside the definition, not here.
+ *
+ * Both prompts are written to disk (see `instruction-files.ts`) and reached
+ * through `systemPromptFilePath` / `instructionsPointer`. The inline fields
+ * below are the exception, for agents that cannot be pointed at a file.
  */
 export interface InvocationContext {
-    systemContext: string;
-    userPrompt: string;
+    /** Absolute path of the file holding the step's system prompt. */
+    systemPromptFilePath: string;
+    /** Verbatim system prompt, only for a step with no file-loading path. */
+    systemPrompt: string;
+    /** Single-line command-line text pointing the agent at its instructions. */
+    instructionsPointer: string;
+    /** Inline handoff contract and pointer to `systemPromptFilePath`. */
+    inlineSystemContext: string;
+    /** Shorter `inlineSystemContext`, substituted on Windows shim overflow. */
+    inlineSystemContextFallback: string;
     workspaceRoot: string;
     /**
      * Name of the run directory under `MIGRATE_RUNS_RELATIVE_DIR` holding this

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HANDOFFS_DIR_NAME = exports.MIGRATE_RUNS_RELATIVE_DIR = void 0;
+exports.PROMPTS_DIR_NAME = exports.HANDOFFS_DIR_NAME = exports.MIGRATE_RUNS_RELATIVE_DIR = void 0;
 exports.isHandoffGitignoreMigration = isHandoffGitignoreMigration;
 /**
  * Workspace-relative directory holding all migrate-run scratch: a run
@@ -12,14 +12,17 @@ exports.isHandoffGitignoreMigration = isHandoffGitignoreMigration;
  */
 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.
+ * The one subtree of a run directory an agent writes; everything beside it is
+ * state Nx owns, so the pre-authorized write scope stops here. Handoff names
+ * derive from step ids or package and migration names, so flattening them into
+ * the run dir would leave Nx no name it could safely add.
  */
 exports.HANDOFFS_DIR_NAME = 'handoffs';
+/**
+ * Sibling subtree holding the per-step prompt files Nx writes for the agent
+ * to read. They stay out of `handoffs/`, which is the agent's to write.
+ */
+exports.PROMPTS_DIR_NAME = 'prompts';
 /**
  * Composite identity of the v23 migration that adds `.nx/migrate-runs` to
  * `.gitignore`. Hard-coded because the agentic preflight is a deliberate

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

@@ -64,6 +64,7 @@ export declare function resolveCreateCommits(args: {
     warning?: string;
     error?: string;
 };
+export declare function currentBranchIfDefault(root: string): string | null;
 /**
  * Asks before a run starts committing on the workspace's default branch, and
  * reports the decision when the answer is no. Returns whether to proceed.

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

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.commitMigrationIfRequested = commitMigrationIfRequested;
 exports.commitCheckpointBeforeMigrations = commitCheckpointBeforeMigrations;
 exports.resolveCreateCommits = resolveCreateCommits;
+exports.currentBranchIfDefault = currentBranchIfDefault;
 exports.confirmMigrationCommitsOnDefaultBranch = confirmMigrationCommitsOnDefaultBranch;
 exports.confirmCommitsOnDefaultBranch = confirmCommitsOnDefaultBranch;
 const tslib_1 = require("tslib");
@@ -180,6 +181,14 @@ function defaultBranchToCompare(baseRef, currentBranch, root) {
         .sort((a, b) => b.length - a.length)[0];
     return remote ? baseRef.slice(remote.length + 1) : baseRef;
 }
+function currentBranchIfDefault(root) {
+    const currentBranch = (0, git_utils_1.getGitCurrentBranch)(root);
+    if (!currentBranch) {
+        return null;
+    }
+    const defaultBranch = defaultBranchToCompare((0, command_line_utils_1.getBaseRef)((0, configuration_1.readNxJson)(root)), currentBranch, root);
+    return currentBranch === defaultBranch ? currentBranch : null;
+}
 /**
  * Asks before a run starts committing on the workspace's default branch, and
  * reports the decision when the answer is no. Returns whether to proceed.

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

@@ -24,13 +24,9 @@ export declare function logMigrationBoundary(index: number, total: number, pkg:
  */
 export declare function logAgenticSuccessOutcome(label: string, sha: string | null, summary: string): void;
 /**
- * Logs the skip line for a migration that waived its AI step through
- * `skipAgentic`, plus a verbose note for any `agentContext` the waiver
- * dropped. A hybrid waives its paired prompt; a generator-only migration
- * waives the validation pass, so callers must reach here only once they know
- * one was on the table. Under `inside-agent` only a hybrid can, so the
- * hand-off dropped alongside is always a prompt's; a waived generator-only
- * migration keeps its own. The note is author-facing, hence `--verbose`.
+ * Callers must already know an agentic step was owed; this only picks which one
+ * the waiver dropped. The dropped-`agentContext` note is aimed at the migration
+ * author, hence `--verbose`.
  */
 export declare function logWaivedAgenticStep(migration: {
     package: string;

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

@@ -52,13 +52,9 @@ function logAgenticSuccessOutcome(label, sha, summary) {
     logger_1.logger.info(`${pc.green('✓')} ${label}${shaPart}: ${summary}`);
 }
 /**
- * Logs the skip line for a migration that waived its AI step through
- * `skipAgentic`, plus a verbose note for any `agentContext` the waiver
- * dropped. A hybrid waives its paired prompt; a generator-only migration
- * waives the validation pass, so callers must reach here only once they know
- * one was on the table. Under `inside-agent` only a hybrid can, so the
- * hand-off dropped alongside is always a prompt's; a waived generator-only
- * migration keeps its own. The note is author-facing, hence `--verbose`.
+ * Callers must already know an agentic step was owed; this only picks which one
+ * the waiver dropped. The dropped-`agentContext` note is aimed at the migration
+ * author, hence `--verbose`.
  */
 function logWaivedAgenticStep(migration, agentContext) {
     logger_1.logger.info(pc.dim((0, migration_shape_1.isHybridMigration)(migration)

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

@@ -1227,7 +1227,7 @@ async function getPackageMigrationsConfigFromRegistry(packageName, packageVersio
     if (!result) {
         return null;
     }
-    const json = JSON.parse(result);
+    const json = (0, package_manager_1.parseRegistryViewJson)(result);
     if (!json['nx-migrations'] && !json['ng-update']) {
         const registry = new node_url_1.URL('dist' in json ? json.dist.tarball : json.tarball)
             .hostname;
@@ -2145,12 +2145,24 @@ async function runMigrations(root, opts, args, isVerbose, shouldCreateCommits, c
         if (createCommitsWarning) {
             output_1.output.warn({ title: createCommitsWarning });
         }
-        // The run commits on the user's behalf across many invocations, so the
-        // default-branch confirmation belongs here, once, before any of them.
-        if (effectiveCreateCommits &&
-            (0, safe_prompt_1.canPrompt)(opts.interactive) &&
-            !(await (0, migrate_commits_1.confirmMigrationCommitsOnDefaultBranch)(root, 'running migrations'))) {
-            return;
+        // The run commits on the user's behalf across many invocations and the
+        // agent driving it cannot answer a terminal prompt, so a commit policy the
+        // user never asked for stops the run on the default branch before any of
+        // them. `--create-commits` or nx.json `migrate.createCommits` is that ask.
+        if (effectiveCreateCommits && shouldCreateCommits === undefined) {
+            const defaultBranch = (0, migrate_commits_1.currentBranchIfDefault)(root);
+            if (defaultBranch) {
+                output_1.output.log({
+                    title: `Not starting the run: you are on the default branch '${defaultBranch}' and nx migrate would create a commit for each migration on it.`,
+                    bodyLines: [
+                        'Ask the user how to proceed, then either:',
+                        '- re-run with --create-commits to commit on this branch for this run,',
+                        '- set "migrate": { "createCommits": true } in nx.json to always allow it, then re-run,',
+                        '- or switch to another branch and re-run.',
+                    ],
+                });
+                return;
+            }
         }
         const { packageJson: orchestratorNxPackageJson } = (0, package_json_1.readModulePackageJson)('nx', (0, installation_directory_1.getNxRequirePaths)(root));
         const { runOrchestratorInit } = require('./run');
@@ -2164,6 +2176,7 @@ async function runMigrations(root, opts, args, isVerbose, shouldCreateCommits, c
             // what the user asked for.
             skipInstall: shouldSkipInstall,
             installedNxVersion: orchestratorNxPackageJson.version,
+            validate: opts.validate,
         });
     }
     (0, migrate_analytics_1.reportMigrateRunStart)({
@@ -2412,7 +2425,7 @@ function stringifyCaught(e) {
         }
     }
 }
-// A resolver-based lookup (including `resolvePackageJsonWithoutCachePollution`,
+// A resolver-based lookup (including `resolveWithoutCachePollution`,
 // which does defeat Node's package self-reference) is the wrong tool here:
 // resolvers fall back to NODE_PATH after the explicit paths, and NODE_PATH
 // names the temp installation when this runs there. The scan below reads its

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

@@ -18,3 +18,13 @@ export declare function logToAgent(message: AgentMessage): void;
 export declare function warnToAgent(message: AgentMessage): void;
 export declare function emitStepBlock(runId: string, stepId: string, action: string, payload: object): void;
 export declare function emitPromptBlock(migrationId: string, payload: object): void;
+/**
+ * Markdown, not JSON: the block carries the runbook file's bytes, so the agent
+ * reads what a resume re-emits from disk. Every `<` opening or closing an
+ * `<nx_migrate_*>` tag is neutralized wherever it sits: a positional check
+ * (line starts plus a blank-character class) can be sidestepped by characters
+ * that render as nothing but match no enumerable class. The renderer never
+ * emits the literal sequence (runbook.spec pins that), so only tampered bytes
+ * change.
+ */
+export declare function emitRunbookBlock(runId: string, content: string): void;

package/dist/src/command-line/migrate/run/agent-output.js

@@ -15,6 +15,7 @@ exports.logToAgent = logToAgent;
 exports.warnToAgent = warnToAgent;
 exports.emitStepBlock = emitStepBlock;
 exports.emitPromptBlock = emitPromptBlock;
+exports.emitRunbookBlock = emitRunbookBlock;
 const output_1 = require("../../../utils/output");
 const print_dropped_agent_context_1 = require("../agentic/print-dropped-agent-context");
 const text_1 = require("../text");
@@ -47,11 +48,11 @@ function blockPayload(payload) {
     return JSON.stringify(payload, null, 2).replace(/</g, '\\u003c');
 }
 // A bare newline pair frames the block so adjacent stdout cannot run into it.
-function writeBlock(tag, attrs, json) {
+function writeBlock(tag, attrs, body) {
     const attrText = attrs
         .map(([name, value]) => ` ${name}="${(0, print_dropped_agent_context_1.escapeXmlAttr)((0, text_1.singleLine)(value))}"`)
         .join('');
-    process.stdout.write(`\n<${tag}${attrText}>\n${json}\n</${tag}>\n\n`);
+    process.stdout.write(`\n<${tag}${attrText}>\n${body}\n</${tag}>\n\n`);
 }
 function emitStepBlock(runId, stepId, action, payload) {
     writeBlock('nx_migrate_step', [
@@ -63,3 +64,16 @@ function emitStepBlock(runId, stepId, action, payload) {
 function emitPromptBlock(migrationId, payload) {
     writeBlock('nx_migrate_prompt', [['migration', migrationId]], blockPayload(payload));
 }
+/**
+ * Markdown, not JSON: the block carries the runbook file's bytes, so the agent
+ * reads what a resume re-emits from disk. Every `<` opening or closing an
+ * `<nx_migrate_*>` tag is neutralized wherever it sits: a positional check
+ * (line starts plus a blank-character class) can be sidestepped by characters
+ * that render as nothing but match no enumerable class. The renderer never
+ * emits the literal sequence (runbook.spec pins that), so only tampered bytes
+ * change.
+ */
+function emitRunbookBlock(runId, content) {
+    const neutralized = content.replace(/<(?=\/?nx_migrate_)/gi, '\\u003c');
+    writeBlock('nx_migrate_runbook', [['run-id', runId]], neutralized);
+}

package/dist/src/command-line/migrate/run/agent-work-payload.d.ts

@@ -0,0 +1,37 @@
+import type { MigrateStepAwaitingKind } from './run-state';
+export declare function agentWorkPayloadPath(runDirPath: string, stepId: string, attempt: number): string;
+export interface ExpectedAgentWorkPayload {
+    migrationId: string;
+    kind: MigrateStepAwaitingKind;
+    promptPath?: string;
+}
+/**
+ * Failures propagate: the runbook promises a parked step's block is
+ * re-emitted, so a caller that cannot store the payload must fail the attempt
+ * rather than park.
+ */
+export declare function persistAgentWorkPayload(filePath: string, payload: object): void;
+/**
+ * The stored payload, or null when nothing usable is on disk: the file is
+ * missing (the park predates this mechanism), does not parse to a plain
+ * object, or does not match what the step awaits. Null is undifferentiated on
+ * purpose: every caller's remediation is the same freshly derived payload.
+ * The returned object is never re-emitted as text; both re-emission sites go
+ * back through the block writer's escaping, so a tampered file cannot break
+ * the framing.
+ */
+export declare function readAgentWorkPayload(filePath: string, expected: ExpectedAgentWorkPayload): Record<string, unknown> | null;
+/**
+ * Returns the newest payload from the current generator lineage, or null.
+ * `fromAttempt` excludes generator runs discarded by reset-backed retries; an
+ * absent boundary fails closed for states written by older Nx.
+ */
+export declare function latestStoredAgentWorkPayload(runDirPath: string, stepId: string, beforeAttempt: number, fromAttempt: number | undefined, expected: ExpectedAgentWorkPayload): Record<string, unknown> | null;
+/**
+ * Best effort per file: the callers run after the outcome or rearm is already
+ * decided, so an entry that cannot be removed (a permission failure, a
+ * directory planted at the path) is left to whole-run pruning rather than
+ * failing the reconcile. A planted directory is never re-handed either way:
+ * reading it fails, which the reader treats as no stored copy.
+ */
+export declare function removeAgentWorkPayloads(runDirPath: string, stepId: string, throughAttempt: number): void;