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

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

@@ -5,6 +5,9 @@ exports.runOrchestratorResume = runOrchestratorResume;
 exports.holdRunToContinue = holdRunToContinue;
 exports.activeRunToReplace = activeRunToReplace;
 exports.releaseRunToHandOff = releaseRunToHandOff;
+exports.activeRunForClassic = activeRunForClassic;
+exports.checkRunForStartFresh = checkRunForStartFresh;
+exports.deleteRunForStartFresh = deleteRunForStartFresh;
 exports.runOrchestratorReconcile = runOrchestratorReconcile;
 exports.completionWarnings = completionWarnings;
 const child_process_1 = require("child_process");
@@ -42,7 +45,7 @@ const issues_1 = require("./issues");
 const runbook_1 = require("./runbook");
 const existing_run_report_1 = require("./existing-run-report");
 const package_manager_1 = require("../../../utils/package-manager");
-// The dark migrate orchestrator: drives a durable run one dispense at a time.
+// The migrate orchestrator: drives a durable run one dispense at a time.
 // An outer AI agent runs each dispensed command and re-invokes `nx migrate
 // --run-id=<id>` to reconcile; there is no long-lived process.
 const PLAN_SNAPSHOT_0 = 'plan-0.json';
@@ -55,7 +58,11 @@ const HANG_THRESHOLD_MS = 15 * 60 * 1000;
 const NO_PROGRESS_THRESHOLD = 3;
 // Two rearms per step: one for the diagnosed fix and one for its correction.
 const REARM_ESCALATION_CAP = 2;
-const INIT_CONTINUE_HINT = 're-run the command, or unset NX_MIGRATE_ORCHESTRATOR to use the standard migrate flow.';
+const INIT_CONTINUE_HINT = 're-run the command, or re-run it with --agentic=false to use the standard migrate flow.';
+const ID_PROBLEM_REFUSALS = {
+    'not-shell-safe': 'contains characters that are not shell-safe. Orchestrated runs require shell-safe migration ids.',
+    duplicate: 'is listed more than once in the plan. Orchestrated runs require each migration id once.',
+};
 function continueRunHint(runId) {
     return `re-run the command to continue run '${runId}'.`;
 }
@@ -92,9 +99,7 @@ function refuseUnsafeScratchExposure(exposure, thenWhat) {
 async function runOrchestratorInit(input) {
     const { root, migrationsJson, migrationsPath, createCommits, commitPrefix, skipInstall, installedNxVersion, validate, finalValidation, emitAgentInstructions = true, onExistingRun = 'report', replaceRunId, confirmStart, } = input;
     const migrations = (migrationsJson.migrations ?? []);
-    const sorted = (0, sort_migrations_1.sortMigrations)(migrations.slice(), {
-        hoistHandoffGitignore: true,
-    });
+    const sorted = (0, sort_migrations_1.sortMigrations)(migrations.slice());
     const plannedIds = sorted.map((m) => `${m.package}:${m.name}`);
     // An active run means a prior init already happened (e.g. it crashed before
     // the agent's first reconcile); starting a second run would compete with it,
@@ -124,13 +129,13 @@ async function runOrchestratorInit(input) {
             }
         });
     }
