nx 23.3.0-beta.7 → 23.3.0-beta.9

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

@@ -6,11 +6,3 @@ export declare const RUN_ID_SAFE: RegExp;
  * mid-run.
  */
 export declare function createRunId(): string;
-/**
- * Hashes a migrations.json plan so a resumed run can detect whether the plan
- * changed since a round was recorded. `nx-console` is stripped first since
- * editors write to it without changing the plan; object keys are sorted
- * recursively (arrays keep their order) so key reordering from a different
- * JSON serializer doesn't change the hash.
- */
-export declare function computePlanHash(migrationsJsonContent: string | object): string;

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

@@ -2,7 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RUN_ID_SAFE = void 0;
 exports.createRunId = createRunId;
-exports.computePlanHash = computePlanHash;
 const crypto_1 = require("crypto");
 // Orchestrator-generated run ids always match; anything else could smuggle
 // shell metacharacters into dispensed commands or a path out of the runs dir
@@ -25,32 +24,3 @@ function compactUtcTimestamp(date) {
         .replace(/[-:]/g, '')
         .replace(/\.\d+Z$/, '');
 }
-/**
- * Hashes a migrations.json plan so a resumed run can detect whether the plan
- * changed since a round was recorded. `nx-console` is stripped first since
- * editors write to it without changing the plan; object keys are sorted
- * recursively (arrays keep their order) so key reordering from a different
- * JSON serializer doesn't change the hash.
- */
-function computePlanHash(migrationsJsonContent) {
-    const parsed = (typeof migrationsJsonContent === 'string'
-        ? JSON.parse(migrationsJsonContent)
-        : migrationsJsonContent);
-    const withoutNxConsole = Object.fromEntries(Object.entries(parsed).filter(([key]) => key !== 'nx-console'));
-    return (0, crypto_1.createHash)('sha256')
-        .update(JSON.stringify(canonicalize(withoutNxConsole)))
-        .digest('hex');
-}
-function canonicalize(value) {
-    if (Array.isArray(value)) {
-        return value.map(canonicalize);
-    }
-    if (value !== null && typeof value === 'object') {
-        const sorted = {};
-        for (const key of Object.keys(value).sort()) {
-            sorted[key] = canonicalize(value[key]);
-        }
-        return sorted;
-    }
-    return value;
-}

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

@@ -14,10 +14,9 @@ declare const MIGRATE_RUN_STATUSES: readonly ['active', 'completed'];
 export type MigrateRunStatus = (typeof MIGRATE_RUN_STATUSES)[number];
 export interface MigrateRunRound {
     index: number;
-    planHash: string;
     planSnapshot: string;
 }
-declare const MIGRATE_STEP_STATUSES: readonly ['pending', 'dispensed', 'running', 'awaiting-prompt-outcome', 'succeeded', 'failed', 'skipped', 'died'];
+declare const MIGRATE_STEP_STATUSES: readonly ['pending', 'dispensed', 'running', 'awaiting-prompt-outcome', 'succeeded', 'failed', 'skipped', 'died', 'unresolved'];
 export type MigrateStepStatus = (typeof MIGRATE_STEP_STATUSES)[number];
 export declare const TERMINAL_STEP_STATUSES: ReadonlySet<MigrateStepStatus>;
 declare const PROMPT_OUTCOME_STATUSES: readonly ['completed', 'skipped', 'failed'];
