@ohos-ports/nx 23.3.0-beta.3 → 24.0.2-beta.0

package/dist/src/command-line/migrate/resolve-package-version.d.ts

@@ -3,10 +3,8 @@
  * than via a real package-manager install. Precedence, highest first:
  *
  * 1. `NX_MIGRATE_USE_REGISTRY_RESOLUTION` ('true' -> enabled, 'false' -> disabled)
- * 2. legacy `NX_MIGRATE_SKIP_REGISTRY_FETCH` (deprecated, removed in Nx 24;
- *    'true' -> disabled, 'false' -> enabled)
- * 3. nx.json `migrate.useRegistryResolution`
- * 4. default: enabled
+ * 2. nx.json `migrate.useRegistryResolution`
+ * 3. default: enabled
  */
 export declare function isRegistryResolutionEnabled(root?: string): boolean;
 /** Test-only: clear the module-level caches between cases. */

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

@@ -21,63 +21,30 @@ const text_1 = require("./text");
  * than via a real package-manager install. Precedence, highest first:
  *
  * 1. `NX_MIGRATE_USE_REGISTRY_RESOLUTION` ('true' -> enabled, 'false' -> disabled)
- * 2. legacy `NX_MIGRATE_SKIP_REGISTRY_FETCH` (deprecated, removed in Nx 24;
- *    'true' -> disabled, 'false' -> enabled)
- * 3. nx.json `migrate.useRegistryResolution`
- * 4. default: enabled
+ * 2. nx.json `migrate.useRegistryResolution`
+ * 3. default: enabled
  */
 function isRegistryResolutionEnabled(root = workspace_root_1.workspaceRoot) {
-    warnIfLegacyRegistryEnvVarSet();
     const explicit = parseBooleanFlag(process.env.NX_MIGRATE_USE_REGISTRY_RESOLUTION);
     if (explicit !== undefined) {
         return explicit;
     }
-    // Legacy env is inverted: SKIP_REGISTRY_FETCH=true disables resolution.
-    const legacy = parseBooleanFlag(process.env.NX_MIGRATE_SKIP_REGISTRY_FETCH);
-    if (legacy !== undefined) {
-        return !legacy;
-    }
     return (0, configuration_1.readNxJson)(root)?.migrate?.useRegistryResolution ?? true;
 }
 function parseBooleanFlag(value) {
     return value === 'true' ? true : value === 'false' ? false : undefined;
 }
-// NX_MIGRATE_SKIP_REGISTRY_FETCH is the inverted, legacy predecessor of
-// NX_MIGRATE_USE_REGISTRY_RESOLUTION: deprecated in Nx 23, removed in Nx 24.
-// Warn once whenever it is present (even when the new var overrides it) so users
-// migrate off it and clean up configs where it lingers - a dormant value would
-// silently re-activate if the new var were later removed.
-function warnIfLegacyRegistryEnvVarSet() {
-    if (legacyRegistryEnvVarDeprecationWarned ||
-        process.env.NX_MIGRATE_SKIP_REGISTRY_FETCH === undefined) {
-        return;
-    }
-    legacyRegistryEnvVarDeprecationWarned = true;
-    const bodyLines = [
-        'Use NX_MIGRATE_USE_REGISTRY_RESOLUTION (or migrate.useRegistryResolution in nx.json) instead, then remove NX_MIGRATE_SKIP_REGISTRY_FETCH from your environment.',
-    ];
-    if (process.env.NX_MIGRATE_USE_REGISTRY_RESOLUTION !== undefined) {
-        bodyLines.push('It is currently being overridden by NX_MIGRATE_USE_REGISTRY_RESOLUTION.');
-    }
-    output_1.output.warn({
-        title: 'NX_MIGRATE_SKIP_REGISTRY_FETCH is deprecated and will be removed in Nx 24.',
-        bodyLines,
-    });
-}
 // The cooldown policy is constant for a migrate run; read it once.
 let cachedPolicyPromise;
 // Dedup the "resolved X instead of Y" notice across repeated specs.
 const reportedChangedOutcomes = new Set();
 // Strict-mode approval is a once-per-run decision (mirrors pnpm prompting once).
 let strictApprovalGranted = false;
