nx 23.3.0 → 24.0.0-beta.1

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

@@ -8,7 +8,7 @@
 // every file the parent could consult is writable from the sandbox, so the
 // parent's own invocation decides what it installs and commits.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MigrateCommitBroker = exports.TreeBusyError = exports.BrokerUnavailableError = exports.BrokerStaleRequestError = exports.BROKER_ENV_VAR = void 0;
+exports.MigrateCommitBroker = exports.COMMIT_INSTALLS_FIRST = exports.TreeBusyError = exports.BrokerUnavailableError = exports.BrokerStaleRequestError = exports.BROKER_ENV_VAR = void 0;
 exports.acquireTreeOperation = acquireTreeOperation;
 exports.releaseTreeOperation = releaseTreeOperation;
 exports.liveTreeOperation = liveTreeOperation;
@@ -19,16 +19,21 @@ exports.commitStepTree = commitStepTree;
 exports.installStepTree = installStepTree;
 exports.resetStepTree = resetStepTree;
 exports.giveUpStepTree = giveUpStepTree;
+exports.commitsStep = commitsStep;
+exports.sessionOperationWayOut = sessionOperationWayOut;
+exports.formatElapsed = formatElapsed;
 const crypto_1 = require("crypto");
 const fs_1 = require("fs");
 const path_1 = require("path");
 const native_1 = require("../../../native");
 const fileutils_1 = require("../../../utils/fileutils");
 const json_1 = require("../../../utils/json");
+const pretty_time_1 = require("../../../tasks-runner/life-cycles/pretty-time");
 const handoff_1 = require("../agentic/handoff");
 const deferred_output_1 = require("../deferred-output");
 const execute_migration_1 = require("../execute-migration");
 const migrate_commits_1 = require("../migrate-commits");
+const agent_output_1 = require("./agent-output");
 const atomic_write_1 = require("./atomic-write");
 const give_up_1 = require("./give-up");
 const run_state_1 = require("./run-state");
@@ -40,6 +45,9 @@ const util_1 = require("./util");
 exports.BROKER_ENV_VAR = 'NX_MIGRATE_BROKER';
 const BROKER_DIR_NAME = 'broker';
 const CHILD_POLL_INTERVAL_MS = 250;
+// The runbook's "Long-running commands" section states both intervals.
+const FIRST_WAITING_LINE_MS = 15_000;
+const WAITING_LINE_INTERVAL_MS = 60_000;
 /** The request no longer matches the step: another attempt owns it. */
 class BrokerStaleRequestError extends Error {
 }
