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

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

@@ -27,6 +27,7 @@ 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");
+const orchestrator_1 = require("./orchestrator");
 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
@@ -35,24 +36,30 @@ async function runSingleMigrationWorker(input) {
     if (runId !== undefined && !run_id_1.RUN_ID_SAFE.test(runId)) {
         throw new Error(`Invalid run id '${runId}'.`);
     }
-    const { migrations, source } = readMigrationsSource(root, runId);
+    const { migrations, source, singleMigration } = readMigrationsSource(root, runId);
     const migration = resolveMigration(migrations, runMigration, source);
-    (0, migrate_analytics_1.reportMigrateSingleMigrationInvocation)({
-        migrationType: (0, migration_shape_1.isPromptOnlyMigration)(migration)
-            ? 'prompt'
-            : (0, migration_shape_1.isHybridMigration)(migration)
-                ? 'hybrid'
-                : 'generator',
-        orchestrated: !!runId,
-    });
+    // A retry in the agent session of a `--run-migration` run belongs to the
+    // invocation that started that run, which already reported.
+    if (!singleMigration) {
+        (0, migrate_analytics_1.reportMigrateSingleMigrationInvocation)({
+            migrationType: (0, migration_shape_1.isPromptOnlyMigration)(migration)
+                ? 'prompt'
+                : (0, migration_shape_1.isHybridMigration)(migration)
+                    ? 'hybrid'
+                    : 'generator',
+            orchestrated: !!runId,
+        });
+    }
     if (runId) {
         // A recorded run takes its commit config from run.json and is driven by
         // the outer agent, so the standalone resolution below doesn't apply. That
         // includes the default-branch confirmation: the run decided once, at init,
         // whether to commit, and asking again would re-prompt on every step.
-        await runRecorded(root, runId, migration, skipInstall, isVerbose);
+        await runRecorded(root, runId, migration, skipInstall, isVerbose, 'worker');
         return;
     }
+    // Before the agent selection, which may prompt.
+    (0, orchestrator_1.prepareSingleMigrationRun)(root);
     let agentic;
     try {
         agentic = await (0, select_1.resolveAgentic)({
@@ -65,6 +72,8 @@ async function runSingleMigrationWorker(input) {
         (0, migrate_analytics_1.reportMigrateRunError)({ code: 'agentic', error: e });
         throw e;
     }
+    // Resolved before the commit policy, which defaults on only for an agent.
+    agentic = (0, select_1.dropUnsupportedAgent)(agentic, (0, run_state_1.migrationIdProblems)([migration]));
     const resolved = (0, migrate_commits_1.resolveCreateCommits)({
         createCommits: input.createCommits,
         mode: agentic.kind,
@@ -78,19 +87,30 @@ async function runSingleMigrationWorker(input) {
         (0, agent_output_1.warnToAgent)({ title: resolved.warning });
     }
     const createCommits = resolved.effective;
-    if (createCommits &&
-        (0, safe_prompt_1.canPrompt)(interactive) &&
-        !(await (0, migrate_commits_1.confirmMigrationCommitsOnDefaultBranch)(root, 'running the migration'))) {
+    const confirmStart = async () => !createCommits ||
+        !(0, safe_prompt_1.canPrompt)(interactive) ||
+        (await (0, migrate_commits_1.confirmMigrationCommitsOnDefaultBranch)(root, 'running the migration'));
+    if (agentic.kind === 'enabled') {
+        return runAgenticSingleMigration({
+            root,
+            migration,
+            agent: agentic.selectedAgent,
+            createCommits,
+            commitPrefix,
+            skipInstall,
+            isVerbose,
+            validate: input.validate,
+            confirmStart,
+        });
+    }
+    if (!(await confirmStart())) {
         return;
     }
     await runStandalone(root, migration, {
-        agentic,
+        agenticKind: agentic.kind,
+        // Inside an agent, --agentic=false drops the review; prompts still go out.
+        validate: input.agentic === false ? false : input.validate,
         createCommits,
-        agenticHasDiffContext: resolved.agenticHasDiffContext,
-        shouldRunValidation: (0, select_1.resolveShouldRunValidation)({
-            validate: input.validate,
-            agenticKind: agentic.kind,
-        }),
         commitPrefix,
         skipInstall,
         isVerbose,
@@ -123,6 +143,7 @@ function readMigrationsSource(root, runId) {
         return {
             migrations: readPlanMigrations(planPath),
             source: round.planSnapshot,
+            singleMigration: state.singleMigration === true,
         };
     }
     const migrationsPath = (0, path_1.join)(root, 'migrations.json');
@@ -155,160 +176,31 @@ function resolveMigration(migrations, id, source) {
     return matches[0];
 }
 async function runStandalone(root, migration, opts) {
-    const { agentic, createCommits, commitPrefix, skipInstall, isVerbose } = opts;
-    // Standalone never writes run state. Warn (don't block) when an orchestrated
-    // run is active so the user knows this execution won't be recorded into it.
-    // A newer-nx run dir must not hard-block this stateless path (the fail-closed
-    // refusal in run-state.ts targets run-starting callers); tolerate it and skip
-    // the warning. A failed scan can't block it either, but gets a warning of its
-    // own: an active run may exist that this execution silently won't record into.
-    let active;
-    try {
-        active = (0, run_state_1.findActiveRun)(root).active;
-    }
-    catch (e) {
-        if (!(e instanceof run_state_1.NewerRunStateFormatError)) {
-            (0, agent_output_1.warnToAgent)({
-                title: `Could not check for an active migrate run: ${e instanceof Error ? e.message : e}`,
-            });
-        }
-        active = null;
-    }
-    if (active) {
-        (0, agent_output_1.warnToAgent)({
-            title: `This migration won't be recorded into the active migrate run '${active.runId}'.`,
-            bodyLines: [
-                `Pass --run-id=${active.runId} to record it into that run instead.`,
-            ],
-        });
-    }
+    const { agenticKind, createCommits, commitPrefix, skipInstall, isVerbose } = opts;
     if ((0, migration_shape_1.isPromptOnlyMigration)(migration)) {
-        if (agentic.kind !== 'enabled') {
-            // No agent to apply the prompt, so nothing runs: no checkpoint, no
-            // commit.
-            emitOrPrintPrompt(root, migration, agentic.kind);
-            return;
-        }
-        // Checkpoint pre-existing working-tree state first, or the migration
-        // commit's `git add -A` folds it in.
-        if (createCommits) {
-            (0, migrate_commits_1.commitCheckpointBeforeMigrations)(root, commitPrefix);
-        }
-        const agenticRun = await prepareAgenticRun(root, migration, agentic, createCommits, commitPrefix);
-        const installer = new execute_migration_1.ChangedDepInstaller(root, skipInstall, (0, execute_migration_1.formatSingleMigrationRerunCommand)(`${migration.package}:${migration.name}`));
-        const installDepsIfChanged = () => installer.installDepsIfChanged();
-        const stepResult = await runAgenticStep(agenticRun, {
-            root,
-            migration,
-            installDepsIfChanged,
-            documentationPath: resolveDocumentationPath(root, migration),
-        });
-        await commitAndLogAgenticOutcome({
-            root,
-            migration,
-            createCommits,
-            commitPrefix,
-            installDepsIfChanged,
-            successLabel: 'Applied',
-            stepResult,
-        });
-        if (installer.skippedInstall) {
-            (0, execute_migration_1.logSkippedPostMigrationInstall)(root);
-        }
+        // No agent to apply the prompt, so nothing runs: no checkpoint, no
+        // commit.
+        emitOrPrintPrompt(root, migration, agenticKind);
         return;
     }
+    // Checkpoint pre-existing working-tree state first, or the migration
+    // commit's `git add -A` folds it in.
     if (createCommits) {
         (0, migrate_commits_1.commitCheckpointBeforeMigrations)(root, commitPrefix);
     }
-    const agenticRun = agentic.kind === 'enabled'
-        ? await prepareAgenticRun(root, migration, agentic, createCommits, commitPrefix)
-        : undefined;
     const installer = new execute_migration_1.ChangedDepInstaller(root, skipInstall, (0, execute_migration_1.formatSingleMigrationRerunCommand)(`${migration.package}:${migration.name}`));
-    const installDepsIfChanged = () => installer.installDepsIfChanged();
-    const validationRun = agenticRun && opts.shouldRunValidation ? agenticRun : undefined;
+    // The outer agent validates a generator-only migration's changes, as the
+    // validation pass of a recorded step would.
+    const shouldValidate = agenticKind === 'inside-agent' && opts.validate !== false;
     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, (0, migration_shape_1.isHybridMigration)(migration) || !!validationRun, resolvedCollection);
-    // Whether an AI step was on the table for `skipAgentic` to waive. A hybrid
-    // owes its prompt in every agentic mode; a generator-only migration owes
-    // only the validation pass, and only where one would have run.
-    const validationApplies = !!validationRun && changes.length > 0;
-    const waivedAgenticStep = skipAgentic && ((0, migration_shape_1.isHybridMigration)(migration) || validationApplies);
-    if ((0, migration_shape_1.isHybridMigration)(migration) && agenticRun && !skipAgentic) {
-        // The prompt half may need the deps the generator half added, so install
-        // before the agent runs.
-        await installDepsIfChanged();
-        const stepResult = await runAgenticStep(agenticRun, {
-            root,
-            migration,
-            installDepsIfChanged,
-            documentationPath: resolveDocumentationPath(root, migration, resolvedCollection),
-            implContext: {
-                logs,
-                changes,
-                agentContext,
-                // No prior migrations run here, so unlike the classic loop there is no
-                // pending-commit debt to suppress the git-inspect context for.
-                hasDiffContext: opts.agenticHasDiffContext,
-            },
-        });
-        await commitAndLogAgenticOutcome({
-            root,
-            migration,
-            createCommits,
-            commitPrefix,
-            installDepsIfChanged,
-            successLabel: 'Applied',
-            stepResult,
-        });
-        if (installer.skippedInstall) {
-            (0, execute_migration_1.logSkippedPostMigrationInstall)(root);
-        }
-        printNextSteps(migration, nextSteps);
-        return;
-    }
-    if (validationApplies && !skipAgentic) {
-        // Commit after validation: a failed validation throws, leaving the changes
-        // in the working tree for review.
-        await installDepsIfChanged();
-        const stepResult = await runAgenticStep(validationRun, {
-            root,
-            migration,
-            installDepsIfChanged,
-            documentationPath: resolveDocumentationPath(root, migration, resolvedCollection),
-            implContext: {
-                logs,
-                changes,
-                agentContext,
-                hasDiffContext: opts.agenticHasDiffContext,
-            },
-            mode: 'generic-validation',
-        });
-        await commitAndLogAgenticOutcome({
-            root,
-            migration,
-            createCommits,
-            commitPrefix,
-            installDepsIfChanged,
-            successLabel: 'Validation passed',
-            stepResult,
-        });
-        if (installer.skippedInstall) {
-            (0, execute_migration_1.logSkippedPostMigrationInstall)(root);
-        }
-        printNextSteps(migration, nextSteps);
-        return;
-    }
-    if (waivedAgenticStep) {
-        (0, migrate_output_1.logWaivedAgenticStep)(migration, agentContext);
-    }
-    else if (!(0, migration_shape_1.isHybridMigration)(migration)) {
-        forwardDroppedAgentContext(migration, agentContext, agentic.kind);
-    }
+    const { changes, nextSteps, agentContext, skipAgentic, logs, madeChanges } = await (0, execute_migration_1.runNxOrAngularMigration)(root, migration, isVerbose, (0, migration_shape_1.isHybridMigration)(migration) || shouldValidate, resolvedCollection);
+    const work = owedAgentWork(migration, shouldValidate, changes, skipAgentic);
+    logWaiverOrForwardAgentContext(migration, work, agentContext, agenticKind);
     // A no-op migration must not build a commit whose `git add -A` absorbs
     // unrelated pending diffs under its name. The commit path installs deps
     // itself, so the else branch does it here instead.
     if (createCommits && madeChanges) {
-        await attemptStandaloneCommit(root, migration, createCommits, commitPrefix, installDepsIfChanged);
+        await (0, migrate_commits_1.commitMigrationIfRequested)(root, migration, createCommits, commitPrefix, () => installer.installDepsIfChanged(), [], 'manual');
     }
     else {
         await installer.installDepsIfChanged();
@@ -317,10 +209,13 @@ async function runStandalone(root, migration, opts) {
         (0, execute_migration_1.logSkippedPostMigrationInstall)(root);
     }
     printNextSteps(migration, nextSteps);
+    if (work.validationOwed) {
+        emitValidationBlock(root, migration, { logs, changes, agentContext }, { resolvedCollection });
+    }
     // A waived prompt is not deferred, so it gets no hand-off to an outer agent
     // and no "apply this manually" block for the user either.
-    if ((0, migration_shape_1.isHybridMigration)(migration) && !skipAgentic) {
-        emitOrPrintPrompt(root, migration, agentic.kind, {
+    if (work.promptOwed) {
+        emitOrPrintPrompt(root, migration, agenticKind, {
             impl: {
                 logs,
                 changes,
@@ -330,16 +225,160 @@ async function runStandalone(root, migration, opts) {
         });
     }
 }
-async function runRecorded(root, runId, migration, skipInstall, isVerbose) {
+// Records the migration as a one-step run and runs its generator part here, as
+// a dispensed worker would. The agent starts only for work the step hands
+// back, and its first "next" gets that work.
+async function runAgenticSingleMigration(input) {
+    const { root, migration, agent, createCommits, skipInstall } = input;
+    const migrationId = `${migration.package}:${migration.name}`;
+    const ready = await (0, orchestrator_1.runOrchestratorInit)({
+        root,
+        migrationsJson: { migrations: [migration] },
+        createCommits,
+        commitPrefix: input.commitPrefix,
+        skipInstall,
+        installedNxVersion: (0, package_json_1.readModulePackageJson)('nx', (0, installation_directory_1.getNxRequirePaths)(root))
+            .packageJson.version,
+        validate: input.validate,
+        finalValidation: false,
+        emitAgentInstructions: false,
+        singleMigration: true,
+        confirmStart: input.confirmStart,
+    });
+    switch (ready.kind) {
+        case 'refused':
+            return;
+        case 'existing-run':
+            throw new Error(`A --run-migration run never reports an active run, but init reported '${ready.runId}'.`);
+        case 'ready':
+            break;
+        default: {
+            const unhandled = ready;
+            throw new Error(`Unhandled init result: ${JSON.stringify(unhandled)}`);
+        }
+    }
+    const { runId } = ready;
+    try {
+        (0, orchestrator_1.dispenseSingleMigrationStep)(root, runId);
+        const parked = await runRecorded(root, runId, migration, skipInstall, input.isVerbose, 'single-run-parent');
+        if (!parked) {
+            (0, agent_output_1.logToAgent)({ title: `Migration ${migrationId} is complete.` });
+            warnAboutLeftovers(root, runId, (0, run_state_1.readRunState)((0, run_state_1.runDir)(root, runId)));
+            (0, migrate_analytics_1.reportMigrateSingleMigrationComplete)({});
+            return;
+        }
+        (0, agent_output_1.logToAgent)({
+            title: `Starting ${agent.displayName} for migration ${migrationId}.`,
+        });
+        const { driveMasterSession } = require('../agentic/master/run-master-session');
+        const rerunHint = `Migration ${migrationId} did not finish. Re-run the same command to run it again.`;
+        const state = await driveMasterSession({
+            agent,
+            ready,
+            policy: { createCommits, skipInstall },
+            migration,
+            notStartedHint: rerunHint,
+        });
+        if (!state)
+            return 1;
+        switch (state.status) {
+            case 'active':
+                (0, migrate_analytics_1.reportMigrateSingleMigrationAbandoned)({ agentUsed: agent.id });
+                (0, agent_output_1.warnToAgent)({ title: rerunHint });
+                return 1;
+            case 'completed': {
+                const unresolved = logSingleMigrationOutcome(state, migrationId);
+                warnAboutLeftovers(root, runId, state);
+                (0, migrate_analytics_1.reportMigrateSingleMigrationComplete)({ agentUsed: agent.id });
+                return unresolved ? 1 : undefined;
+            }
+            default: {
+                const unhandled = state.status;
+                throw new Error(`Unhandled migrate run status: ${unhandled}`);
+            }
+        }
+    }
+    finally {
+        (0, state_lock_1.withRunCreationLock)(root, () => (0, orchestrator_1.removeSingleMigrationRun)(root, runId));
+    }
+}
+function warnAboutLeftovers(root, runId, state) {
+    for (const lines of (0, orchestrator_1.completionWarnings)(root, runId, state)) {
+        (0, agent_output_1.warnToAgent)({ title: lines[0], bodyLines: lines.slice(1) });
+    }
+}
+// The record is removed next, so the closing output carries the settling
+// summary and commit. Returns whether the migration was left unresolved.
+function logSingleMigrationOutcome(state, migrationId) {
+    const [step] = state.steps;
+    const sha = (0, orchestrator_1.lastCoveringLandedEntry)(state, step)?.sha;
+    const outcomeLines = (summary) => [
+        ...(summary?.trim() ? [summary] : []),
+        ...(sha ? [`Commit: ${sha}`] : []),
+    ];
+    switch (step.status) {
+        case 'succeeded':
+            (0, agent_output_1.logToAgent)({
+                title: `Migration ${migrationId} is complete.`,
+                // Adopt writes outcome.summary; promptOutcome still holds the failed
+                // handoff.
+                bodyLines: outcomeLines(step.adopted
+                    ? step.outcome?.summary
+                    : (step.promptOutcome?.summary ?? step.outcome?.summary)),
+            });
+            return false;
+        case 'skipped':
+            (0, agent_output_1.logToAgent)({
+                title: `Migration ${migrationId} was skipped.`,
+                // After a --step-action skip, promptOutcome is the failed handoff's.
+                bodyLines: outcomeLines(step.promptOutcome?.status === 'skipped'
+                    ? step.promptOutcome.summary
+                    : undefined),
+            });
+            return false;
+        case 'unresolved':
+            (0, agent_output_1.errorToAgent)({
+                title: `Migration ${migrationId} is unresolved.`,
+                bodyLines: outcomeLines((0, state_machine_1.unresolvedFailureDetail)(step)),
+            });
+            return true;
+        case 'pending':
+        case 'dispensed':
+        case 'running':
+        case 'awaiting-prompt-outcome':
+        case 'failed':
+        case 'died':
+            throw new Error(`Migrate run completed with migration ${migrationId} in status '${step.status}'.`);
+        default: {
+            const unhandled = step.status;
+            throw new Error(`Unhandled step status: ${unhandled}`);
+        }
+    }
+}
+// 'worker': a dispensed command, whose output the agent driving the run reads.
+// 'single-run-parent': the first attempt of a `--run-migration` run's step, run
+// by the process that starts the agent only afterwards. Returns whether the
+// step was parked for an agent.
+async function runRecorded(root, runId, migration, skipInstall, isVerbose, caller) {
     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,
+    // A worker never resolves the agentic flow: the outer agent drives the run,
     // 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';
+    // step awaiting an outcome whose payload was never emitted. The parent of a
+    // `--run-migration` run stores the work it hands back without printing it:
+    // its agent gets that work from the first "next".
+    const emitsHandBack = caller === 'worker';
+    const agenticKind = emitsHandBack
+        ? 'inside-agent'
+        : 'enabled';
     const migrationId = `${migration.package}:${migration.name}`;
+    // The parent's run is removed when it ends, so its hint is the command the
+    // user ran.
+    const rerunCommand = emitsHandBack
+        ? `${(0, execute_migration_1.formatSingleMigrationRerunCommand)(migrationId)} --run-id=${runId}`
+        : (0, execute_migration_1.formatSingleMigrationRerunCommand)(migrationId);
     // 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);
@@ -375,16 +414,17 @@ async function runRecorded(root, runId, migration, skipInstall, isVerbose) {
     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);
+    const reinstallFromBaseline = () => (0, broker_1.installStepTree)(dir, startedStep, 'install', () => recordingInstallFailure(dir, step.id, () => (0, util_1.installDepsChangedSinceDispense)(root, dir, startedStep, effectiveSkipInstall, rerunCommand)), scope);
     let outcome;
     let awaitingKind;
     const payloadPath = (0, agent_work_payload_1.agentWorkPayloadPath)(dir, step.id, startedStep.attempt);
     try {
         try {
             if ((0, migration_shape_1.isPromptOnlyMigration)(migration)) {
-                emitOrPrintPrompt(root, migration, agenticKind, {
-                    persistPath: payloadPath,
-                });
+                const payload = promptPayload(root, migration, undefined, undefined);
+                (0, agent_work_payload_1.persistAgentWorkPayload)(payloadPath, payload);
+                if (emitsHandBack)
+                    emitPromptForOuterAgent(migrationId, payload, true);
                 awaitingKind = 'migration-prompt';
             }
             else if (generatorAlreadyCompleted &&
@@ -424,39 +464,30 @@ async function runRecorded(root, runId, migration, skipInstall, isVerbose) {
                 awaitingKind = 'generator-validation';
             }
             else if (generatorAlreadyCompleted) {
-                state = await finishCompletedGenerator(dir, root, state, startedStep, migration, effectiveSkipInstall, runId, scope);
+                state = await finishCompletedGenerator(dir, root, state, startedStep, migration, effectiveSkipInstall, rerunCommand, scope);
                 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}`);
+                const installer = new execute_migration_1.ChangedDepInstaller(root, effectiveSkipInstall, rerunCommand);
                 // 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;
+                const work = owedAgentWork(migration, shouldValidate, changes, skipAgentic);
+                const { validationOwed, promptOwed } = work;
                 // 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,
+                    agenticWaived: work.waived,
                     validationOwed,
                     madeChanges,
                 });
-                if (waivedAgenticStep) {
-                    (0, migrate_output_1.logWaivedAgenticStep)(migration, agentContext);
-                }
-                else if (!(0, migration_shape_1.isHybridMigration)(migration) && !validationApplies) {
-                    forwardDroppedAgentContext(migration, agentContext, agenticKind);
-                }
+                logWaiverOrForwardAgentContext(migration, work, 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 };
@@ -490,11 +521,13 @@ async function runRecorded(root, runId, migration, skipInstall, isVerbose) {
                 }
                 printNextSteps(migration, nextSteps);
                 if (validationOwed) {
-                    emitValidationPayload(migrationId, owed);
+                    if (emitsHandBack)
+                        emitValidationPayload(migrationId, owed, true);
                     awaitingKind = 'generator-validation';
                 }
                 else if (promptOwed) {
-                    emitPromptForOuterAgent(migrationId, owed, true);
+                    if (emitsHandBack)
+                        emitPromptForOuterAgent(migrationId, owed, true);
                     awaitingKind = 'migration-prompt';
                 }
                 else {
@@ -525,7 +558,7 @@ async function runRecorded(root, runId, migration, skipInstall, isVerbose) {
                 finishedAt: (0, util_1.nowIso)(),
                 awaitingKind,
             });
-            return;
+            return true;
         }
         transition(dir, {
             type: 'succeed',
@@ -533,6 +566,7 @@ async function runRecorded(root, runId, migration, skipInstall, isVerbose) {
             finishedAt: (0, util_1.nowIso)(),
             ...(outcome ? { outcome } : {}),
         });
+        return false;
     }
     finally {
         scope.lease?.release();
@@ -569,9 +603,8 @@ 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, 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}`));
+async function finishCompletedGenerator(dir, root, state, step, migration, skipInstall, rerunCommand, scope) {
+    const installDeps = () => recordingInstallFailure(dir, step.id, () => (0, util_1.installDepsChangedSinceDispense)(root, dir, step, skipInstall, rerunCommand));
     // 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.
@@ -587,9 +620,10 @@ async function finishCompletedGenerator(dir, root, state, step, migration, skipI
 // ledger entry and the commit body name the same ones.
 async function commitStepChanges(dir, root, state, step, migration, installDeps, scope) {
     const absorbedStepIds = (0, state_machine_1.uncoveredFailedStepIds)(state).filter((id) => id !== step.id);
+    const recovery = (0, util_1.commitFailureRecovery)(state);
     let commit;
     try {
-        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);
+        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), recovery), scope);
     }
     catch (commitError) {
         // Nothing ran for a stale or refused request, so there is no debt.
@@ -603,7 +637,7 @@ async function commitStepChanges(dir, root, state, step, migration, installDeps,
         throw commitError;
     }
     if (commit.result.status === 'failed') {
-        (0, util_1.warnCommitFailed)(migration.name);
+        (0, util_1.warnCommitFailed)(migration.name, recovery);
     }
     const entry = (0, state_machine_1.commitResultToLedgerEntry)(commit.result, step.id, commit.absorbedStepIds);
     // A session's parent records what it commits itself, receipt included.
@@ -634,61 +668,27 @@ function buildOutcome(changes, nextSteps, description, root) {
     }
     return outcome;
 }
-// Only `run-step` is actually deferred by these requires, and it is the one
-// worth deferring: it pulls in the prompt builders, which nothing but an
-// enabled agentic flow needs. The other two are loaded either way, since the
-// `run/` barrel every caller comes through re-exports `orchestrator.ts`, which
-// imports both statically.
-async function prepareAgenticRun(root, migration, agentic, effectiveCreateCommits, commitPrefix) {
-    const { applyAgenticHandoffGitignoreFallback } = require('../agentic/handoff-gitignore');
-    const { packageJson: nxPackageJson } = (0, package_json_1.readModulePackageJson)('nx', (0, installation_directory_1.getNxRequirePaths)(root));
-    await applyAgenticHandoffGitignoreFallback({
-        migrations: [migration],
-        installedNxVersion: nxPackageJson.version,
-        effectiveCreateCommits,
-        commitPrefix,
-        root,
-    });
-    const { initRunDir, resolveAgenticRunId } = require('../agentic/handoff');
-    const { runAgenticPromptStep } = require('../agentic/run-step');
+// `skipAgentic` counts as a waiver only when an AI step was owed.
+function owedAgentWork(migration, shouldValidate, changes, skipAgentic) {
+    const hybrid = (0, migration_shape_1.isHybridMigration)(migration);
+    const validationApplies = shouldValidate && !hybrid && changes.length > 0;
+    const waived = skipAgentic && (hybrid || validationApplies);
     return {
-        agentic,
-        runDir: initRunDir(root, resolveAgenticRunId([migration])),
-        runStep: runAgenticPromptStep,
+        waived,
+        validationOwed: validationApplies && !waived,
+        promptOwed: hybrid && !waived,
     };
 }
-async function runAgenticStep(agenticRun, input) {
-    try {
-        return await agenticRun.runStep({
-            ...input,
-            agentic: agenticRun.agentic,
-            runDir: agenticRun.runDir,
-        });
-    }
-    catch (e) {
-        (0, migrate_analytics_1.reportMigrateRunError)({
-            code: 'agentic',
-            migrationPackage: input.migration.package,
-            migrationName: input.migration.name,
-            error: e,
-        });
-        throw e;
+// Agent work payloads already carry `agentContext`; forward it separately
+// only when an outer agent has no owed work.
+function logWaiverOrForwardAgentContext(migration, work, agentContext, agenticKind) {
+    if (work.waived) {
+        (0, migrate_output_1.logWaivedAgenticStep)(migration, agentContext);
     }
-}
-// A standalone run has no later commit or end-of-run recap to absorb a failed
-// 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 any remaining uncommitted changes manually.');
-}
-async function commitAndLogAgenticOutcome(args) {
-    const commit = await attemptStandaloneCommit(args.root, args.migration, args.createCommits, args.commitPrefix, args.installDepsIfChanged);
-    (0, migrate_output_1.logAgenticSuccessOutcome)(args.stepResult.ambiguous ? 'Marked complete by user' : args.successLabel, commit.status === 'committed' ? commit.sha : null, args.stepResult.summary);
-}
-// Hybrids are excluded by the caller: their `agentContext` rides in the
-// prompt payload instead.
-function forwardDroppedAgentContext(migration, agentContext, agenticKind) {
-    if (agentContext.length > 0 && agenticKind === 'inside-agent') {
+    else if (!work.validationOwed &&
+        !work.promptOwed &&
+        agentContext.length > 0 &&
+        agenticKind === 'inside-agent') {
         (0, print_dropped_agent_context_1.printDroppedAgentContextForOuterAgent)({ migration, agentContext });
     }
 }
@@ -797,13 +797,15 @@ function emitValidationBlock(root, migration, impl, opts = {}) {
     if (opts.persistPath) {
         (0, agent_work_payload_1.persistAgentWorkPayload)(opts.persistPath, payload);
     }
-    emitValidationPayload(`${migration.package}:${migration.name}`, payload);
+    emitValidationPayload(`${migration.package}:${migration.name}`, payload, opts.persistPath !== undefined);
 }
-function emitValidationPayload(migrationId, payload) {
+function emitValidationPayload(migrationId, payload, recorded) {
     (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.`,
+        title: payload.impl === undefined
+            ? `${CHANGES_AWAIT_VALIDATION} ${RUN_NEXT_FIRST} Inspect the changes with git.`
+            : `The following migration's generator ran without an AI-driven part. ${recorded
+                ? RUN_NEXT_FIRST
+                : "Validate its changes in this workspace, fixing only what lies within the migration's scope, then continue."}`,
     });
     (0, agent_output_1.emitPromptBlock)(migrationId, payload);
 }