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

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];
@@ -128,8 +141,10 @@ export interface MigrateRunState {
     noProgress?: MigrateRunNoProgress;
     checkpointFailed?: boolean;
     treeOperation?: MigrateTreeOperation;
+    singleMigration?: boolean;
     analytics: MigrateRunAnalytics;
 }
+export declare function runKind(state: MigrateRunState): 'single' | 'active' | 'finished';
 export declare const TREE_OPERATION_KINDS: readonly ['commit', 'install', 'fold-install', 'action-install', 'reset', 'give-up', 'checkpoint'];
 export type MigrateTreeOperationKind = (typeof TREE_OPERATION_KINDS)[number];
 export interface MigrateTreeOperation {
@@ -187,7 +202,8 @@ export interface UninterpretableRunDir {
  *
  * A dir that reads cleanly as a finished run is skipped whatever its name is:
  * it competes with nothing, and reporting it would block every future run
- * with no way for retention to ever clear it.
+ * with no way for retention to ever clear it. A `--run-migration` run's record
+ * is skipped too: nothing continues it, and a leftover must not block a run.
  *
  * Throws {@link NewerRunStateFormatError} when any run dir holds a
  * newer-format run.json: whether that run is active can't be determined

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

@@ -1,7 +1,9 @@
 "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.runKind = runKind;
 exports.migrateRunsDir = migrateRunsDir;
 exports.runDir = runDir;
 exports.runHandoffsDir = runHandoffsDir;
@@ -32,6 +34,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
@@ -117,6 +139,21 @@ exports.MIGRATE_ISSUE_DISPOSITIONS = [
     'resolved',
     'deferred-final',
 ];
+// A `--run-migration` record is 'single' whatever its status.
+function runKind(state) {
+    if (state.singleMigration === true)
+        return 'single';
+    switch (state.status) {
+        case 'active':
+            return 'active';
+        case 'completed':
+            return 'finished';
+        default: {
+            const unhandled = state.status;
+            throw new Error(`Unhandled migrate run status: ${unhandled}`);
+        }
+    }
+}
 exports.TREE_OPERATION_KINDS = [
     'commit',
     'install',
@@ -409,6 +446,7 @@ function hasValidRunStateShape(parsed) {
         isOptionalBoolean(parsed.checkpointFailed) &&
         isOptionalBoolean(parsed.skipInstall) &&
         isOptionalBoolean(parsed.validate) &&
+        isOptionalBoolean(parsed.singleMigration) &&
         isOptionalSha(parsed.gitRefAtInit) &&
         isOptionalMatching(RUNBOOK_NAME, parsed.runbookPath) &&
         isOptionalString(parsed.branch) &&
@@ -566,7 +604,8 @@ function readRunDirState(candidateDir) {
  *
  * A dir that reads cleanly as a finished run is skipped whatever its name is:
  * it competes with nothing, and reporting it would block every future run
- * with no way for retention to ever clear it.
+ * with no way for retention to ever clear it. A `--run-migration` run's record
+ * is skipped too: nothing continues it, and a leftover must not block a run.
  *
  * Throws {@link NewerRunStateFormatError} when any run dir holds a
  * newer-format run.json: whether that run is active can't be determined
@@ -598,7 +637,7 @@ function findActiveRun(root) {
             });
             continue;
         }
-        if (state.status !== 'active')
+        if (runKind(state) !== 'active')
             continue;
         // Run ids are joined into paths and interpolated into dispensed commands,
         // so a dir whose name fails the gate is never trusted as a resumable run.

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

@@ -8,6 +8,7 @@ export interface RunbookContext {
     createCommits: boolean;
     validate: boolean;
     finalValidation: boolean;
+    singleMigration: boolean;
 }
 /**
  * Every interpolated value is collapsed to a single line: the rendered content

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

@@ -22,8 +22,9 @@ exports.RUNBOOK_FILE_NAME = 'RUNBOOK.md';
 function renderRunbook(ctx) {
     const runId = (0, text_1.singleLine)(ctx.runId);
     const reconcile = (0, text_1.singleLine)(ctx.reconcileCommand);
-    // Run-scoped like the Claude runner grant: a wildcard run segment would let
-    // a configured child write handoffs that settle steps in another run.
+    // Run-scoped like the Claude Code handoff grant: a wildcard run segment
+    // would let a configured child write handoffs that settle steps in another
+    // run.
     const handoffsGlob = `${types_1.MIGRATE_RUNS_RELATIVE_DIR}/${runId}/${types_1.HANDOFFS_DIR_NAME}/**`;
     const lines = [
         `# Nx migrate run ${runId}`,
@@ -57,9 +58,17 @@ function renderRunbook(ctx) {
         `2. Do what the block says. For a \`next-step\` action, run the given`,
         `   worker command; it applies one migration.`,
         `3. When a step hands work back to you (see "Agent work" below), run the`,
-        `   \`next\` command first: its response restates the work, names the`,
-        `   handoff file to write, and lists any recorded issues assigned to the`,
-        `   step. Do the work, write the handoff file, then run \`next\` again.`,
+        ...(ctx.singleMigration
+            ? [
+                `   \`next\` command first: its response restates the work and names`,
+                `   the handoff file to write. Do the work, write the handoff file,`,
+                `   then run \`next\` again.`,
+            ]
+            : [
+                `   \`next\` command first: its response restates the work, names the`,
+                `   handoff file to write, and lists any recorded issues assigned to the`,
+                `   step. Do the work, write the handoff file, then run \`next\` again.`,
+            ]),
         `4. Repeat until the orchestrator reports the run \`complete\`.`,
         ``,
         `Execute only what the current block asks. Do not run migrations the`,
@@ -72,9 +81,39 @@ function renderRunbook(ctx) {
         `repeated instructions or report the blocker to the user; re-running the`,
         `reconcile command alone changes nothing.`,
         ``,
-        `An \`existing-run\` action means no run was started because one is`,
-        `already active. Show its report to the user and let them choose between`,
-        `the two commands it lists; do not choose for them.`,
+        ...(ctx.singleMigration
+            ? []
+            : [
+                `An \`existing-run\` action means no run was started because one is`,
+                `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`,
+        ...(ctx.singleMigration
+            ? [
+                `  session, then press Ctrl+C in the terminal to end it, and run the`,
+                `  same \`nx migrate --run-migration\` command again afterwards.`,
+            ]
+            : [
+                `  session, then press Ctrl+C in the terminal to end it, and resume the run`,
+                `  afterwards.`,
+            ]),
         ``,
         `## Agent work`,
         ``,
@@ -83,9 +122,7 @@ function renderRunbook(ctx) {
         `- A migration with an AI-driven part makes its worker emit a`,
         `  \`nx_migrate_prompt\` block pointing at an instructions file. Apply`,
         `  those instructions to the workspace. Scope rules for that work:`,
-        ...(0, fragments_1.renderAuthorScopeRuleLines)((0, text_1.singleLine)(ctx.pmExec), {
-            source: 'dispensed-step',
-        }).map((line) => `  ${line}`),
+        ...(0, fragments_1.renderAuthorScopeRuleLines)((0, text_1.singleLine)(ctx.pmExec)).map((line) => `  ${line}`),
         NX_JSON_MIGRATE_RULE,
         `  The \`nx migrate\` commands this runbook and the step blocks hand you`,
         `  (the reconcile, worker and \`next\` commands) are the exception to the`,
@@ -97,16 +134,76 @@ function renderRunbook(ctx) {
     if (ctx.finalValidation) {
         lines.push(`- The run's last step is a validation pass over the whole workspace,`, `  dispensed once every migration step is done. Its \`nx_migrate_prompt\``, `  block points at an instructions file; that file names the base ref its`, `  \`nx affected\` runs use. Scope rules for that work:`, ...(0, fragments_1.renderFinalValidationScopeRuleLines)().map((line) => `  ${line}`), NX_JSON_MIGRATE_RULE);
     }
-    lines.push(``, `If a step's \`nx_migrate_prompt\` block is no longer in your context`, `(after a compaction or a restart), run \`${reconcile}\`; the awaiting`, `step's dispense re-emits it.`, ``, `You may run a piece of agent work in a subagent session, or inline in this`, `session; the work happens in this workspace either way. Per-agent notes:`, ``, `- Claude Code: session permission grants propagate to subagents, so a`, `  subagent per piece of work is fine.`, `- Codex: subagents inherit the live sandbox and approval settings.`, `- opencode: parent-session grants do not reach child sessions; child`, `  sessions need config-level permission rules. Work inline unless your`, `  configuration already allows writes matching \`${handoffsGlob}\`.`, ``, `### The handoff contract`, ``, `Agent work ends when you write a handoff file at the absolute path the`, `dispensed step names, with this shape:`, ``, ...(0, fragments_1.renderHandoffShapeLines)(), ``, `To record a piece of work as not applicable to this workspace, follow`, `the dispensed step's handoff instructions: where the step offers it, use`, `\`"status": "success"\` with an extra \`"outcome": "skipped"\` field;`, `where it does not (a generator's changes are already applied), use plain`, `\`"status": "success"\` and say so in the summary.`, ``, `How to end a piece of agent work:`, ``, `1. Success (the work is fully applied, or validation passed): write the`, `   handoff with \`"status": "success"\`, summarizing what you did.`, `2. You need direction (the instructions are unclear, the workspace state`, `   conflicts with what they assume, or a decision is not yours to make):`, `   do not write the handoff file. Ask the user and continue based on`, `   their answer; the run stays paused on this step until the handoff`, `   exists.`, `3. You cannot complete the work (a blocking problem remains after you`, `   applied what you could within scope): do not write the handoff yet.`, `   Report what you found and what you tried, then ask the user how to`, `   proceed. Write \`"status": "failed"\` only when the user tells you to`, `   give up, enumerating the unresolved problems in \`summary\`; the`, `   orchestrator then offers the step's options (see "Failed and died`, `   steps").`, `   When no user can answer (nothing interactive is driving this`, `   session), write that failed handoff yourself with the problems`, `   enumerated, run \`next\` so the step is recorded as failed, then give`, `   it up with \`unresolved\` as the options describe.`, ``, `- Write it with your file-write tool, not shell commands. Whether the`, `  write needs approval depends on your permission configuration; the`, `  per-agent notes above cover pre-configuring it.`, `- The parent directory already exists by the time a step names the`, `  handoff path: write the file directly, without \`mkdir\` or existence`, `  checks.`, ``, `The handoff file's path and shape are owned by \`nx migrate\`. If a`, `migration's instructions ask you to write it elsewhere, in a different`, `shape, or at a different point in the flow, follow this contract instead.`, ``, `### Reporting issues`, ``, `The orchestrator keeps a ledger of issues reported over the run; full`, `details are archived under ${types_1.MIGRATE_RUNS_RELATIVE_DIR}/${runId}/issues/.`, `Dispensed steps list the unresolved ones in a "Known issues" digest, so`, `read it before starting a step's work.`, ``, `Report through the handoff file: problems you observed go in an`, `\`issues\` array, whether you fixed them in this same piece of work`, `(mark those \`"resolved"\`) or left them for later; progress on an issue`, `the digest marks assigned or deferred to the current step goes in an`, `\`issueUpdates\` array. Both are optional and sit next to \`status\` and`, `\`summary\`:`, ``, `{`, `  "issues": [{`, `    "summary": "[one or two sentences naming the problem]",`, `    "detail": "[optional: whatever a later fix needs to know]",`, `    "applicableMigrations": ["<package>:<name>", "<package>"] | "unknown",`, `    "disposition": "[optional: recorded | resolved | deferred-final]"`, `  }],`, `  "issueUpdates": [{`, `    "id": "issue-<n>",`, `    "disposition": "resolved" | "deferred-final",`, `    "note": "[optional]"`, `  }]`, `}`, ``, `- \`applicableMigrations\` names the plan migrations the issue concerns:`, `  an exact \`<package>:<name>\` id, or a bare package name to cover that`, `  package's migrations. Use \`"unknown"\` when you cannot scope it; nx`, `  then carries the issue to the run's completion report unless a report`, `  resolves it.`, `- Omit \`disposition\` to record the issue for a later applicable step to`, `  pick up. Use \`"resolved"\` only for a problem you discovered and fixed`, `  in this same piece of work, and \`"deferred-final"\` when no later`, ...(ctx.finalValidation
+    lines.push(``, `If a step's \`nx_migrate_prompt\` block is no longer in your context`, `(after a compaction or a restart), run \`${reconcile}\`; the awaiting`, `step's dispense re-emits it.`, ``, `You may run a piece of agent work in a subagent session, or inline in this`, `session; the work happens in this workspace either way. Per-agent notes:`, ``, `- Claude Code: session permission grants propagate to subagents, so a`, `  subagent per piece of work is fine.`, `- Codex: subagents inherit the live sandbox and approval settings.`, `- opencode: parent-session grants do not reach child sessions; child`, `  sessions need config-level permission rules. Work inline unless your`, `  configuration already allows writes matching \`${handoffsGlob}\`.`, ``, `### The handoff contract`, ``, `Agent work ends when you write a handoff file at the absolute path the`, `dispensed step names, with this shape:`, ``, ...(0, fragments_1.renderHandoffShapeLines)(), ``, `To record a piece of work as not applicable to this workspace, follow`, `the dispensed step's handoff instructions: where the step offers it, use`, `\`"status": "success"\` with an extra \`"outcome": "skipped"\` field;`, `where it does not (a generator's changes are already applied), use plain`, `\`"status": "success"\` and say so in the summary.`, ``, `How to end a piece of agent work:`, ``, `1. Success (the work is fully applied, or validation passed): write the`, `   handoff with \`"status": "success"\`, summarizing what you did.`, `2. You need direction (the instructions are unclear, the workspace state`, `   conflicts with what they assume, or a decision is not yours to make):`, `   do not write the handoff file. Ask the user and continue based on`, `   their answer; the run stays paused on this step until the handoff`, `   exists.`, `3. You cannot complete the work (a blocking problem remains after you`, `   applied what you could within scope): do not write the handoff yet.`, `   Report what you found and what you tried, then ask the user how to`, `   proceed. Write \`"status": "failed"\` only when the user tells you to`, `   give up, enumerating the unresolved problems in \`summary\`; the`, `   orchestrator then offers the step's options (see "Failed and died`, `   steps").`, `   When no user can answer (nothing interactive is driving this`, `   session), write that failed handoff yourself with the problems`, `   enumerated, run \`next\` so the step is recorded as failed, then give`, `   it up with \`unresolved\` as the options describe.`, ``, `- Write it with your file-write tool, not shell commands. Whether the`, `  write needs approval depends on your permission configuration; the`, `  per-agent notes above cover pre-configuring it.`, `- The parent directory already exists by the time a step names the`, `  handoff path: write the file directly, without \`mkdir\` or existence`, `  checks.`, ``, `The handoff file's path and shape are owned by \`nx migrate\`. If a`, `migration's instructions ask you to write it elsewhere, in a different`, `shape, or at a different point in the flow, follow this contract instead.`, ``, ...(ctx.singleMigration
+        ? [
+            `Nx prints the handoff's \`summary\` when the run ends, so put anything`,
+            `the user should know in it, including problems you left open.`,
+        ]
+        : [
+            `### Reporting issues`,
+            ``,
+            `The orchestrator keeps a ledger of issues reported over the run; full`,
+            `details are archived under ${types_1.MIGRATE_RUNS_RELATIVE_DIR}/${runId}/issues/.`,
+            `Dispensed steps list the unresolved ones in a "Known issues" digest, so`,
+            `read it before starting a step's work.`,
+            ``,
+            `Report through the handoff file: problems you observed go in an`,
+            `\`issues\` array, whether you fixed them in this same piece of work`,
+            `(mark those \`"resolved"\`) or left them for later; progress on an issue`,
+            `the digest marks assigned or deferred to the current step goes in an`,
+            `\`issueUpdates\` array. Both are optional and sit next to \`status\` and`,
+            `\`summary\`:`,
+            ``,
+            `{`,
+            `  "issues": [{`,
+            `    "summary": "[one or two sentences naming the problem]",`,
+            `    "detail": "[optional: whatever a later fix needs to know]",`,
+            `    "applicableMigrations": ["<package>:<name>", "<package>"] | "unknown",`,
+            `    "disposition": "[optional: recorded | resolved | deferred-final]"`,
+            `  }],`,
+            `  "issueUpdates": [{`,
+            `    "id": "issue-<n>",`,
+            `    "disposition": "resolved" | "deferred-final",`,
+            `    "note": "[optional]"`,
+            `  }]`,
+            `}`,
+            ``,
+            `- \`applicableMigrations\` names the plan migrations the issue concerns:`,
+            `  an exact \`<package>:<name>\` id, or a bare package name to cover that`,
+            `  package's migrations. Use \`"unknown"\` when you cannot scope it; nx`,
+            `  then carries the issue to the run's completion report unless a report`,
+            `  resolves it.`,
+            `- Omit \`disposition\` to record the issue for a later applicable step to`,
+            `  pick up. Use \`"resolved"\` only for a problem you discovered and fixed`,
+            `  in this same piece of work, and \`"deferred-final"\` when no later`,
+            ...(ctx.finalValidation
+                ? [
+                    `  migration step should pick it up; it is carried to the final`,
+                    `  validation pass, and the completion report lists what that pass`,
+                    `  leaves unresolved.`,
+                ]
+                : [
+                    `  migration step should pick it up; it is carried to the completion`,
+                    `  report instead.`,
+                ]),
+            `- \`issueUpdates\` may only reference issues the digest marks assigned or`,
+            `  deferred to the current step.`,
+            `- Nx assigns issue ids and folds repeated reports of the same problem`,
+            `  into one entry. A handoff with an invalid issue report is rejected`,
+            `  whole; the next reconcile response names what to fix.`,
+        ]), ``, `## Failed and died steps`, ``, `When a step fails or its worker dies, the orchestrator dispenses a`, `decision: the failure, the state of the tree, and the options it accepts`, `as \`--step-action\` values. Diagnose the failure before choosing.`, ``, `- \`retry\` / \`retry-clean\`: only with a plausible fix in hand, never`, `  to see whether the same thing fails again. A step allows two retries;`, `  ask the user before using the last one. Past that, no retry is`, `  accepted.`, `- \`adopt\`: the migration's result is already in the working tree (you`, `  or the user applied it by hand, or a died worker's changes landed);`, `  record it as applied.`, `- \`skip\`: the migration does not apply to this workspace.`, ...(ctx.singleMigration
         ? [
-            `  migration step should pick it up; it is carried to the final`,
-            `  validation pass, and the completion report lists what that pass`,
-            `  leaves unresolved.`,
+            `- \`unresolved\`: give the migration up. Nx settles the tree as the`,
+            `  option describes and ends the run, which exits non-zero and prints`,
+            `  the failure.`,
         ]
         : [
-            `  migration step should pick it up; it is carried to the completion`,
-            `  report instead.`,
-        ]), `- \`issueUpdates\` may only reference issues the digest marks assigned or`, `  deferred to the current step.`, `- Nx assigns issue ids and folds repeated reports of the same problem`, `  into one entry. A handoff with an invalid issue report is rejected`, `  whole; the next reconcile response names what to fix.`, ``, `## Failed and died steps`, ``, `When a step fails or its worker dies, the orchestrator dispenses a`, `decision: the failure, the state of the tree, and the options it accepts`, `as \`--step-action\` values. Diagnose the failure before choosing.`, ``, `- \`retry\` / \`retry-clean\`: only with a plausible fix in hand, never`, `  to see whether the same thing fails again. A step allows two retries;`, `  ask the user before using the last one. Past that, no retry is`, `  accepted.`, `- \`adopt\`: the migration's result is already in the working tree (you`, `  or the user applied it by hand, or a died worker's changes landed);`, `  record it as applied.`, `- \`skip\`: the migration does not apply to this workspace.`, `- \`unresolved\`: give the migration up. Nx records the failure as a run`, `  issue, settles the tree as the option describes, and moves on. The`, `  completion report lists it, and a session Nx started for this run`, `  exits non-zero; when you drive the loop yourself, the completion`, `  block's unresolved tally and warnings are what say work remains.`, `  Withheld, with \`skip\`, when a commit of this migration's changes`, `  landed, or was started and never recorded; the dispense then offers`, `  \`adopt\` in their place.`, ``, `Present the options to the user unless the choice is clearly yours to`, `make. When no user can answer (nothing interactive is driving this`, `session), give the step up with \`unresolved\` and continue the run`, `rather than stalling on it. Where the dispense withholds it, a commit of`, `the migration may already be in history: \`adopt\` only once you have`, `inspected the tree and finished the migration; otherwise stop and`, `report.`, ``, `## Commits`, ``);
+            `- \`unresolved\`: give the migration up. Nx records the failure as a run`,
+            `  issue, settles the tree as the option describes, and moves on. The`,
+            `  completion report lists it, and a session Nx started for this run`,
+            `  exits non-zero; when you drive the loop yourself, the completion`,
+            `  block's unresolved tally and warnings are what say work remains.`,
+        ]), `  Withheld, with \`skip\`, when a commit of this migration's changes`, `  landed, or was started and never recorded; the dispense then offers`, `  \`adopt\` in their place.`, ``, `Present the options to the user unless the choice is clearly yours to`, `make. When no user can answer (nothing interactive is driving this`, `session), give the step up with \`unresolved\` and continue the run`, `rather than stalling on it. Where the dispense withholds it, a commit of`, `the migration may already be in history: \`adopt\` only once you have`, `inspected the tree and finished the migration; otherwise stop and`, `report.`, ``, `## Commits`, ``);
     if (ctx.createCommits) {
         lines.push(`Nx commits each migration's changes itself. Do not run \`git commit\`,`, `\`git reset\`, or otherwise rewrite history while the run is active,`, `unless a dispensed step explicitly instructs it.`);
     }

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

@@ -27,10 +27,33 @@ export declare function updateRunState(runDirPath: string, apply: (fresh: Migrat
  * Marks this process as acting on the run until it exits or releases the
  * hold, so a `--start-fresh` elsewhere refuses to delete it. One lock file per
  * process and run, taken under the creation lock that deletion probes under.
- * `exclusive` refuses while another process holds the run, even when this one
- * already does. No-op under WASM, which has no native lock.
+ * Refuses while another process works on a different run, which shares the
+ * workspace. `exclusive` also refuses while another process holds this run,
+ * even when this one already does. No-op under WASM, which has no native lock.
  */
 export declare function holdRunActivity(root: string, runId: string, exclusive?: boolean): void;
+export interface LiveRun {
+    dirName: string;
+    starting: boolean;
+    state: MigrateRunState | null;
+    readError?: unknown;
+    holders: number[] | 'unknown';
+}
+/**
+ * The runs other than `ownRunId` that another live process works on: runs
+ * being started, active runs, `--run-migration` runs, and runs whose run.json
+ * can't be read. A finished `--run-migrations` run doesn't count. Every run
+ * changes the same workspace, so two live runs would install and commit over
+ * each other.
+ */
+export declare function findOtherLiveRuns(root: string, ownRunId?: string): LiveRun[];
+export declare function listOtherRuns(root: string, ownRunId?: string): LiveRun[];
+/**
+ * The refusal of a command that would change the workspace while another
+ * process works on `run`. `refusal` opens it, as in "Not running the
+ * migration".
+ */
+export declare function liveRunRefusal(refusal: string, run: LiveRun): Error;
 export declare function heldRunError(action: 'continuing' | 'deleting', runId: string, holders: number[] | 'unknown'): Error;
 export declare function describeHolders(holders: number[]): string;
 /**
@@ -50,7 +73,9 @@ export declare function releaseRunActivity(dir: string): void;
 export declare function liveRunActivityPids(dir: string): number[] | 'unknown';
 /**
  * Whether any live process, this one included, holds an activity lock on the
- * run: for the init discovery that treats a held directory without run.json
- * as a run being started, whichever process is starting it. Fails closed.
+ * run: for the discovery that treats a held directory without run.json as a
+ * run being started, whichever process is starting it. Fails closed, so under
+ * WASM any lock file counts.
  */
 export declare function hasAnyLiveRunActivity(dir: string): boolean;
+export declare function isHeld(holders: readonly unknown[] | 'unknown'): boolean;

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

@@ -5,8 +5,8 @@
 // the kernel releases a dead holder's lock automatically, so there is no
 // stale-lock state to detect or clean up. Under WASM the native lock is
 // unavailable and sections run unserialized, matching the project graph's
-// IS_WASM guard for this lock. Not part of run/'s public surface (not
-// re-exported via ./index): import directly within run/.
+// IS_WASM guard for this lock. Only `isHeld` is part of run/'s public surface
+// (re-exported via ./index): import the rest directly within run/.
 //
 // Locked sections must stay synchronous. lock() blocks the whole thread, so
 // if a holder parked on an await while a second in-process caller reached
@@ -17,16 +17,22 @@ exports.withRunStateLock = withRunStateLock;
 exports.withRunCreationLock = withRunCreationLock;
 exports.updateRunState = updateRunState;
 exports.holdRunActivity = holdRunActivity;
+exports.findOtherLiveRuns = findOtherLiveRuns;
+exports.listOtherRuns = listOtherRuns;
+exports.liveRunRefusal = liveRunRefusal;
 exports.heldRunError = heldRunError;
 exports.describeHolders = describeHolders;
 exports.registerRunActivity = registerRunActivity;
 exports.releaseRunActivity = releaseRunActivity;
 exports.liveRunActivityPids = liveRunActivityPids;
 exports.hasAnyLiveRunActivity = hasAnyLiveRunActivity;
+exports.isHeld = isHeld;
 const crypto_1 = require("crypto");
 const fs_1 = require("fs");
 const path_1 = require("path");
 const native_1 = require("../../../native");
+const types_1 = require("../agentic/types");
+const text_1 = require("../text");
 const run_state_1 = require("./run-state");
 const STATE_LOCK_FILE_NAME = 'run.json.lock';
 const CREATION_LOCK_FILE_NAME = 'init.lock';
@@ -91,8 +97,9 @@ const heldActivity = new Map();
  * Marks this process as acting on the run until it exits or releases the
  * hold, so a `--start-fresh` elsewhere refuses to delete it. One lock file per
  * process and run, taken under the creation lock that deletion probes under.
- * `exclusive` refuses while another process holds the run, even when this one
- * already does. No-op under WASM, which has no native lock.
+ * Refuses while another process works on a different run, which shares the
+ * workspace. `exclusive` also refuses while another process holds this run,
+ * even when this one already does. No-op under WASM, which has no native lock.
  */
 function holdRunActivity(root, runId, exclusive = false) {
     if (native_1.IS_WASM)
@@ -106,13 +113,94 @@ function holdRunActivity(root, runId, exclusive = false) {
         }
         if (exclusive) {
             const others = liveRunActivityPids(dir);
-            if (others === 'unknown' || others.length > 0) {
+            if (isHeld(others)) {
                 throw heldRunError('continuing', runId, others);
             }
         }
+        const [otherRun] = findOtherLiveRuns(root, runId);
+        if (otherRun) {
+            throw liveRunRefusal(`Not continuing migrate run '${runId}'`, otherRun);
+        }
         registerRunActivity(dir);
     });
 }
+/**
+ * The runs other than `ownRunId` that another live process works on: runs
+ * being started, active runs, `--run-migration` runs, and runs whose run.json
+ * can't be read. A finished `--run-migrations` run doesn't count. Every run
+ * changes the same workspace, so two live runs would install and commit over
+ * each other.
+ */
+function findOtherLiveRuns(root, ownRunId) {
+    return listOtherRuns(root, ownRunId).filter((run) => isHeld(run.holders));
+}
+// findOtherLiveRuns' runs, including the ones no process holds.
+function listOtherRuns(root, ownRunId) {
+    let entries;
+    try {
+        entries = (0, fs_1.readdirSync)((0, run_state_1.migrateRunsDir)(root), { withFileTypes: true });
+    }
+    catch (e) {
+        if (e?.code === 'ENOENT')
+            return [];
+        throw e;
+    }
+    const runs = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name === ownRunId)
+            continue;
+        const dir = (0, path_1.join)((0, run_state_1.migrateRunsDir)(root), entry.name);
+        const starting = !(0, run_state_1.hasRunState)(dir);
+        // A directory without run.json that no process holds is an older nx's
+        // agentic scratch, or what a dead init or an unfinished removal left.
+        if (starting && !hasAnyLiveRunActivity(dir))
+            continue;
+        let state = null;
+        let readError;
+        if (!starting) {
+            try {
+                state = (0, run_state_1.readRunState)(dir);
+            }
+            catch (e) {
+                readError = e;
+            }
+            if (state && (0, run_state_1.runKind)(state) === 'finished')
+                continue;
+        }
+        runs.push({
+            dirName: entry.name,
+            starting,
+            state,
+            readError,
+            holders: liveRunActivityPids(dir),
+        });
+    }
+    return runs;
+}
+/**
+ * The refusal of a command that would change the workspace while another
+ * process works on `run`. `refusal` opens it, as in "Not running the
+ * migration".
+ */
+function liveRunRefusal(refusal, run) {
+    const path = `${types_1.MIGRATE_RUNS_RELATIVE_DIR}/${(0, text_1.singleLine)(run.dirName)}`;
+    // Refused at once, never waited for: this process may be a git hook of the
+    // init's checkpoint commit, which the init waits on.
+    if (run.starting && run.holders !== 'unknown') {
+        return new Error(`Another nx migrate process is starting a run (${path}). Wait for it to finish, then re-run the command.`);
+    }
+    const described = run.starting
+        ? `the run being started in ${path}`
+        : run.state?.singleMigration === true
+            ? `an nx migrate --run-migration run (${path})`
+            : `migrate run '${(0, text_1.singleLine)(run.dirName)}'`;
+    if (run.holders !== 'unknown') {
+        return new Error(`${refusal} while ${described} is in use: ${describeHolders(run.holders)}. Wait for it to end, then re-run the command.`);
+    }
+    return new Error(native_1.IS_WASM
+        ? `${refusal}: the WASM build cannot tell whether another nx migrate process is working on ${described}. Re-run the command with the native nx binary, or make sure no nx migrate process is acting on it, remove ${path}, then re-run the command.`
+        : `${refusal}: nx cannot tell whether another nx migrate process is working on ${described}. Make sure none is, remove ${path}, then re-run the command.`);
+}
 // 'unknown' is the fail-closed case: the activity folder could not be read or
 // a lock could not be probed.
 function heldRunError(action, runId, holders) {
@@ -166,15 +254,19 @@ function liveRunActivityPids(dir) {
 }
 /**
  * Whether any live process, this one included, holds an activity lock on the
- * run: for the init discovery that treats a held directory without run.json
- * as a run being started, whichever process is starting it. Fails closed.
+ * run: for the discovery that treats a held directory without run.json as a
+ * run being started, whichever process is starting it. Fails closed, so under
+ * WASM any lock file counts.
  */
 function hasAnyLiveRunActivity(dir) {
-    const names = liveActivityNames(dir, undefined);
-    return names === 'unknown' || names.length > 0;
+    return isHeld(liveActivityNames(dir, undefined));
+}
+// Whether a run's holders or held lock names show it held; 'unknown' counts.
+function isHeld(holders) {
+    return holders === 'unknown' || holders.length > 0;
 }
 // The names of the held lock files other than `skip`; 'unknown' when the
-// folder cannot be listed or a lock cannot be probed.
+// folder cannot be listed or a lock cannot be probed, as under WASM.
 function liveActivityNames(dir, skip) {
     let names;
     try {

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

@@ -1,5 +1,6 @@
 import type { MigrateOutputSink } from '../deferred-output';
-import type { MigrateStep } from './run-state';
+import type { CommitFailureRecovery } from '../migrate-commits';
+import { type MigrateRunState, type MigrateStep } from './run-state';
 export declare function nowIso(): string;
 /**
  * Fingerprints the workspace dependencies so a step can persist what they
@@ -28,6 +29,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>;
 /**
@@ -55,7 +59,8 @@ export declare function installDepsChangedSinceDispense(root: string, dir: strin
 export declare function recordInstallLanded(root: string, dir: string, stepId: string): void;
 export declare function isPidAlive(pid: number): boolean;
 export declare function summarizeError(e: unknown): string;
-export declare function warnCommitFailed(name: string, cause?: unknown): void;
+export declare function commitFailureRecovery(state: MigrateRunState): CommitFailureRecovery;
+export declare function warnCommitFailed(name: string, recovery: CommitFailureRecovery, cause?: unknown): void;
 export declare function pmExecPrefix(root: string): string;
 export declare function runMigrationsFlag(migrationsPath: string): string | null;
 export declare function pmInstallCommand(root: string): string;