@depup/nx 23.2.1-depup.7 → 23.3.0-depup.0

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

@@ -7,7 +7,6 @@ const git_utils_1 = require("../../../utils/git-utils");
 const fileutils_1 = require("../../../utils/fileutils");
 const installation_directory_1 = require("../../../utils/installation-directory");
 const package_json_1 = require("../../../utils/package-json");
-const inception_1 = require("../agentic/inception");
 const print_dropped_agent_context_1 = require("../agentic/print-dropped-agent-context");
 const select_1 = require("../agentic/select");
 const types_1 = require("../agentic/types");
@@ -23,8 +22,11 @@ const run_id_1 = require("./run-id");
 const state_machine_1 = require("./state-machine");
 const state_lock_1 = require("./state-lock");
 const util_1 = require("./util");
+const broker_1 = require("./broker");
 const text_1 = require("../text");
 const agent_output_1 = require("./agent-output");
+const agent_work_payload_1 = require("./agent-work-payload");
+const issues_1 = require("./issues");
 async function runSingleMigrationWorker(input) {
     const { root, runMigration, runId, commitPrefix, interactive, skipInstall, isVerbose, } = input;
     // The worker is a second CLI entry point: the run id reaches runDir() (where
@@ -97,13 +99,15 @@ async function runSingleMigrationWorker(input) {
 function readMigrationsSource(root, runId) {
     if (runId) {
         const dir = (0, run_state_1.runDir)(root, runId);
-        // A missing run.json would surface a raw ENOENT from readRunState's
-        // readFileSync; report it the way the orchestrator does instead, down to
-        // carrying no remediation: starting a run is a separate, gated entry point,
-        // and `--run-migrations` would run the whole plan in process instead.
+        // A missing run.json would surface a raw ENOENT from readRunState; report
+        // it the way the orchestrator does instead, with no remediation: starting
+        // a run is a gated entry point of its own.
         if (!(0, run_state_1.hasRunState)(dir)) {
             throw new Error(`No migrate run '${runId}' was found under ${types_1.MIGRATE_RUNS_RELATIVE_DIR}.`);
         }
+        // Before the state and plan reads: a concurrent start-fresh must not
+        // delete the run while this worker resolves its migration.
+        (0, state_lock_1.holdRunActivity)(root, runId);
         // Version refusal (NewerRunStateFormatError) propagates.
         const state = (0, run_state_1.readRunState)(dir);
         const round = (0, state_machine_1.latestRound)(state);
@@ -317,27 +321,31 @@ async function runStandalone(root, migration, opts) {
     // and no "apply this manually" block for the user either.
     if ((0, migration_shape_1.isHybridMigration)(migration) && !skipAgentic) {
         emitOrPrintPrompt(root, migration, agentic.kind, {
-            logs,
-            changes,
-            agentContext,
-        }, resolvedCollection);
+            impl: {
+                logs,
+                changes,
+                agentContext,
+            },
+            resolvedCollection,
+        });
     }
 }
 async function runRecorded(root, runId, migration, skipInstall, isVerbose) {
     const dir = (0, run_state_1.runDir)(root, runId);
     // Version refusal (NewerRunStateFormatError) propagates.
     let state = (0, run_state_1.readRunState)(dir);
-    // A recorded run never resolves the agentic flow (the outer agent drives
-    // it); prompts are emitted for that agent or printed for a user hand-running
-    // the dispensed command.
-    const agenticKind = (0, inception_1.isInsideAgent)()
-        ? 'inside-agent'
-        : 'disabled';
+    // A recorded run never resolves the agentic flow: the outer agent drives it,
+    // and the dispensed command is part of the orchestrated protocol whoever
+    // re-runs it. Gating the block on ambient agent detection would park the
+    // step awaiting an outcome whose payload was never emitted.
+    const agenticKind = 'inside-agent';
     const migrationId = `${migration.package}:${migration.name}`;
     // The plan was read from the latest round's snapshot, so only that round's
     // step may match; a same-id step from an older round must not.
     const latest = (0, state_machine_1.latestRound)(state);
-    const step = state.steps.find((s) => s.migrationId === migrationId && s.roundIndex === latest?.index);
+    const step = state.steps.find((s) => s.kind === 'migration' &&
+        s.migrationId === migrationId &&
+        s.roundIndex === latest?.index);
     if (!step) {
         throw new Error(`The migrate run '${runId}' has no step for migration '${migrationId}'.`);
     }
@@ -350,99 +358,185 @@ async function runRecorded(root, runId, migration, skipInstall, isVerbose) {
         startedAt: (0, util_1.nowIso)(),
     });
     // A prior attempt's generator half already ran, so this attempt must not
-    // reapply it against a tree that already holds its changes: a hybrid
-    // re-emits only its prompt, and a plain generator step has nothing left to
-    // do but the install and commit its previous attempt failed on.
-    // Read from the state the start transition returned: a delayed invocation
-    // may have claimed a later attempt whose flag its entry snapshot predates.
+    // reapply it against a tree that already holds its changes. Read from the
+    // state the start transition returned, not the entry snapshot: a delayed
+    // invocation may have claimed a later attempt whose flag `step` predates.
     const startedStep = state.steps.find((s) => s.id === step.id);
     const generatorAlreadyCompleted = startedStep.generatorCompleted === true;
-    // The run records its own install policy because dispensed worker commands
-    // are re-invoked by the loop and never carry the user's flags; an explicit
-    // --skip-install on this invocation still applies on top of it.
+    // Dispensed worker commands never carry the user's flags, so the run records
+    // its install policy. An explicit --skip-install here applies only to the
+    // installs this process runs itself; a parent session answers from its own.
     const effectiveSkipInstall = state.skipInstall === true || skipInstall;
+    // The run records the resolved validation policy at init; absent (a state
+    // predating the field) falls back to the same default init applies.
+    const shouldValidate = state.validate !== false;
+    // The tree reservation an in-process install or commit takes is held until
+    // the transition that records this attempt's outcome is written.
+    const scope = {};
+    // Called before a retry hands the step's work back: the prompt or validation
+    // may need the dependencies the earlier attempt's generator added.
+    const reinstallFromBaseline = () => (0, broker_1.installStepTree)(dir, startedStep, 'install', () => recordingInstallFailure(dir, step.id, () => (0, util_1.installDepsChangedSinceDispense)(root, dir, startedStep, effectiveSkipInstall, `${(0, execute_migration_1.formatSingleMigrationRerunCommand)(migrationId)} --run-id=${runId}`)), scope);
     let outcome;
+    let awaitingKind;
+    const payloadPath = (0, agent_work_payload_1.agentWorkPayloadPath)(dir, step.id, startedStep.attempt);
     try {
-        if ((0, migration_shape_1.isPromptOnlyMigration)(migration) ||
-            (generatorAlreadyCompleted && (0, migration_shape_1.isHybridMigration)(migration))) {
-            emitOrPrintPrompt(root, migration, agenticKind);
-        }
-        else if (generatorAlreadyCompleted) {
-            state = await finishCompletedGenerator(dir, root, state, startedStep, migration, effectiveSkipInstall, runId);
-            outcome = buildOutcome([], [], 'The generator ran in an earlier attempt; this attempt completed its install and commit.', root);
-        }
-        else {
-            const installer = new execute_migration_1.ChangedDepInstaller(root, effectiveSkipInstall, `${(0, execute_migration_1.formatSingleMigrationRerunCommand)(migrationId)} --run-id=${runId}`);
-            // Read once; the run and the hybrid documentation resolution share it.
-            const resolvedCollection = (0, execute_migration_1.readMigrationCollection)(migration.package, root);
-            const { changes, nextSteps, agentContext, logs, madeChanges } = await (0, execute_migration_1.runNxOrAngularMigration)(root, migration, isVerbose, (0, migration_shape_1.isHybridMigration)(migration), resolvedCollection);
-            // Recorded before the commit is attempted: from here on the changes are
-            // in the tree, so a failed install or commit must leave a retry with
-            // only those left to do rather than running the generator again.
-            state = transition(dir, {
-                type: 'markGeneratorCompleted',
-                stepId: step.id,
-            });
-            if (!(0, migration_shape_1.isHybridMigration)(migration)) {
-                forwardDroppedAgentContext(migration, agentContext, agenticKind);
-            }
-            const install = () => recordingInstallFailure(dir, step.id, () => installer.installDepsIfChanged());
-            // Commits follow the run config, not CLI flags, and only when the
-            // generator changed something: a no-op step must not create a commit (nor
-            // a ledger entry) that absorbs prior pending diffs under its name.
-            if (state.createCommits && madeChanges) {
-                state = await commitStepChanges(dir, root, state, step, migration, install);
-            }
-            else {
-                await install();
+        try {
+            if ((0, migration_shape_1.isPromptOnlyMigration)(migration)) {
+                emitOrPrintPrompt(root, migration, agenticKind, {
+                    persistPath: payloadPath,
+                });
+                awaitingKind = 'migration-prompt';
             }
-            if (installer.skippedInstall) {
-                (0, execute_migration_1.logSkippedPostMigrationInstall)(root);
+            else if (generatorAlreadyCompleted &&
+                startedStep.agenticWaived !== true &&
+                (0, migration_shape_1.isHybridMigration)(migration)) {
+                await reinstallFromBaseline();
+                const carried = (0, agent_work_payload_1.latestStoredAgentWorkPayload)(dir, step.id, startedStep.attempt, startedStep.generatorCompletedAtAttempt, {
+                    migrationId,
+                    kind: 'migration-prompt',
+                    promptPath: migration.prompt,
+                });
+                if (carried) {
+                    reemitCarriedAgentWork(migrationId, 'migration-prompt', payloadPath, carried);
+                }
+                else {
+                    emitOrPrintPrompt(root, migration, agenticKind, {
+                        persistPath: payloadPath,
+                    });
+                }
+                awaitingKind = 'migration-prompt';
             }
-            else if (installer.installed) {
-                (0, util_1.recordInstallLanded)(root, dir, step.id);
+            else if (generatorAlreadyCompleted &&
+                startedStep.validationOwed === true) {
+                // The flag is the only record that these changes still owe a validation
+                // pass; the decision needed the generator result, which is gone with the
+                // attempt that made it. The commit stays with the fold.
+                await reinstallFromBaseline();
+                const carried = (0, agent_work_payload_1.latestStoredAgentWorkPayload)(dir, step.id, startedStep.attempt, startedStep.generatorCompletedAtAttempt, { migrationId, kind: 'generator-validation' });
+                if (carried) {
+                    reemitCarriedAgentWork(migrationId, 'generator-validation', payloadPath, carried);
+                }
+                else {
+                    emitValidationBlock(root, migration, undefined, {
+                        persistPath: payloadPath,
+                    });
+                }
+                awaitingKind = 'generator-validation';
             }
-            printNextSteps(migration, nextSteps);
-            if ((0, migration_shape_1.isHybridMigration)(migration)) {
-                emitOrPrintPrompt(root, migration, agenticKind, {
-                    logs,
-                    changes,
-                    agentContext,
-                }, resolvedCollection);
+            else if (generatorAlreadyCompleted) {
+                state = await finishCompletedGenerator(dir, root, state, startedStep, migration, effectiveSkipInstall, runId, scope);
+                outcome = buildOutcome([], [], 'The generator ran in an earlier attempt; this attempt completed its install and commit.', root);
             }
             else {
-                outcome = buildOutcome(changes, nextSteps, migration.description, root);
+                const installer = new execute_migration_1.ChangedDepInstaller(root, effectiveSkipInstall, `${(0, execute_migration_1.formatSingleMigrationRerunCommand)(migrationId)} --run-id=${runId}`);
+                // Read once; the run and the hybrid documentation resolution share it.
+                const resolvedCollection = (0, execute_migration_1.readMigrationCollection)(migration.package, root);
+                const { changes, nextSteps, agentContext, skipAgentic, logs, madeChanges, } = await (0, execute_migration_1.runNxOrAngularMigration)(root, migration, isVerbose, 
+                // Captured whenever an agent step may consume it: a hybrid's prompt
+                // payload, or the validation pass over the generator's changes.
+                (0, migration_shape_1.isHybridMigration)(migration) || shouldValidate, resolvedCollection);
+                // Mirrors the classic loop's waiver semantics (migrate.ts): the two must
+                // agree on when an AI step was owed for skipAgentic to waive.
+                const validationApplies = shouldValidate && !(0, migration_shape_1.isHybridMigration)(migration) && changes.length > 0;
+                const waivedAgenticStep = skipAgentic && ((0, migration_shape_1.isHybridMigration)(migration) || validationApplies);
+                const validationOwed = validationApplies && !waivedAgenticStep;
+                const promptOwed = (0, migration_shape_1.isHybridMigration)(migration) && !waivedAgenticStep;
+                // Recorded before the commit is attempted: from here on the changes are
+                // in the tree, so a failed install or commit must leave a retry with
+                // only those left to do rather than running the generator again.
+                state = transition(dir, {
+                    type: 'markGeneratorCompleted',
+                    stepId: step.id,
+                    agenticWaived: waivedAgenticStep,
+                    validationOwed,
+                    madeChanges,
+                });
+                if (waivedAgenticStep) {
+                    (0, migrate_output_1.logWaivedAgenticStep)(migration, agentContext);
+                }
+                else if (!(0, migration_shape_1.isHybridMigration)(migration) && !validationApplies) {
+                    forwardDroppedAgentContext(migration, agentContext, agenticKind);
+                }
+                // Stored before the install: a failed install fails the attempt, and
+                // the retry re-hands this payload instead of a context-free one.
+                const impl = { logs, changes, agentContext };
+                const owed = validationOwed
+                    ? validationPayload(root, migration, impl, resolvedCollection)
+                    : promptOwed
+                        ? promptPayload(root, migration, impl, resolvedCollection)
+                        : undefined;
+                if (owed) {
+                    (0, agent_work_payload_1.persistAgentWorkPayload)(payloadPath, owed);
+                }
+                const install = () => recordingInstallFailure(dir, step.id, () => installer.installDepsIfChanged());
+                // A no-op step's commit would absorb prior pending diffs under its name;
+                // a step handing work back defers its commit to the fold, so the
+                // migration still lands as one commit. The install runs either way: the
+                // agent may run tasks that need what the generator added.
+                if (state.createCommits &&
+                    madeChanges &&
+                    !validationOwed &&
+                    !promptOwed) {
+                    state = await commitStepChanges(dir, root, state, startedStep, migration, install, scope);
+                }
+                else {
+                    await (0, broker_1.installStepTree)(dir, startedStep, 'install', install, scope);
+                }
+                if (installer.skippedInstall) {
+                    (0, execute_migration_1.logSkippedPostMigrationInstall)(root);
+                }
+                else if (installer.installed) {
+                    (0, util_1.recordInstallLanded)(root, dir, step.id);
+                }
+                printNextSteps(migration, nextSteps);
+                if (validationOwed) {
+                    emitValidationPayload(migrationId, owed);
+                    awaitingKind = 'generator-validation';
+                }
+                else if (promptOwed) {
+                    emitPromptForOuterAgent(migrationId, owed, true);
+                    awaitingKind = 'migration-prompt';
+                }
+                else {
+                    outcome = buildOutcome(changes, nextSteps, migration.description, root);
+                }
             }
         }
-    }
-    catch (e) {
-        // The failed-step dispense surfaces this so the agent can decide
-        // retry-vs-skip; carry the error's first line, not a full stack.
+        catch (e) {
+            // Another attempt owns the step, and `fail` is not attempt-bound.
+            if (e instanceof broker_1.BrokerStaleRequestError)
+                throw e;
+            // The failed-step dispense surfaces this so the agent can decide
+            // retry-vs-skip; carry the error's first line, not a full stack.
+            transition(dir, {
+                type: 'fail',
+                stepId: step.id,
+                finishedAt: (0, util_1.nowIso)(),
+                outcome: { summary: (0, util_1.summarizeError)(e) },
+            });
+            throw e;
+        }
+        // Handed-back work is applied by a separate actor, so parking exits
+        // successfully rather than failing the step.
+        if (awaitingKind !== undefined) {
+            transition(dir, {
+                type: 'awaitPromptOutcome',
+                stepId: step.id,
+                finishedAt: (0, util_1.nowIso)(),
+                awaitingKind,
+            });
+            return;
+        }
         transition(dir, {
-            type: 'fail',
+            type: 'succeed',
             stepId: step.id,
             finishedAt: (0, util_1.nowIso)(),
-            outcome: { summary: (0, util_1.summarizeError)(e) },
+            ...(outcome ? { outcome } : {}),
         });
-        throw e;
     }
-    // A prompt half (prompt-only, or the prompt phase of a hybrid) is applied by
-    // a separate actor, so the step parks in awaiting-prompt-outcome and this
-    // process exits successfully.
-    if ((0, migration_shape_1.isPromptOnlyMigration)(migration) || (0, migration_shape_1.isHybridMigration)(migration)) {
-        transition(dir, {
-            type: 'awaitPromptOutcome',
-            stepId: step.id,
-            finishedAt: (0, util_1.nowIso)(),
-        });
-        return;
+    finally {
+        scope.lease?.release();
     }
-    transition(dir, {
-        type: 'succeed',
-        stepId: step.id,
-        finishedAt: (0, util_1.nowIso)(),
-        ...(outcome ? { outcome } : {}),
-    });
 }
 // Applies a step event to the freshest on-disk state under the lock, writes it,
 // and returns it. Reading fresh is what makes a racing worker's 'start' see the
@@ -475,44 +569,52 @@ async function recordingInstallFailure(dir, stepId, install) {
 // on the install or the commit. The generator's changes are already in the
 // tree, so only those two are left, and the install compares against the
 // step's persisted baseline rather than against what that generator wrote.
-async function finishCompletedGenerator(dir, root, state, step, migration, skipInstall, runId) {
+async function finishCompletedGenerator(dir, root, state, step, migration, skipInstall, runId, scope) {
     const migrationId = `${migration.package}:${migration.name}`;
     const installDeps = () => recordingInstallFailure(dir, step.id, () => (0, util_1.installDepsChangedSinceDispense)(root, dir, step, skipInstall, `${(0, execute_migration_1.formatSingleMigrationRerunCommand)(migrationId)} --run-id=${runId}`));
-    if (!state.createCommits) {
-        await installDeps();
+    // Same no-op guard as the first attempt. Only an explicit false skips the
+    // commit: absent means an older nx wrote the marker without recording the
+    // answer, and the commit is kept as that version's retries did.
+    if (!state.createCommits || step.generatorMadeChanges === false) {
+        await (0, broker_1.installStepTree)(dir, step, 'install', installDeps, scope);
         return state;
     }
-    return commitStepChanges(dir, root, state, step, migration, installDeps);
+    return commitStepChanges(dir, root, state, step, migration, installDeps, scope);
 }
 // Installs what the step changed, commits it, and records the result in the
 // ledger, shared by a step's first attempt and by one that only has the commit
 // left to do. The absorbed step ids are computed before the commit so the
 // ledger entry and the commit body name the same ones.
-async function commitStepChanges(dir, root, state, step, migration, installDeps) {
+async function commitStepChanges(dir, root, state, step, migration, installDeps, scope) {
     const absorbedStepIds = (0, state_machine_1.uncoveredFailedStepIds)(state).filter((id) => id !== step.id);
-    let result;
+    let commit;
     try {
-        result = await (0, migrate_commits_1.commitMigrationIfRequested)(root, migration, true, state.commitPrefix, installDeps, (0, state_machine_1.stepsToPendingMigrations)(state, absorbedStepIds));
+        commit = await (0, broker_1.commitStepTree)(dir, step, absorbedStepIds, () => (0, migrate_commits_1.commitMigrationIfRequested)(root, migration, true, state.commitPrefix, installDeps, (0, state_machine_1.stepsToPendingMigrations)(state, absorbedStepIds)), scope);
     }
     catch (commitError) {
-        // A post-migration install failure leaves the diff uncommitted; record the
-        // debt so only a landed entry can cover it.
-        appendCommit(dir, { kind: 'failed', stepIds: [step.id] });
+        // Nothing ran for a stale or refused request, so there is no debt.
+        if (commitError instanceof broker_1.BrokerStaleRequestError ||
+            commitError instanceof broker_1.TreeBusyError) {
+            throw commitError;
+        }
+        // The install failed, or the session ended unanswered and the commit may
+        // or may not have landed; record the debt until a landed entry covers it.
+        recordCommitEntry(dir, { kind: 'failed', stepIds: [step.id] });
         throw commitError;
     }
-    if (result.status === 'failed') {
+    if (commit.result.status === 'failed') {
         (0, util_1.warnCommitFailed)(migration.name);
     }
-    const entry = (0, state_machine_1.commitResultToLedgerEntry)(result, step.id, absorbedStepIds);
-    return entry ? appendCommit(dir, entry) : state;
+    const entry = (0, state_machine_1.commitResultToLedgerEntry)(commit.result, step.id, commit.absorbedStepIds);
+    // A session's parent records what it commits itself, receipt included.
+    return entry && !commit.recorded ? recordCommitEntry(dir, entry) : state;
 }
-// Appends a ledger entry to the freshest on-disk state under the lock. The git
-// commit itself already ran outside the lock; only this pure append is locked.
-function appendCommit(dir, entry) {
-    return (0, state_lock_1.updateRunState)(dir, (fresh) => ({
-        ...fresh,
-        commits: [...fresh.commits, entry],
-    }));
+// The git commit itself already ran outside the lock; only this pure append is
+// locked. A landed entry carries the resolved issues of every step it names,
+// same as the orchestrator's fold and adopt appends: an absorbed step's
+// resolutions would otherwise land unattached.
+function recordCommitEntry(dir, entry) {
+    return (0, state_lock_1.updateRunState)(dir, (fresh) => (0, state_machine_1.appendCommit)(fresh, (0, issues_1.attachIssueIdsToCommitEntry)(fresh, entry)));
 }
 function buildOutcome(changes, nextSteps, description, root) {
     const outcome = {};
@@ -577,7 +679,7 @@ async function runAgenticStep(agenticRun, input) {
 // commit's diff, so it passes its own guidance instead of the default.
 // `commitMigrationIfRequested` logs a failed commit itself with that guidance.
 function attemptStandaloneCommit(root, migration, createCommits, commitPrefix, installDepsIfChanged) {
-    return (0, migrate_commits_1.commitMigrationIfRequested)(root, migration, createCommits, commitPrefix, installDepsIfChanged, [], 'Commit or revert the changes manually.');
+    return (0, migrate_commits_1.commitMigrationIfRequested)(root, migration, createCommits, commitPrefix, installDepsIfChanged, [], 'Commit or revert any remaining uncommitted changes manually.');
 }
 async function commitAndLogAgenticOutcome(args) {
     const commit = await attemptStandaloneCommit(args.root, args.migration, args.createCommits, args.commitPrefix, args.installDepsIfChanged);
@@ -598,32 +700,60 @@ function printNextSteps(migration, nextSteps) {
         bodyLines: nextSteps.map((line) => `- ${(0, text_1.singleLine)(line)}`),
     });
 }
-function emitOrPrintPrompt(root, migration, agenticKind, impl, resolvedCollection) {
+function emitOrPrintPrompt(root, migration, agenticKind, opts = {}) {
     const migrationId = `${migration.package}:${migration.name}`;
-    const promptPath = migration.prompt;
-    const documentationPath = resolveDocumentationPath(root, migration, resolvedCollection);
     if (agenticKind === 'inside-agent') {
-        emitPromptForOuterAgent(migrationId, promptPath, documentationPath, impl);
+        const payload = promptPayload(root, migration, opts.impl, opts.resolvedCollection);
+        if (opts.persistPath) {
+            (0, agent_work_payload_1.persistAgentWorkPayload)(opts.persistPath, payload);
+        }
+        emitPromptForOuterAgent(migrationId, payload, opts.persistPath !== undefined);
     }
     else {
-        printPromptForUser(root, migration, promptPath, documentationPath);
+        printPromptForUser(root, migration, migration.prompt, resolveDocumentationPath(root, migration, opts.resolvedCollection));
     }
 }
-function emitPromptForOuterAgent(migrationId, promptPath, documentationPath, impl) {
-    const payload = { migrationId, prompt: promptPath };
+function promptPayload(root, migration, impl, resolvedCollection) {
+    const payload = {
+        migrationId: `${migration.package}:${migration.name}`,
+        prompt: migration.prompt,
+    };
+    const documentationPath = resolveDocumentationPath(root, migration, resolvedCollection);
     if (documentationPath)
         payload.documentationPath = documentationPath;
-    if (impl) {
-        payload.impl = {
-            logs: impl.logs,
-            changes: impl.changes.map((c) => ({ type: c.type, path: c.path })),
-            ...(impl.agentContext.length > 0
-                ? { agentContext: impl.agentContext }
-                : {}),
-        };
-    }
+    if (impl)
+        payload.impl = implPayload(impl);
+    return payload;
+}
+const PROMPT_NOT_APPLIED = `The following prompt-based migration was not applied automatically.`;
+// Recorded steps hand work back through the orchestrator, per the runbook's loop.
+const RUN_NEXT_FIRST = `Run the dispensed "next" command first: its response restates this work and names the handoff file to write.`;
+const CHANGES_AWAIT_VALIDATION = `The following migration's generator ran in an earlier attempt and its changes still await validation.`;
+function emitPromptForOuterAgent(migrationId, payload, recorded) {
     (0, agent_output_1.logToAgent)({
-        title: `The following prompt-based migration was not applied automatically. Apply it to this workspace, then continue.`,
+        title: recorded
+            ? `${PROMPT_NOT_APPLIED} ${RUN_NEXT_FIRST}`
+            : `${PROMPT_NOT_APPLIED} Apply it to this workspace, then continue.`,
+    });
+    (0, agent_output_1.emitPromptBlock)(migrationId, payload);
+}
+function implPayload(impl) {
+    return {
+        logs: impl.logs,
+        changes: impl.changes.map((c) => ({ type: c.type, path: c.path })),
+        ...(impl.agentContext.length > 0
+            ? { agentContext: impl.agentContext }
+            : {}),
+    };
+}
+// Re-hands what an earlier attempt stored. The payload is re-persisted under
+// this attempt because the dispense reads only the current attempt's file.
+function reemitCarriedAgentWork(migrationId, kind, payloadPath, payload) {
+    (0, agent_work_payload_1.persistAgentWorkPayload)(payloadPath, payload);
+    (0, agent_output_1.logToAgent)({
+        title: `${kind === 'migration-prompt'
+            ? PROMPT_NOT_APPLIED
+            : CHANGES_AWAIT_VALIDATION} ${RUN_NEXT_FIRST}`,
     });
     (0, agent_output_1.emitPromptBlock)(migrationId, payload);
 }
@@ -660,6 +790,37 @@ function printPromptForUser(root, migration, promptPath, documentationPath) {
         bodyLines,
     });
 }
+// `impl` is absent on a retry whose earlier attempt left no stored payload;
+// the emission then points at the tree.
+function emitValidationBlock(root, migration, impl, opts = {}) {
+    const payload = validationPayload(root, migration, impl, opts.resolvedCollection);
+    if (opts.persistPath) {
+        (0, agent_work_payload_1.persistAgentWorkPayload)(opts.persistPath, payload);
+    }
+    emitValidationPayload(`${migration.package}:${migration.name}`, payload);
+}
+function emitValidationPayload(migrationId, payload) {
+    (0, agent_output_1.logToAgent)({
+        title: payload.impl !== undefined
+            ? `The following migration's generator ran without an AI-driven part. ${RUN_NEXT_FIRST}`
+            : `${CHANGES_AWAIT_VALIDATION} ${RUN_NEXT_FIRST} Inspect the changes with git.`,
+    });
+    (0, agent_output_1.emitPromptBlock)(migrationId, payload);
+}
+function validationPayload(root, migration, impl, resolvedCollection) {
+    // `kind` is what tells the block apart from an applied-prompt payload,
+    // which carries `prompt` instead.
+    const payload = {
+        migrationId: `${migration.package}:${migration.name}`,
+        kind: 'generator-validation',
+    };
+    const documentationPath = resolveDocumentationPath(root, migration, resolvedCollection);
+    if (documentationPath)
+        payload.documentationPath = documentationPath;
+    if (impl)
+        payload.impl = implPayload(impl);
+    return payload;
+}
 // Non-fatal: documentation is supplementary, so a failure warns and the
 // prompt still runs without it.
 function resolveDocumentationPath(root, migration, resolvedCollection) {

package/dist/src/command-line/migrate/step-actions.d.ts

@@ -1,5 +1,5 @@
 /** Allowed values for `--step-action`, the orchestrated reconcile's decision relay. */
-export declare const STEP_ACTIONS: readonly ['retry', 'skip', 'retry-clean', 'adopt'];
+export declare const STEP_ACTIONS: readonly ['retry', 'skip', 'retry-clean', 'adopt', 'unresolved'];
 export type StepAction = (typeof STEP_ACTIONS)[number];
 /** Runtime guard backed by {@link STEP_ACTIONS} so the two can't drift apart. */
 export declare function isStepAction(value: unknown): value is StepAction;

package/dist/src/command-line/migrate/step-actions.js

@@ -5,7 +5,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.STEP_ACTIONS = void 0;
 exports.isStepAction = isStepAction;
 /** Allowed values for `--step-action`, the orchestrated reconcile's decision relay. */
-exports.STEP_ACTIONS = ['retry', 'skip', 'retry-clean', 'adopt'];
+exports.STEP_ACTIONS = [
+    'retry',
+    'skip',
+    'retry-clean',
+    'adopt',
+    'unresolved',
+];
 /** Runtime guard backed by {@link STEP_ACTIONS} so the two can't drift apart. */
 function isStepAction(value) {
     return exports.STEP_ACTIONS.includes(value);

package/dist/src/command-line/migrate/text.d.ts

@@ -16,3 +16,9 @@
  * real terminator can put a value at the start of a line.
  */
 export declare function singleLine(value: string): string;
+export declare function hasLineBreak(value: string): boolean;
+/**
+ * Renders an ISO timestamp as a human age ("6 hours ago"), falling back to
+ * the raw value when it is not parseable or lies in the future.
+ */
+export declare function formatAge(timestamp: string): string;

package/dist/src/command-line/migrate/text.js

@@ -4,6 +4,8 @@
 // run/util.ts without a cycle through run/state-lock.ts.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.singleLine = singleLine;
+exports.hasLineBreak = hasLineBreak;
+exports.formatAge = formatAge;
 /**
  * Collapses every character a reader could take for a line break, so a value
  * cannot break out of the line it is rendered on. The driving agent scans the
@@ -24,3 +26,26 @@ exports.singleLine = singleLine;
 function singleLine(value) {
     return value.replace(/[\r\n\u000b\u000c\u0085\u2028\u2029]+/g, ' ');
 }
+function hasLineBreak(value) {
+    return singleLine(value) !== value;
+}
+/**
+ * Renders an ISO timestamp as a human age ("6 hours ago"), falling back to
+ * the raw value when it is not parseable or lies in the future.
+ */
+function formatAge(timestamp) {
+    const elapsedMs = Date.now() - Date.parse(timestamp);
+    if (!Number.isFinite(elapsedMs) || elapsedMs < 0) {
+        return timestamp;
+    }
+    const minutes = Math.floor(elapsedMs / 60_000);
+    if (minutes < 60) {
+        return `${minutes} minute${minutes === 1 ? '' : 's'} ago`;
+    }
+    const hours = Math.floor(elapsedMs / 3_600_000);
+    if (hours < 48) {
+        return `${hours} hour${hours === 1 ? '' : 's'} ago`;
+    }
+    const days = Math.floor(elapsedMs / 86_400_000);
+    return `${days} day${days === 1 ? '' : 's'} ago`;
+}

package/dist/src/command-line/migrate/version-skew-guard.js

@@ -19,6 +19,8 @@ const version_utils_1 = require("./version-utils");
 // pass this floor and route to a temp CLI that drops the new flags and runs
 // the plan phase instead.
 exports.NEW_MIGRATE_FLAGS_FLOOR = '23.2.0';
+// List only flags that pick which migrate path runs: an older nx drops them
+// and runs another one. Flags read only by --run-migrations do not belong.
 // yargs accepts both spellings of each flag and the raw argv is forwarded
 // across both migrate hops, so detection must catch every one.
 exports.NEW_MIGRATE_FLAGS = [