@@ -74,7 +82,7 @@ function acquireTreeOperation(dir, request, owner = (0, crypto_1.randomBytes)(4)
         if (held)
             throw new TreeBusyError(treeBusyMessage(held));
         marks =
-            (request.kind === 'commit' || request.kind === 'give-up') &&
+            commitsStep(request.kind) &&
                 fresh.steps.find((s) => s.id === request.stepId)?.commitStarted !== true;
         return {
             ...(marks ? (0, state_machine_1.markCommitStarted)(fresh, request.stepId) : fresh),
@@ -113,22 +121,22 @@ function liveTreeOperation(state, owner) {
         return undefined;
     return held;
 }
-function treeBusyMessage(held) {
-    return `The working tree is held by process ${held.pid} for ${treeOperationLabel(held)}; run the reconcile again once it finishes.`;
+function treeBusyMessage(held, stepName) {
+    return `The working tree is held by process ${held.pid} for ${treeOperationLabel(held, stepName)}; run the reconcile again once it finishes.`;
 }
-function treeOperationLabel(held) {
+function treeOperationLabel(held, stepName = `step '${held.stepId}'`) {
     switch (held.kind) {
         case 'checkpoint':
             return 'the checkpoint commit';
         case 'commit':
         case 'give-up':
-            return `the commit of step '${held.stepId}'`;
+            return `the commit of ${stepName}`;
         case 'reset':
-            return `the reset of step '${held.stepId}'`;
+            return `the reset of ${stepName}`;
         case 'install':
         case 'fold-install':
         case 'action-install':
-            return `the install of step '${held.stepId}'`;
+            return `the install of ${stepName}`;
         default: {
             const exhaustive = held.kind;
             throw new Error(`Unhandled tree operation '${exhaustive}'.`);
@@ -204,7 +212,7 @@ async function commitStepTree(dir, step, absorbedStepIds, commitInProcess, scope
             lease.markedStepId = undefined;
         return { result, absorbedStepIds, recorded: false };
     }
-    const answer = await ask(dir, nonce, request);
+    const answer = await ask(dir, nonce, request, (0, state_machine_1.stepLabel)(step));
     if (answer.kind !== 'commit') {
         throw new Error(`Unexpected '${answer.kind}' answer to a commit request.`);
     }
@@ -229,7 +237,7 @@ async function installStepTree(dir, step, seam, installInProcess, scope) {
         scope.lease = acquireTreeOperation(dir, request);
         return installInProcess();
     }
-    const answer = await ask(dir, nonce, request);
+    const answer = await ask(dir, nonce, request, (0, state_machine_1.stepLabel)(step));
     if (answer.kind !== 'installed') {
         throw new Error(`Unexpected '${answer.kind}' answer to an install request.`);
     }
@@ -251,7 +259,7 @@ async function resetStepTree(dir, step, resetInProcess, scope) {
         scope.lease = acquireTreeOperation(dir, request);
         return resetInProcess();
     }
-    const answer = await ask(dir, nonce, request);
+    const answer = await ask(dir, nonce, request, (0, state_machine_1.stepLabel)(step));
     if (answer.kind !== 'reset') {
         throw new Error(`Unexpected '${answer.kind}' answer to a reset request.`);
     }
@@ -280,13 +288,13 @@ async function giveUpStepTree(root, dir, step, skipInstall, reconcileCommand, sc
             reconcileCommand,
         });
     }
-    const answer = await ask(dir, nonce, request);
+    const answer = await ask(dir, nonce, request, (0, state_machine_1.stepLabel)(step));
     if (answer.kind !== 'give-up') {
         throw new Error(`Unexpected '${answer.kind}' answer to a give-up request.`);
     }
     return answer.outcome;
 }
-async function ask(dir, nonce, request) {
+async function ask(dir, nonce, request, stepName) {
     const id = `${nonce}-${request.stepId}-${request.attempt}-${request.kind}${request.invocation ? `-${request.invocation}` : ''}${request.commitAs !== undefined ? `-${request.commitAs}` : ''}`;
     const path = resultPath(dir, id);
     // A repeat reads the first answer, whatever became of the session since.
@@ -313,6 +321,8 @@ async function ask(dir, nonce, request) {
     catch (e) {
         throw notAccepting(e);
     }
+    const askedAt = Date.now();
+    let nextWaitingLineAt = askedAt + FIRST_WAITING_LINE_MS;
     for (;;) {
         if ((0, fs_1.existsSync)(path)) {
             return settle((0, fileutils_1.readJsonFile)(path));
@@ -323,9 +333,49 @@ async function ask(dir, nonce, request) {
                 continue;
             throw new BrokerUnavailableError(`The nx migrate session that started this step ended before its request was answered. The install or the commit may still have landed; check the working tree and git log.`);
         }
+        if (Date.now() >= nextWaitingLineAt) {
+            nextWaitingLineAt = Date.now() + WAITING_LINE_INTERVAL_MS;
+            (0, agent_output_1.logLineToAgent)(waitingLine(request, stepName, Date.now() - askedAt));
+        }
         await new Promise((resolve) => setTimeout(resolve, CHILD_POLL_INTERVAL_MS));
     }
 }
+function waitingLine(request, stepName, waitedMs) {
+    return [
+        `[nx] Waiting for the nx process that started this session to finish ${treeOperationLabel(request, stepName)} (${formatElapsed(waitedMs)} so far).`,
+        ...(commitsStep(request.kind)
+            ? [
+                exports.COMMIT_INSTALLS_FIRST,
+                'A signing popup or a security key can also hold a commit until the user answers it.',
+            ]
+            : []),
+        `If it seems stuck, the user can ${sessionOperationWayOut('it')}.`,
+    ].join(' ');
+}
+exports.COMMIT_INSTALLS_FIRST = 'A commit first installs any dependency changes.';
+function commitsStep(kind) {
+    switch (kind) {
+        case 'commit':
+        case 'give-up':
+            return true;
+        case 'checkpoint':
+        case 'install':
+        case 'fold-install':
+        case 'action-install':
+        case 'reset':
+            return false;
+        default: {
+            const exhaustive = kind;
+            throw new Error(`Unhandled tree operation '${exhaustive}'.`);
+        }
+    }
+}
+function sessionOperationWayOut(operation) {
+    return `quit this session, then press Ctrl+C in the terminal to end ${operation}, and resume the run afterwards`;
+}
+function formatElapsed(ms) {
+    return (0, pretty_time_1.prettyTime)(Math.max(0, Math.round(ms)) * 1e6, 's');
+}
 function notAccepting(e) {
     return new BrokerUnavailableError(`The nx migrate session that started this step is not accepting its request (${e instanceof Error ? e.message : String(e)}).`);
 }
@@ -387,7 +437,7 @@ class MigrateCommitBroker {
         this.lock = native_1.IS_WASM ? null : new native_1.FileLock(lockPath(dir, this.nonce));
         this.lock?.lock();
     }
-    /** The request whose operation this process is running right now. */
+    /** The request whose operation this process is running right now, and since when. */
     get requestInFlight() {
         return this.inFlight;
     }
@@ -423,8 +473,6 @@ class MigrateCommitBroker {
             this.handled.add(id);
             let result;
             try {
-                if (lease)
-                    this.inFlight = request;
                 result = lease ? await this.answer(request, lease) : { kind: 'stale' };
                 // Recorded by the process that ran the commit, before the answer: the
                 // step reading it can die with the commit already in history. A failed
@@ -466,13 +514,13 @@ class MigrateCommitBroker {
         const step = state.steps.find((s) => s.id === request.stepId);
         if (!Object.hasOwn(SEAM_STATUSES, request.kind) ||
             !isAtSeam(step, request) ||
-            ((request.kind === 'commit' ||
-                request.kind === 'reset' ||
-                request.kind === 'give-up') &&
+            ((commitsStep(request.kind) || request.kind === 'reset') &&
                 !this.policy.createCommits) ||
             (request.commitAs !== undefined && request.commitAs !== 'adopt')) {
             return { kind: 'stale' };
         }
+        const stepName = (0, state_machine_1.stepLabel)(step);
+        this.inFlight = { request, startedAt: Date.now(), stepName };
         if (request.kind === 'give-up') {
             const output = new deferred_output_1.DeferredOutputCollector();
             const outcome = await (0, give_up_1.giveUpWithCommit)({
@@ -540,7 +588,7 @@ class MigrateCommitBroker {
             };
         }
     }
-    /** Releases the lock; call after the last `service` settled. */
+    /** Releases the lock; call after the last `service` settled, or once giving up on it. */
     close() {
         this.lock?.unlock();
         // A reservation this session still holds would only expire with its pid.

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

@@ -1,12 +1,13 @@
-export { CURRENT_RUN_STATE_FORMAT_VERSION, NewerRunStateFormatError, migrateRunsDir, runDir, runHandoffsDir, readRunState, writeRunState, findActiveRun, createRun, } from './run-state';
+export { CURRENT_RUN_STATE_FORMAT_VERSION, NewerRunStateFormatError, migrateRunsDir, runDir, runHandoffsDir, readRunState, writeRunState, findActiveRun, createRun, TERMINAL_STEP_STATUSES, } from './run-state';
 export type { MigrateRunStatus, MigrateRunRound, MigrateStepStatus, PromptOutcomeStatus, MigrateStepAwaitingKind, MigrateStepOutcome, MigrateStepPromptOutcome, MigrateStep, MigrateCommitKind, MigrateCommitLedgerEntry, MigrateIssueDisposition, MigrateRunIssue, MigrateRunAnalytics, MigrateRunNoProgress, MigrateRunPolicy, MigrateRunState, } from './run-state';
-export { applyStepEvent, completionSummaryLines, hasPendingCommitDebt, latestRound, runTallies, tallySteps, } from './state-machine';
+export { applyStepEvent, completionSummaryLines, hasPendingCommitDebt, latestRound, runTallies, stepLabel, tallySteps, } from './state-machine';
 export { hasUnresolvedIssues } from './issues';
 export type { StepAction, StepEvent, ApplyStepEventResult, } from './state-machine';
 export { createRunId } from './run-id';
+export { pmInstallCommand } from './util';
 export { runSingleMigrationWorker } from './worker';
 export type { RunSingleMigrationWorkerInput } from './worker';
 export { activeRunToReplace, completionWarnings, holdRunToContinue, releaseRunToHandOff, runOrchestratorInit, runOrchestratorReconcile, runOrchestratorResume, } from './orchestrator';
 export type { OrchestratorInitResult, RunOrchestratorInitInput, RunOrchestratorReconcileInput, } from './orchestrator';
 export { renderContinueCommand, renderExistingRunCommands, renderExistingRunReport, } from './existing-run-report';
-export { BROKER_ENV_VAR, MigrateCommitBroker, treeOperationLabel, } from './broker';
+export { BROKER_ENV_VAR, COMMIT_INSTALLS_FIRST, formatElapsed, MigrateCommitBroker, commitsStep, treeOperationLabel, } from './broker';

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.treeOperationLabel = exports.MigrateCommitBroker = exports.BROKER_ENV_VAR = exports.renderExistingRunReport = exports.renderExistingRunCommands = exports.renderContinueCommand = exports.runOrchestratorResume = exports.runOrchestratorReconcile = exports.runOrchestratorInit = exports.releaseRunToHandOff = exports.holdRunToContinue = exports.completionWarnings = exports.activeRunToReplace = exports.runSingleMigrationWorker = exports.createRunId = exports.hasUnresolvedIssues = exports.tallySteps = exports.runTallies = exports.latestRound = exports.hasPendingCommitDebt = exports.completionSummaryLines = exports.applyStepEvent = exports.createRun = exports.findActiveRun = exports.writeRunState = exports.readRunState = exports.runHandoffsDir = exports.runDir = exports.migrateRunsDir = exports.NewerRunStateFormatError = exports.CURRENT_RUN_STATE_FORMAT_VERSION = void 0;
+exports.treeOperationLabel = exports.commitsStep = exports.MigrateCommitBroker = exports.formatElapsed = exports.COMMIT_INSTALLS_FIRST = exports.BROKER_ENV_VAR = exports.renderExistingRunReport = exports.renderExistingRunCommands = exports.renderContinueCommand = exports.runOrchestratorResume = exports.runOrchestratorReconcile = exports.runOrchestratorInit = exports.releaseRunToHandOff = exports.holdRunToContinue = exports.completionWarnings = exports.activeRunToReplace = exports.runSingleMigrationWorker = exports.pmInstallCommand = exports.createRunId = exports.hasUnresolvedIssues = exports.tallySteps = exports.stepLabel = exports.runTallies = exports.latestRound = exports.hasPendingCommitDebt = exports.completionSummaryLines = exports.applyStepEvent = exports.TERMINAL_STEP_STATUSES = exports.createRun = exports.findActiveRun = exports.writeRunState = exports.readRunState = exports.runHandoffsDir = exports.runDir = exports.migrateRunsDir = exports.NewerRunStateFormatError = exports.CURRENT_RUN_STATE_FORMAT_VERSION = void 0;
 var run_state_1 = require("./run-state");
 Object.defineProperty(exports, "CURRENT_RUN_STATE_FORMAT_VERSION", { enumerable: true, get: function () { return run_state_1.CURRENT_RUN_STATE_FORMAT_VERSION; } });
 Object.defineProperty(exports, "NewerRunStateFormatError", { enumerable: true, get: function () { return run_state_1.NewerRunStateFormatError; } });
@@ -11,17 +11,21 @@ Object.defineProperty(exports, "readRunState", { enumerable: true, get: function
 Object.defineProperty(exports, "writeRunState", { enumerable: true, get: function () { return run_state_1.writeRunState; } });
 Object.defineProperty(exports, "findActiveRun", { enumerable: true, get: function () { return run_state_1.findActiveRun; } });
 Object.defineProperty(exports, "createRun", { enumerable: true, get: function () { return run_state_1.createRun; } });
+Object.defineProperty(exports, "TERMINAL_STEP_STATUSES", { enumerable: true, get: function () { return run_state_1.TERMINAL_STEP_STATUSES; } });
 var state_machine_1 = require("./state-machine");
 Object.defineProperty(exports, "applyStepEvent", { enumerable: true, get: function () { return state_machine_1.applyStepEvent; } });
 Object.defineProperty(exports, "completionSummaryLines", { enumerable: true, get: function () { return state_machine_1.completionSummaryLines; } });
 Object.defineProperty(exports, "hasPendingCommitDebt", { enumerable: true, get: function () { return state_machine_1.hasPendingCommitDebt; } });
 Object.defineProperty(exports, "latestRound", { enumerable: true, get: function () { return state_machine_1.latestRound; } });
 Object.defineProperty(exports, "runTallies", { enumerable: true, get: function () { return state_machine_1.runTallies; } });
+Object.defineProperty(exports, "stepLabel", { enumerable: true, get: function () { return state_machine_1.stepLabel; } });
 Object.defineProperty(exports, "tallySteps", { enumerable: true, get: function () { return state_machine_1.tallySteps; } });
 var issues_1 = require("./issues");
 Object.defineProperty(exports, "hasUnresolvedIssues", { enumerable: true, get: function () { return issues_1.hasUnresolvedIssues; } });
 var run_id_1 = require("./run-id");
 Object.defineProperty(exports, "createRunId", { enumerable: true, get: function () { return run_id_1.createRunId; } });
+var util_1 = require("./util");
+Object.defineProperty(exports, "pmInstallCommand", { enumerable: true, get: function () { return util_1.pmInstallCommand; } });
 var worker_1 = require("./worker");
 Object.defineProperty(exports, "runSingleMigrationWorker", { enumerable: true, get: function () { return worker_1.runSingleMigrationWorker; } });
 var orchestrator_1 = require("./orchestrator");
@@ -38,5 +42,8 @@ Object.defineProperty(exports, "renderExistingRunCommands", { enumerable: true,
 Object.defineProperty(exports, "renderExistingRunReport", { enumerable: true, get: function () { return existing_run_report_1.renderExistingRunReport; } });
 var broker_1 = require("./broker");
 Object.defineProperty(exports, "BROKER_ENV_VAR", { enumerable: true, get: function () { return broker_1.BROKER_ENV_VAR; } });
+Object.defineProperty(exports, "COMMIT_INSTALLS_FIRST", { enumerable: true, get: function () { return broker_1.COMMIT_INSTALLS_FIRST; } });
+Object.defineProperty(exports, "formatElapsed", { enumerable: true, get: function () { return broker_1.formatElapsed; } });
 Object.defineProperty(exports, "MigrateCommitBroker", { enumerable: true, get: function () { return broker_1.MigrateCommitBroker; } });
+Object.defineProperty(exports, "commitsStep", { enumerable: true, get: function () { return broker_1.commitsStep; } });
 Object.defineProperty(exports, "treeOperationLabel", { enumerable: true, get: function () { return broker_1.treeOperationLabel; } });

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

@@ -776,6 +776,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 +788,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 +866,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 +1139,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 +1332,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 +1649,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 +1660,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 +1700,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 +1819,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 +1854,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 +1884,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 +2128,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/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/nx-cloud/connect/connect-to-nx-cloud.js

@@ -155,23 +155,28 @@ async function runConnectToNxCloud(options, command) {
         installationSource: command ?? installationSource,
     });
     const connectCloudUrl = await (0, url_shorten_1.createNxCloudOnboardingURL)('nx-connect', token, undefined, options?.generateToken === true);
+    const manualConnectNote = {
+        title: `Your Nx Cloud workspace is ready.`,
+        bodyLines: [
+            `To claim it, connect it to your Nx Cloud account:`,
+            `- Go to the following URL to connect your workspace to Nx Cloud:`,
+            '',
+            `${connectCloudUrl}`,
+        ],
+    };
     try {
         const cloudConnectSpinner = ora(`Opening Nx Cloud ${connectCloudUrl} in your browser to connect your workspace.`).start();
         await sleep(2000);
-        const { default: open } = await new Function('return import("open")')();
-        await open(connectCloudUrl);
-        cloudConnectSpinner.succeed();
+        if ((0, native_1.openUrl)(connectCloudUrl)) {
+            cloudConnectSpinner.succeed();
+        }
+        else {
+            cloudConnectSpinner.fail();
+            output_1.output.note(manualConnectNote);
+        }
     }
     catch (e) {
-        output_1.output.note({
-            title: `Your Nx Cloud workspace is ready.`,
-            bodyLines: [
-                `To claim it, connect it to your Nx Cloud account:`,
-                `- Go to the following URL to connect your workspace to Nx Cloud:`,
-                '',
-                `${connectCloudUrl}`,
-            ],
-        });
+        output_1.output.note(manualConnectNote);
     }
     return true;
 }

package/dist/src/command-line/release/utils/remote-release-clients/github.js

@@ -5,6 +5,7 @@ const tslib_1 = require("tslib");
 const pc = tslib_1.__importStar(require("picocolors"));
 const prompt_helpers_1 = require("../../../../utils/prompt-helpers");
 const node_child_process_1 = require("node:child_process");
+const native_1 = require("../../../../native");
 const node_fs_1 = require("node:fs");
 const node_os_1 = require("node:os");
 const output_1 = require("../../../../utils/output");
@@ -238,18 +239,16 @@ class GithubRemoteReleaseClient extends remote_release_client_1.RemoteReleaseCli
         if (!shouldContinueInGitHub) {
             return;
         }
-        const { default: open } = await new Function('return import("open")')();
-        await open(result.url)
-            .then(() => {
+        if ((0, native_1.openUrl)(result.url)) {
             console.info(`\nFollow up in the browser to manually create the release:\n\n` +
                 pc.underline(pc.cyan(result.url)) +
                 `\n`);
-        })
-            .catch(() => {
+        }
+        else {
             console.info(`Open this link to manually create a release: \n` +
                 pc.underline(pc.cyan(result.url)) +
                 '\n');
-        });
+        }
     }
     async promptForContinueInGitHub() {
         try {

package/dist/src/command-line/release/utils/remote-release-clients/gitlab.js

@@ -5,6 +5,7 @@ const tslib_1 = require("tslib");
 const pc = tslib_1.__importStar(require("picocolors"));
 const prompt_helpers_1 = require("../../../../utils/prompt-helpers");
 const node_child_process_1 = require("node:child_process");
+const native_1 = require("../../../../native");
 const output_1 = require("../../../../utils/output");
 const extract_repo_slug_1 = require("./extract-repo-slug");
 const remote_release_client_1 = require("./remote-release-client");
@@ -157,18 +158,16 @@ class GitLabRemoteReleaseClient extends remote_release_client_1.RemoteReleaseCli
         if (!shouldContinueInGitLab) {
             return;
         }
-        const { default: open } = await new Function('return import("open")')();
-        await open(result.url)
-            .then(() => {
+        if ((0, native_1.openUrl)(result.url)) {
             console.info(`\nFollow up in the browser to manually create the release:\n\n` +
                 pc.underline(pc.cyan(result.url)) +
                 `\n`);
-        })
-            .catch(() => {
+        }
+        else {
             console.info(`Open this link to manually create a release: \n` +
                 pc.underline(pc.cyan(result.url)) +
                 '\n');
-        });
+        }
     }
     async promptForContinueInGitLab() {
         try {