@@ -50,6 +49,8 @@ export interface MigrateStep {
     depsHashAtDispense?: string;
     outcome?: MigrateStepOutcome;
     promptOutcome?: MigrateStepPromptOutcome;
+    adopted?: boolean;
+    unresolvedIssueId?: string;
     awaitingKind?: MigrateStepAwaitingKind;
     commitLedgerIndex?: number;
     commitStarted?: boolean;
@@ -112,6 +113,7 @@ export interface MigrateRunState {
     skipInstall?: boolean;
     validate?: boolean;
     runbookPath?: string;
+    branch?: string;
     rounds: MigrateRunRound[];
     steps: MigrateStep[];
     commits: MigrateCommitLedgerEntry[];
@@ -121,7 +123,7 @@ export interface MigrateRunState {
     treeOperation?: MigrateTreeOperation;
     analytics: MigrateRunAnalytics;
 }
-export declare const TREE_OPERATION_KINDS: readonly ['commit', 'install', 'fold-install', 'action-install', 'reset', 'checkpoint'];
+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 {
     kind: MigrateTreeOperationKind;
@@ -135,15 +137,14 @@ export declare function runDir(root: string, runId: string): string;
 /** See `HANDOFFS_DIR_NAME` for why the subtree exists. */
 export declare function runHandoffsDir(runDirPath: string): string;
 /**
- * Thrown when a run.json declares a `formatVersion` newer than this Nx
+ * Thrown for a run.json whose `formatVersion` is newer than this Nx
  * understands. Callers must not treat such a run as absent: an older Nx
  * ignoring a newer active run would start a competing run on top of it.
  *
- * Adding a member to any persisted closed set (run status, step status,
- * awaiting kind, prompt-outcome status, commit kind, issue disposition) needs a
- * `CURRENT_RUN_STATE_FORMAT_VERSION` bump: without it, an older Nx reading
- * the new value would reject the run as corrupt (the closed-set validation
- * fails) instead of refusing with this error's ask for a newer Nx.
+ * Adding a member to a persisted closed set needs a
+ * `CURRENT_RUN_STATE_FORMAT_VERSION` bump only once a released Nx can read the
+ * run, or that Nx rejects the new value as corruption instead of asking for a
+ * newer Nx.
  */
 export declare class NewerRunStateFormatError extends Error {
     constructor(message: string);
@@ -191,6 +192,7 @@ export declare function findActiveRun(root: string): {
         runId: string;
         state: MigrateRunState;
     } | null;
+    activeRunIds: string[];
     uninterpretable: UninterpretableRunDir[];
 };
 /**

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

@@ -82,12 +82,13 @@ const MIGRATE_STEP_STATUSES = [
     'failed',
     'skipped',
     'died',
+    'unresolved',
 ];
-// 'failed' and 'died' are not terminal: both can be re-armed into a fresh
-// attempt.
+// 'failed' and 'died' can be re-armed; 'unresolved' cannot.
 exports.TERMINAL_STEP_STATUSES = new Set([
     'succeeded',
     'skipped',
+    'unresolved',
 ]);
 const PROMPT_OUTCOME_STATUSES = ['completed', 'skipped', 'failed'];
 const MIGRATE_STEP_AWAITING_KINDS = [
@@ -118,6 +119,7 @@ exports.TREE_OPERATION_KINDS = [
     'fold-install',
     'action-install',
     'reset',
+    'give-up',
     'checkpoint',
 ];
 const REQUIRED_TOP_LEVEL_FIELDS = [
@@ -192,7 +194,6 @@ function isStepIdArray(value) {
 function isRoundShape(value) {
     return (isPlainObject(value) &&
         typeof value.index === 'number' &&
-        typeof value.planHash === 'string' &&
         typeof value.planSnapshot === 'string' &&
         PLAN_SNAPSHOT_NAME.test(value.planSnapshot));
 }
@@ -251,6 +252,11 @@ function isStepShape(value) {
         isOptionalBoolean(value.validationOwed) &&
         isOptionalBoolean(value.generatorMadeChanges) &&
         isOptionalBoolean(value.installFailed) &&
+        isOptionalBoolean(value.adopted) &&
+        isOptionalMatching(exports.ISSUE_ID, value.unresolvedIssueId) &&
+        // Minted by the same write that gives the step up, so it never names a
+        // step in any other status.
+        (value.unresolvedIssueId === undefined || value.status === 'unresolved') &&
         // A cross-field invariant the rest of the loop relies on: a running step
         // without a pid is never reclassified as died and no step action targets
         // it, so it stalls the run forever.
@@ -385,6 +391,7 @@ function hasValidRunStateShape(parsed) {
         isOptionalBoolean(parsed.skipInstall) &&
         isOptionalBoolean(parsed.validate) &&
         isOptionalMatching(RUNBOOK_NAME, parsed.runbookPath) &&
+        isOptionalString(parsed.branch) &&
         parsed.rounds.every(isRoundShape) &&
         parsed.steps.every(isStepShape) &&
         hasUniqueStepIds(parsed.steps) &&
@@ -398,24 +405,28 @@ function hasValidRunStateShape(parsed) {
         // Written only for issues that already existed: a dangling id could make a
         // future issue's resolution look carried by a commit that predates it.
         parsed.commits.every((c) => c.issueIds === undefined ||
-            c.issueIds.every((id) => (parsed.issues ?? []).some((i) => i.id === id))) &&
+            c.issueIds.every((id) => hasIssueWithId(parsed, id))) &&
+        parsed.steps.every((s) => s.unresolvedIssueId === undefined ||
+            hasIssueWithId(parsed, s.unresolvedIssueId)) &&
         isNoProgressShape(parsed.noProgress) &&
         isTreeOperationShape(parsed.treeOperation) &&
         isAnalyticsShape(parsed.analytics));
 }
+function hasIssueWithId(parsed, id) {
+    return (parsed.issues ?? []).some((i) => i.id === id);
+}
 function corruptRunStateError(filePath, reason) {
     return new Error(`Corrupt run state at ${filePath}: ${reason}`);
 }
 /**
- * Thrown when a run.json declares a `formatVersion` newer than this Nx
+ * Thrown for a run.json whose `formatVersion` is newer than this Nx
  * understands. Callers must not treat such a run as absent: an older Nx
  * ignoring a newer active run would start a competing run on top of it.
  *
- * Adding a member to any persisted closed set (run status, step status,
- * awaiting kind, prompt-outcome status, commit kind, issue disposition) needs a
- * `CURRENT_RUN_STATE_FORMAT_VERSION` bump: without it, an older Nx reading
- * the new value would reject the run as corrupt (the closed-set validation
- * fails) instead of refusing with this error's ask for a newer Nx.
+ * Adding a member to a persisted closed set needs a
+ * `CURRENT_RUN_STATE_FORMAT_VERSION` bump only once a released Nx can read the
+ * run, or that Nx rejects the new value as corruption instead of asking for a
+ * newer Nx.
  */
 class NewerRunStateFormatError extends Error {
     constructor(message) {
@@ -458,7 +469,7 @@ function readRunState(runDirPath) {
         const createdBy = typeof parsed.nxVersion === 'string'
             ? `Nx ${(0, text_1.singleLine)(parsed.nxVersion)}`
             : 'a newer version of Nx';
-        throw new NewerRunStateFormatError(`This migrate run was created with ${createdBy} (run state format v${parsed.formatVersion}), which is newer than the Nx version currently running, ${versions_1.nxVersion} (run state format v${exports.CURRENT_RUN_STATE_FORMAT_VERSION}). Re-run your migrate command with ${createdBy} or later to resume this run.`);
+        throw new NewerRunStateFormatError(`This migrate run was created with ${createdBy} (run state format v${parsed.formatVersion}), which is newer than the Nx version currently running, ${versions_1.nxVersion} (run state format v${exports.CURRENT_RUN_STATE_FORMAT_VERSION}). Re-run your migrate command with ${createdBy} or later.`);
     }
     if (REQUIRED_TOP_LEVEL_FIELDS.some((field) => !(field in parsed)) ||
         !hasValidRunStateShape(parsed)) {
@@ -541,6 +552,7 @@ function readRunDirState(candidateDir) {
  */
 function findActiveRun(root) {
     let newest = null;
+    const activeRunIds = [];
     const uninterpretable = [];
     for (const entry of readDirEntries(migrateRunsDir(root))) {
         if (!entry.isDirectory())
@@ -574,11 +586,12 @@ function findActiveRun(root) {
             });
             continue;
         }
+        activeRunIds.push(entry.name);
         if (!newest || state.createdAt > newest.state.createdAt) {
             newest = { runId: entry.name, state };
         }
     }
-    return { active: newest, uninterpretable };
+    return { active: newest, activeRunIds, uninterpretable };
 }
 /**
  * Creates a new run directory and writes its initial state, then prunes old

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

@@ -8,8 +8,9 @@ exports.renderRunbook = renderRunbook;
 const fragments_1 = require("../agentic/prompts/fragments");
 const types_1 = require("../agentic/types");
 const text_1 = require("../text");
-// A resume without a commit flag takes its policy from nx.json and refuses
-// the run when it differs from the recorded one.
+// A run's reconciles and workers skip the nx.json overlay and a continue takes
+// only `agentic` from it, but the next init reads the whole section: an edit
+// mid-run changes what a start-fresh or a later run does.
 const NX_JSON_MIGRATE_RULE = `  - Do not edit the \`migrate\` section of nx.json.`;
 exports.RUNBOOK_FILE_NAME = 'RUNBOOK.md';
 /**
@@ -71,6 +72,10 @@ 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.`,
+        ``,
         `## Agent work`,
         ``,
         `Some steps hand work back to you:`,
@@ -89,13 +94,13 @@ function renderRunbook(ctx) {
     if (ctx.validate) {
         lines.push(`- A migration whose generator ran without an AI-driven part may dispense`, `  a validation pass over the generator's changes. Scope rules for that`, `  work:`, ...(0, fragments_1.renderValidationScopeRuleLines)().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 retry and skip options for the step.`, ``, `- 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 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`, `  migration step should pick it up; it is carried to the completion`, `  report instead.`, `- \`issueUpdates\` may only reference issues the digest marks assigned 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.`, ``, `## Commits`, ``);
+    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 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`, `  migration step should pick it up; it is carried to the completion`, `  report instead.`, `- \`issueUpdates\` may only reference issues the digest marks assigned 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`, ``);
     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.`);
     }
     else {
         lines.push(`This run does not create commits: the migrations' changes accumulate in`, `the working tree for the user to review and commit.`);
     }
-    lines.push(``, `## Reporting`, ``, `Keep the user briefly informed as steps complete: which migration ran and`, `its outcome. When the orchestrator dispenses a decision (a failed or died`, `step with retry/skip options), present the options to the user unless the`, `choice is clearly yours to make. When the run is reported complete,`, `summarize the outcome for the user.`, ``);
+    lines.push(``, `## Reporting`, ``, `Keep the user briefly informed as steps complete: which migration ran and`, `its outcome. When the run is reported complete, summarize the outcome for`, `the user: what was applied, adopted, skipped, or left unresolved, and any`, `warnings the completion carries.`, ``);
     return lines.join('\n');
 }

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

@@ -23,3 +23,34 @@ export declare function withRunCreationLock<T>(root: string, fn: () => T): T;
  * corrupt or newer-format run.json propagates from the read.
  */
 export declare function updateRunState(runDirPath: string, apply: (fresh: MigrateRunState) => MigrateRunState | null): MigrateRunState;
+/**
+ * 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.
+ */
+export declare function holdRunActivity(root: string, runId: string, exclusive?: boolean): void;
+export declare function heldRunError(action: 'continuing' | 'deleting', runId: string, holders: number[] | 'unknown'): Error;
+export declare function describeHolders(holders: number[]): string;
+/**
+ * The hold without the creation lock: for the init that creates the run
+ * inside its own creation-lock section, so the run is never discoverable
+ * without a holder. Every other caller goes through holdRunActivity.
+ */
+export declare function registerRunActivity(dir: string): void;
+export declare function releaseRunActivity(dir: string): void;
+/**
+ * The pids of the other live processes holding the run, from their lock
+ * names. This process's own hold is skipped: a deleting init may hold the run
+ * from its report or preflight, which is not competing work. Locks left by
+ * dead holders are free. 'unknown' under WASM, and when the folder cannot be
+ * listed, a lock cannot be probed, or a held lock's name carries no pid.
+ */
+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.
+ */
+export declare function hasAnyLiveRunActivity(dir: string): boolean;

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

@@ -16,12 +16,21 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.withRunStateLock = withRunStateLock;
 exports.withRunCreationLock = withRunCreationLock;
 exports.updateRunState = updateRunState;
+exports.holdRunActivity = holdRunActivity;
+exports.heldRunError = heldRunError;
+exports.describeHolders = describeHolders;
+exports.registerRunActivity = registerRunActivity;
+exports.releaseRunActivity = releaseRunActivity;
+exports.liveRunActivityPids = liveRunActivityPids;
+exports.hasAnyLiveRunActivity = hasAnyLiveRunActivity;
+const crypto_1 = require("crypto");
 const fs_1 = require("fs");
 const path_1 = require("path");
 const native_1 = require("../../../native");
 const run_state_1 = require("./run-state");
 const STATE_LOCK_FILE_NAME = 'run.json.lock';
 const CREATION_LOCK_FILE_NAME = 'init.lock';
+const ACTIVITY_DIR_NAME = 'activity';
 function withFileLock(lockPath, fn) {
     if (native_1.IS_WASM) {
         return fn();
@@ -74,3 +83,120 @@ function updateRunState(runDirPath, apply) {
         return next;
     });
 }
+// The activity locks this process holds, one per run dir. Each is held until
+// the process exits (the kernel releases it) or until this process releases
+// it: deleting the run, or handing a continue off to the workspace-local nx.
+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.
+ */
+function holdRunActivity(root, runId, exclusive = false) {
+    if (native_1.IS_WASM)
+        return;
+    const dir = (0, run_state_1.runDir)(root, runId);
+    if (heldActivity.has(dir) && !exclusive)
+        return;
+    withRunCreationLock(root, () => {
+        if (!(0, run_state_1.hasRunState)(dir)) {
+            throw new Error(`Migrate run '${runId}' was deleted while this command was starting.`);
+        }
+        if (exclusive) {
+            const others = liveRunActivityPids(dir);
+            if (others === 'unknown' || others.length > 0) {
+                throw heldRunError('continuing', runId, others);
+            }
+        }
+        registerRunActivity(dir);
+    });
+}
+// '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) {
+    const refusal = `Not ${action} migrate run '${runId}'`;
+    return new Error(holders === 'unknown'
+        ? `${refusal}: nx cannot tell whether another nx migrate process is still working on it.`
+        : `${refusal}: ${describeHolders(holders)} (an agent session, a reconcile, or a step). Wait for it to end, then re-run the command.`);
+}
+function describeHolders(holders) {
+    return holders.length === 1
+        ? `process ${holders[0]} is still working on it`
+        : `processes ${holders.join(', ')} are still working on it`;
+}
+/**
+ * The hold without the creation lock: for the init that creates the run
+ * inside its own creation-lock section, so the run is never discoverable
+ * without a holder. Every other caller goes through holdRunActivity.
+ */
+function registerRunActivity(dir) {
+    if (native_1.IS_WASM || heldActivity.has(dir))
+        return;
+    const name = `${process.pid}-${(0, crypto_1.randomBytes)(4).toString('hex')}.lock`;
+    const lock = new native_1.FileLock((0, path_1.join)(dir, ACTIVITY_DIR_NAME, name));
+    lock.lock();
+    heldActivity.set(dir, { lock, name });
+}
+function releaseRunActivity(dir) {
+    const held = heldActivity.get(dir);
+    if (held === undefined)
+        return;
+    held.lock.unlock();
+    heldActivity.delete(dir);
+}
+/**
+ * The pids of the other live processes holding the run, from their lock
+ * names. This process's own hold is skipped: a deleting init may hold the run
+ * from its report or preflight, which is not competing work. Locks left by
+ * dead holders are free. 'unknown' under WASM, and when the folder cannot be
+ * listed, a lock cannot be probed, or a held lock's name carries no pid.
+ */
+function liveRunActivityPids(dir) {
+    if (native_1.IS_WASM)
+        return 'unknown';
+    const names = liveActivityNames(dir, heldActivity.get(dir)?.name);
+    if (names === 'unknown')
+        return 'unknown';
+    const pids = names.map((name) => Number(name.split('-', 1)[0]));
+    return pids.every((pid) => Number.isInteger(pid) && pid > 0)
+        ? pids
+        : '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.
+ */
+function hasAnyLiveRunActivity(dir) {
+    const names = liveActivityNames(dir, undefined);
+    return names === 'unknown' || names.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.
+function liveActivityNames(dir, skip) {
+    let names;
+    try {
+        names = (0, fs_1.readdirSync)((0, path_1.join)(dir, ACTIVITY_DIR_NAME));
+    }
+    catch (e) {
+        if (e?.code === 'ENOENT')
+            return [];
+        return 'unknown';
+    }
+    const held = [];
+    for (const name of names) {
+        if (name === skip)
+            continue;
+        try {
+            if (new native_1.FileLock((0, path_1.join)(dir, ACTIVITY_DIR_NAME, name)).check()) {
+                held.push(name);
+            }
+        }
+        catch {
+            return 'unknown';
+        }
+    }
+    return held;
+}

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

@@ -1,5 +1,6 @@
 import type { CommitResult } from '../migrate-commits';
 import type { MigrateCommitLedgerEntry, MigrateRunState, MigrateStep, MigrateStepAwaitingKind, MigrateStepOutcome, MigrateStepPromptOutcome } from './run-state';
+import type { MigrateOrchestratorTallies } from '../migrate-analytics';
 import type { StepAction } from '../step-actions';
 export type { StepAction };
 export type StepEvent = {
@@ -59,6 +60,19 @@ export declare function applyStepEvent(state: MigrateRunState, event: StepEvent)
  * commit already carries its changes.
  */
 export declare function discardGeneratorRun(state: MigrateRunState, stepId: string): MigrateRunState;
+export interface StepTally {
+    applied: number;
+    adopted: number;
+    skipped: number;
+    unresolved: MigrateStep[];
+    remaining: number;
+    stalled: number;
+}
+export declare function tallySteps(state: MigrateRunState): StepTally;
+export declare function runTallies(state: MigrateRunState): MigrateOrchestratorTallies;
+export declare function unresolvedFailureDetail(step: MigrateStep): string;
+export declare function completionSummaryLines(state: MigrateRunState): string[];
+export declare function unresolvedCommitName(step: MigrateStep): string;
 /**
  * Records that the run could not install the dependency changes a step left
  * behind. Not a {@link StepEvent}: it annotates a step instead of moving it,
@@ -102,6 +116,7 @@ export declare function stepsToPendingMigrations(state: MigrateRunState, stepIds
     package: string;
     name: string;
 }[];
+export declare function gitRan(result: CommitResult): boolean;
 /**
  * Classifies a commit attempt into the ledger entry to record, or null when
  * there is nothing to record ('no-changes' / 'disabled'). A landed entry