-// The deprecated NX_MIGRATE_SKIP_REGISTRY_FETCH heads-up is shown once per run.
-let legacyRegistryEnvVarDeprecationWarned = false;
 /** Test-only: clear the module-level caches between cases. */
 function resetResolvePackageVersionState() {
     cachedPolicyPromise = undefined;
     reportedChangedOutcomes.clear();
     strictApprovalGranted = false;
-    legacyRegistryEnvVarDeprecationWarned = false;
 }
 function getPolicy() {
     cachedPolicyPromise ??= (0, policy_1.readMinReleaseAgePolicy)();

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

@@ -16,6 +16,8 @@ export interface AgentMessage {
 export declare function safeLines(lines: readonly string[]): string[];
 export declare function logToAgent(message: AgentMessage): void;
 export declare function warnToAgent(message: AgentMessage): void;
+export declare function errorToAgent(message: AgentMessage): void;
+export declare function logLineToAgent(line: string): void;
 export declare function emitStepBlock(runId: string, stepId: string, action: string, payload: object): void;
 export declare function emitPromptBlock(migrationId: string, payload: object): void;
 export declare function emitStepPromptBlock(stepId: string, payload: object): void;

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

@@ -13,10 +13,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.safeLines = safeLines;
 exports.logToAgent = logToAgent;
 exports.warnToAgent = warnToAgent;
+exports.errorToAgent = errorToAgent;
+exports.logLineToAgent = logLineToAgent;
 exports.emitStepBlock = emitStepBlock;
 exports.emitPromptBlock = emitPromptBlock;
 exports.emitStepPromptBlock = emitStepPromptBlock;
 exports.emitRunbookBlock = emitRunbookBlock;
+const logger_1 = require("../../../utils/logger");
 const output_1 = require("../../../utils/output");
 const print_dropped_agent_context_1 = require("../agentic/print-dropped-agent-context");
 const text_1 = require("../text");
@@ -40,6 +43,12 @@ function logToAgent(message) {
 function warnToAgent(message) {
     output_1.output.warn(safe(message));
 }
+function errorToAgent(message) {
+    output_1.output.error(safe(message));
+}
+function logLineToAgent(line) {
+    logger_1.logger.info((0, text_1.singleLine)(line));
+}
 /**
  * Serializes a block payload. `<` becomes its JSON unicode escape so a raw one
  * in a value cannot forge the closing tag, and the result stays valid JSON for

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

@@ -91,8 +91,8 @@ export declare function acquireTreeOperation(dir: string, request: TreeOperation
 export declare function releaseTreeOperation(dir: string, owner: string, markedStepId?: string): void;
 /** The reservation a live process other than `owner` holds, if any. */
 export declare function liveTreeOperation(state: MigrateRunState, owner?: string): MigrateTreeOperation | undefined;
-export declare function treeBusyMessage(held: MigrateTreeOperation): string;
-export declare function treeOperationLabel(held: Pick<MigrateTreeOperation, 'kind' | 'stepId'>): string;
+export declare function treeBusyMessage(held: MigrateTreeOperation, stepName?: string): string;
+export declare function treeOperationLabel(held: Pick<MigrateTreeOperation, 'kind' | 'stepId'>, stepName?: string): string;
 export declare function brokerDir(runDirPath: string): string;
 /**
  * Runs the step's install and commit where they can land: in this process
@@ -119,6 +119,15 @@ export declare function resetStepTree(dir: string, step: MigrateStep, resetInPro
  * reservation it runs with, so the caller writes no transition of its own.
  */
 export declare function giveUpStepTree(root: string, dir: string, step: MigrateStep, skipInstall: boolean, reconcileCommand: string, scope: TreeScope): Promise<GiveUpOutcome>;
+export declare const COMMIT_INSTALLS_FIRST = "A commit first installs any dependency changes.";
+export declare function commitsStep(kind: MigrateTreeOperation['kind']): boolean;
+export declare function sessionOperationWayOut(operation: string): string;
+export declare function formatElapsed(ms: number): string;
+export interface InFlightOperation {
+    request: BrokerRequest;
+    startedAt: number;
+    stepName: string;
+}
 /**
  * The parent side. Holds one exclusive lock for the session's lifetime so a
  * waiting step can tell a slow parent from a dead one, answers each request
@@ -138,13 +147,13 @@ export declare class MigrateCommitBroker {
     private inFlight;
     private readonly lock;
     constructor(root: string, dir: string, reconcileCommand: string, policy: MigrateRunPolicy);
-    /** The request whose operation this process is running right now. */
-    get requestInFlight(): BrokerRequest | null;
+    /** The request whose operation this process is running right now, and since when. */
+    get requestInFlight(): InFlightOperation | null;
     /** Answers this session's unanswered requests, one at a time. */
     service(): Promise<void>;
     private record;
     private answer;
-    /** 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(): void;
     private notADirectory;
 }

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)({
@@ -514,7 +562,7 @@ class MigrateCommitBroker {
                 return { kind: 'installed', output: output.render('drop') };
             }
             const absorbedStepIds = (0, state_machine_1.uncoveredFailedStepIds)(state).filter((id) => id !== step.id);
-            const result = await (0, migrate_commits_1.commitMigrationIfRequested)(this.root, { name: (0, state_machine_1.commitNameForStep)(step) }, true, state.commitPrefix, install, (0, state_machine_1.stepsToPendingMigrations)(state, absorbedStepIds), undefined, output);
+            const result = await (0, migrate_commits_1.commitMigrationIfRequested)(this.root, { name: (0, state_machine_1.commitNameForStep)(step) }, true, state.commitPrefix, install, (0, state_machine_1.stepsToPendingMigrations)(state, absorbedStepIds), (0, util_1.commitFailureRecovery)(state), output);
             return {
                 kind: 'commit',
                 result,
@@ -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/clean-retry.js

@@ -4,7 +4,7 @@ exports.canOfferCleanRetry = canOfferCleanRetry;
 exports.cleanRetryUnavailableReason = cleanRetryUnavailableReason;
 exports.resetForCleanRetry = resetForCleanRetry;
 const git_utils_1 = require("../../../utils/git-utils");
-const types_1 = require("../agentic/types");
+const migrate_commits_1 = require("../migrate-commits");
 const agent_output_1 = require("./agent-output");
 const issues_1 = require("./issues");
 const state_lock_1 = require("./state-lock");
@@ -95,5 +95,7 @@ function resetForCleanRetry(root, dir, stepId) {
         return reopened.state;
     });
     archiveReopenedResolutions(dir, prepared, updates, (0, state_machine_1.stepLabel)(step));
-    (0, git_utils_1.resetWorkingTree)(step.gitRefBefore, [types_1.MIGRATE_RUNS_RELATIVE_DIR], root);
+    // Unlike the commit exclusions, every owned path, committed or not: a failed
+    // probe must not let the reset remove the plan or prompt files.
+    (0, git_utils_1.resetWorkingTree)(step.gitRefBefore, migrate_commits_1.MIGRATE_OWNED_PATHS, root);
 }

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

@@ -41,7 +41,7 @@ export interface ExistingRunCommands {
         migrationsPath: string;
     };
 }
-export declare function renderExistingRunCommands(root: string, facts: ExistingRunFacts, migrationsPath: string | undefined, agentId?: string): ExistingRunCommands;
+export declare function renderExistingRunCommands(root: string, facts: ExistingRunFacts, migrationsPath: string | undefined, agentic?: string | false): ExistingRunCommands;
 /**
  * Title plus body lines, in the shape the agent-output writers take. Every
  * body line goes through `singleLine`: branch names and timestamps came from

package/dist/src/command-line/migrate/run/existing-run-report.js

@@ -108,16 +108,18 @@ function otherActiveRuns(root, runId) {
 function renderContinueCommand(root, runId, policy, agentId) {
     return `${(0, util_1.pmExecPrefix)(root)} nx migrate --run-migrations --agentic${agentId === undefined ? '' : `=${agentId}`} --run-id=${runId} ${policy.createCommits ? '--create-commits' : '--no-create-commits'}${policy.skipInstall ? ' --skip-install' : ''}`;
 }
-function renderExistingRunCommands(root, facts, migrationsPath, agentId) {
+// `agentic` echoes the invocation's choice into the start-fresh command; the
+// continue command needs an agent, so it takes only an agent id.
+function renderExistingRunCommands(root, facts, migrationsPath, agentic) {
     const flag = migrationsPath === undefined
         ? '--run-migrations'
         : (0, util_1.runMigrationsFlag)(migrationsPath);
     return {
-        continueCommand: renderContinueCommand(root, facts.runId, facts.policy, agentId),
+        continueCommand: renderContinueCommand(root, facts.runId, facts.policy, agentic === false ? undefined : agentic),
         startFresh: flag === null
             ? { migrationsPath }
             : {
-                command: `${(0, util_1.pmExecPrefix)(root)} nx migrate ${flag}${agentId === undefined ? '' : ` --agentic=${agentId}`} --start-fresh --run-id=${facts.runId}`,
+                command: `${(0, util_1.pmExecPrefix)(root)} nx migrate ${flag}${agentic === undefined ? '' : ` --agentic=${agentic}`} --start-fresh --run-id=${facts.runId}`,
             },
     };
 }
@@ -153,12 +155,12 @@ function renderExistingRunReport(facts, commands) {
         lines.push(`  other active runs on disk: ${facts.otherActiveRuns.join(', ')}`);
     }
     if (facts.appliedStillPlanned !== undefined) {
-        lines.push(`  plan overlap: ${facts.appliedStillPlanned} of the applied migrations ${facts.appliedStillPlanned === 1 ? 'is' : 'are'} still in the plan; a new run applies ${facts.appliedStillPlanned === 1 ? 'it' : 'them'} again`);
+        lines.push(`  plan overlap: ${facts.appliedStillPlanned} of the applied migrations ${facts.appliedStillPlanned === 1 ? 'is' : 'are'} still in the plan; running the plan applies ${facts.appliedStillPlanned === 1 ? 'it' : 'them'} again`);
     }
     if (commands) {
         lines.push(``, `To continue the run: ${commands.continueCommand}`, `To start fresh (deletes the run record, then runs the whole plan again): ${'command' in commands.startFresh
             ? commands.startFresh.command
-            : `re-run this command with --start-fresh --run-id=${facts.runId}, keeping the --run-migrations argument, which names ${displayPath(commands.startFresh.migrationsPath)}; that path cannot be rendered as a command for this shell`}`, `Run either command with NX_MIGRATE_ORCHESTRATOR=true set in the environment.`);
+            : `re-run this command with --start-fresh --run-id=${facts.runId}, keeping the --run-migrations argument, which names ${displayPath(commands.startFresh.migrationsPath)}; that path cannot be rendered as a command for this shell`}`);
     }
     return {
         title: `A migrate run is already active: ${facts.runId}`,

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

@@ -1,4 +1,4 @@
-import { type CommitResult } from '../migrate-commits';
+import { type CommitFailureRecovery, type CommitResult } from '../migrate-commits';
 import type { MigrateOutputSink } from '../deferred-output';
 import type { TreeLease } from './broker';
 import { type MigrateRunState, type MigrateStep } from './run-state';
@@ -25,7 +25,8 @@ export interface GiveUpInput {
 export declare function giveUpWithCommit(input: GiveUpInput): Promise<GiveUpOutcome>;
 /**
  * Mints the issue that carries a given-up step's failure and points the step
- * at it, on state where the step is already unresolved. The archive file is
+ * at it, on state where the step is already unresolved. A single run keeps no
+ * issue ledger, so its state comes back unchanged. The archive file is
  * best-effort: run.json is authoritative, and undoing the transition for a
  * lost detail file would make the agent re-issue an action the run already
  * took.
@@ -38,4 +39,4 @@ export declare function warnUnresolvedNotArchived(label: string, archiveError: s
 /** What the reconcile owes the agent for a give-up that went through. */
 export declare function warnAboutGiveUp(step: MigrateStep, outcome: Extract<GiveUpOutcome, {
     kind: 'given-up';
-}>): void;
+}>, recovery: CommitFailureRecovery): void;

package/dist/src/command-line/migrate/run/give-up.js

@@ -36,7 +36,7 @@ async function giveUpWithCommit(input) {
     let commit;
     let entry;
     try {
-        const result = await (0, migrate_commits_1.commitMigrationIfRequested)(root, { name: (0, state_machine_1.unresolvedCommitName)(step) }, true, state.commitPrefix, () => (0, util_1.installDepsChangedSinceDispense)(root, dir, step, input.skipInstall, input.reconcileCommand, input.output), (0, state_machine_1.stepsToPendingMigrations)(state, absorbedStepIds), undefined, input.output);
+        const result = await (0, migrate_commits_1.commitMigrationIfRequested)(root, { name: (0, state_machine_1.unresolvedCommitName)(step) }, true, state.commitPrefix, () => (0, util_1.installDepsChangedSinceDispense)(root, dir, step, input.skipInstall, input.reconcileCommand, input.output), (0, state_machine_1.stepsToPendingMigrations)(state, absorbedStepIds), (0, util_1.commitFailureRecovery)(state), input.output);
         commit = result;
         entry = (0, state_machine_1.commitResultToLedgerEntry)(result, step.id, absorbedStepIds);
     }
@@ -91,12 +91,15 @@ async function giveUpWithCommit(input) {
 }
 /**
  * Mints the issue that carries a given-up step's failure and points the step
- * at it, on state where the step is already unresolved. The archive file is
+ * at it, on state where the step is already unresolved. A single run keeps no
+ * issue ledger, so its state comes back unchanged. The archive file is
  * best-effort: run.json is authoritative, and undoing the transition for a
  * lost detail file would make the agent re-issue an action the run already
  * took.
  */
 function recordUnresolvedIssue(dir, state, stepId) {
+    if (state.singleMigration === true)
+        return { state };
     // Minted from the transitioned step: a died one only gains its failure in
     // the transition.
     const minted = (0, issues_1.mintUnresolvedIssue)(state, state.steps.find((s) => s.id === stepId));
@@ -124,14 +127,14 @@ function warnUnresolvedNotArchived(label, archiveError) {
     });
 }
 /** What the reconcile owes the agent for a give-up that went through. */
-function warnAboutGiveUp(step, outcome) {
+function warnAboutGiveUp(step, outcome, recovery) {
     const name = (0, state_machine_1.unresolvedCommitName)(step);
     switch (outcome.commit.status) {
         case 'install-failed':
-            (0, util_1.warnCommitFailed)(name, outcome.commit.reason);
+            (0, util_1.warnCommitFailed)(name, recovery, outcome.commit.reason);
             break;
         case 'failed':
-            (0, util_1.warnCommitFailed)(name);
+            (0, util_1.warnCommitFailed)(name, recovery);
             break;
         case 'committed':
         case 'no-changes':

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

@@ -1,12 +1,14 @@
-export { CURRENT_RUN_STATE_FORMAT_VERSION, NewerRunStateFormatError, migrateRunsDir, runDir, runHandoffsDir, readRunState, writeRunState, findActiveRun, createRun, } 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 { CURRENT_RUN_STATE_FORMAT_VERSION, NewerRunStateFormatError, migrateRunsDir, runDir, runHandoffsDir, readRunState, writeRunState, findActiveRun, createRun, TERMINAL_STEP_STATUSES, migrationIdProblems, } from './run-state';
+export type { MigrateRunStatus, MigrateRunRound, MigrateStepStatus, PromptOutcomeStatus, MigrateStepAwaitingKind, MigrateStepOutcome, MigrateStepPromptOutcome, MigrateStep, MigrateCommitKind, MigrateCommitLedgerEntry, MigrateIssueDisposition, MigrateRunIssue, MigrateRunAnalytics, MigrateRunNoProgress, MigrateRunPolicy, MigrateRunState, MigrationIdProblem, } from './run-state';
+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 { isHeld } from './state-lock';
+export { pmInstallCommand } from './util';
 export { runSingleMigrationWorker } from './worker';
 export type { RunSingleMigrationWorkerInput } from './worker';
-export { activeRunToReplace, completionWarnings, holdRunToContinue, releaseRunToHandOff, runOrchestratorInit, runOrchestratorReconcile, runOrchestratorResume, } from './orchestrator';
+export { activeRunForClassic, activeRunToReplace, checkRunForStartFresh, checkRunsForSingleMigration, completionWarnings, deleteRunForStartFresh, holdRunToContinue, refuseNewRunAlongsideLiveRun, 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.refuseNewRunAlongsideLiveRun = exports.holdRunToContinue = exports.deleteRunForStartFresh = exports.completionWarnings = exports.checkRunsForSingleMigration = exports.checkRunForStartFresh = exports.activeRunToReplace = exports.activeRunForClassic = exports.runSingleMigrationWorker = exports.pmInstallCommand = exports.isHeld = exports.createRunId = exports.hasUnresolvedIssues = exports.tallySteps = exports.stepLabel = exports.runTallies = exports.latestRound = exports.hasPendingCommitDebt = exports.completionSummaryLines = exports.applyStepEvent = exports.migrationIdProblems = 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,23 +11,35 @@ 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; } });
+Object.defineProperty(exports, "migrationIdProblems", { enumerable: true, get: function () { return run_state_1.migrationIdProblems; } });
 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 state_lock_1 = require("./state-lock");
+Object.defineProperty(exports, "isHeld", { enumerable: true, get: function () { return state_lock_1.isHeld; } });
+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");
+Object.defineProperty(exports, "activeRunForClassic", { enumerable: true, get: function () { return orchestrator_1.activeRunForClassic; } });
 Object.defineProperty(exports, "activeRunToReplace", { enumerable: true, get: function () { return orchestrator_1.activeRunToReplace; } });
+Object.defineProperty(exports, "checkRunForStartFresh", { enumerable: true, get: function () { return orchestrator_1.checkRunForStartFresh; } });
+Object.defineProperty(exports, "checkRunsForSingleMigration", { enumerable: true, get: function () { return orchestrator_1.checkRunsForSingleMigration; } });
 Object.defineProperty(exports, "completionWarnings", { enumerable: true, get: function () { return orchestrator_1.completionWarnings; } });
+Object.defineProperty(exports, "deleteRunForStartFresh", { enumerable: true, get: function () { return orchestrator_1.deleteRunForStartFresh; } });
 Object.defineProperty(exports, "holdRunToContinue", { enumerable: true, get: function () { return orchestrator_1.holdRunToContinue; } });
+Object.defineProperty(exports, "refuseNewRunAlongsideLiveRun", { enumerable: true, get: function () { return orchestrator_1.refuseNewRunAlongsideLiveRun; } });
 Object.defineProperty(exports, "releaseRunToHandOff", { enumerable: true, get: function () { return orchestrator_1.releaseRunToHandOff; } });
 Object.defineProperty(exports, "runOrchestratorInit", { enumerable: true, get: function () { return orchestrator_1.runOrchestratorInit; } });
 Object.defineProperty(exports, "runOrchestratorReconcile", { enumerable: true, get: function () { return orchestrator_1.runOrchestratorReconcile; } });
@@ -38,5 +50,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/issues.js

@@ -75,9 +75,14 @@ function quoted(value) {
  */
 function parseHandoffIssues(extras, state, reportingStep) {
     if (extras !== undefined) {
-        const unknown = unknownKey(extras, ['outcome', 'issues', 'issueUpdates']);
+        // A single run keeps no issue ledger: nx prints its handoff summary when
+        // the run ends, and deletes the run's record.
+        const singleMigration = state.singleMigration === true;
+        const unknown = unknownKey(extras, singleMigration ? ['outcome'] : ['outcome', 'issues', 'issueUpdates']);
         if (unknown !== undefined) {
-            return invalid(`the handoff has an unrecognized field ${quoted(unknown)}; the fields accepted next to "status" and "summary" are "outcome", "issues" and "issueUpdates"`);
+            return invalid(`the handoff has an unrecognized field ${quoted(unknown)}; ${singleMigration
+                ? `a --run-migration run accepts only "outcome" next to "status" and "summary", and its problems go in "summary"`
+                : `the fields accepted next to "status" and "summary" are "outcome", "issues" and "issueUpdates"`}`);
         }
         if (extras['outcome'] !== undefined && extras['outcome'] !== 'skipped') {
             return invalid(`the handoff has an unrecognized "outcome" value ${quoted(extras['outcome'])}; the only accepted value is "skipped"`);