-    // Dispensed commands interpolate migration ids verbatim, so every init
-    // validates the incoming plan's ids. Before the delete below: a run must
-    // not be thrown away for a plan that cannot start.
-    for (const id of plannedIds) {
-        if (!run_state_1.SHELL_SAFE_VALUE.test(id)) {
-            throw new Error(`The migration id '${id}' contains characters that are not shell-safe. Orchestrated runs require shell-safe migration ids.`);
-        }
+    // Dispensed commands interpolate migration ids verbatim and a worker finds
+    // its step by id, so every init validates the incoming plan's ids. Before
+    // the delete below: a run must not be thrown away for a plan that cannot
+    // start.
+    const [idProblem] = (0, run_state_1.migrationIdProblems)(sorted);
+    if (idProblem !== undefined) {
+        throw new Error(`The migration id '${idProblem.id}' ${ID_PROBLEM_REFUSALS[idProblem.problem]} To run the plan without orchestration, re-run with --agentic=false.`);
     }
     if (confirmStart && !(await confirmStart())) {
         return { kind: 'refused' };
@@ -152,9 +157,8 @@ async function runOrchestratorInit(input) {
     // Applied before the checkpoint so the entry (when it can be added) already
     // covers older scratch by the time the checkpoint's `git add -A` runs; the
     // fallback's standalone commit is suppressed because that checkpoint
-    // carries the edit. Unlike the classic loop, a planned ignore migration
-    // can't be deferred to: the run dir is created below, before that
-    // migration runs.
+    // carries the edit. A planned ignore migration can't be deferred to: the
+    // run dir is created below, before that migration runs.
     await (0, handoff_gitignore_1.applyAgenticHandoffGitignoreFallback)({
         migrations: sorted,
         installedNxVersion,
@@ -314,11 +318,65 @@ function activeRunToReplace(root, runId) {
 function releaseRunToHandOff(root, runId) {
     (0, state_lock_1.releaseRunActivity)((0, run_state_1.runDir)(root, runId));
 }
+/**
+ * The active run a classic `--run-migrations` must not run over, held while
+ * the caller reports it or asks what to do; null when no run is active. Run
+ * directories that cannot be read refuse as they do for init.
+ */
+function activeRunForClassic(root, plannedIds) {
+    const active = findActiveRunForInit(root);
+    if (!active)
+        return null;
+    // Held before the facts are read, as init's report does.
+    (0, state_lock_1.holdRunActivity)(root, active.runId);
+    return {
+        runId: active.runId,
+        facts: (0, existing_run_report_1.collectExistingRunFacts)(root, active.runId, active.state, plannedIds),
+    };
+}
+/**
+ * Throws when a classic start fresh could not delete the active run `runId`.
+ * Run before the commit prompt, as init does, so the user is not asked for a
+ * run that is then refused; deleteRunForStartFresh repeats the checks.
+ */
+function checkRunForStartFresh(root, runId) {
+    (0, state_lock_1.withRunCreationLock)(root, () => {
+        const active = activeRunToDelete(root, runId);
+        refuseUndeletableRun(root, runId, active.state);
+    });
+}
+/**
+ * Deletes the record of the active run `runId` for a classic start fresh,
+ * under the refusals init applies before it replaces a run. The classic loop
+ * records no run of its own afterwards.
+ */
+function deleteRunForStartFresh(root, runId) {
+    const deleted = (0, state_lock_1.withRunCreationLock)(root, () => {
+        activeRunToDelete(root, runId);
+        return deleteRunRecord(root, runId);
+    });
+    if (deleted) {
+        removeDeletedRunDir(root, runId);
+    }
+}
+// Call under the creation lock. A run that became active since the user chose
+// is refused, never deleted in place of the one they saw.
+function activeRunToDelete(root, runId) {
+    refuseLiveReservation(root);
+    const active = findActiveRunForInit(root, true);
+    if (!active) {
+        throw new Error(noActiveRunToReplace(runId));
+    }
+    if (active.runId !== runId) {
+        throw new Error(`Not starting fresh: migrate run '${active.runId}' became active while this command was starting. Re-run the command to see it.`);
+    }
+    return active;
+}
 // Reads the newest active run; null when no run is active. Uninterpretable
 // run dirs refuse a fresh start (one of them could be an active run this
-// init would compete with) but only warn when a healthy active run is found,
-// unless `refuseUninterpretable`: a start-fresh would delete that run and
-// then find only the unreadable ones. NewerRunStateFormatError propagates
+// invocation would compete with) but only warn when a healthy active run is
+// found, unless `refuseUninterpretable`: a start-fresh would delete that run
+// and then find only the unreadable ones. NewerRunStateFormatError propagates
 // from the read.
 function findActiveRunForInit(root, refuseUninterpretable = false) {
     const { active, uninterpretable } = (0, run_state_1.findActiveRun)(root);
@@ -331,7 +389,7 @@ function findActiveRunForInit(root, refuseUninterpretable = false) {
         const details = uninterpretable.map((u) => `${types_1.MIGRATE_RUNS_RELATIVE_DIR}/${(0, text_1.singleLine)(u.dirName)}: ${(0, text_1.singleLine)(u.reason)}`);
         if (!active || refuseUninterpretable) {
             throw new Error([
-                `Whether a migrate run is still active could not be determined; starting a new run could re-apply migrations an unfinished run already applied.`,
+                `Whether a migrate run is still active could not be determined; running the plan could re-apply migrations an unfinished run already applied.`,
                 ...details,
                 `Fix or remove the listed ${noun}, then re-run the command.`,
             ].join('\n'));
@@ -776,6 +834,8 @@ async function runOrchestratorReconcile(input) {
                     return;
                 }
                 (0, give_up_1.warnAboutGiveUp)(target, outcome);
+                if (target.installFailed === true)
+                    warnInstallLeftToUser(root, target);
                 // Settled already; the dispense refuses a tree still held.
                 scope.lease?.release();
                 scope.lease = undefined;
@@ -786,8 +846,9 @@ async function runOrchestratorReconcile(input) {
             // sections stay synchronous); the transition and any unrecorded entry then
             // land in one write. Adopt and skip keep the tree, so the install they owe
             // runs here: the next dispense would take the changed deps as its baseline.
-            // Giving up keeps it the same way when the run does not commit. Retries
-            // owe nothing: the rearmed attempt reconciles itself.
+            // Giving up keeps it the same way when the run does not commit. An install
+            // that already failed is left to the step's mark instead. Retries owe
+            // nothing: the rearmed attempt reconciles itself.
             const { entry, installFailed, recorded } = await stepActionSideEffects(root, dir, state, target, stepAction, result.resetTree, scope);
             // A rearm starts a fresh attempt; drop the stale handoff before the rearm
             // is persisted so a crash in between can't refold the old outcome into the
@@ -863,6 +924,11 @@ async function runOrchestratorReconcile(input) {
             if (unresolvedArchiveError !== undefined) {
                 (0, give_up_1.warnUnresolvedNotArchived)((0, state_machine_1.stepLabel)(target), unresolvedArchiveError);
             }
+            // A retry's rearm drops the mark: its next attempt installs.
+            if (target.installFailed === true &&
+                written.steps.find((s) => s.id === target.id)?.installFailed === true) {
+                warnInstallLeftToUser(root, target);
+            }
             state = written;
         }
         finally {
@@ -1131,6 +1197,14 @@ async function installFailedForStep(root, dir, state, step, seam, scope) {
         return true;
     }
 }
+function warnInstallLeftToUser(root, step) {
+    (0, agent_output_1.warnToAgent)({
+        title: `The dependency changes made by ${(0, state_machine_1.stepLabel)(step)} are not installed.`,
+        bodyLines: [
+            `Run \`${(0, util_1.pmInstallCommand)(root)}\` once the cause of the failed install is fixed. The run's final report repeats this unless a later install covers them.`,
+        ],
+    });
+}
 // A failed handoff fails the prompt; a success handoff completes it, unless it
 // marks the prompt not applicable via `extras.outcome === 'skipped'`.
 function handoffToPromptOutcome(handoff) {
@@ -1316,11 +1390,13 @@ function unresolvedResetsTree(state, step, cleanRetry) {
 async function stepActionSideEffects(root, dir, state, step, action, resetTree, scope) {
     switch (action) {
         case 'adopt':
-            // A died worker's unrecorded commit request is reused. A failed step, or
-            // a recorded commit, needs an adopt request of its own, or the old answer
-            // would be replayed.
+            // A died worker's commit request is reused while nothing records its
+            // outcome, since the session may still answer it. Otherwise the adopt
+            // asks under its own request, or the old answer would be replayed.
             return state.createCommits
                 ? commitForStep(root, dir, state, step, scope, step.status === 'failed' ||
+                    step.commitLedgerIndex !== undefined ||
+                    step.installFailed === true ||
                     (0, state_machine_1.coveringLandedEntries)(state, step.id).length > 0
                     ? 'adopt'
                     : undefined)
@@ -1631,6 +1707,7 @@ function emitRetryFailed(root, runId, state, step, noProgress) {
         `  current HEAD: ${head ?? '(unknown)'}`,
         `  working tree: ${tree === null ? '(unknown)' : tree ? `\n${tree}` : '(clean)'}`,
         ``,
+        ...unfinishedOperationLines(root, state, step),
         retryBudgetLine(step, committed),
         ``,
         `Decide how to proceed and re-run reconcile with one of:`,
@@ -1641,11 +1718,15 @@ function emitRetryFailed(root, runId, state, step, noProgress) {
     if (cleanRetry && !capReached) {
         lines.push(`  retry-clean: reset the tree to ${step.gitRefBefore ?? 'the pre-migration ref'} (discarding its uncommitted tracked changes and the untracked files git does not ignore, ${types_1.MIGRATE_RUNS_RELATIVE_DIR} kept) and retry from that clean state by running: ${reconcileCommand(root, runId, 'retry-clean')}`);
     }
+    // A failed commit is already named above the choices.
+    const adoptWhen = recordedCommitFailed(state, step)
+        ? ''
+        : committed
+            ? `a commit of this ${(0, state_machine_1.stepNoun)(step)}'s changes was started and never recorded; `
+            : `the ${(0, state_machine_1.stepNoun)(step)} was ${step.kind === 'migration' ? 'applied' : 'done'} by hand; `;
     lines.push(landed
         ? `  adopt: keep the landed commit${landed.sha ? ` ${landed.sha}` : ''} and the current working-tree state as the ${(0, state_machine_1.stepNoun)(step)}'s result, then run: ${reconcileCommand(root, runId, 'adopt')}`
-        : `  adopt: ${committed
-            ? `a commit of this ${(0, state_machine_1.stepNoun)(step)}'s changes was started and never recorded`
-            : `the ${(0, state_machine_1.stepNoun)(step)} was ${step.kind === 'migration' ? 'applied' : 'done'} by hand`}; keep the current working-tree state as its result, then run: ${reconcileCommand(root, runId, 'adopt')}`);
+        : `  adopt: ${adoptWhen}keep the current working-tree state as its result, then run: ${reconcileCommand(root, runId, 'adopt')}`);
     // Refused by the state machine: the migration is, or may be, committed.
     if (!committed) {
         lines.push(`  skip:  ${reconcileCommand(root, runId, 'skip')}`, unresolvedOptionLine(root, runId, state, step, unresolvedResetsTree(state, step, cleanRetry)));
@@ -1677,6 +1758,26 @@ function retryBudgetLine(step, committed) {
         ? `adopt only once you have inspected the tree and finished the ${(0, state_machine_1.stepNoun)(step)}; otherwise stop and report`
         : 'give the step up with unresolved and continue'}.`;
 }
+// A recorded failed commit with the mark standing withdraws skip and
+// unresolved, so every choice left commits.
+function unfinishedOperationLines(root, state, step) {
+    const lines = [];
+    if (step.installFailed === true) {
+        lines.push(`Its dependency install did not complete. A retry runs it again, so fix the cause first if it can be fixed. Any other choice settles the step without installing and leaves the install to you; the run's final report asks for \`${(0, util_1.pmInstallCommand)(root)}\`.`, ``);
+    }
+    if (recordedCommitFailed(state, step)) {
+        lines.push(`Its commit did not complete. Every choice below commits again.`, ``);
+    }
+    return lines;
+}
+function recordedCommitFailed(state, step) {
+    // Not commitReceipt, which throws on an index the ledger lacks: a dispense
+    // has to render whatever run.json holds.
+    const receipt = step.commitLedgerIndex === undefined
+        ? undefined
+        : state.commits[step.commitLedgerIndex];
+    return step.commitStarted === true && receipt?.kind === 'failed';
+}
 // Opens a capped dispense and is the reason a retry past the cap is refused.
 function rearmCapLine(step, committed) {
     return `This ${(0, state_machine_1.stepNoun)(step)} has already been retried ${step.attempt - 1} times without completing, and no further retry is accepted. ${committed
@@ -1776,6 +1877,7 @@ function emitDied(root, runId, state, step, noProgress) {
         `  current HEAD: ${head ?? '(unknown)'}`,
         `  working tree: ${tree === null ? '(unknown)' : tree ? `\n${tree}` : '(clean)'}`,
         ``,
+        ...unfinishedOperationLines(root, state, step),
         retryBudgetLine(step, committed),
         ``,
     ];
@@ -1810,9 +1912,19 @@ function emitDied(root, runId, state, step, noProgress) {
     }, noProgress);
 }
 function emitHeld(root, runId, state, step, held, noProgress) {
+    const heldStep = state.steps.find((s) => s.id === held.stepId);
+    const heldStepName = heldStep && (0, state_machine_1.stepLabel)(heldStep);
     emit(root, runId, state, step, 'held', {
         next: reconcileCommand(root, runId),
-        instructionLines: [(0, broker_1.treeBusyMessage)(held)],
+        instructionLines: [
+            (0, broker_1.treeBusyMessage)(held, heldStepName),
+            // Quitting this session frees the terminal only for its own parent.
+            ...(held.owner === process.env[broker_1.BROKER_ENV_VAR]
+                ? [
+                    `If it seems stuck, the user can ${(0, broker_1.sessionOperationWayOut)((0, broker_1.treeOperationLabel)(held, heldStepName))}.`,
+                ]
+                : []),
+        ],
     }, noProgress);
 }
 function emitStillRunning(root, runId, state, step, held, noProgress) {
@@ -1830,7 +1942,7 @@ function emitStillRunning(root, runId, state, step, held, noProgress) {
     if (ageMs >= HANG_THRESHOLD_MS) {
         const hung = `It has been running for ${Math.floor(ageMs / 60000)} minutes and may be hung.`;
         lines.push(parentOperation
-            ? `${hung} Report this to the user: they can quit this session, then press Ctrl+C in the terminal to end ${parentOperation}, and resume the run afterwards.`
+            ? `${hung} Report this to the user: they can ${(0, broker_1.sessionOperationWayOut)(parentOperation)}.`
             : `${hung} Verify pid ${step.pid}; either keep waiting, or kill it so the next reconcile can classify it as died.`);
     }
     emit(root, runId, state, step, 'still-running', {
@@ -2074,14 +2186,19 @@ function completionWarnings(root, runId, state) {
     // fact absorbed; suppress the warning only on a verified-clean tree. A dirty
     // tree can still be unrelated edits, so the warning only claims the changes
     // "may remain".
-    const commitDebt = (0, state_machine_1.hasPendingCommitDebt)(state) && (0, git_utils_1.getWorkingTreeStatus)(root) !== 'clean';
+    const debtStepIds = (0, state_machine_1.uncoveredFailedStepIds)(state);
+    const uncommitted = debtStepIds.length > 0 && (0, git_utils_1.getWorkingTreeStatus)(root) !== 'clean'
+        ? state.steps.filter((s) => debtStepIds.includes(s.id))
+        : [];
     const uninstalled = state.steps.filter((s) => s.installFailed);
     const issueLines = (0, issues_1.renderUnresolvedIssueLines)(state, runId);
     return [
-        ...(commitDebt
+        ...(uncommitted.length > 0
             ? [
                 [
-                    'Some migration changes could not be committed and may remain in the working tree; review and commit them manually.',
+                    `The changes made by ${uncommitted
+                        .map(state_machine_1.stepLabel)
+                        .join(', ')} could not be committed and may remain in the working tree; review and commit them manually.`,
                 ],
             ]
             : []),

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

@@ -9,6 +9,19 @@ export declare const RUN_STATE_FILE_NAME = "run.json";
  * with fails closed as corrupt instead of being dispensed.
  */
 export declare const SHELL_SAFE_VALUE: RegExp;
+export type MigrationIdProblem = 'not-shell-safe' | 'duplicate';
+/**
+ * The ids of `migrations` that no orchestrated run can take, each once, in the
+ * order found. A worker finds its step by migration id, so an id the plan
+ * lists twice can't name one step.
+ */
+export declare function migrationIdProblems(migrations: ReadonlyArray<{
+    package: string;
+    name: string;
+}>): {
+    id: string;
+    problem: MigrationIdProblem;
+}[];
 export declare const ISSUE_ID: RegExp;
 declare const MIGRATE_RUN_STATUSES: readonly ['active', 'completed'];
 export type MigrateRunStatus = (typeof MIGRATE_RUN_STATUSES)[number];

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NewerRunStateFormatError = exports.TREE_OPERATION_KINDS = exports.MIGRATE_ISSUE_DISPOSITIONS = exports.TERMINAL_STEP_STATUSES = exports.ISSUE_ID = exports.SHELL_SAFE_VALUE = exports.RUN_STATE_FILE_NAME = exports.CURRENT_RUN_STATE_FORMAT_VERSION = void 0;
+exports.migrationIdProblems = migrationIdProblems;
 exports.issueFingerprint = issueFingerprint;
 exports.migrateRunsDir = migrateRunsDir;
 exports.runDir = runDir;
@@ -32,6 +33,26 @@ exports.RUN_STATE_FILE_NAME = 'run.json';
  * with fails closed as corrupt instead of being dispensed.
  */
 exports.SHELL_SAFE_VALUE = /^[A-Za-z0-9@/:._-]+$/;
+/**
+ * The ids of `migrations` that no orchestrated run can take, each once, in the
+ * order found. A worker finds its step by migration id, so an id the plan
+ * lists twice can't name one step.
+ */
+function migrationIdProblems(migrations) {
+    const seen = new Set();
+    const problems = new Map();
+    for (const m of migrations) {
+        const id = `${m.package}:${m.name}`;
+        if (!exports.SHELL_SAFE_VALUE.test(id)) {
+            problems.set(id, 'not-shell-safe');
+        }
+        else if (seen.has(id) && !problems.has(id)) {
+            problems.set(id, 'duplicate');
+        }
+        seen.add(id);
+    }
+    return [...problems].map(([id, problem]) => ({ id, problem }));
+}
 // `new Date().toISOString()`, the only shape Nx writes. Retention and active-run
 // selection compare these lexicographically, and the value is rendered into the
 // stdout the agent scans for blocks, so neither a different notation nor an

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

@@ -76,6 +76,25 @@ function renderRunbook(ctx) {
         `already active. Show its report to the user and let them choose between`,
         `the two commands it lists; do not choose for them.`,
         ``,
+        `## Long-running commands`,
+        ``,
+        `A worker or \`next\` command can wait for minutes on a dependency install`,
+        `or a commit. When Nx started this session, the nx process that started it`,
+        `runs them, and the waiting command prints an \`[nx]\` line after 15`,
+        `seconds and then once a minute: what nx is running and for how long.`,
+        ``,
+        `- If your shell tool can run a command in the background, start worker and`,
+        `  \`next\` commands that way and check their output about once a minute.`,
+        `  Each time, tell the user in one sentence what the latest \`[nx]\` line`,
+        `  says.`,
+        `- Claude Code: start each worker and \`next\` command with`,
+        `  \`run_in_background\`, then start a Monitor on its output that passes`,
+        `  \`[nx]\` lines through. A \`next\` command can wait as long as a worker.`,
+        `- Stopping a worker or \`next\` command does not stop the install or the`,
+        `  commit it waits on. If one seems stuck, tell the user they can quit this`,
+        `  session, then press Ctrl+C in the terminal to end it, and resume the run`,
+        `  afterwards.`,
+        ``,
         `## Agent work`,
         ``,
         `Some steps hand work back to you:`,

package/dist/src/command-line/migrate/run/state-machine.js

@@ -231,7 +231,10 @@ function applyStepAction(state, index, step, action) {
     };
 }
 function workerDiedSummary(step) {
-    return `the worker process${step.pid === undefined ? '' : ` (pid ${step.pid})`} died before recording an outcome`;
+    const worker = `the worker process${step.pid === undefined ? '' : ` (pid ${step.pid})`}`;
+    return step.installFailed === true
+        ? `its dependency install did not complete, and ${worker} died`
+        : `${worker} died before recording an outcome`;
 }
 // Re-arms for a retry that resets the tree first. The reset target predates
 // the generator unless a commit of this step's own already carries it, so the

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

@@ -28,6 +28,9 @@ export declare function depsHash(root: string): string | null;
  * dispense-time probe failed has no baseline, which says the dependencies it
  * started from are unknown rather than unchanged, and skipping there would
  * strand the change with nothing left to detect it.
+ *
+ * A failed or died step whose install already failed settles without it, so
+ * the settle cannot hang on that install again. A retry's rearm drops the mark.
  */
 export declare function installDepsChangedSinceDispense(root: string, dir: string, step: MigrateStep, skipInstall: boolean, rerunCommand?: string, sink?: MigrateOutputSink): Promise<void>;
 /**

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

@@ -1,5 +1,4 @@
 "use strict";
-// Internal to run/: deliberately not re-exported from ./index.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.nowIso = nowIso;
 exports.depsHash = depsHash;
@@ -51,8 +50,15 @@ function depsHash(root) {
  * dispense-time probe failed has no baseline, which says the dependencies it
  * started from are unknown rather than unchanged, and skipping there would
  * strand the change with nothing left to detect it.
+ *
+ * A failed or died step whose install already failed settles without it, so
+ * the settle cannot hang on that install again. A retry's rearm drops the mark.
  */
 async function installDepsChangedSinceDispense(root, dir, step, skipInstall, rerunCommand, sink) {
+    if (step.installFailed === true &&
+        (step.status === 'failed' || step.status === 'died')) {
+        return;
+    }
     const current = depsHash(root);
     if (current !== null && current === step.depsHashAtDispense)
         return;

package/dist/src/command-line/migrate/sort-migrations.d.ts

@@ -5,12 +5,6 @@ interface SortableMigration {
 }
 /**
  * Sorts in place (like `Array.prototype.sort`) and returns the same array.
- *
- * `hoistHandoffGitignore` is set for agentic runs, which write scratch under
- * `.nx/migrate-runs`; see `agentic/handoff-gitignore.ts` for why the v23
- * gitignore migration must run first there.
  */
-export declare function sortMigrations<T extends SortableMigration>(migrations: T[], opts: {
-    hoistHandoffGitignore: boolean;
-}): T[];
+export declare function sortMigrations<T extends SortableMigration>(migrations: T[]): T[];
 export {};

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

@@ -2,23 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sortMigrations = sortMigrations;
 const semver_1 = require("semver");
-const types_1 = require("./agentic/types");
 const version_utils_1 = require("./version-utils");
 /**
  * Sorts in place (like `Array.prototype.sort`) and returns the same array.
- *
- * `hoistHandoffGitignore` is set for agentic runs, which write scratch under
- * `.nx/migrate-runs`; see `agentic/handoff-gitignore.ts` for why the v23
- * gitignore migration must run first there.
  */
-function sortMigrations(migrations, opts) {
+function sortMigrations(migrations) {
     return migrations.sort((a, b) => {
-        if (opts.hoistHandoffGitignore) {
-            if ((0, types_1.isHandoffGitignoreMigration)(a))
-                return -1;
-            if ((0, types_1.isHandoffGitignoreMigration)(b))
-                return 1;
-        }
         if (a.name === '15-7-0-split-configuration-into-project-json-files') {
             return -1;
         }

package/dist/src/command-line/show/show-target/info.js

@@ -126,7 +126,7 @@ function resolveTaskGraphDependencies(graph, extraTargetDeps, projectName, targe
         const directDeps = [
             ...(taskGraph.dependencies[rootId] ?? []),
             ...(taskGraph.continuousDependencies[rootId] ?? []),
-        ];
+        ].map((edge) => edge.id);
         const directDepSet = new Set(directDeps);
         const depSourceIndices = directDeps.map((depTaskId) => {
             const task = taskGraph.tasks[depTaskId];

package/dist/src/config/nx-json.d.ts

@@ -711,7 +711,9 @@ export interface NxSyncConfiguration {
 export interface NxMigrateConfiguration {
     /**
      * Whether to automatically create a git commit after each migration runs.
-     * Equivalent to the `--create-commits` flag. Defaults to `false`.
+     * Equivalent to the `--create-commits` flag. Defaults to `true` when the
+     * agentic flow runs the migrations in a Git repository, and `false`
+     * otherwise.
      */
     createCommits?: boolean;
     /**
@@ -753,11 +755,18 @@ export interface NxMigrateConfiguration {
      */
     agentic?: boolean | AgentId;
     /**
-     * Whether to run agent-driven validation after generator-only migrations when
-     * the agentic flow is enabled. Equivalent to the `--validate` flag. Defaults
-     * to `true` when the agentic flow is enabled.
+     * Whether the AI agent driving a migrate run reviews the changes of
+     * generator-only migrations. Equivalent to the `--validate` flag. Defaults to
+     * `true`.
      */
     validate?: boolean;
+    /**
+     * Whether a migrate run an AI agent drives ends with a final check, where the
+     * agent makes sure the projects the run touched still lint, build, and pass
+     * their unit tests. Equivalent to the `--final-validation` flag. Defaults to
+     * `true`.
+     */
+    finalValidation?: boolean;
 }
 /**
  * Nx.json configuration

package/dist/src/config/task-graph.d.ts

@@ -3,4 +3,4 @@
  * `packages/nx/src/native/tasks/types.rs` and exposed to TypeScript via NAPI.
  * This file re-exports them so existing imports keep working.
  */
-export type { Task, TaskGraph, TaskTarget, TaskHashDetails, TaskUltracacheSettings, } from '../native';
+export type { Task, TaskGraph, TaskGraphEdge, TaskTarget, TaskHashDetails, TaskUltracacheSettings, } from '../native';

package/dist/src/config/workspace-json-project-json.d.ts

@@ -163,6 +163,54 @@ export type Spreadable<T> = T & {
  * permits `'...'`, which target merging resolves away.
  */
 export type TargetUltracacheSettings = Spreadable<TaskUltracacheSettings>;
+export interface ReadyWhenOptions {
+    /**
+     * Milliseconds to wait for readiness before failing dependents that wait
+     * for it. Default is 60000.
+     */
+    timeout?: number;
+    /**
+     * Milliseconds between probe attempts. By default attempts back off from
+     * 100 to 1000 milliseconds. Unused by `logMatches`.
+     */
+    interval?: number;
+}
+/**
+ * Readiness probe of a continuous target. Exactly one of `url`, `port`,
+ * `command` or `logMatches` must be set. Strings may use the `{workspaceRoot}`,
+ * `{projectRoot}`, `{projectName}` and `{options.*}` placeholders, resolved
+ * against the options the task runs with.
+ */
+export type ReadyWhen = ({
+    /**
+     * Ready when an HTTP or HTTPS GET gets a status from 200 to 403. A
+     * redirect counts as ready and is not followed.
+     */
+    url: string;
+} & ReadyWhenOptions) | ({
+    /**
+     * Ready when a TCP connection to the port succeeds. A string must
+     * resolve to a port number through a placeholder such as
+     * `{options.port}`.
+     */
+    port: number | string;
+    /**
+     * Host to connect to. By default 127.0.0.1 and ::1 are both tried.
+     */
+    host?: string;
+} & ReadyWhenOptions) | ({
+    /**
+     * Ready when the command, run through the shell at the workspace root,
+     * exits with code 0.
+     */
+    command: string;
+} & ReadyWhenOptions) | ({
+    /**
+     * Ready when every one of these substrings has appeared in the task's
+     * output.
+     */
+    logMatches: string | string[];
+} & ReadyWhenOptions);
 export interface TargetDependencyConfig {
     /**
      * A list of projects that have `target`.
@@ -192,22 +240,40 @@ export interface TargetDependencyConfig {
      * target's hash. It still runs first. Has no effect on other dependencies.
      */
     inputs?: boolean;
+    /**
+     * When the dependency is a continuous task, whether this target waits for
+     * it to have started (default) or to be ready per its `readyWhen`.
+     * Ignored when the dependency is not continuous or declares no `readyWhen`.
+     */
+    waitFor?: 'started' | 'ready';
 }
+/**
+ * `always`: the files the input resolves to stay in the hash even when the task
+ * is hashed from its ultracache recording.
+ * `dependencies` with `projects`: the selected projects' dependencies (as `^input`
+ * resolves for each), not the projects themselves.
+ */
 export type InputDefinition = {
     input: string;
     projects: string | string[];
+    dependencies?: boolean;
+    always?: boolean;
 } | {
     input: string;
     dependencies: true;
+    always?: boolean;
 } | {
     input: string;
+    always?: boolean;
 } | {
     fileset: string;
     includeIgnored?: boolean;
+    always?: boolean;
 } | {
     fileset: string;
     dependencies: true;
     includeIgnored?: boolean;
+    always?: boolean;
 } | {
     runtime: string;
 } | {
@@ -282,6 +348,12 @@ export interface TargetConfiguration<T = any> {
      * Whether this target runs continuously
      */
     continuous?: boolean;
+    /**
+     * How Nx detects that this continuous target is ready. Only honored when
+     * `continuous` is true; dependents opt in with `waitFor: 'ready'` on their
+     * `dependsOn` entry.
+     */
+    readyWhen?: ReadyWhen;
     /**
      * List of generators to run before the target to ensure the workspace
      * is up to date.