nx 23.2.1 → 23.3.0-beta.1

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

@@ -9,6 +9,7 @@ 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 declare const ISSUE_ID: RegExp;
 declare const MIGRATE_RUN_STATUSES: readonly ['active', 'completed'];
 export type MigrateRunStatus = (typeof MIGRATE_RUN_STATUSES)[number];
 export interface MigrateRunRound {
@@ -18,8 +19,11 @@ export interface MigrateRunRound {
 }
 declare const MIGRATE_STEP_STATUSES: readonly ['pending', 'dispensed', 'running', 'awaiting-prompt-outcome', 'succeeded', 'failed', 'skipped', 'died'];
 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'];
 export type PromptOutcomeStatus = (typeof PROMPT_OUTCOME_STATUSES)[number];
+declare const MIGRATE_STEP_AWAITING_KINDS: readonly ['migration-prompt', 'generator-validation'];
+export type MigrateStepAwaitingKind = (typeof MIGRATE_STEP_AWAITING_KINDS)[number];
 export interface MigrateStepOutcome {
     fileChanges?: string[];
     gitRefAfter?: string;
@@ -46,7 +50,12 @@ export interface MigrateStep {
     depsHashAtDispense?: string;
     outcome?: MigrateStepOutcome;
     promptOutcome?: MigrateStepPromptOutcome;
+    awaitingKind?: MigrateStepAwaitingKind;
     generatorCompleted?: boolean;
+    generatorCompletedAtAttempt?: number;
+    agenticWaived?: boolean;
+    validationOwed?: boolean;
+    generatorMadeChanges?: boolean;
     installFailed?: boolean;
 }
 declare const MIGRATE_COMMIT_KINDS: readonly ['checkpoint', 'landed', 'failed'];
@@ -55,11 +64,37 @@ export interface MigrateCommitLedgerEntry {
     sha?: string;
     kind: MigrateCommitKind;
     stepIds: string[];
+    issueIds?: string[];
+}
+/**
+ * Dedup key: the same underlying problem reported twice folds into one ledger
+ * entry. Derived from the normalized summary, so agent text never becomes a
+ * path or command fragment; the state reader re-checks the derivation on
+ * every persisted entry.
+ */
+export declare function issueFingerprint(summary: string): string;
+export declare const MIGRATE_ISSUE_DISPOSITIONS: readonly ['recorded', 'resolved', 'deferred-final'];
+export type MigrateIssueDisposition = (typeof MIGRATE_ISSUE_DISPOSITIONS)[number];
+export interface MigrateRunIssue {
+    id: string;
+    fingerprint: string;
+    summary: string;
+    reportedByStepId: string;
+    applicableStepIds: string[] | 'unknown';
+    disposition: MigrateIssueDisposition;
+    claimedByStepId?: string;
+    resolvedByStepId?: string;
+    resolvedAtCommitCount?: number;
 }
 export interface MigrateRunAnalytics {
     startEmitted: boolean;
     completeEmitted: boolean;
 }
+export interface MigrateRunNoProgress {
+    fingerprint: string;
+    consecutiveCount: number;
+    firstSeenAt: string;
+}
 export interface MigrateRunState {
     formatVersion: number;
     runId: string;
@@ -69,9 +104,13 @@ export interface MigrateRunState {
     createCommits: boolean;
     commitPrefix: string;
     skipInstall?: boolean;
+    validate?: boolean;
+    runbookPath?: string;
     rounds: MigrateRunRound[];
     steps: MigrateStep[];
     commits: MigrateCommitLedgerEntry[];
+    issues?: MigrateRunIssue[];
+    noProgress?: MigrateRunNoProgress;
     checkpointFailed?: boolean;
     analytics: MigrateRunAnalytics;
 }
@@ -85,7 +124,7 @@ export declare function runHandoffsDir(runDirPath: string): string;
  * 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,
- * prompt-outcome status, commit kind) needs a
+ * 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.
@@ -94,13 +133,9 @@ export declare class NewerRunStateFormatError extends Error {
     constructor(message: string);
 }
 /**
- * Reads and validates `run.json` from a run directory.
- *
- * A `formatVersion` newer than {@link CURRENT_RUN_STATE_FORMAT_VERSION} means
- * the run was created by a newer Nx than the one currently running, so the
- * shape may not be interpretable here; this throws rather than attempting a
- * best-effort read. An older `formatVersion` is returned as-is: only v1
- * exists today, so there is nothing to migrate yet.
+ * Reads and validates `run.json` from a run directory. A `formatVersion`
+ * newer than {@link CURRENT_RUN_STATE_FORMAT_VERSION} throws instead of being
+ * read best-effort; an older one is returned as-is.
  */
 export declare function readRunState(runDirPath: string): MigrateRunState;
 /**

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NewerRunStateFormatError = exports.SHELL_SAFE_VALUE = exports.RUN_STATE_FILE_NAME = exports.CURRENT_RUN_STATE_FORMAT_VERSION = void 0;
+exports.NewerRunStateFormatError = 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.issueFingerprint = issueFingerprint;
 exports.migrateRunsDir = migrateRunsDir;
 exports.runDir = runDir;
 exports.runHandoffsDir = runHandoffsDir;
@@ -13,6 +14,7 @@ const fs_1 = require("fs");
 const crypto_1 = require("crypto");
 const path_1 = require("path");
 const fileutils_1 = require("../../../utils/fileutils");
+const atomic_write_1 = require("./atomic-write");
 const git_utils_1 = require("../../../utils/git-utils");
 const versions_1 = require("../../../utils/versions");
 const types_1 = require("../agentic/types");
@@ -48,7 +50,21 @@ const PLAN_SNAPSHOT_NAME = /^plan-\d+\.json$/;
  * transition with, and the worker throws that reason, which puts it in front
  * of the agent without passing the block-safe writer.
  */
-const STEP_ID = /^step-\d+$/;
+const STEP_ID = /^step-\d{1,18}$/;
+// The id names the archived detail file in the run's issues directory, so a
+// tampered value must not resolve outside it. The suffix is bounded so the
+// allocator, which mints against this same pattern, can never produce an id
+// past the filesystem's component limit and then fail forever.
+exports.ISSUE_ID = /^issue-\d{1,18}$/;
+/**
+ * A resume joins this to the run directory and re-emits the file's bytes
+ * verbatim, so a tampered value naming a sibling (`run.json`, a plan
+ * snapshot) would leak that file's bytes past every line-safety check.
+ */
+const RUNBOOK_NAME = /^RUNBOOK\.md$/;
+// The terminators `singleLine` collapses. An embedded one could open a forged
+// block at a line start in the stdout the agent scans.
+const LINE_TERMINATORS = /[\r\n\u000b\u000c\u0085\u2028\u2029]/;
 // Keeps `.nx/migrate-runs` from growing unbounded across many `nx migrate`
 // invocations over the life of a workspace.
 const MAX_RETAINED_COMPLETED_RUNS = 5;
@@ -66,8 +82,35 @@ const MIGRATE_STEP_STATUSES = [
     'skipped',
     'died',
 ];
+// 'failed' and 'died' are not terminal: both can be re-armed into a fresh
+// attempt.
+exports.TERMINAL_STEP_STATUSES = new Set([
+    'succeeded',
+    'skipped',
+]);
 const PROMPT_OUTCOME_STATUSES = ['completed', 'skipped', 'failed'];
+const MIGRATE_STEP_AWAITING_KINDS = [
+    'migration-prompt',
+    'generator-validation',
+];
 const MIGRATE_COMMIT_KINDS = ['checkpoint', 'landed', 'failed'];
+/**
+ * Dedup key: the same underlying problem reported twice folds into one ledger
+ * entry. Derived from the normalized summary, so agent text never becomes a
+ * path or command fragment; the state reader re-checks the derivation on
+ * every persisted entry.
+ */
+function issueFingerprint(summary) {
+    return (0, crypto_1.createHash)('sha256')
+        .update(summary.toLowerCase().replace(/\s+/g, ' ').trim())
+        .digest('hex')
+        .slice(0, 16);
+}
+exports.MIGRATE_ISSUE_DISPOSITIONS = [
+    'recorded',
+    'resolved',
+    'deferred-final',
+];
 const REQUIRED_TOP_LEVEL_FIELDS = [
     'formatVersion',
     'runId',
@@ -127,6 +170,16 @@ function isOptionalStringArray(value) {
     return (value === undefined ||
         (Array.isArray(value) && value.every((item) => typeof item === 'string')));
 }
+function isOptionalMatching(pattern, value) {
+    return (value === undefined || (typeof value === 'string' && pattern.test(value)));
+}
+function isLineSafeString(value) {
+    return typeof value === 'string' && !LINE_TERMINATORS.test(value);
+}
+function isStepIdArray(value) {
+    return (Array.isArray(value) &&
+        value.every((id) => typeof id === 'string' && STEP_ID.test(id)));
+}
 function isRoundShape(value) {
     return (isPlainObject(value) &&
         typeof value.index === 'number' &&
@@ -156,7 +209,11 @@ function isStepShape(value) {
         typeof value.migrationId === 'string' &&
         exports.SHELL_SAFE_VALUE.test(value.migrationId) &&
         isOneOf(MIGRATE_STEP_STATUSES, value.status) &&
-        typeof value.attempt === 'number' &&
+        // The attempt is interpolated into the stored-payload file name and
+        // range-compared against it (agent-work-payload.ts), so a fractional or
+        // non-finite value (JSON's 1e400 parses to Infinity) must be refused here.
+        Number.isSafeInteger(value.attempt) &&
+        value.attempt >= 1 &&
         typeof value.dispenseCount === 'number' &&
         isOptionalBoolean(value.hasGenerator) &&
         isOptionalNumber(value.pid) &&
@@ -167,7 +224,19 @@ function isStepShape(value) {
         isOptionalString(value.depsHashAtDispense) &&
         isStepOutcomeShape(value.outcome) &&
         isPromptOutcomeShape(value.promptOutcome) &&
+        (value.awaitingKind === undefined ||
+            isOneOf(MIGRATE_STEP_AWAITING_KINDS, value.awaitingKind)) &&
         isOptionalBoolean(value.generatorCompleted) &&
+        // Bounded by the step's attempt: a higher value could not name one that
+        // exists.
+        (value.generatorCompletedAtAttempt === undefined ||
+            (Number.isSafeInteger(value.generatorCompletedAtAttempt) &&
+                value.generatorCompletedAtAttempt >= 1 &&
+                value.generatorCompletedAtAttempt <=
+                    value.attempt)) &&
+        isOptionalBoolean(value.agenticWaived) &&
+        isOptionalBoolean(value.validationOwed) &&
+        isOptionalBoolean(value.generatorMadeChanges) &&
         isOptionalBoolean(value.installFailed) &&
         // 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
@@ -177,9 +246,97 @@ function isStepShape(value) {
 function isCommitLedgerEntryShape(value) {
     return (isPlainObject(value) &&
         isOneOf(MIGRATE_COMMIT_KINDS, value.kind) &&
-        Array.isArray(value.stepIds) &&
-        value.stepIds.every((id) => typeof id === 'string' && STEP_ID.test(id)) &&
-        isOptionalSha(value.sha));
+        isStepIdArray(value.stepIds) &&
+        isOptionalSha(value.sha) &&
+        (value.issueIds === undefined ||
+            (Array.isArray(value.issueIds) &&
+                value.issueIds.every((id) => typeof id === 'string' && exports.ISSUE_ID.test(id)))));
+}
+// The id names the archived `issues/<id>.json`, so a duplicate would alias two
+// entries onto one file. Runs after isIssueShape, so the ids are known strings.
+function hasUniqueIssueIds(issues) {
+    return (new Set(issues.map((issue) => issue.id)).size ===
+        issues.length);
+}
+// A duplicate would make every step lookup ambiguous, and a bare-package
+// report against it would write applicability this same reader rejects.
+function hasUniqueStepIds(steps) {
+    return (new Set(steps.map((step) => step.id)).size ===
+        steps.length);
+}
+// The fingerprint is the duplicate-report fold key; two entries sharing one
+// would make ledger order decide which entry a report folds into.
+function hasUniqueIssueFingerprints(issues) {
+    return (new Set(issues.map((issue) => issue.fingerprint)).size === issues.length);
+}
+// Cross-entry references, checked after the per-entry shapes so the casts
+// hold. nx never writes these violations, and the helpers that trust the
+// fields (routing, resolver credit, carried checks) cannot repair them.
+function hasSoundIssueRefs(parsed) {
+    const issues = parsed.issues;
+    const steps = parsed.steps;
+    const stepIds = new Set(steps.map((s) => s.id));
+    const stepOrder = new Map(steps.map((s, index) => [s.id, index]));
+    const commitCount = parsed.commits.length;
+    return issues.every((issue) => stepIds.has(issue.reportedByStepId) &&
+        (issue.applicableStepIds === 'unknown' ||
+            (issue.applicableStepIds.every((id) => stepIds.has(id)) &&
+                // Applicability is a plan-ordered set (mints and merges both emit it that
+                // way): a duplicate would read as newly supplied routing in the normalizing
+                // merge, and an unordered scope is a shape no transition writes.
+                issue.applicableStepIds.every((id, index) => index === 0 ||
+                    stepOrder.get(issue.applicableStepIds[index - 1]) <
+                        stepOrder.get(id)))) &&
+        (issue.claimedByStepId === undefined ||
+            (Array.isArray(issue.applicableStepIds) &&
+                issue.applicableStepIds.includes(issue.claimedByStepId))) &&
+        (issue.resolvedByStepId === undefined ||
+            stepIds.has(issue.resolvedByStepId)) &&
+        (issue.resolvedAtCommitCount === undefined ||
+            issue.resolvedAtCommitCount <= commitCount));
+}
+function isIssueShape(value) {
+    return (isPlainObject(value) &&
+        typeof value.id === 'string' &&
+        exports.ISSUE_ID.test(value.id) &&
+        isLineSafeString(value.summary) &&
+        // The derivation is enforced, not just the shape: a fingerprint detached from
+        // its summary would split one problem into independent histories.
+        value.fingerprint === issueFingerprint(value.summary) &&
+        typeof value.reportedByStepId === 'string' &&
+        STEP_ID.test(value.reportedByStepId) &&
+        // Reports carry 1+ identifiers and merges only widen, so [] is unproducible.
+        (value.applicableStepIds === 'unknown' ||
+            (isStepIdArray(value.applicableStepIds) &&
+                value.applicableStepIds.length > 0)) &&
+        isOneOf(exports.MIGRATE_ISSUE_DISPOSITIONS, value.disposition) &&
+        isOptionalMatching(STEP_ID, value.claimedByStepId) &&
+        isOptionalMatching(STEP_ID, value.resolvedByStepId) &&
+        // The helpers built on these (commit association, retry-clean reverts, update
+        // ownership) break on a state outside them.
+        (value.claimedByStepId === undefined || value.disposition === 'recorded') &&
+        (value.disposition === 'resolved') ===
+            (value.resolvedByStepId !== undefined) &&
+        // A resolution without a stamp has no carried-commit window; a stamp without
+        // a resolution fences nothing that exists.
+        (value.disposition === 'resolved') ===
+            (value.resolvedAtCommitCount !== undefined) &&
+        (value.resolvedAtCommitCount === undefined ||
+            (Number.isSafeInteger(value.resolvedAtCommitCount) &&
+                value.resolvedAtCommitCount >= 0)));
+}
+// The record drives the no-progress cutoff: a count outside the positive
+// integers (JSON's 1e400 parses to Infinity) could delay it forever, and an
+// empty fingerprint would collapse unrelated responses into one streak.
+function isNoProgressShape(value) {
+    return (value === undefined ||
+        (isPlainObject(value) &&
+            isLineSafeString(value.fingerprint) &&
+            value.fingerprint.length > 0 &&
+            Number.isSafeInteger(value.consecutiveCount) &&
+            value.consecutiveCount > 0 &&
+            typeof value.firstSeenAt === 'string' &&
+            ISO_TIMESTAMP.test(value.firstSeenAt)));
 }
 function isAnalyticsShape(value) {
     return (isPlainObject(value) &&
@@ -200,9 +357,23 @@ function hasValidRunStateShape(parsed) {
         isOneOf(MIGRATE_RUN_STATUSES, parsed.status) &&
         isOptionalBoolean(parsed.checkpointFailed) &&
         isOptionalBoolean(parsed.skipInstall) &&
+        isOptionalBoolean(parsed.validate) &&
+        isOptionalMatching(RUNBOOK_NAME, parsed.runbookPath) &&
         parsed.rounds.every(isRoundShape) &&
         parsed.steps.every(isStepShape) &&
+        hasUniqueStepIds(parsed.steps) &&
         parsed.commits.every(isCommitLedgerEntryShape) &&
+        (parsed.issues === undefined ||
+            (Array.isArray(parsed.issues) &&
+                parsed.issues.every(isIssueShape) &&
+                hasUniqueIssueIds(parsed.issues) &&
+                hasUniqueIssueFingerprints(parsed.issues) &&
+                hasSoundIssueRefs(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))) &&
+        isNoProgressShape(parsed.noProgress) &&
         isAnalyticsShape(parsed.analytics));
 }
 function corruptRunStateError(filePath, reason) {
@@ -214,7 +385,7 @@ function corruptRunStateError(filePath, reason) {
  * 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,
- * prompt-outcome status, commit kind) needs a
+ * 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.
@@ -227,13 +398,9 @@ class NewerRunStateFormatError extends Error {
 }
 exports.NewerRunStateFormatError = NewerRunStateFormatError;
 /**
- * Reads and validates `run.json` from a run directory.
- *
- * A `formatVersion` newer than {@link CURRENT_RUN_STATE_FORMAT_VERSION} means
- * the run was created by a newer Nx than the one currently running, so the
- * shape may not be interpretable here; this throws rather than attempting a
- * best-effort read. An older `formatVersion` is returned as-is: only v1
- * exists today, so there is nothing to migrate yet.
+ * Reads and validates `run.json` from a run directory. A `formatVersion`
+ * newer than {@link CURRENT_RUN_STATE_FORMAT_VERSION} throws instead of being
+ * read best-effort; an older one is returned as-is.
  */
 function readRunState(runDirPath) {
     const filePath = (0, path_1.join)(runDirPath, exports.RUN_STATE_FILE_NAME);
@@ -288,9 +455,7 @@ function readRunState(runDirPath) {
  */
 function writeRunState(runDirPath, state) {
     const filePath = (0, path_1.join)(runDirPath, exports.RUN_STATE_FILE_NAME);
-    const tmpPath = `${filePath}~${(0, crypto_1.randomBytes)(4).toString('hex')}`;
-    (0, fileutils_1.writeJsonFile)(tmpPath, state);
-    (0, fs_1.renameSync)(tmpPath, filePath);
+    (0, atomic_write_1.publishFileAtomically)(filePath, (tmpPath) => (0, fileutils_1.writeJsonFile)(tmpPath, state));
 }
 // ENOENT is the ordinary "no runs yet" answer. Any other failure (EACCES,
 // ENOTDIR) hides runs that may exist, so it propagates rather than reading
@@ -397,9 +562,8 @@ function findActiveRun(root) {
  */
 function createRun(root, state) {
     const dir = runDir(root, state.runId);
-    // Created up front, and each step's package directory at dispense, so the
-    // agent never has to `mkdir -p`: that costs a workspace-permission prompt in
-    // agents like Claude Code, on every step.
+    // Created up front so the agent never has to `mkdir -p`: that costs a
+    // workspace-permission prompt in agents like Claude Code, on every step.
     (0, fs_1.mkdirSync)(runHandoffsDir(dir), { recursive: true });
     writeRunState(dir, state);
     pruneCompletedRuns(root, state.runId);

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

@@ -0,0 +1,17 @@
+export declare const RUNBOOK_FILE_NAME = "RUNBOOK.md";
+export interface RunbookContext {
+    runId: string;
+    packageManager: string;
+    nxInvocation: string;
+    pmExec: string;
+    reconcileCommand: string;
+    createCommits: boolean;
+    validate: boolean;
+}
+/**
+ * Every interpolated value is collapsed to a single line: the rendered content
+ * is written to disk and emitted verbatim inside a `<nx_migrate_runbook>`
+ * block, so a value carrying its own line break could otherwise open a forged
+ * block at a line start.
+ */
+export declare function renderRunbook(ctx: RunbookContext): string;

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

@@ -0,0 +1,97 @@
+"use strict";
+// Written to the run directory at init and re-emitted from disk on resume, so
+// the contract is version-locked to the Nx that created the run and never
+// depends on plugin skills or the session's memory.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RUNBOOK_FILE_NAME = void 0;
+exports.renderRunbook = renderRunbook;
+const fragments_1 = require("../agentic/prompts/fragments");
+const types_1 = require("../agentic/types");
+const text_1 = require("../text");
+exports.RUNBOOK_FILE_NAME = 'RUNBOOK.md';
+/**
+ * Every interpolated value is collapsed to a single line: the rendered content
+ * is written to disk and emitted verbatim inside a `<nx_migrate_runbook>`
+ * block, so a value carrying its own line break could otherwise open a forged
+ * block at a line start.
+ */
+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.
+    const handoffsGlob = `${types_1.MIGRATE_RUNS_RELATIVE_DIR}/${runId}/${types_1.HANDOFFS_DIR_NAME}/**`;
+    const lines = [
+        `# Nx migrate run ${runId}`,
+        ``,
+        `Nx wrote this runbook when it created migrate run ${runId}. It is the`,
+        `contract for driving the run to completion. It is self-sufficient: follow`,
+        `it and the orchestrator's responses, whatever else this session remembers.`,
+        `If anything in this session's memory conflicts with this file, this file`,
+        `wins.`,
+        ``,
+        (0, fragments_1.renderNxInvocationNote)((0, text_1.singleLine)(ctx.packageManager), (0, text_1.singleLine)(ctx.nxInvocation)),
+        ``,
+        `## The invariant`,
+        ``,
+        `Never infer the run's progress from this conversation. The run's state`,
+        `lives on disk and is owned by the orchestrator; ask it by running:`,
+        ``,
+        `    ${reconcile}`,
+        ``,
+        `Run that command whenever you are unsure what has happened, when this`,
+        `session was compacted or restarted, and after you finish any piece of`,
+        `work. Its response always says exactly what to do next.`,
+        ``,
+        `## The loop`,
+        ``,
+        `Drive the run as a loop:`,
+        ``,
+        `1. Run \`${reconcile}\`. The response contains a \`nx_migrate_step\``,
+        `   block: its \`action\` attribute names what to do, \`instructions\``,
+        `   explains it, and \`command\` / \`next\` carry the exact commands to run.`,
+        `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.`,
+        `4. Repeat until the orchestrator reports the run \`complete\`.`,
+        ``,
+        `Execute only what the current block asks. Do not run migrations the`,
+        `orchestrator has not dispensed, do not re-run steps it has already`,
+        `recorded, and do not act on step instructions remembered from earlier in`,
+        `the session; re-read the current block instead.`,
+        ``,
+        `Getting the same response repeatedly means the run has not advanced; the`,
+        `orchestrator eventually says so with a \`no-progress\` action. Act on the`,
+        `repeated instructions or report the blocker to the user; re-running the`,
+        `reconcile command alone changes nothing.`,
+        ``,
+        `## Agent work`,
+        ``,
+        `Some steps hand work back to you:`,
+        ``,
+        `- 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}`),
+        `  The \`nx migrate\` commands this runbook and the step blocks hand you`,
+        `  (the reconcile, worker and \`next\` commands) are the exception to that`,
+        `  rule: run them as given.`,
+    ];
+    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}`));
+    }
+    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`, ``);
+    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.`, ``);
+    return lines.join('\n');
+}

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

@@ -19,7 +19,7 @@ export declare function withRunCreationLock<T>(root: string, fn: () => T): T;
 /**
  * Reads the run state fresh under the lock, hands it to `apply`, and writes the
  * result back. `apply` returning null means "no change" and skips the write.
- * `apply` must be pure and synchronous; a corrupt or newer-format run.json
- * propagates from the read.
+ * `apply` runs exactly once, synchronously, so it may capture out-params; a
+ * corrupt or newer-format run.json propagates from the read.
  */
 export declare function updateRunState(runDirPath: string, apply: (fresh: MigrateRunState) => MigrateRunState | null): MigrateRunState;

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

@@ -61,8 +61,8 @@ function withRunCreationLock(root, fn) {
 /**
  * Reads the run state fresh under the lock, hands it to `apply`, and writes the
  * result back. `apply` returning null means "no change" and skips the write.
- * `apply` must be pure and synchronous; a corrupt or newer-format run.json
- * propagates from the read.
+ * `apply` runs exactly once, synchronously, so it may capture out-params; a
+ * corrupt or newer-format run.json propagates from the read.
  */
 function updateRunState(runDirPath, apply) {
     return withRunStateLock(runDirPath, () => {

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

@@ -1,5 +1,5 @@
 import type { CommitResult } from '../migrate-commits';
-import type { MigrateCommitLedgerEntry, MigrateRunState, MigrateStepOutcome, MigrateStepPromptOutcome } from './run-state';
+import type { MigrateCommitLedgerEntry, MigrateRunState, MigrateStepAwaitingKind, MigrateStepOutcome, MigrateStepPromptOutcome } from './run-state';
 import type { StepAction } from '../step-actions';
 export type { StepAction };
 export type StepEvent = {
@@ -24,6 +24,7 @@ export type StepEvent = {
     type: 'awaitPromptOutcome';
     stepId: string;
     finishedAt: string;
+    awaitingKind: MigrateStepAwaitingKind;
 } | {
     type: 'foldPromptOutcome';
     stepId: string;
@@ -32,6 +33,9 @@ export type StepEvent = {
 } | {
     type: 'markGeneratorCompleted';
     stepId: string;
+    agenticWaived: boolean;
+    validationOwed: boolean;
+    madeChanges: boolean;
 } | {
     type: 'markDied';
     stepId: string;

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

@@ -68,11 +68,21 @@ function applyStepEvent(state, event) {
                 ...step,
                 status: 'awaiting-prompt-outcome',
                 finishedAt: event.finishedAt,
+                awaitingKind: event.awaitingKind,
             });
         case 'markGeneratorCompleted':
             if (step.status !== 'running')
                 return illegal(step, event.type);
-            return commit(state, index, { ...step, generatorCompleted: true });
+            return commit(state, index, {
+                ...step,
+                generatorCompleted: true,
+                generatorCompletedAtAttempt: step.attempt,
+                ...(event.agenticWaived ? { agenticWaived: true } : {}),
+                ...(event.validationOwed ? { validationOwed: true } : {}),
+                // Written even when false, unlike the conditional spreads above: absent is
+                // reserved for markers an older nx wrote.
+                generatorMadeChanges: event.madeChanges,
+            });
         case 'foldPromptOutcome':
             if (step.status !== 'awaiting-prompt-outcome')
                 return illegal(step, event.type);
@@ -195,6 +205,22 @@ function rearm(step, keepGeneratorCompleted) {
         ...(keepGeneratorCompleted && step.generatorCompleted
             ? { generatorCompleted: true }
             : {}),
+        ...(keepGeneratorCompleted &&
+            step.generatorCompleted &&
+            step.generatorCompletedAtAttempt !== undefined
+            ? { generatorCompletedAtAttempt: step.generatorCompletedAtAttempt }
+            : {}),
+        ...(keepGeneratorCompleted && step.generatorCompleted && step.agenticWaived
+            ? { agenticWaived: true }
+            : {}),
+        ...(keepGeneratorCompleted && step.generatorCompleted && step.validationOwed
+            ? { validationOwed: true }
+            : {}),
+        ...(keepGeneratorCompleted &&
+            step.generatorCompleted &&
+            step.generatorMadeChanges !== undefined
+            ? { generatorMadeChanges: step.generatorMadeChanges }
+            : {}),
     };
 }
 // A guarded transition whose observation was made against an earlier attempt