@ohos-ports/nx 23.2.1-beta.0 → 23.3.0-beta.0

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

@@ -0,0 +1,843 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSingleMigrationWorker = runSingleMigrationWorker;
+const fs_1 = require("fs");
+const path_1 = require("path");
+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 print_dropped_agent_context_1 = require("../agentic/print-dropped-agent-context");
+const select_1 = require("../agentic/select");
+const types_1 = require("../agentic/types");
+const command_object_1 = require("../command-object");
+const execute_migration_1 = require("../execute-migration");
+const migrate_analytics_1 = require("../migrate-analytics");
+const migrate_commits_1 = require("../migrate-commits");
+const migrate_output_1 = require("../migrate-output");
+const migration_shape_1 = require("../migration-shape");
+const safe_prompt_1 = require("../safe-prompt");
+const run_state_1 = require("./run-state");
+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
+    // join resolves '..'), so validate it up front exactly as the orchestrator
+    // does before it trusts a run id.
+    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 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,
+    });
+    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);
+        return;
+    }
+    let agentic;
+    try {
+        agentic = await (0, select_1.resolveAgentic)({
+            agentic: input.agentic,
+            migrations: [migration],
+            interactive,
+        });
+    }
+    catch (e) {
+        (0, migrate_analytics_1.reportMigrateRunError)({ code: 'agentic', error: e });
+        throw e;
+    }
+    const resolved = (0, migrate_commits_1.resolveCreateCommits)({
+        createCommits: input.createCommits,
+        mode: agentic.kind,
+        isGitRepo: (0, git_utils_1.isGitRepository)(root),
+        commitPrefixIsCustom: commitPrefix !== command_object_1.DEFAULT_MIGRATION_COMMIT_PREFIX,
+    });
+    if (resolved.error) {
+        throw new Error(resolved.error);
+    }
+    if (resolved.warning) {
+        (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'))) {
+        return;
+    }
+    await runStandalone(root, migration, {
+        agentic,
+        createCommits,
+        agenticHasDiffContext: resolved.agenticHasDiffContext,
+        shouldRunValidation: (0, select_1.resolveShouldRunValidation)({
+            validate: input.validate,
+            agenticKind: agentic.kind,
+        }),
+        commitPrefix,
+        skipInstall,
+        isVerbose,
+    });
+}
+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; 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);
+        if (!round) {
+            throw new Error(`The migrate run '${runId}' has no recorded plan, so there is no migration to run.`);
+        }
+        // Safe to join and to name in the error below only because the read
+        // refuses any planSnapshot that is not a bare `plan-<round>.json`.
+        const planPath = (0, path_1.join)(dir, round.planSnapshot);
+        if (!(0, fs_1.existsSync)(planPath)) {
+            throw new Error(`The plan snapshot '${round.planSnapshot}' for migrate run '${runId}' doesn't exist, can't run the migration.`);
+        }
+        return {
+            migrations: readPlanMigrations(planPath),
+            source: round.planSnapshot,
+        };
+    }
+    const migrationsPath = (0, path_1.join)(root, 'migrations.json');
+    if (!(0, fs_1.existsSync)(migrationsPath)) {
+        throw new Error(`File 'migrations.json' doesn't exist, can't run the migration. Run \`${(0, util_1.pmExecPrefix)(root)} nx migrate\` to generate it first.`);
+    }
+    return {
+        migrations: readPlanMigrations(migrationsPath),
+        source: 'migrations.json',
+    };
+}
+function readPlanMigrations(path) {
+    return ((0, fileutils_1.readJsonFile)(path).migrations ?? []);
+}
+function resolveMigration(migrations, id, source) {
+    // Split on the first ':' only, so a name that itself contains one survives.
+    const colon = id.indexOf(':');
+    const matches = colon === -1
+        ? migrations.filter((m) => m.name === id)
+        : migrations.filter((m) => m.package === id.slice(0, colon) && m.name === id.slice(colon + 1));
+    if (matches.length === 0) {
+        throw new Error(`No migration matching '${id}' was found in ${source}.`);
+    }
+    if (matches.length > 1) {
+        throw new Error([
+            `More than one migration matches '${id}' in ${source}. Re-run with the full '<package>:<name>' id:`,
+            ...matches.map((m) => `  - ${m.package}:${m.name}`),
+        ].join('\n'));
+    }
+    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.`,
+            ],
+        });
+    }
+    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);
+        }
+        return;
+    }
+    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;
+    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);
+    }
+    // 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);
+    }
+    else {
+        await installer.installDepsIfChanged();
+    }
+    if (installer.skippedInstall) {
+        (0, execute_migration_1.logSkippedPostMigrationInstall)(root);
+    }
+    printNextSteps(migration, nextSteps);
+    // 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, {
+            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,
+    // 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.kind === 'migration' &&
+        s.migrationId === migrationId &&
+        s.roundIndex === latest?.index);
+    if (!step) {
+        throw new Error(`The migrate run '${runId}' has no step for migration '${migrationId}'.`);
+    }
+    // Validated against the fresh disk state: a second worker racing the same
+    // dispensed step reads 'running' here and aborts before the engine runs.
+    state = transition(dir, {
+        type: 'start',
+        stepId: step.id,
+        pid: process.pid,
+        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. 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;
+    // 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 {
+        try {
+            if ((0, migration_shape_1.isPromptOnlyMigration)(migration)) {
+                emitOrPrintPrompt(root, migration, agenticKind, {
+                    persistPath: payloadPath,
+                });
+                awaitingKind = 'migration-prompt';
+            }
+            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 (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';
+            }
+            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 {
+                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) {
+            // 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: 'succeed',
+            stepId: step.id,
+            finishedAt: (0, util_1.nowIso)(),
+            ...(outcome ? { outcome } : {}),
+        });
+    }
+    finally {
+        scope.lease?.release();
+    }
+}
+// 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
+// step already 'running' and abort. An illegal transition (e.g. a step that was
+// never dispensed) fails with the state machine's own reason.
+function transition(dir, event) {
+    return (0, state_lock_1.updateRunState)(dir, (fresh) => {
+        const result = (0, state_machine_1.applyStepEvent)(fresh, event);
+        if (result.kind === 'error') {
+            throw new Error(`Cannot record this migration into the run: ${result.reason}`);
+        }
+        return result.state;
+    });
+}
+// Records a dependency install failure on the step before letting it fail the
+// attempt. The 'failed' status says this attempt did not finish, not that the
+// workspace's dependencies are missing, and the two part ways as soon as the
+// agent skips the step or a later step's commit absorbs its diff: either one
+// completes the run with node_modules stale and nothing left to warn about.
+async function recordingInstallFailure(dir, stepId, install) {
+    try {
+        return await install();
+    }
+    catch (e) {
+        (0, state_lock_1.updateRunState)(dir, (fresh) => (0, state_machine_1.markInstallFailed)(fresh, stepId));
+        throw e;
+    }
+}
+// Finishes a step whose generator ran in an earlier attempt that then failed
+// 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}`));
+    // 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, 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, scope) {
+    const absorbedStepIds = (0, state_machine_1.uncoveredFailedStepIds)(state).filter((id) => id !== step.id);
+    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);
+    }
+    catch (commitError) {
+        // 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 (commit.result.status === 'failed') {
+        (0, util_1.warnCommitFailed)(migration.name);
+    }
+    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;
+}
+// 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 = {};
+    if (changes.length > 0) {
+        outcome.fileChanges = changes.map((c) => c.path);
+    }
+    // Non-git repos have no HEAD; omit rather than record a placeholder.
+    const gitRefAfter = (0, git_utils_1.getLatestCommitSha)(root);
+    if (gitRefAfter) {
+        outcome.gitRefAfter = gitRefAfter;
+    }
+    if (nextSteps.length > 0) {
+        outcome.nextSteps = nextSteps;
+    }
+    if (description) {
+        outcome.summary = description;
+    }
+    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');
+    return {
+        agentic,
+        runDir: initRunDir(root, resolveAgenticRunId([migration])),
+        runStep: runAgenticPromptStep,
+    };
+}
+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;
+    }
+}
+// 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') {
+        (0, print_dropped_agent_context_1.printDroppedAgentContextForOuterAgent)({ migration, agentContext });
+    }
+}
+function printNextSteps(migration, nextSteps) {
+    if (nextSteps.length === 0)
+        return;
+    (0, agent_output_1.logToAgent)({
+        title: `Next steps for ${migration.package}: ${migration.name}`,
+        bodyLines: nextSteps.map((line) => `- ${(0, text_1.singleLine)(line)}`),
+    });
+}
+function emitOrPrintPrompt(root, migration, agenticKind, opts = {}) {
+    const migrationId = `${migration.package}:${migration.name}`;
+    if (agenticKind === 'inside-agent') {
+        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, migration.prompt, resolveDocumentationPath(root, migration, opts.resolvedCollection));
+    }
+}
+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 = 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: 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);
+}
+function printPromptForUser(root, migration, promptPath, documentationPath) {
+    const bodyLines = [];
+    if (promptPath)
+        bodyLines.push(`Instructions file: ${promptPath}`);
+    if (documentationPath)
+        bodyLines.push(`Documentation: ${documentationPath}`);
+    let content = '';
+    let readErrorCode;
+    if (promptPath) {
+        try {
+            content = (0, fs_1.readFileSync)((0, path_1.join)(root, promptPath), 'utf-8');
+        }
+        catch (e) {
+            const err = e;
+            readErrorCode = err.code ?? err.message;
+        }
+    }
+    if (readErrorCode) {
+        // Point at the file and error code: the generic "review the instructions
+        // above" copy would sit under an empty body.
+        bodyLines.push('', `The instructions file '${promptPath}' could not be read (${readErrorCode}). Open it manually and apply the instructions.`);
+    }
+    else {
+        if (content) {
+            bodyLines.push('', ...content.split('\n'));
+        }
+        bodyLines.push('', 'Review the instructions above and apply them manually.');
+    }
+    (0, agent_output_1.logToAgent)({
+        title: `Prompt-based migration ${migration.package}: ${migration.name} must be applied manually`,
+        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) {
+    if (!migration.documentation)
+        return undefined;
+    let documentationPath;
+    try {
+        const { collectionPath } = resolvedCollection ?? (0, execute_migration_1.readMigrationCollection)(migration.package, root);
+        documentationPath = (0, execute_migration_1.resolveDocumentationFileToWorkspacePath)(root, (0, path_1.dirname)(collectionPath), migration.documentation);
+    }
+    catch {
+        // An unreadable collection is reported through the warning below.
+    }
+    if (!documentationPath) {
+        (0, agent_output_1.warnToAgent)({
+            title: `Could not resolve the "documentation" file "${migration.documentation}" declared for migration "${migration.package}: ${migration.name}". It will be skipped.`,
+        });
+    }
+    return documentationPath;
+}