nx 23.0.0-beta.19 → 23.0.0-beta.20

package/dist/src/adapter/ngcli-adapter.d.ts

@@ -3,7 +3,7 @@ import { FileBuffer } from '@angular-devkit/core/src/virtual-fs/host/interface';
 import { Observable } from 'rxjs';
 import type { GenerateOptions } from '../command-line/generate/generate';
 import { ProjectConfiguration } from '../config/workspace-json-project-json';
-import { Tree } from '../generators/tree';
+import { FileChange, Tree } from '../generators/tree';
 import type { ProjectGraph } from '../config/project-graph';
 import { ExecutorContext, GeneratorCallback } from '../config/misc-interfaces';
 export declare function createBuilderContext(builderInfo: {
@@ -59,6 +59,7 @@ export declare class NxScopeHostUsedForWrappedSchematics extends NxScopedHost {
 export declare function generate(root: string, opts: GenerateOptions, projects: Record<string, ProjectConfiguration>, verbose: boolean, projectGraph: ProjectGraph): Promise<number>;
 export declare function runMigration(root: string, packageName: string, migrationName: string, projects: Record<string, ProjectConfiguration>, isVerbose: boolean, projectGraph: ProjectGraph): Promise<{
     loggingQueue: string[];
+    changes: FileChange[];
     madeChanges: boolean;
 }>;
 /**

package/dist/src/adapter/ngcli-adapter.js

@@ -239,20 +239,38 @@ async function createRecorder(host, record, logger) {
         }
         else if (event.kind === 'update') {
             record.loggingQueue.push(core_1.tags.oneLine `${pc.white('UPDATE')} ${eventPath}`);
+            record.changes?.push(emptyFileChange('UPDATE', eventPath));
         }
         else if (event.kind === 'create') {
             record.loggingQueue.push(core_1.tags.oneLine `${pc.green('CREATE')} ${eventPath}`);
+            record.changes?.push(emptyFileChange('CREATE', eventPath));
         }
         else if (event.kind === 'delete') {
             record.loggingQueue.push(`${pc.yellow('DELETE')} ${eventPath}`);
+            record.changes?.push({ type: 'DELETE', path: eventPath, content: null });
         }
         else if (event.kind === 'rename') {
             record.loggingQueue.push(`${pc.blue('RENAME')} ${eventPath} => ${event.to}`);
+            // Surface as DELETE source + CREATE destination so downstream consumers
+            // (e.g. the agentic validation prompt's `<files_changed>` block) see
+            // both endpoints.
+            const toPath = event.to.startsWith('/') ? event.to.slice(1) : event.to;
+            record.changes?.push({ type: 'DELETE', path: eventPath, content: null });
+            record.changes?.push(emptyFileChange('CREATE', toPath));
         }
     };
 }
+// Empty content for non-DELETE FileChange entries: the Angular workflow has
+// already flushed bytes to disk, and our only downstream consumer (agentic
+// prompt builders) reads `path` + `type` only. `null` is reserved for DELETE.
+function emptyFileChange(type, path) {
+    return { type, path, content: Buffer.alloc(0) };
+}
 async function runSchematic(host, root, workflow, logger, opts, schematic, printDryRunMessage = true, recorder = null) {
-    const record = { loggingQueue: [], error: false };
+    const record = {
+        loggingQueue: [],
+        error: false,
+    };
     workflow.reporter.subscribe(recorder || (await createRecorder(host, record, logger)));
     try {
         await workflow
@@ -643,7 +661,11 @@ async function runMigration(root, packageName, migrationName, projects, isVerbos
     const fsHost = new NxScopeHostUsedForWrappedSchematics(root, new tree_1.FsTree(root, isVerbose, `ng-cli migration: ${packageName}:${migrationName}`), projectGraph);
     const workflow = createWorkflow(fsHost, root, {}, projects);
     const collection = resolveMigrationsCollection(packageName);
-    const record = { loggingQueue: [], error: false };
+    const record = {
+        loggingQueue: [],
+        changes: [],
+        error: false,
+    };
     workflow.reporter.subscribe(await createRecorder(fsHost, record, logger));
     await workflow
         .execute({
@@ -656,6 +678,7 @@ async function runMigration(root, packageName, migrationName, projects, isVerbos
         .toPromise();
     return {
         loggingQueue: record.loggingQueue,
+        changes: record.changes,
         madeChanges: record.loggingQueue.length > 0,
     };
 }

package/dist/src/command-line/init/implementation/dot-nx/add-nx-scripts.js

@@ -102,6 +102,7 @@ function updateGitIgnore(host) {
         '.nx/cache',
         '.nx/workspace-data',
         '.nx/self-healing',
+        '.nx/migrate-runs',
     ].forEach((file) => {
         if (!contents.includes(file)) {
             contents = [contents, file].join('\n');

package/dist/src/command-line/init/implementation/utils.js

@@ -217,6 +217,13 @@ function updateGitIgnore(root) {
             }
             lines.push('.nx/workspace-data');
         }
+        if (!contents.includes('.nx/migrate-runs')) {
+            if (!sepIncluded) {
+                lines.push('\n');
+                sepIncluded = true;
+            }
+            lines.push('.nx/migrate-runs');
+        }
         (0, fs_1.writeFileSync)(ignorePath, lines.join('\n'), 'utf-8');
     }
     catch { }

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

@@ -0,0 +1,22 @@
+/**
+ * Tees `console.{log,warn,error,info,debug}` into an internal buffer while
+ * preserving the original behavior. Does not intercept
+ * `process.{stdout,stderr}.write` — those bypass `console` and would also
+ * pick up unrelated framework output. Restoration is idempotent.
+ */
+export interface GeneratorOutputCapture {
+    flush(): string;
+    restore(): void;
+}
+export declare function installGeneratorOutputCapture(): GeneratorOutputCapture;
+/**
+ * Convenience wrapper that installs the capture, runs `fn`, restores on
+ * completion or throw, and returns the captured logs alongside `fn`'s value.
+ * Throws from `fn` propagate with the captured logs attached as
+ * `(err as any).capturedLogs` — the most useful diagnostic when a generator
+ * crashes mid-output.
+ */
+export declare function withGeneratorOutputCapture<T>(fn: () => Promise<T> | T): Promise<{
+    result: T;
+    logs: string;
+}>;

package/dist/src/command-line/migrate/agentic/capture-generator-output.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installGeneratorOutputCapture = installGeneratorOutputCapture;
+exports.withGeneratorOutputCapture = withGeneratorOutputCapture;
+const node_util_1 = require("node:util");
+const logger_1 = require("../../../utils/logger");
+const CONSOLE_METHODS = [
+    'log',
+    'warn',
+    'error',
+    'info',
+    'debug',
+];
+// Marks `console[method]` as a wrapper installed by this module. Seeing it on
+// entry means the previous install never restored — refuse rather than layer,
+// otherwise the leak compounds silently into a wrapper-wrapping-a-wrapper.
+const CAPTURED_MARKER = Symbol.for('nx-migrate.generator-output-captured');
+const NOOP_CAPTURE = {
+    flush: () => '',
+    restore: () => { },
+};
+function installGeneratorOutputCapture() {
+    // Refuse to layer if the previous install never restored. Returns a noop
+    // handle so callers' `flush()` / `restore()` calls remain safe.
+    for (const method of CONSOLE_METHODS) {
+        if (console[method][CAPTURED_MARKER]) {
+            logger_1.logger.verbose(`nx migrate: refusing to layer a second generator-output capture; the previous one was not restored. This typically means a caller skipped its \`try/finally\`. The inner caller's \`flush()\` will return empty, but its console output is still being captured by the outer install.`);
+            return NOOP_CAPTURE;
+        }
+    }
+    const buffer = [];
+    const originals = new Map();
+    for (const method of CONSOLE_METHODS) {
+        originals.set(method, console[method]);
+        const original = console[method].bind(console);
+        const wrapper = ((...args) => {
+            original(...args);
+            try {
+                buffer.push((0, node_util_1.format)(...args));
+            }
+            catch {
+                // `format` is robust against the common pathologies but a user arg
+                // with a throwing `toString()` would otherwise turn a benign
+                // `console.log(...)` into a generator crash.
+            }
+        });
+        Object.defineProperty(wrapper, CAPTURED_MARKER, {
+            value: true,
+            enumerable: false,
+            configurable: true,
+            writable: false,
+        });
+        console[method] = wrapper;
+    }
+    let restored = false;
+    return {
+        flush() {
+            return buffer.join('\n');
+        },
+        restore() {
+            if (restored)
+                return;
+            restored = true;
+            for (const [method, fn] of originals) {
+                console[method] = fn;
+            }
+        },
+    };
+}
+/**
+ * Convenience wrapper that installs the capture, runs `fn`, restores on
+ * completion or throw, and returns the captured logs alongside `fn`'s value.
+ * Throws from `fn` propagate with the captured logs attached as
+ * `(err as any).capturedLogs` — the most useful diagnostic when a generator
+ * crashes mid-output.
+ */
+async function withGeneratorOutputCapture(fn) {
+    const capture = installGeneratorOutputCapture();
+    try {
+        const result = await fn();
+        return { result, logs: capture.flush() };
+    }
+    catch (err) {
+        if (err && typeof err === 'object') {
+            // A frozen / sealed / non-extensible error would make this throw a
+            // TypeError under TS-emitted strict-mode code, masking the original
+            // generator error. Swallow that failure; the diagnostic is best-effort.
+            try {
+                err.capturedLogs = capture.flush();
+            }
+            catch {
+                /* attachment failed; preserve the original error */
+            }
+        }
+        throw err;
+    }
+    finally {
+        capture.restore();
+    }
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Canonical list of agent ids for the migrate agentic flow. Used by the yargs
+ * layer for `--agentic` validation and by the runtime as the source of truth
+ * for the {@link AgentId} union.
+ */
+export declare const AGENT_IDS: readonly ["claude-code", "codex", "opencode"];
+export type AgentId = (typeof AGENT_IDS)[number];
+/**
+ * Shape-only normalization of `--agentic`; validation of agent-id strings is
+ * done upstream in the yargs `.check()` chain.
+ */
+export declare function coerceAgenticArg(value: unknown): string | boolean | undefined;

package/dist/src/command-line/migrate/agentic/cli-args.js

@@ -0,0 +1,38 @@
+"use strict";
+// Zero-dep helpers for --agentic — keeps the agentic chain out of every
+// nx CLI startup.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENT_IDS = void 0;
+exports.coerceAgenticArg = coerceAgenticArg;
+/**
+ * Canonical list of agent ids for the migrate agentic flow. Used by the yargs
+ * layer for `--agentic` validation and by the runtime as the source of truth
+ * for the {@link AgentId} union.
+ */
+exports.AGENT_IDS = ['claude-code', 'codex', 'opencode'];
+/**
+ * Shape-only normalization of `--agentic`; validation of agent-id strings is
+ * done upstream in the yargs `.check()` chain.
+ */
+function coerceAgenticArg(value) {
+    if (value === undefined)
+        return undefined;
+    // yargs collects repeated occurrences into an array; error rather than
+    // silently picking last/first. `--agentic` is single-value by intent.
+    if (Array.isArray(value)) {
+        const received = value
+            .map((v) => (typeof v === 'string' ? `--agentic=${v}` : '--agentic'))
+            .join(' ');
+        throw new Error(`Error: --agentic was passed more than once (received: ${received}). Specify --agentic at most one time.`);
+    }
+    if (value === true || value === '' || value === 'true' || value === 'yes') {
+        return true;
+    }
+    if (value === false || value === 'false' || value === 'no') {
+        return false;
+    }
+    if (typeof value === 'string') {
+        return value;
+    }
+    return undefined;
+}

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

@@ -0,0 +1,6 @@
+import { AgentDefinition, AgentId } from './types';
+export declare const claudeCodeDefinition: AgentDefinition;
+export declare const codexDefinition: AgentDefinition;
+export declare const opencodeDefinition: AgentDefinition;
+export declare const AGENT_DEFINITIONS: readonly AgentDefinition[];
+export declare function getAgentDefinition(id: AgentId): AgentDefinition | undefined;

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

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENT_DEFINITIONS = exports.opencodeDefinition = exports.codexDefinition = exports.claudeCodeDefinition = void 0;
+exports.getAgentDefinition = getAgentDefinition;
+const os_1 = require("os");
+const path_1 = require("path");
+// --- Claude Code ---------------------------------------------------------
+function claudeCodeWellKnownPaths() {
+    if (process.platform === 'win32') {
+        const home = process.env.USERPROFILE;
+        return home ? [(0, path_1.join)(home, '.local', 'bin', 'claude.exe')] : [];
+    }
+    return [(0, path_1.join)((0, os_1.homedir)(), '.claude', 'local', 'claude')];
+}
+function claudeCodeBuildInteractive(ctx) {
+    return {
+        args: ['--system-prompt', ctx.systemContext, ctx.userPrompt],
+        cwd: ctx.workspaceRoot,
+    };
+}
+exports.claudeCodeDefinition = {
+    id: 'claude-code',
+    displayName: 'Claude Code',
+    binaryNames: ['claude'],
+    wellKnownPaths: claudeCodeWellKnownPaths,
+    buildInteractive: claudeCodeBuildInteractive,
+};
+// --- OpenAI Codex --------------------------------------------------------
+function codexWellKnownPaths() {
+    return [];
+}
+function codexBuildInteractive(ctx) {
+    return {
+        args: ['-c', `developer_instructions=${ctx.systemContext}`, ctx.userPrompt],
+        cwd: ctx.workspaceRoot,
+    };
+}
+exports.codexDefinition = {
+    id: 'codex',
+    displayName: 'OpenAI Codex',
+    binaryNames: ['codex'],
+    wellKnownPaths: codexWellKnownPaths,
+    buildInteractive: codexBuildInteractive,
+};
+// --- OpenCode ------------------------------------------------------------
+const OPENCODE_TRANSIENT_AGENT_NAME = 'nx-migrate';
+function opencodeWellKnownPaths() {
+    if (process.platform === 'win32') {
+        return [];
+    }
+    const candidates = [];
+    const home = (0, os_1.homedir)();
+    const installDir = process.env.OPENCODE_INSTALL_DIR;
+    const xdgBinDir = process.env.XDG_BIN_DIR;
+    if (installDir) {
+        candidates.push((0, path_1.join)(installDir, 'opencode'));
+    }
+    if (xdgBinDir) {
+        candidates.push((0, path_1.join)(xdgBinDir, 'opencode'));
+    }
+    candidates.push((0, path_1.join)(home, 'bin', 'opencode'));
+    candidates.push((0, path_1.join)(home, '.opencode', 'bin', 'opencode'));
+    return candidates;
+}
+function opencodeBuildInteractive(ctx) {
+    const config = {
+        agent: {
+            [OPENCODE_TRANSIENT_AGENT_NAME]: { prompt: ctx.systemContext },
+        },
+    };
+    return {
+        args: [
+            '--agent',
+            OPENCODE_TRANSIENT_AGENT_NAME,
+            '--prompt',
+            ctx.userPrompt,
+        ],
+        env: { OPENCODE_CONFIG_CONTENT: JSON.stringify(config) },
+        cwd: ctx.workspaceRoot,
+    };
+}
+exports.opencodeDefinition = {
+    id: 'opencode',
+    displayName: 'OpenCode',
+    binaryNames: ['opencode'],
+    wellKnownPaths: opencodeWellKnownPaths,
+    buildInteractive: opencodeBuildInteractive,
+};
+// --- Registry ------------------------------------------------------------
+exports.AGENT_DEFINITIONS = [
+    exports.claudeCodeDefinition,
+    exports.codexDefinition,
+    exports.opencodeDefinition,
+];
+const byId = new Map(exports.AGENT_DEFINITIONS.map((definition) => [definition.id, definition]));
+function getAgentDefinition(id) {
+    return byId.get(id);
+}

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

@@ -0,0 +1,10 @@
+import { AgentDefinition, DetectedInstalledAgent } from './types';
+/**
+ * Probes each given agent definition for an installed binary on the user's
+ * machine. PATH is checked first via `which` (which handles Windows PATHEXT),
+ * then the per-agent well-known fallback paths. Probes run in parallel.
+ *
+ * Returns only the agents that were found, preserving the order of the input
+ * `definitions` argument for callers that rely on it for picker presentation.
+ */
+export declare function detectInstalledAgents(definitions: readonly AgentDefinition[]): Promise<DetectedInstalledAgent[]>;

package/dist/src/command-line/migrate/agentic/detect-installed.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectInstalledAgents = detectInstalledAgents;
+const tslib_1 = require("tslib");
+const promises_1 = require("fs/promises");
+const which_1 = tslib_1.__importDefault(require("which"));
+const logger_1 = require("../../../utils/logger");
+async function isExecutable(path) {
+    try {
+        await (0, promises_1.access)(path, promises_1.constants.X_OK);
+        return true;
+    }
+    catch (err) {
+        // EACCES on an existing path means "this looks installed but we can't
+        // execute it" — surface so the user can answer "why isn't my agent
+        // detected?" without grep-debugging the filesystem.
+        const code = err?.code;
+        if (code && code !== 'ENOENT') {
+            logger_1.logger.verbose(`Agent detection: cannot probe ${path} (${code}).`);
+        }
+        return false;
+    }
+}
+async function findOnPath(binaryNames) {
+    for (const name of binaryNames) {
+        // `{ nothrow: true }` avoids the throw-per-missing-binary overhead;
+        // EACCES on existing-but-unexecutable paths is handled by `isExecutable`.
+        const found = await (0, which_1.default)(name, { nothrow: true });
+        if (typeof found === 'string') {
+            return found;
+        }
+    }
+    return null;
+}
+async function detectOne(definition) {
+    const onPath = await findOnPath(definition.binaryNames);
+    if (onPath) {
+        return {
+            id: definition.id,
+            displayName: definition.displayName,
+            binary: onPath,
+            source: 'path',
+        };
+    }
+    for (const candidate of definition.wellKnownPaths()) {
+        if (await isExecutable(candidate)) {
+            return {
+                id: definition.id,
+                displayName: definition.displayName,
+                binary: candidate,
+                source: 'well-known',
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Probes each given agent definition for an installed binary on the user's
+ * machine. PATH is checked first via `which` (which handles Windows PATHEXT),
+ * then the per-agent well-known fallback paths. Probes run in parallel.
+ *
+ * Returns only the agents that were found, preserving the order of the input
+ * `definitions` argument for callers that rely on it for picker presentation.
+ */
+async function detectInstalledAgents(definitions) {
+    const results = await Promise.all(definitions.map(detectOne));
+    return results.filter((result) => result !== null);
+}

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

@@ -0,0 +1,46 @@
+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
+ * `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.
+ *
+ * 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`.
+ *
+ *   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`).
+ *
+ * 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.
+ */
+export declare function applyAgenticHandoffGitignoreFallback({ migrations, installedNxVersion, effectiveCreateCommits, commitPrefix, root, }: {
+    migrations: ReadonlyArray<{
+        package: string;
+        name: string;
+    }>;
+    /**
+     * The version of `nx` currently installed in the workspace. After
+     * `nx migrate latest` runs (the step before `--run-migrations`), this is
+     * the target nx version. We use it as the v23 cutoff instead of walking
+     * the migration list: any third-party plugin migration with a `23.x`
+     * version is irrelevant to whether `nx` itself crossed v23.
+     */
+    installedNxVersion: string;
+    effectiveCreateCommits: boolean;
+    commitPrefix: string;
+    root: string;
+}): Promise<void>;

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

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isHandoffGitignoreMigration = isHandoffGitignoreMigration;
+exports.applyAgenticHandoffGitignoreFallback = applyAgenticHandoffGitignoreFallback;
+const tslib_1 = require("tslib");
+const semver_1 = require("semver");
+const pc = tslib_1.__importStar(require("picocolors"));
+const add_migrate_runs_to_git_ignore_1 = tslib_1.__importDefault(require("../../../migrations/update-23-0-0/add-migrate-runs-to-git-ignore"));
+const tree_1 = require("../../../generators/tree");
+const git_utils_1 = require("../../../utils/git-utils");
+const logger_1 = require("../../../utils/logger");
+/**
+ * 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
+ * `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.
+ *
+ * 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`.
+ *
+ *   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`).
+ *
+ * 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.
+ */
+async function applyAgenticHandoffGitignoreFallback({ migrations, installedNxVersion, effectiveCreateCommits, commitPrefix, root, }) {
+    if (migrations.some(isHandoffGitignoreMigration)) {
+        // The hoist path handles this via the sort comparator.
+        return;
+    }
+    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;
+    }
+    const tree = new tree_1.FsTree(root, false);
+    await (0, add_migrate_runs_to_git_ignore_1.default)(tree);
+    const changes = tree.listChanges();
+    if (changes.length === 0) {
+        // Migration body short-circuited (no `.gitignore`, Lerna without nx.json,
+        // or the entry is already covered by an existing pattern).
+        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)
+        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);
+        if (sha) {
+            logger_1.logger.info(pc.dim(`  Commit: ${sha}`));
+        }
+        // `null` return = commit landed but `git rev-parse HEAD` raced. The
+        // diff cleared from the working tree; nothing more to say.
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        logger_1.logger.info(pc.yellow(`Could not create the agentic preflight commit:\n${reason}\n` +
+            `The .gitignore change remains in the working tree; commit it manually or it will be absorbed into the first per-migration commit.`));
+    }
+}

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

@@ -0,0 +1,63 @@
+import { HandoffFile } from './types';
+/** Returns the run directory for a given workspace + run id (target version). */
+export declare function runDirPath(workspaceRoot: string, runId: string): string;
+/**
+ * `mkdir -p` with a contextual error wrapper. Without this, the raw
+ * ENOSPC/EACCES/EROFS surfaces with no indication of which directory the
+ * migrate orchestrator was trying to create.
+ */
+export declare function mkdirSafely(dir: string, purpose: string): void;
+/**
+ * Wipes any prior contents for this run id and recreates an empty directory.
+ *
+ * Scope of the wipe is intentionally narrow (only `<run-id>/`) so that handoff
+ * artifacts from prior runs targeting different versions remain on disk for
+ * inspection.
+ */
+export declare function initRunDir(workspaceRoot: string, runId: string): string;
+/**
+ * Absolute path of the handoff file for a migration step within a run.
+ * 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.
+ */
+export declare function stepHandoffPath(runDir: string, migration: {
+    package: string;
+    name: string;
+}): string;
+export type HandoffReadFailureReason = 'missing' | 'read-error' | 'parse-error' | 'shape-mismatch';
+export type HandoffReadResult = {
+    ok: true;
+    handoff: HandoffFile;
+} | {
+    ok: false;
+    reason: HandoffReadFailureReason;
+    detail?: string;
+};
+/**
+ * Reads and validates a handoff file written by an agent. Returns a tagged
+ * result so callers (the in-loop poller and the post-exit resolver) can
+ * distinguish "file not yet written" from "file written but garbage" — the
+ * latter is surfaced to the user instead of being collapsed into the same
+ * generic ambiguous-outcome prompt.
+ */
+export declare function readHandoffWithReason(filePath: string): HandoffReadResult;
+/**
+ * Convenience wrapper preserving the original null-on-any-failure contract.
+ * Used by the polling loop (`waitForValidHandoff`) where every failure mode
+ * is "keep waiting" — the file may be missing, mid-write, or being rewritten.
+ */
+export declare function readHandoff(filePath: string): HandoffFile | null;
+/**
+ * Polls for a valid handoff file. Resolves once `readHandoff` accepts the
+ * file's contents. Used to detect when the agent has finished its work so the
+ * orchestrator can close the agent's session without depending on the agent
+ * exiting on its own.
+ *
+ * Rejects with the abort reason when `options.signal` is aborted.
+ */
+export declare function waitForValidHandoff(handoffFilePath: string, options?: {
+    intervalMs?: number;
+    signal?: AbortSignal;
+}): Promise<void>;