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

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

@@ -0,0 +1,2272 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runOrchestratorInit = runOrchestratorInit;
+exports.runOrchestratorResume = runOrchestratorResume;
+exports.holdRunToContinue = holdRunToContinue;
+exports.activeRunToReplace = activeRunToReplace;
+exports.releaseRunToHandOff = releaseRunToHandOff;
+exports.runOrchestratorReconcile = runOrchestratorReconcile;
+exports.completionWarnings = completionWarnings;
+const child_process_1 = require("child_process");
+const crypto_1 = require("crypto");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const native_1 = require("../../../native");
+const fileutils_1 = require("../../../utils/fileutils");
+const atomic_write_1 = require("./atomic-write");
+const clean_retry_1 = require("./clean-retry");
+const broker_1 = require("./broker");
+const git_utils_1 = require("../../../utils/git-utils");
+const versions_1 = require("../../../utils/versions");
+const handoff_1 = require("../agentic/handoff");
+const format_command_1 = require("../agentic/format-command");
+const handoff_gitignore_1 = require("../agentic/handoff-gitignore");
+const instruction_files_1 = require("../agentic/instruction-files");
+const final_validation_1 = require("../agentic/prompts/final-validation");
+const fragments_1 = require("../agentic/prompts/fragments");
+const types_1 = require("../agentic/types");
+const migrate_commits_1 = require("../migrate-commits");
+const migrate_analytics_1 = require("../migrate-analytics");
+const sort_migrations_1 = require("../sort-migrations");
+const run_id_1 = require("./run-id");
+const run_state_1 = require("./run-state");
+const state_lock_1 = require("./state-lock");
+const state_machine_1 = require("./state-machine");
+const give_up_1 = require("./give-up");
+const migration_shape_1 = require("../migration-shape");
+const util_1 = require("./util");
+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 runbook_1 = require("./runbook");
+const existing_run_report_1 = require("./existing-run-report");
+const package_manager_1 = require("../../../utils/package-manager");
+// The dark migrate orchestrator: drives a durable run one dispense at a time.
+// An outer AI agent runs each dispensed command and re-invokes `nx migrate
+// --run-id=<id>` to reconcile; there is no long-lived process.
+const PLAN_SNAPSHOT_0 = 'plan-0.json';
+// A running worker older than this may be hung; the still-running dispense
+// escalates so the agent can verify or kill it.
+const HANG_THRESHOLD_MS = 15 * 60 * 1000;
+// Identical responses in a row before the dispense escalates to a
+// 'no-progress' action. A still-running worker is exempt until the hang
+// threshold: waiting on a live worker is not looping.
+const NO_PROGRESS_THRESHOLD = 3;
+// Two rearms per step: one for the diagnosed fix and one for its correction.
+const REARM_ESCALATION_CAP = 2;
+const INIT_CONTINUE_HINT = 're-run the command, or unset NX_MIGRATE_ORCHESTRATOR to use the standard migrate flow.';
+function continueRunHint(runId) {
+    return `re-run the command to continue run '${runId}'.`;
+}
+// Refuses to proceed when the run's `git add -A` commits could sweep in the
+// scratch under .nx/migrate-runs. Only commit-creating runs probe: without
+// commits the worst case is git-status noise. Fails closed on an unusable
+// probe: createCommits reaching the orchestrator means git was a repository
+// at resolution time (resolveCreateCommits), so an unusable git here is an
+// anomaly, and proceeding would risk absorbing run state into commits, where
+// a later retry-clean `git reset --hard` could roll the tracked state back
+// to a stale snapshot.
+function assertScratchDirSafeForCommits(root, thenWhat) {
+    refuseUnsafeScratchExposure((0, git_utils_1.getPathCommitExposure)(types_1.MIGRATE_RUNS_RELATIVE_DIR, root), thenWhat);
+}
+function refuseUnsafeScratchExposure(exposure, thenWhat) {
+    switch (exposure) {
+        case 'ignored':
+            return;
+        case 'tracked':
+            throw new Error(`Files under ${types_1.MIGRATE_RUNS_RELATIVE_DIR} are committed to git, and ignore rules do not apply to tracked files, so migrate's commits would keep capturing this run's scratch state. ` +
+                `Untrack them with \`git rm -r --cached ${types_1.MIGRATE_RUNS_RELATIVE_DIR}\`, commit that change, make sure .gitignore lists ${types_1.MIGRATE_RUNS_RELATIVE_DIR}, then ${thenWhat}`);
+        case 'unignored':
+            throw new Error(`${types_1.MIGRATE_RUNS_RELATIVE_DIR} is not ignored by git, so migrate's commits would capture this run's scratch state. ` +
+                `Add a \`${types_1.MIGRATE_RUNS_RELATIVE_DIR}\` entry to .gitignore, then ${thenWhat}`);
+        case 'unknown':
+            throw new Error(`Could not verify with git that ${types_1.MIGRATE_RUNS_RELATIVE_DIR} is ignored, so migrate's commits could capture this run's scratch state. ` +
+                `Make sure git is usable in this workspace, then ${thenWhat}`);
+        default: {
+            const exhaustive = exposure;
+            throw new Error(`Unrecognized scratch exposure '${exhaustive}'.`);
+        }
+    }
+}
+async function runOrchestratorInit(input) {
+    const { root, migrationsJson, migrationsPath, createCommits, commitPrefix, skipInstall, installedNxVersion, validate, finalValidation, emitAgentInstructions = true, onExistingRun = 'report', replaceRunId, confirmStart, } = input;
+    const migrations = (migrationsJson.migrations ?? []);
+    const sorted = (0, sort_migrations_1.sortMigrations)(migrations.slice(), {
+        hoistHandoffGitignore: true,
+    });
+    const plannedIds = sorted.map((m) => `${m.package}:${m.name}`);
+    // An active run means a prior init already happened (e.g. it crashed before
+    // the agent's first reconcile); starting a second run would compete with it,
+    // and whether to continue it or replace it is the user's call, not a guess
+    // from the plans. Reported before the migration id check below: this plan
+    // is not being started. NewerRunStateFormatError propagates.
+    const active = onExistingRun === 'start-fresh'
+        ? activeRunToReplace(root, replaceRunId)
+        : findActiveRunForInit(root);
+    if (active &&
+        (onExistingRun === 'report' ||
+            (replaceRunId !== undefined && active.runId !== replaceRunId))) {
+        return reportExistingRun(root, active.runId, active.state, plannedIds, migrationsPath, emitAgentInstructions, replaceRunId);
+    }
+    // Held through confirmStart so a concurrent start-fresh cannot delete the
+    // run while the user is asked. The refusals run here first, before the
+    // prompt, the .gitignore fallback and the checkpoint; the locked pass below
+    // is authoritative. Skipped without the scratch dir: the lock would create it.
+    if (active) {
+        (0, state_lock_1.holdRunActivity)(root, active.runId);
+    }
+    if ((0, fs_1.existsSync)((0, run_state_1.migrateRunsDir)(root))) {
+        (0, state_lock_1.withRunCreationLock)(root, () => {
+            refuseLiveReservation(root);
+            if (active) {
+                refuseUndeletableRun(root, active.runId, active.state);
+            }
+        });
+    }
+    // Dispensed commands interpolate migration ids verbatim, so every init
+    // validates the incoming plan's ids. Before the delete below: a run must
+    // not be thrown away for a plan that cannot start.
+    for (const id of plannedIds) {
+        if (!run_state_1.SHELL_SAFE_VALUE.test(id)) {
+            throw new Error(`The migration id '${id}' contains characters that are not shell-safe. Orchestrated runs require shell-safe migration ids.`);
+        }
+    }
+    if (confirmStart && !(await confirmStart())) {
+        return { kind: 'refused' };
+    }
+    const runId = (0, run_id_1.createRunId)();
+    const dir = (0, run_state_1.runDir)(root, runId);
+    // Probe before any git side effect: the checkpoint below is a `git add -A`
+    // commit, so on a workspace where scratch is committable it would sweep in
+    // prior runs' directories and manufacture the very tracked state the probe
+    // refuses. Missing ignore coverage alone is not refused yet, because the
+    // fallback below may still add the entry. 'ignored' also stands in for
+    // "no hazard" when commits are off.
+    const scratchExposure = createCommits
+        ? (0, git_utils_1.getPathCommitExposure)(types_1.MIGRATE_RUNS_RELATIVE_DIR, root)
+        : 'ignored';
+    if (scratchExposure !== 'unignored') {
+        refuseUnsafeScratchExposure(scratchExposure, INIT_CONTINUE_HINT);
+    }
+    // Applied before the checkpoint so the entry (when it can be added) already
+    // covers older scratch by the time the checkpoint's `git add -A` runs; the
+    // fallback's standalone commit is suppressed because that checkpoint
+    // carries the edit. Unlike the classic loop, a planned ignore migration
+    // can't be deferred to: the run dir is created below, before that
+    // migration runs.
+    await (0, handoff_gitignore_1.applyAgenticHandoffGitignoreFallback)({
+        migrations: sorted,
+        installedNxVersion,
+        effectiveCreateCommits: createCommits,
+        commitPrefix,
+        root,
+        applyWhenPlanned: true,
+        commitStandalone: false,
+    });
+    if (scratchExposure === 'unignored') {
+        // The fallback was the workspace's last chance at ignore coverage;
+        // refuse when it could not add the entry (v23+ conscious removal, no
+        // .gitignore, Lerna without nx.json).
+        refuseUnsafeScratchExposure((0, git_utils_1.getPathCommitExposure)(types_1.MIGRATE_RUNS_RELATIVE_DIR, root), INIT_CONTINUE_HINT);
+    }
+    // One creation-lock section: two inits cannot both create a run, and a
+    // start-fresh's delete and the new directory's reservation (no run.json
+    // yet) land together. Git stays outside the lock: a hook re-entering nx
+    // migrate would wait on this process. The .gitignore fallback is idempotent.
+    let deleted = false;
+    const reserved = (0, state_lock_1.withRunCreationLock)(root, () => {
+        refuseLiveReservation(root);
+        const nowActive = findActiveRunForInit(root, active !== null);
+        if (nowActive && nowActive.runId !== active?.runId) {
+            return nowActive;
+        }
+        if (active) {
+            // Completed meanwhile (a reconcile finished it): nothing to replace.
+            if (!nowActive) {
+                throw new Error(noActiveRunToReplace(active.runId));
+            }
+            deleted = deleteRunRecord(root, active.runId);
+        }
+        // The snapshot must exist before run.json makes the run discoverable: a
+        // crash in between must not leave an active run without its plan.
+        (0, fs_1.mkdirSync)(dir, { recursive: true });
+        (0, fileutils_1.writeJsonFile)((0, path_1.join)(dir, PLAN_SNAPSHOT_0), migrationsJson);
+        // Held from here until run.json is written below and past it: a run must
+        // never be discoverable, or reserved, without a holder.
+        (0, state_lock_1.registerRunActivity)(dir);
+        return null;
+    });
+    if (reserved) {
+        // A run created concurrently since the check above. Reported, not
+        // deleted, even under 'start-fresh': that consent covered the run the
+        // user saw, not one that appeared while this init was running.
+        return reportExistingRun(root, reserved.runId, reserved.state, plannedIds, migrationsPath, emitAgentInstructions);
+    }
+    if (deleted) {
+        removeDeletedRunDir(root, active.runId);
+    }
+    // Checkpoint pre-existing working-tree state BEFORE run.json exists, so a
+    // clean tree stays uncommitted (writing run.json would otherwise dirty it
+    // and fire a spurious checkpoint). A crash between here and createRun
+    // leaves the committed changes orphaned but never lost, and the reserved
+    // directory unlocked, which discovery ignores; the next init re-checkpoints
+    // a now-clean tree as a no-op.
+    // Read before the checkpoint so its content (the planning phase's package
+    // bump and lockfile churn) is inside the whole-run diff the pass selects
+    // from; on the run because a step's gitRefBefore moves on re-dispense.
+    const gitRefAtInit = (0, git_utils_1.getLatestCommitSha)(root);
+    const checkpoint = createCommits
+        ? checkpointEntry(root, commitPrefix, gitRefAtInit)
+        : null;
+    // The preflight checkpoint swallows its own failures, so the tree itself is
+    // the only reliable signal: anything still uncommitted here predates every
+    // step's gitRefBefore and rules out clean retries for the whole run. A
+    // failed probe counts as dirty: mistaking it for clean would let a later
+    // retry-clean reset destroy the very work this flag exists to protect.
+    const checkpointFailed = createCommits && (0, git_utils_1.getWorkingTreeStatus)(root) !== 'clean';
+    const branch = (0, git_utils_1.getGitCurrentBranch)(root);
+    const state = {
+        formatVersion: run_state_1.CURRENT_RUN_STATE_FORMAT_VERSION,
+        runId,
+        createdAt: (0, util_1.nowIso)(),
+        nxVersion: versions_1.nxVersion,
+        status: 'active',
+        createCommits,
+        commitPrefix,
+        ...(skipInstall ? { skipInstall: true } : {}),
+        validate: validate !== false,
+        ...(gitRefAtInit ? { gitRefAtInit } : {}),
+        runbookPath: runbook_1.RUNBOOK_FILE_NAME,
+        ...(branch ? { branch } : {}),
+        rounds: [
+            {
+                index: 0,
+                planSnapshot: PLAN_SNAPSHOT_0,
+            },
+        ],
+        steps: buildSteps(sorted, finalValidation !== false),
+        commits: checkpoint ? [checkpoint] : [],
+        ...(checkpointFailed ? { checkpointFailed: true } : {}),
+        analytics: { startEmitted: false, completeEmitted: false },
+    };
+    (0, state_lock_1.withRunCreationLock)(root, () => {
+        // The runbook gets the snapshot's crash guarantee: a discoverable run
+        // always has the runbook a resume re-emits from disk. 'wx' creates
+        // without following links, so nothing pre-planted at the path can
+        // redirect it.
+        (0, fs_1.writeFileSync)((0, path_1.join)(dir, runbook_1.RUNBOOK_FILE_NAME), (0, runbook_1.renderRunbook)(runbookContext(root, runId, state)), { flag: 'wx' });
+        (0, run_state_1.createRun)(root, state);
+    });
+    return finishInit(root, dir, runId, state, 'created', emitAgentInstructions);
+}
+/**
+ * Continues the active run `runId` names: the `--run-migrations --run-id`
+ * shape on both paths. Refuses as holdRunToContinue does.
+ */
+function runOrchestratorResume(input) {
+    const { root, runId, policy, emitAgentInstructions = true } = input;
+    const state = holdRunToContinue(root, runId);
+    return resumeRun(root, runId, state, policy, emitAgentInstructions);
+}
+/**
+ * Holds the active run `runId` names and returns its state. A continue calls
+ * this before the install and the agent selection: a concurrent start-fresh
+ * must not delete the run meanwhile. Throws when the id names no run or a
+ * finished one, and while another process holds the run: continuing would
+ * open a second session over a live one. Under WASM nothing is held and no
+ * holder refuses.
+ */
+function holdRunToContinue(root, runId) {
+    if (!run_id_1.RUN_ID_SAFE.test(runId)) {
+        throw new Error(`Invalid run id '${runId}'.`);
+    }
+    const dir = (0, run_state_1.runDir)(root, runId);
+    if (!(0, run_state_1.hasRunState)(dir)) {
+        throw new Error(`No migrate run '${runId}' was found under ${types_1.MIGRATE_RUNS_RELATIVE_DIR}.`);
+    }
+    const state = (0, run_state_1.readRunState)(dir);
+    if (state.status !== 'active') {
+        throw new Error(`Migrate run '${runId}' is already complete; there is nothing to continue.`);
+    }
+    (0, state_lock_1.holdRunActivity)(root, runId, true);
+    return state;
+}
+// The active run a start-fresh naming `runId` finds, read-only: init's first
+// check, which the CLI also runs before the install. None refuses, since a
+// completed run means the plan already ran. A different active run is returned
+// too: init reports it instead of deleting it.
+function activeRunToReplace(root, runId) {
+    if (runId !== undefined && !run_id_1.RUN_ID_SAFE.test(runId)) {
+        throw new Error(`Invalid run id '${runId}'.`);
+    }
+    const active = findActiveRunForInit(root, true);
+    if (!active) {
+        throw new Error(noActiveRunToReplace(runId));
+    }
+    return active;
+}
+/**
+ * Drops the hold holdRunToContinue took, for a wrapper that hands the
+ * continue to the workspace-local nx: the child takes its own hold, and an
+ * exclusive one refuses while this process still holds.
+ */
+function releaseRunToHandOff(root, runId) {
+    (0, state_lock_1.releaseRunActivity)((0, run_state_1.runDir)(root, runId));
+}
+// Reads the newest active run; null when no run is active. Uninterpretable
+// run dirs refuse a fresh start (one of them could be an active run this
+// init would compete with) but only warn when a healthy active run is found,
+// unless `refuseUninterpretable`: a start-fresh would delete that run and
+// then find only the unreadable ones. NewerRunStateFormatError propagates
+// from the read.
+function findActiveRunForInit(root, refuseUninterpretable = false) {
+    const { active, uninterpretable } = (0, run_state_1.findActiveRun)(root);
+    if (uninterpretable.length > 0) {
+        const noun = uninterpretable.length === 1 ? 'directory' : 'directories';
+        // A directory name is whatever is on disk and a reason quotes what it
+        // found, so neither can be trusted to stay on the line it is put on.
+        // Sanitized here rather than left to the gateway: these same lines are
+        // joined into the throw below, which leaves through handleErrors.
+        const details = uninterpretable.map((u) => `${types_1.MIGRATE_RUNS_RELATIVE_DIR}/${(0, text_1.singleLine)(u.dirName)}: ${(0, text_1.singleLine)(u.reason)}`);
+        if (!active || refuseUninterpretable) {
+            throw new Error([
+                `Whether a migrate run is still active could not be determined; starting a new run could re-apply migrations an unfinished run already applied.`,
+                ...details,
+                `Fix or remove the listed ${noun}, then re-run the command.`,
+            ].join('\n'));
+        }
+        (0, agent_output_1.warnToAgent)({
+            title: `Ignoring ${uninterpretable.length} migrate run ${noun} that could not be read.`,
+            bodyLines: details,
+        });
+    }
+    return active;
+}
+// A run directory without run.json but with a live activity lock is an init
+// between reserving the directory and writing run.json: the checkpoint commit
+// is in flight and no run may start alongside it. Refused at once, never
+// waited for: a git hook re-entering nx migrate during that commit would
+// otherwise wait on the process waiting for the hook. An unlocked one is the
+// remains of an init that died, which discovery ignores like any other
+// directory without run.json. Call under the creation lock.
+function refuseLiveReservation(root) {
+    for (const entry of (0, fs_1.readdirSync)((0, run_state_1.migrateRunsDir)(root), {
+        withFileTypes: true,
+    })) {
+        if (!entry.isDirectory())
+            continue;
+        const dir = (0, path_1.join)((0, run_state_1.migrateRunsDir)(root), entry.name);
+        if ((0, run_state_1.hasRunState)(dir) || !(0, state_lock_1.hasAnyLiveRunActivity)(dir))
+            continue;
+        throw new Error(`Another nx migrate process is starting a run (${types_1.MIGRATE_RUNS_RELATIVE_DIR}/${(0, text_1.singleLine)(entry.name)}). Wait for it to finish, then re-run the command.`);
+    }
+}
+// The report for an init that found a run already active. On the agent path
+// the report and both ways forward go to stdout, in a block of its own kind:
+// an `error` block would read as a crash, and this is a decision for the
+// user. Held before the facts are read: a concurrent start-fresh must not
+// delete the run under the report or the prompt after it.
+function reportExistingRun(root, runId, state, plannedIds, migrationsPath, emitAgentInstructions, replaceRunId) {
+    (0, state_lock_1.holdRunActivity)(root, runId);
+    const facts = (0, existing_run_report_1.collectExistingRunFacts)(root, runId, state, plannedIds);
+    if (replaceRunId !== undefined) {
+        facts.replacedRunId = replaceRunId;
+    }
+    (0, migrate_analytics_1.reportMigrateOrchestratorExistingRun)({
+        ...(0, state_machine_1.runTallies)(state),
+        activity: facts.otherHolders === 'unknown'
+            ? 'unknown'
+            : facts.otherHolders.length > 0
+                ? 'held'
+                : 'idle',
+    });
+    if (emitAgentInstructions) {
+        const report = (0, existing_run_report_1.renderExistingRunReport)(facts, (0, existing_run_report_1.renderExistingRunCommands)(root, facts, migrationsPath));
+        (0, agent_output_1.logToAgent)(report);
+        const lines = (0, agent_output_1.safeLines)([
+            report.title,
+            ...report.bodyLines,
+            ``,
+            `No migration step ran in this response. Show this report to the user and let them choose; run neither command until they do.`,
+        ]);
+        (0, agent_output_1.emitStepBlock)(runId, '-', 'existing-run', {
+            instructions: lines.join('\n'),
+        });
+    }
+    return { kind: 'existing-run', runId, facts };
+}
+// Throws when the run's record must not be deleted: a worker the run
+// dispensed or another nx migrate process is still acting on it, or another
+// run is active alongside it and would be reported in place of the
+// replacement. `state` is the run state the worker check reads.
+function refuseUndeletableRun(root, runId, state) {
+    if (native_1.IS_WASM) {
+        throw new Error(`Not deleting migrate run '${runId}': without a native file lock nx cannot tell whether another nx migrate process is acting on it. Make sure none is, remove ${types_1.MIGRATE_RUNS_RELATIVE_DIR}/${runId}, then re-run the command.`);
+    }
+    const holders = (0, state_lock_1.liveRunActivityPids)((0, run_state_1.runDir)(root, runId));
+    if (holders === 'unknown' || holders.length > 0) {
+        throw (0, state_lock_1.heldRunError)('deleting', runId, holders);
+    }
+    const workers = (0, existing_run_report_1.liveWorkers)(state);
+    if (workers.length > 0) {
+        throw new Error(`Not deleting migrate run '${runId}': ${(0, existing_run_report_1.workersLine)(workers)}. ` +
+            `Wait for it to finish, then re-run the command. If that pid is not an nx migrate worker, stop it or remove ${types_1.MIGRATE_RUNS_RELATIVE_DIR}/${runId}, then re-run the command.`);
+    }
+    const others = (0, run_state_1.findActiveRun)(root).activeRunIds.filter((id) => id !== runId);
+    if (others.length > 0) {
+        throw new Error(`Not deleting migrate run '${runId}': other migrate runs are active on disk (${others.join(', ')}), and a new run cannot start alongside them. Remove ${types_1.MIGRATE_RUNS_RELATIVE_DIR}/<run id> for each one that should not be continued, then re-run the command.`);
+    }
+}
+function noActiveRunToReplace(runId) {
+    return `Not starting fresh: ${runId === undefined ? 'no migrate run' : `no migrate run '${runId}'`} is active, so there is nothing to replace. To start a run, re-run the command without --start-fresh and --run-id.`;
+}
+// Removes run.json under the state lock, so no reconcile or worker can start
+// against a directory about to disappear. The refusals run again on fresh
+// state: the early pass predates the prompt. False when already gone.
+function deleteRunRecord(root, runId) {
+    const dir = (0, run_state_1.runDir)(root, runId);
+    return (0, state_lock_1.withRunStateLock)(dir, () => {
+        if (!(0, run_state_1.hasRunState)(dir))
+            return false;
+        refuseUndeletableRun(root, runId, (0, run_state_1.readRunState)(dir));
+        // The hold's lock file is inside the directory removeDeletedRunDir removes.
+        (0, state_lock_1.releaseRunActivity)(dir);
+        (0, fs_1.rmSync)((0, path_1.join)(dir, run_state_1.RUN_STATE_FILE_NAME), { force: true });
+        return true;
+    });
+}
+// The rest of a deleted run's directory, removed outside the locks and best
+// effort: what is left holds no run.
+function removeDeletedRunDir(root, runId) {
+    try {
+        (0, fs_1.rmSync)((0, run_state_1.runDir)(root, runId), { recursive: true, force: true });
+    }
+    catch (e) {
+        (0, agent_output_1.warnToAgent)({
+            title: `Could not remove the rest of ${types_1.MIGRATE_RUNS_RELATIVE_DIR}/${runId}: ${(0, util_1.summarizeError)(e)}. It no longer holds a run; remove it when convenient.`,
+        });
+    }
+    (0, agent_output_1.logToAgent)({ title: `Deleted the record of migrate run ${runId}.` });
+}
+// The continue tail behind runOrchestratorResume: the runbook, checkpoint and
+// analytics steps a paused run needs before it can be driven again.
+function resumeRun(root, runId, state, policy, emitAgentInstructions) {
+    // Refused before the checkpoint retry below, which commits.
+    if (state.createCommits !== policy.createCommits ||
+        (state.skipInstall === true) !== policy.skipInstall) {
+        throw new Error(`Nx did not resume the active migrate run because its recorded install and commit policy differs from this invocation's. ` +
+            `Nx takes that policy from --create-commits and --skip-install on the command line. ` +
+            `Re-run with the flags run '${runId}' recorded (its report shows them). To start fresh, re-run with --start-fresh --run-id=${runId}, keeping the same --run-migrations[=<path>] argument used to start the run.`);
+    }
+    const dir = (0, run_state_1.runDir)(root, runId);
+    // Ignore/index state can change while a durable run is paused (a checkout,
+    // a .gitignore edit, a forced add). Probe before the checkpoint retry:
+    // ensureCheckpoint is a `git add -A` commit, so on a workspace that became
+    // unsafe it would absorb the run's own scratch.
+    if (state.createCommits) {
+        assertScratchDirSafeForCommits(root, continueRunHint(runId));
+    }
+    // Read, repair, or refuse the runbook before the checkpoint retry and the
+    // analytics watermark: an invocation that cannot provide the run's
+    // contract must not first change git history or durable run state.
+    const runbook = ensureRunbook(root, dir, runId, state);
+    if (runbook === null) {
+        return { kind: 'refused' };
+    }
+    // A run flagged checkpointFailed gets one more chance to capture the
+    // pre-existing tree state before its first migration commit absorbs it.
+    const resumed = ensureCheckpoint(root, dir, state);
+    announceResume(runId, resumed);
+    return finishInit(root, dir, runId, resumed, 'resumed', emitAgentInstructions, runbook);
+}
+function announceResume(runId, state) {
+    (0, agent_output_1.logToAgent)({
+        title: `nx migrate: resuming run ${runId}`,
+        bodyLines: [
+            `  started: ${state.createdAt}`,
+            `  progress: ${(0, existing_run_report_1.progressLine)((0, state_machine_1.tallySteps)(state))}`,
+        ],
+    });
+}
+// Resume-only checkpoint retry, gated on checkpointFailed: a fresh init always
+// evaluates the checkpoint before run.json exists, so an unflagged run
+// without a checkpoint entry started from a clean tree and there is nothing to
+// capture (retrying there would commit the run's own scratch instead). Skipped
+// once any step has advanced (a late checkpoint would absorb an already-run
+// migration's changes, or the parked validation pass's in-flight edits).
+function ensureCheckpoint(root, dir, state) {
+    if (!state.createCommits || !state.checkpointFailed)
+        return state;
+    if (state.steps.some((s) => s.status !== 'pending'))
+        return state;
+    // Reserved so no step is dispensed into the tree the checkpoint captures;
+    // a run that moved on since the snapshot has nothing left to capture.
+    let lease;
+    try {
+        lease = (0, broker_1.acquireTreeOperation)(dir, { kind: 'checkpoint' });
+    }
+    catch (e) {
+        if (e instanceof broker_1.BrokerStaleRequestError)
+            return state;
+        throw e;
+    }
+    try {
+        // The checkpoint commit is a git side effect, so it runs before the lock;
+        // the ledger append and flag clear then apply to the fresh on-disk state.
+        const checkpoint = checkpointEntry(root, state.commitPrefix, (0, git_utils_1.getLatestCommitSha)(root));
+        // The retried checkpoint captured everything, so clean retries are safe
+        // again. Only a verified-clean tree clears the flag: a failed probe proves
+        // nothing was captured.
+        const cleared = (0, git_utils_1.getWorkingTreeStatus)(root) === 'clean';
+        if (!checkpoint && !cleared)
+            return state;
+        return (0, state_lock_1.updateRunState)(dir, (fresh) => {
+            // Re-check both guards on the fresh state: a concurrent reconcile may
+            // have cleared the flag or advanced a step while the commit ran.
+            // Skipping here can leave that commit unledgered, the documented
+            // crash-window shape.
+            if (!fresh.checkpointFailed ||
+                fresh.steps.some((s) => s.status !== 'pending')) {
+                return null;
+            }
+            // gitRefAtInit stays: no step has moved HEAD since init, so the late
+            // checkpoint sits right after it and inside the whole-run diff.
+            const next = checkpoint ? (0, state_machine_1.appendCommit)(fresh, checkpoint) : fresh;
+            return cleared ? { ...next, checkpointFailed: false } : next;
+        });
+    }
+    finally {
+        lease.release();
+    }
+}
+// Commits pre-existing working-tree state so the first migration's commit can't
+// absorb it, returning the ledger entry only when a commit verifiably landed
+// past `before`, the HEAD the caller read. A clean tree is a no-op. Failure
+// detection is the caller's job: the commit helper swallows failures, so
+// callers re-check the tree afterwards.
+function checkpointEntry(root, commitPrefix, before) {
+    // Skip only on a verified-clean tree; on a failed probe the commit attempt
+    // below re-probes and may succeed once the transient failure passes.
+    if ((0, git_utils_1.getWorkingTreeStatus)(root) === 'clean') {
+        return null;
+    }
+    (0, migrate_commits_1.commitCheckpointBeforeMigrations)(root, commitPrefix);
+    const after = (0, git_utils_1.getLatestCommitSha)(root);
+    if (after && after !== before) {
+        return { kind: 'checkpoint', sha: after, stepIds: [] };
+    }
+    return null;
+}
+// No migration step is dispensed here: the agent reads the runbook first and
+// asks for the run's current step by reconciling, so the contract always lands
+// before the first command does.
+function finishInit(root, dir, runId, state, origin, emitAgentInstructions, 
+// The runbook bytes when the caller already ensured them (the resume path,
+// which must fail before its git and state side effects).
+runbook) {
+    let current = state;
+    if (!current.analytics.startEmitted) {
+        // Claim the watermark on the fresh state first: of two concurrent inits
+        // exactly one flips it, and only that one reports.
+        let claimed = false;
+        current = (0, state_lock_1.updateRunState)(dir, (fresh) => {
+            if (fresh.analytics.startEmitted)
+                return null;
+            claimed = true;
+            return {
+                ...fresh,
+                analytics: { ...fresh.analytics, startEmitted: true },
+            };
+        });
+        if (claimed) {
+            (0, migrate_analytics_1.reportMigrateOrchestratorInit)({
+                // The pass is a step, not a migration.
+                migrationCount: current.steps.filter((s) => s.kind === 'migration')
+                    .length,
+                createCommits: current.createCommits,
+            });
+        }
+    }
+    if (origin === 'resumed') {
+        (0, migrate_analytics_1.reportMigrateOrchestratorResume)((0, state_machine_1.runTallies)(current));
+    }
+    const content = runbook ?? ensureRunbook(root, dir, runId, current);
+    if (content === null) {
+        return { kind: 'refused' };
+    }
+    const ready = {
+        kind: 'ready',
+        runId,
+        runRoot: root,
+        runbookPath: (0, path_1.join)(dir, current.runbookPath ?? runbook_1.RUNBOOK_FILE_NAME),
+        reconcileCommand: reconcileCommand(root, runId),
+    };
+    if (!emitAgentInstructions) {
+        return ready;
+    }
+    (0, agent_output_1.emitRunbookBlock)(runId, content);
+    const instructionLines = [
+        `Nx ${origin} migrate run ${runId}. No migration step ran in this response.`,
+        `Read the runbook above; it is the contract for driving this run. Then run the "next" command to get the run's current step.`,
+        ...runbookFooterLines(root, runId),
+    ];
+    const lines = (0, agent_output_1.safeLines)(instructionLines);
+    (0, agent_output_1.logToAgent)({ title: `nx migrate: run ${origin}`, bodyLines: lines });
+    (0, agent_output_1.emitStepBlock)(runId, '-', 'initialized', {
+        next: ready.reconcileCommand,
+        instructions: lines.join('\n'),
+    });
+    return ready;
+}
+// A missing runbook is re-rendered only by the nx version that created the
+// run: its content is version-locked, and a different nx re-rendering it would
+// silently hand the agent a contract the run was not created under. Returns
+// null after emitting the exit-0 refusal instead.
+function ensureRunbook(root, dir, runId, state) {
+    const filePath = (0, path_1.join)(dir, state.runbookPath ?? runbook_1.RUNBOOK_FILE_NAME);
+    const stat = lstatRunbook(filePath);
+    if (stat?.isFile()) {
+        // The read is the proof the entry is usable: read errors (an unreadable
+        // mode, an I/O failure) propagate rather than letting an unreadable
+        // runbook pass the guard.
+        return (0, handoff_1.readInspectedFile)(filePath, stat, `${types_1.MIGRATE_RUNS_RELATIVE_DIR}/${runId}/${runbook_1.RUNBOOK_FILE_NAME} was replaced while being read; ${continueRunHint(runId)}`);
+    }
+    if (stat) {
+        // A directory here is a corrupted run dir; erasing its contents as a side
+        // effect of a reconcile is not this code's call to make.
+        if (stat.isDirectory()) {
+            throw new Error(`${types_1.MIGRATE_RUNS_RELATIVE_DIR}/${runId}/${runbook_1.RUNBOOK_FILE_NAME} is a directory, not the runbook file nx wrote there. Remove it, then ${continueRunHint(runId)}`);
+        }
+        // Any other non-regular entry (a symlink most likely) is cleared before the
+        // rename publish below: POSIX rename replaces it in place, but not every
+        // platform guarantees that, and a removal failure must propagate rather
+        // than leave the entry standing.
+        (0, fs_1.rmSync)(filePath, { force: true });
+    }
+    if (state.nxVersion !== versions_1.nxVersion) {
+        const reason = [
+            `The runbook for run '${runId}' is missing from ${types_1.MIGRATE_RUNS_RELATIVE_DIR}/${runId}, and this nx (${versions_1.nxVersion}) cannot re-render the one nx ${(0, text_1.singleLine)(state.nxVersion)} wrote.`,
+            `Restore the file (or, if the run was created before runbooks existed, re-run with the nx version that created it). To start fresh, re-run with --start-fresh --run-id=${runId}, keeping the same --run-migrations[=<path>] argument used to start the run.`,
+        ];
+        (0, agent_output_1.warnToAgent)({ title: reason[0], bodyLines: [reason[1]] });
+        (0, agent_output_1.emitStepBlock)(runId, '-', 'error', {
+            instructions: reason.join('\n'),
+        });
+        return null;
+    }
+    const content = (0, runbook_1.renderRunbook)(runbookContext(root, runId, state));
+    // A crashed repair leaves the path missing rather than truncated. 'wx'
+    // creates without following links, so anything planted at the temp name
+    // fails the repair instead of redirecting it.
+    (0, atomic_write_1.publishFileAtomically)(filePath, (tmpPath) => (0, fs_1.writeFileSync)(tmpPath, content, { flag: 'wx' }));
+    (0, state_lock_1.updateRunState)(dir, (fresh) => fresh.runbookPath ? null : { ...fresh, runbookPath: runbook_1.RUNBOOK_FILE_NAME });
+    (0, agent_output_1.warnToAgent)({
+        title: `The runbook for run '${runId}' was missing; it has been re-rendered.`,
+    });
+    return content;
+}
+// lstat that treats only a missing entry as null; other inspection failures
+// (permissions, I/O) propagate rather than masquerading as "missing". Bigint
+// stats so the inode identity compared above cannot lose precision.
+function lstatRunbook(filePath) {
+    try {
+        return (0, fs_1.lstatSync)(filePath, { bigint: true });
+    }
+    catch (e) {
+        if (e?.code === 'ENOENT') {
+            return null;
+        }
+        throw e;
+    }
+}
+function runbookContext(root, runId, state) {
+    return {
+        runId,
+        packageManager: (0, package_manager_1.detectPackageManager)(root),
+        nxInvocation: `${(0, util_1.pmExecPrefix)(root)} nx`,
+        pmExec: (0, util_1.pmExecPrefix)(root),
+        reconcileCommand: reconcileCommand(root, runId),
+        createCommits: state.createCommits,
+        // The same `!== false` read the flag itself gets, so a run recorded
+        // without the field renders validation on.
+        validate: state.validate !== false,
+        // The pass guidance follows the plan: an opted-out run, or one recorded
+        // before the pass existed, has no pass step to dispense.
+        finalValidation: state.steps.some((s) => s.kind === 'final-validation'),
+    };
+}
+// Only the newest recorded commit is checked, so the warning stops on its own
+// once the next step commits on the new history; checking every ledger entry
+// would repeat it on every reconcile after a rebase.
+function warnIfHistoryRewound(root, runId, state) {
+    const commits = (0, existing_run_report_1.recordedCommits)(state);
+    const newest = commits[commits.length - 1]?.sha;
+    if (!newest)
+        return;
+    const head = (0, git_utils_1.getLatestCommitSha)(root);
+    if (!head || (0, git_utils_1.getAncestorStatus)(newest, head, root) !== 'not-ancestor') {
+        return;
+    }
+    const facts = (0, existing_run_report_1.collectExistingRunFacts)(root, runId, state);
+    (0, agent_output_1.warnToAgent)({
+        title: `The newest commit migrate run ${runId} recorded is not reachable from HEAD. Continuing the run as asked.`,
+        bodyLines: (0, existing_run_report_1.renderExistingRunReport)(facts).bodyLines,
+    });
+}
+async function runOrchestratorReconcile(input) {
+    const { root, runId, stepAction } = input;
+    if (!run_id_1.RUN_ID_SAFE.test(runId)) {
+        throw new Error(`Invalid run id '${runId}'.`);
+    }
+    const dir = (0, run_state_1.runDir)(root, runId);
+    if (!(0, run_state_1.hasRunState)(dir)) {
+        // No remediation beyond the id: starting a run is a separate, gated entry
+        // point, so pointing at it here would hand most callers a command that
+        // does something else entirely.
+        throw new Error(`No migrate run '${runId}' was found under ${types_1.MIGRATE_RUNS_RELATIVE_DIR}.`);
+    }
+    (0, state_lock_1.holdRunActivity)(root, runId);
+    // Version refusal (NewerRunStateFormatError) propagates.
+    let state = (0, run_state_1.readRunState)(dir);
+    warnIfHistoryRewound(root, runId, state);
+    // Ignore/index state can change while a durable run is paused (a checkout,
+    // a .gitignore edit, a forced add); re-verify before foldHandoffs, which
+    // can itself commit a settled prompt step.
+    if (state.createCommits) {
+        assertScratchDirSafeForCommits(root, continueRunHint(runId));
+    }
+    // The runbook is the run's persisted contract; read, repair, or refuse it
+    // before any fold or dispense, so the run can never advance while the
+    // contract is unavailable. A completed run, and an active run whose steps are
+    // all terminal, are exempt: no work can advance, the only thing left is the
+    // self-contained terminal response, and hiding it behind a missing contract
+    // would leave the run active forever.
+    if (state.status !== 'completed' &&
+        firstActionableStep(state) !== undefined &&
+        ensureRunbook(root, dir, runId, state) === null) {
+        return;
+    }
+    // (a) fold handoffs into prompt outcomes (committing completed ones).
+    state = await foldHandoffs(root, dir, state);
+    // (b) reclassify running steps whose worker process is gone.
+    state = detectDeaths(dir, state);
+    // (c) apply the decision relay to the single failed/died step.
+    if (stepAction) {
+        // Owns the tree reservation a clean retry's reset, an adopt's commit, a
+        // give-up or a skip's install takes, released once the transition that
+        // records it is written.
+        const scope = {};
+        try {
+            const result = await applyReconcileStepAction(root, dir, state, stepAction, scope);
+            if (result.kind === 'error') {
+                emitError(root, runId, result.reason);
+                return; // no transition was written
+            }
+            const target = result.targetStep;
+            // Unless a reset ran, give-up.ts commits the partial result under the
+            // migration's name and settles the step in one operation; a failed
+            // install or commit settles it with the debt recorded.
+            if (stepAction === 'unresolved' &&
+                state.createCommits &&
+                !result.resetTree) {
+                const outcome = await (0, broker_1.giveUpStepTree)(root, dir, target, state.skipInstall === true, reconcileCommand(root, runId), scope);
+                if (outcome.kind === 'refused') {
+                    emitError(root, runId, outcome.reason);
+                    return;
+                }
+                (0, give_up_1.warnAboutGiveUp)(target, outcome);
+                // Settled already; the dispense refuses a tree still held.
+                scope.lease?.release();
+                scope.lease = undefined;
+                advanceAndDispense(root, dir, runId);
+                return;
+            }
+            // The commit is a git side effect, so it runs before the lock (locked
+            // sections stay synchronous); the transition and any unrecorded entry then
+            // land in one write. Adopt and skip keep the tree, so the install they owe
+            // runs here: the next dispense would take the changed deps as its baseline.
+            // Giving up keeps it the same way when the run does not commit. Retries
+            // owe nothing: the rearmed attempt reconciles itself.
+            const { entry, installFailed, recorded } = await stepActionSideEffects(root, dir, state, target, stepAction, result.resetTree, scope);
+            // A rearm starts a fresh attempt; drop the stale handoff before the rearm
+            // is persisted so a crash in between can't refold the old outcome into the
+            // new attempt. Losing the handoff without the rearm is safe: the step is
+            // still failed/died and the agent re-issues the action.
+            if (stepAction === 'retry' || stepAction === 'retry-clean') {
+                removeHandoff(dir, target.id);
+                // A reset-backed retry reruns the generator, so payloads from earlier
+                // attempts describe a tree that was reset away. Hygiene only: the persisted
+                // generatorCompletedAtAttempt bound is the correctness gate.
+                if (stepAction === 'retry-clean' &&
+                    result.state.steps.find((s) => s.id === target.id)
+                        .generatorCompleted !== true) {
+                    (0, agent_work_payload_1.removeAgentWorkPayloads)(dir, target.id, target.attempt);
+                }
+            }
+            // Re-validate against fresh disk state so a concurrent reconcile's own
+            // rejection surfaces through emitError instead of being written over. The
+            // bound attempt keeps the snapshot checks above honest.
+            let freshRejection;
+            let unresolvedArchiveError;
+            const written = (0, state_lock_1.updateRunState)(dir, (fresh) => {
+                // A plain retry takes no reservation of its own, so this is where it
+                // learns that a live process still commits or installs for the step.
+                const held = (0, broker_1.liveTreeOperation)(fresh, scope.lease?.owner);
+                if (held) {
+                    freshRejection = (0, broker_1.treeBusyMessage)(held);
+                    return null;
+                }
+                // A plain retry's acceptance read the generator marker on the
+                // snapshot; a clean retry that started meanwhile forgets the marker
+                // without moving the attempt, so the attempt check cannot see it.
+                const freshStep = fresh.steps.find((s) => s.id === target.id);
+                if (stepAction === 'retry' &&
+                    freshStep !== undefined &&
+                    generatorPending(freshStep) !== generatorPending(target)) {
+                    freshRejection = `Cannot apply action 'retry' to step '${target.id}': whether its generator ran changed since this reconcile read it. Run the reconcile again.`;
+                    return null;
+                }
+                const reapplied = (0, state_machine_1.applyStepEvent)(fresh, {
+                    type: 'stepAction',
+                    stepId: target.id,
+                    action: stepAction,
+                    attempt: target.attempt,
+                });
+                if (reapplied.kind === 'error') {
+                    freshRejection = reapplied.reason;
+                    return null;
+                }
+                let settled = reapplied.state;
+                // The unresolved status and its issue are persisted together.
+                if (stepAction === 'unresolved') {
+                    const recorded = (0, give_up_1.recordUnresolvedIssue)(dir, settled, target.id);
+                    unresolvedArchiveError = recorded.archiveError;
+                    settled = recorded.state;
+                }
+                const next = installFailed
+                    ? (0, state_machine_1.markInstallFailed)(settled, target.id)
+                    : settled;
+                // An adopted commit absorbs uncovered failed steps the same way a fold
+                // commit does, so it carries their resolved issues too. A session's
+                // parent records its own commits as it answers.
+                return entry && !recorded
+                    ? (0, state_machine_1.appendCommit)(next, (0, issues_1.attachIssueIdsToCommitEntry)(next, entry))
+                    : next;
+            });
+            if (freshRejection) {
+                emitError(root, runId, entry?.kind === 'landed' && entry.sha
+                    ? `${freshRejection} Note: this action's commit ${entry.sha} had already landed and stays in history; resolve the step against the tree as it stands now.`
+                    : freshRejection);
+                return;
+            }
+            if (unresolvedArchiveError !== undefined) {
+                (0, give_up_1.warnUnresolvedNotArchived)((0, state_machine_1.stepLabel)(target), unresolvedArchiveError);
+            }
+            state = written;
+        }
+        finally {
+            scope.lease?.release();
+        }
+    }
+    // (d) choose and emit the next dispense.
+    advanceAndDispense(root, dir, runId);
+}
+// The final validation pass has no generator half: a retry re-hands the pass
+// over the tree it left.
+function buildSteps(sortedMigrations, finalValidation) {
+    const migrations = sortedMigrations.map((m, index) => ({
+        id: `step-${index + 1}`,
+        roundIndex: 0,
+        kind: 'migration',
+        migrationId: `${m.package}:${m.name}`,
+        status: 'pending',
+        attempt: 1,
+        dispenseCount: 0,
+        hasGenerator: !(0, migration_shape_1.isPromptOnlyMigration)(m),
+    }));
+    if (!finalValidation)
+        return migrations;
+    return [
+        ...migrations,
+        {
+            id: `step-${migrations.length + 1}`,
+            roundIndex: 0,
+            kind: 'final-validation',
+            status: 'pending',
+            attempt: 1,
+            dispenseCount: 0,
+            hasGenerator: false,
+        },
+    ];
+}
+async function foldHandoffs(root, dir, state) {
+    let current = state;
+    // Step ids are fixed for the life of a run, so the ids come from the caller's
+    // snapshot while every status read comes from `current`: each iteration can
+    // have advanced the run.
+    for (const { id } of state.steps) {
+        const step = current.steps.find((s) => s.id === id);
+        if (step.status !== 'awaiting-prompt-outcome')
+            continue;
+        const result = readStepHandoff(dir, step.id);
+        if (!result.ok)
+            continue; // still awaiting; the dispense asks to settle it
+        let promptOutcome = handoffToPromptOutcome(result.handoff);
+        // A skipped handoff completes a step whose generator changed the tree.
+        // Prompt-only and no-op hybrid steps remain skipped so they cannot commit
+        // unrelated pending diffs.
+        if (generatorChangesApplied(step) && promptOutcome.status === 'skipped') {
+            promptOutcome = { ...promptOutcome, status: 'completed' };
+        }
+        // Archive under the lock before committing or marking the step terminal.
+        // Failure leaves the handoff retryable instead of landing an unrecorded
+        // commit or a ledger entry without detail; replayed archive writes are
+        // idempotent.
+        let ready = false;
+        let archiveError = null;
+        const reconstructedIssueIds = [];
+        (0, state_lock_1.withRunStateLock)(dir, () => {
+            const fresh = (0, run_state_1.readRunState)(dir);
+            const applied = (0, state_machine_1.applyStepEvent)(fresh, {
+                type: 'foldPromptOutcome',
+                stepId: step.id,
+                attempt: step.attempt,
+                promptOutcome,
+            });
+            if (applied.kind === 'error')
+                return;
+            // A corrupt receipt refuses the fold here, before the commit below
+            // could land unrecorded.
+            (0, state_machine_1.commitReceipt)(fresh, fresh.steps.find((s) => s.id === step.id));
+            const issues = (0, issues_1.parseHandoffIssues)(result.handoff.extras, fresh, step);
+            if (issues.ok !== true)
+                return;
+            try {
+                // The sink survives a throw: a shell rebuilt before the failure is
+                // durable and reads healthy on the retry, so only this pass can
+                // warn that its original detail is gone.
+                (0, issues_1.archiveIssues)(dir, (0, issues_1.applyReportedIssues)(applied.state, step, issues.issues, issues.updates), reconstructedIssueIds);
+            }
+            catch (e) {
+                archiveError = e;
+                return;
+            }
+            ready = true;
+        });
+        (0, issues_1.warnReconstructedArchives)(reconstructedIssueIds);
+        if (archiveError !== null) {
+            (0, agent_output_1.warnToAgent)({
+                title: `The issue details reported by ${(0, state_machine_1.stepLabel)(step)} could not be archived (${(0, util_1.summarizeError)(archiveError)}).`,
+                bodyLines: [
+                    `The step's outcome was not folded; fix the underlying problem, then run the reconcile again.`,
+                ],
+            });
+        }
+        if (!ready)
+            continue;
+        // Phase 2: the commit and the install are side effects, so they run outside
+        // the lock; the transition, the issue application and any unrecorded ledger
+        // entry then land in one fresh-state write.
+        let folded = false;
+        let updateArchiveError = null;
+        let detailArchiveError = null;
+        let archivesDegraded = false;
+        const refoldReconstructedIds = [];
+        const scope = {};
+        try {
+            const { entry, installFailed, recorded } = await foldLedgerEntry(root, dir, current, step, promptOutcome, scope);
+            // Bound to the attempt this handoff was read for: the window is wide (a
+            // commit plus an install) and 'awaiting-prompt-outcome' recurs, so a
+            // concurrent retry could otherwise take this outcome as its own. Under the
+            // lock so the issue application re-archives on the state it lands on.
+            current = (0, state_lock_1.withRunStateLock)(dir, () => {
+                const fresh = (0, run_state_1.readRunState)(dir);
+                if ((0, broker_1.liveTreeOperation)(fresh, scope.lease?.owner))
+                    return fresh;
+                const applied = (0, state_machine_1.applyStepEvent)(fresh, {
+                    type: 'foldPromptOutcome',
+                    stepId: step.id,
+                    attempt: step.attempt,
+                    promptOutcome,
+                });
+                if (applied.kind === 'error')
+                    return fresh;
+                const issues = (0, issues_1.parseHandoffIssues)(result.handoff.extras, fresh, step);
+                if (issues.ok !== true)
+                    return fresh;
+                // A commit this process ran takes the handoff's resolutions when it is
+                // appended below; otherwise the entry already recorded for this attempt
+                // takes them, stamped at its index.
+                const receipt = (0, state_machine_1.commitReceipt)(applied.state, applied.state.steps.find((s) => s.id === step.id));
+                const carrier = entry && !recorded ? undefined : receipt;
+                const application = (0, issues_1.applyReportedIssues)(applied.state, step, issues.issues, issues.updates, carrier?.index);
+                try {
+                    // Phase 1 wrote these files, so a reconstruction here means one
+                    // vanished between the phases; the ids surface that loss. The sink
+                    // survives a throw, so a shell rebuilt before a later batch failed
+                    // still gets warned.
+                    (0, issues_1.archiveIssues)(dir, application, refoldReconstructedIds);
+                }
+                catch (e) {
+                    // A landed commit outranks the drop: refolding would re-attempt
+                    // its commit against a clean tree as no-changes and lose the entry
+                    // for good. Phase 1 already archived this handoff's records durably
+                    // once; the fold proceeds and the loss is warned.
+                    const intact = (0, issues_1.applicationArchivesIntact)(dir, application);
+                    if (entry?.kind !== 'landed' && intact !== true) {
+                        detailArchiveError = e;
+                        return fresh;
+                    }
+                    updateArchiveError = e;
+                    archivesDegraded = intact !== true;
+                }
+                folded = true;
+                let next = installFailed
+                    ? (0, state_machine_1.markInstallFailed)(application.state, step.id)
+                    : application.state;
+                // A landed commit carries the fixes of every issue resolved by a step it
+                // names, absorbed steps included.
+                if (carrier)
+                    next = (0, issues_1.enrichCommitEntryIssueIds)(next, carrier.index);
+                const written = entry && !recorded
+                    ? (0, state_machine_1.appendCommit)(next, (0, issues_1.attachIssueIdsToCommitEntry)(next, entry))
+                    : next;
+                (0, run_state_1.writeRunState)(dir, written);
+                return written;
+            });
+        }
+        finally {
+            scope.lease?.release();
+        }
+        // The written state still names the lease just released; the caller's
+        // own reservation checks must not read it as another process's hold.
+        if (scope.lease)
+            current = (0, run_state_1.readRunState)(dir);
+        (0, issues_1.warnReconstructedArchives)(refoldReconstructedIds);
+        if (detailArchiveError !== null) {
+            (0, agent_output_1.warnToAgent)({
+                title: `The issue details reported by ${(0, state_machine_1.stepLabel)(step)} could not be archived (${(0, util_1.summarizeError)(detailArchiveError)}).`,
+                bodyLines: [
+                    `The step's outcome was not folded; fix the underlying problem, then run the reconcile again.`,
+                ],
+            });
+        }
+        if (updateArchiveError !== null) {
+            (0, agent_output_1.warnToAgent)(archivesDegraded
+                ? {
+                    title: `Some issue transition records for ${(0, state_machine_1.stepLabel)(step)} could not be archived (${(0, util_1.summarizeError)(updateArchiveError)}).`,
+                    bodyLines: [
+                        `run.json stays authoritative for the dispositions; the archived files under the run's issues directory are missing or incomplete for this fold's issues, and its landed commit takes precedence over retrying the archive.`,
+                    ],
+                }
+                : {
+                    title: `Re-archiving the issue records for ${(0, state_machine_1.stepLabel)(step)} failed (${(0, util_1.summarizeError)(updateArchiveError)}).`,
+                    bodyLines: [
+                        `Nothing was lost: the fold's records were verified on disk and recorded in run.json. The failed write may point at a disk problem worth checking.`,
+                    ],
+                });
+        }
+        // A rejected fold leaves the handoff in place: it belongs to whichever
+        // attempt is on disk now, and that attempt's own reconcile still has to
+        // read it. The stored agent-work payloads go with a terminal outcome; a
+        // failed fold keeps them, since a retry re-hands the newest surviving copy.
+        if (folded) {
+            removeHandoff(dir, step.id);
+            if (promptOutcome.status !== 'failed') {
+                (0, agent_work_payload_1.removeAgentWorkPayloads)(dir, step.id, step.attempt);
+            }
+        }
+    }
+    return current;
+}
+// What a folded prompt outcome owes the run state. Only a completed prompt
+// with commits on rides its install in on the commit path; every other
+// outcome installs here, or the next dispense takes the unreconciled
+// package.json edit as its own baseline. A tree that is not verifiably clean
+// records debt; a failed probe counts as dirty.
+async function foldLedgerEntry(root, dir, state, step, promptOutcome, scope) {
+    if (promptOutcome.status === 'completed') {
+        if (state.createCommits) {
+            return commitForStep(root, dir, state, step, scope);
+        }
+        return {
+            entry: null,
+            installFailed: await installFailedForStep(root, dir, state, step, 'fold-install', scope),
+        };
+    }
+    return retainedTreeSideEffects(root, dir, state, step, 'fold-install', scope);
+}
+// Shared by prompts that did not complete and by skipped failed or died steps:
+// the tree is kept as it stands, so the step still owes the install of any
+// dependency edits it left and, with commits on, a debt record when the tree
+// is not verifiably clean (see foldLedgerEntry for why).
+async function retainedTreeSideEffects(root, dir, state, step, seam, scope) {
+    const installFailed = await installFailedForStep(root, dir, state, step, seam, scope);
+    const entry = state.createCommits && (0, git_utils_1.getWorkingTreeStatus)(root) !== 'clean'
+        ? { kind: 'failed', stepIds: [step.id] }
+        : null;
+    return { entry, installFailed };
+}
+// Installs the dependency changes a step's tree may carry when no commit path
+// will, returning whether the install failed. A failure is recorded rather
+// than thrown: reconcile still owes the agent a dispense. Broker errors do
+// throw, as in commitForStep: the next reconcile redoes the action.
+async function installFailedForStep(root, dir, state, step, seam, scope) {
+    const skipInstall = state.skipInstall === true;
+    try {
+        await (0, broker_1.installStepTree)(dir, step, seam, () => (0, util_1.installDepsChangedSinceDispense)(root, dir, step, skipInstall, reconcileCommand(root, state.runId)), scope);
+        return false;
+    }
+    catch (e) {
+        if (e instanceof broker_1.BrokerStaleRequestError ||
+            e instanceof broker_1.BrokerUnavailableError ||
+            e instanceof broker_1.TreeBusyError) {
+            throw e;
+        }
+        (0, agent_output_1.warnToAgent)({
+            title: `The dependencies changed by ${(0, state_machine_1.stepLabel)(step)} could not be installed (${(0, util_1.summarizeError)(e)}).`,
+            bodyLines: [`Run \`${(0, util_1.pmInstallCommand)(root)}\` before continuing.`],
+        });
+        return true;
+    }
+}
+// A failed handoff fails the prompt; a success handoff completes it, unless it
+// marks the prompt not applicable via `extras.outcome === 'skipped'`.
+function handoffToPromptOutcome(handoff) {
+    if (handoff.status === 'failed') {
+        return { status: 'failed', summary: handoff.summary };
+    }
+    if (handoff.extras && handoff.extras['outcome'] === 'skipped') {
+        return { status: 'skipped', summary: handoff.summary };
+    }
+    return { status: 'completed', summary: handoff.summary };
+}
+function detectDeaths(dir, state) {
+    let current = state;
+    // As in foldHandoffs: ids from the caller's snapshot, statuses from
+    // `current`, so an earlier iteration's write is visible to the next.
+    for (const { id } of state.steps) {
+        const step = current.steps.find((s) => s.id === id);
+        if (step.status !== 'running')
+            continue;
+        if (step.pid === undefined || (0, util_1.isPidAlive)(step.pid))
+            continue;
+        // markDied re-validates against fresh disk state, on the attempt and pid
+        // this observation was made for: if the worker finished between the
+        // snapshot and the write, or a retry already put a live worker on the
+        // step, the transition is rejected and the step is left as recorded.
+        current = (0, state_lock_1.updateRunState)(dir, (fresh) => {
+            // A dead worker's commit or install may still be running in the
+            // session's parent; the step stays running until that lands.
+            if ((0, broker_1.liveTreeOperation)(fresh))
+                return null;
+            const applied = (0, state_machine_1.applyStepEvent)(fresh, {
+                type: 'markDied',
+                stepId: step.id,
+                attempt: step.attempt,
+            });
+            return applied.kind === 'ok' ? applied.state : null;
+        });
+    }
+    return current;
+}
+async function applyReconcileStepAction(root, dir, state, action, scope) {
+    const candidates = state.steps.filter((s) => s.status === 'failed' || s.status === 'died');
+    if (candidates.length === 0) {
+        return {
+            kind: 'error',
+            reason: `No step is failed or died, so there is nothing for --step-action=${action} to target.`,
+        };
+    }
+    if (candidates.length > 1) {
+        return {
+            kind: 'error',
+            reason: `More than one step is failed or died; --step-action targets exactly one. Resolve them one at a time.`,
+        };
+    }
+    const step = candidates[0];
+    const held = (0, broker_1.liveTreeOperation)(state);
+    if (held) {
+        return { kind: 'error', reason: (0, broker_1.treeBusyMessage)(held) };
+    }
+    if ((action === 'retry' || action === 'retry-clean') &&
+        rearmCapReached(step)) {
+        return {
+            kind: 'error',
+            reason: `Cannot apply action '${action}' to step '${step.id}': ${rearmCapLine(step, (0, state_machine_1.commitMayBeInHistory)(state, step))}`,
+        };
+    }
+    // A retry-clean the dispense would not have offered must be refused here
+    // too, or a hand-crafted reconcile could reset a tree with no restore point
+    // and destroy prior steps' work.
+    if (action === 'retry-clean') {
+        const head = (0, git_utils_1.getLatestCommitSha)(root);
+        const fallback = `Use ${actionList([
+            ...(step.status === 'died' ? [] : ['retry']),
+            'adopt',
+            ...((0, state_machine_1.commitMayBeInHistory)(state, step) ? [] : ['skip', 'unresolved']),
+        ])} instead.`;
+        if (!(0, clean_retry_1.canOfferCleanRetry)(root, state, step, head)) {
+            return {
+                kind: 'error',
+                reason: `Cannot apply action 'retry-clean' to step '${step.id}': ${(0, clean_retry_1.cleanRetryUnavailableReason)(root, state, step, head)} ${fallback}`,
+            };
+        }
+        // Reset under the reservation: the checks above ran on a snapshot, and
+        // resetForCleanRetry re-checks against the state read once it is held.
+        try {
+            await (0, broker_1.resetStepTree)(dir, step, () => (0, clean_retry_1.resetForCleanRetry)(root, dir, step.id), scope);
+        }
+        catch (e) {
+            if (e instanceof broker_1.BrokerStaleRequestError ||
+                e instanceof broker_1.BrokerUnavailableError ||
+                e instanceof broker_1.TreeBusyError) {
+                throw e;
+            }
+            return {
+                kind: 'error',
+                reason: `Cannot apply action 'retry-clean' to step '${step.id}': the reset to ${step.gitRefBefore} failed: ${e instanceof Error ? e.message : String(e)} ${fallback}`,
+            };
+        }
+        // Only the tree can say whether the reset left it clean. Anything else is
+        // refused: accepting would rearm a step whose next attempt reruns the
+        // generator over the previous attempt's output.
+        if ((0, git_utils_1.getWorkingTreeStatus)(root) !== 'clean') {
+            return {
+                kind: 'error',
+                reason: `Cannot apply action 'retry-clean' to step '${step.id}': the working tree is not verifiably clean after the reset to ${step.gitRefBefore}. Inspect it with \`git status\`, then re-run it. ${fallback}`,
+            };
+        }
+    }
+    // Giving up discards what a generator that never completed left behind
+    // when the same restore point a clean retry needs exists, through the same
+    // reserved reset. When there is no such point the tree is kept: what an
+    // agent authored is never discarded, and a reset here would have no
+    // verified target.
+    const resetTree = action === 'unresolved' &&
+        unresolvedResetsTree(state, step, (0, clean_retry_1.canOfferCleanRetry)(root, state, step, (0, git_utils_1.getLatestCommitSha)(root)));
+    if (resetTree) {
+        try {
+            await (0, broker_1.resetStepTree)(dir, step, () => (0, clean_retry_1.resetForCleanRetry)(root, dir, step.id), scope);
+        }
+        catch (e) {
+            if (e instanceof broker_1.BrokerStaleRequestError ||
+                e instanceof broker_1.BrokerUnavailableError ||
+                e instanceof broker_1.TreeBusyError) {
+                throw e;
+            }
+            return {
+                kind: 'error',
+                reason: `Cannot apply action 'unresolved' to step '${step.id}': the reset to ${step.gitRefBefore} failed: ${e instanceof Error ? e.message : String(e)}`,
+            };
+        }
+        if ((0, git_utils_1.getWorkingTreeStatus)(root) !== 'clean') {
+            return {
+                kind: 'error',
+                reason: `Cannot apply action 'unresolved' to step '${step.id}': the working tree is not verifiably clean after the reset to ${step.gitRefBefore}. Inspect it with \`git status\`, then re-run it.`,
+            };
+        }
+    }
+    // A failed generator can have written to the tree before throwing, and a
+    // plain retry reruns it, so a pre-marker retry is accepted only when git
+    // can see nothing of the failed attempt in the tree. The state machine is
+    // pure and cannot read the tree, which is why the gate lives here.
+    if (action === 'retry' &&
+        step.status === 'failed' &&
+        generatorPending(step)) {
+        const safety = assessPreMarkerRetry(root, step);
+        if (safety.kind === 'unsafe') {
+            return {
+                kind: 'error',
+                reason: `Cannot apply action 'retry' to step '${step.id}': ${safety.reason} Use 'retry-clean' where offered${(0, state_machine_1.commitMayBeInHistory)(state, step) ? '' : `, 'skip' or 'unresolved'`}, or 'adopt'.`,
+            };
+        }
+        if (safety.kind === 'warned') {
+            (0, agent_output_1.warnToAgent)({
+                title: `Retrying ${(0, state_machine_1.stepLabel)(step)} without verification`,
+                bodyLines: [safety.warning],
+            });
+        }
+    }
+    const applied = (0, state_machine_1.applyStepEvent)(state, {
+        type: 'stepAction',
+        stepId: step.id,
+        action,
+        attempt: step.attempt,
+    });
+    if (applied.kind === 'error') {
+        return applied;
+    }
+    return { kind: 'ok', state: applied.state, targetStep: step, resetTree };
+}
+function actionList(actions) {
+    const quoted = actions.map((a) => `'${a}'`);
+    return quoted.length === 1
+        ? quoted[0]
+        : `${quoted.slice(0, -1).join(', ')} or ${quoted[quoted.length - 1]}`;
+}
+// The reset runs before the transition, so it is withheld where the
+// transition refuses the give-up.
+function unresolvedResetsTree(state, step, cleanRetry) {
+    return (generatorPending(step) && !(0, state_machine_1.commitMayBeInHistory)(state, step) && cleanRetry);
+}
+// Git and install side effects run here, before the transition and outside the
+// synchronous state lock.
+async function stepActionSideEffects(root, dir, state, step, action, resetTree, scope) {
+    switch (action) {
+        case 'adopt':
+            // A died worker's unrecorded commit request is reused. A failed step, or
+            // a recorded commit, needs an adopt request of its own, or the old answer
+            // would be replayed.
+            return state.createCommits
+                ? commitForStep(root, dir, state, step, scope, step.status === 'failed' ||
+                    (0, state_machine_1.coveringLandedEntries)(state, step.id).length > 0
+                    ? 'adopt'
+                    : undefined)
+                : {
+                    entry: null,
+                    installFailed: await installFailedForStep(root, dir, state, step, 'action-install', scope),
+                };
+        case 'unresolved':
+            // A reset restored the tree the step was dispensed against, so nothing
+            // is left to install or to record as debt.
+            if (resetTree)
+                return { entry: null, installFailed: false };
+            // A run that commits settles the step in giveUpStepTree instead.
+            return retainedTreeSideEffects(root, dir, state, step, 'action-install', scope);
+        case 'skip':
+            return retainedTreeSideEffects(root, dir, state, step, 'action-install', scope);
+        case 'retry':
+        case 'retry-clean':
+            return { entry: null, installFailed: false };
+        default: {
+            const exhaustive = action;
+            throw new Error(`Unhandled step action '${exhaustive}'.`);
+        }
+    }
+}
+// Commits the working tree left by a folded prompt outcome or an adopted step
+// (failed or died). The caller persists `entry` with the step transition
+// unless `recorded` says a session's parent already did; null when nothing to
+// commit. A crash between the git commit and the state write leaves that
+// commit in history and out of the ledger, with the failures it absorbed
+// uncovered; completion rechecks the tree before warning about that debt.
+async function commitForStep(root, dir, state, step, scope, commitAs) {
+    const name = (0, state_machine_1.commitNameForStep)(step);
+    const absorbedStepIds = (0, state_machine_1.uncoveredFailedStepIds)(state).filter((id) => id !== step.id);
+    const skipInstall = state.skipInstall === true;
+    let commit;
+    try {
+        commit = await (0, broker_1.commitStepTree)(dir, step, absorbedStepIds, () => (0, migrate_commits_1.commitMigrationIfRequested)(root, { name }, true, state.commitPrefix, () => (0, util_1.installDepsChangedSinceDispense)(root, dir, step, skipInstall, reconcileCommand(root, state.runId)), (0, state_machine_1.stepsToPendingMigrations)(state, absorbedStepIds)), scope, commitAs);
+    }
+    catch (e) {
+        // Nothing to record: the step moved on, another process holds the tree, or
+        // the parent never answered. The next reconcile redoes this fold or adopt.
+        if (e instanceof broker_1.BrokerStaleRequestError ||
+            e instanceof broker_1.BrokerUnavailableError ||
+            e instanceof broker_1.TreeBusyError) {
+            throw e;
+        }
+        // The dependency install is the only other thrower: the commit attempt
+        // reports through result.status. The debt cannot stand in for the install
+        // failure, since a later commit absorbing this diff clears the debt while
+        // the dependencies are still missing.
+        (0, util_1.warnCommitFailed)(name, e);
+        return {
+            entry: { kind: 'failed', stepIds: [step.id] },
+            installFailed: true,
+        };
+    }
+    if (commit.result.status === 'failed') {
+        (0, util_1.warnCommitFailed)(name);
+    }
+    return {
+        entry: (0, state_machine_1.commitResultToLedgerEntry)(commit.result, step.id, commit.absorbedStepIds),
+        installFailed: false,
+        recorded: commit.recorded,
+    };
+}
+function advanceAndDispense(root, dir, runId) {
+    // Demote recorded issues no remaining step can claim before anything is
+    // rendered. Done here, at the single choke point every dispense, retry
+    // prompt, and completion goes through, on a fresh locked read: a step
+    // turned terminal by a concurrent reconcile or worker since the caller's
+    // read must not leave an unclaimable issue labeled recorded in a digest
+    // or the completion report.
+    const state = (0, state_lock_1.updateRunState)(dir, (fresh) => {
+        const settled = (0, issues_1.settleUnclaimableIssues)(fresh);
+        return settled === fresh ? null : settled;
+    });
+    const step = firstActionableStep(state);
+    if (!step) {
+        completeRun(root, dir, runId, state);
+        return;
+    }
+    // Track the response streak before emitting: a crash in between costs at
+    // most a count one ahead of what was emitted, and the escalation is
+    // advisory. Only the step responses below count: the completion response
+    // above repeats by design, and a rejected --step-action ends the reconcile
+    // before reaching here, already naming its own fix.
+    const noProgress = trackNoProgress(dir, step);
+    // Another live process holds the tree: the responses below would offer
+    // actions it refuses or name a pid already gone. A running step's own
+    // operation with a live worker keeps still-running, which offers none.
+    const held = (0, broker_1.liveTreeOperation)(state);
+    if (held && !isOwnOperation(step, held)) {
+        emitHeld(root, runId, state, step, held, noProgress);
+        return;
+    }
+    switch (step.status) {
+        case 'pending':
+            dispenseNextStep(root, dir, runId, state, step, noProgress);
+            break;
+        case 'dispensed':
+            // Re-entry before the worker advanced the step; re-emit its command.
+            emitNextStep(root, runId, state, step, noProgress);
+            break;
+        case 'failed':
+            emitRetryFailed(root, runId, state, step, noProgress);
+            break;
+        case 'died':
+            emitDied(root, runId, state, step, noProgress);
+            break;
+        case 'running':
+            emitStillRunning(root, runId, state, step, held, noProgress);
+            break;
+        case 'awaiting-prompt-outcome':
+            emitAwaitPrompt(root, dir, runId, step, noProgress);
+            break;
+        case 'succeeded':
+        case 'skipped':
+        case 'unresolved':
+            // firstActionableStep already excludes these via TERMINAL_STEP_STATUSES;
+            // landing here means an already-terminal step slipped through
+            // unclassified rather than being left to stall the run silently.
+            throw new Error(`Orchestrator could not dispense step '${step.id}': step is already ${step.status}.`);
+        default: {
+            // A new MigrateStepStatus member with no case above fails typecheck
+            // here until it is classified.
+            const exhaustive = step.status;
+            throw new Error(`Orchestrator could not dispense step '${step.id}': unrecognized status '${exhaustive}'.`);
+        }
+    }
+}
+function isOwnOperation(step, held) {
+    return (step.status === 'running' &&
+        held.stepId === step.id &&
+        step.pid !== undefined &&
+        (0, util_1.isPidAlive)(step.pid));
+}
+function firstActionableStep(state) {
+    return state.steps.find((s) => !run_state_1.TERMINAL_STEP_STATUSES.has(s.status));
+}
+// The fingerprint digests the whole persisted state (minus the streak itself),
+// so any durable change resets the count with no per-field enumeration to fall
+// out of date. A response whose own production writes state after the streak
+// is tracked fingerprints the pre-write state, so its first repeat resets
+// rather than increments.
+function responseFingerprint(state) {
+    return (0, crypto_1.createHash)('sha256')
+        .update(JSON.stringify({ ...state, noProgress: undefined }))
+        .digest('hex');
+}
+// A young, parseably-started worker neither increments nor resets the
+// actionable-response streak. Unproven age counts normally.
+function trackNoProgress(dir, step) {
+    if (step.status === 'running') {
+        const startedAt = step.startedAt ? Date.parse(step.startedAt) : NaN;
+        if (Number.isFinite(startedAt) &&
+            Date.now() - startedAt < HANG_THRESHOLD_MS) {
+            return null;
+        }
+    }
+    let streak;
+    (0, state_lock_1.updateRunState)(dir, (fresh) => {
+        const fingerprint = responseFingerprint(fresh);
+        const prev = fresh.noProgress;
+        streak =
+            prev && prev.fingerprint === fingerprint
+                ? { ...prev, consecutiveCount: prev.consecutiveCount + 1 }
+                : {
+                    fingerprint,
+                    consecutiveCount: 1,
+                    firstSeenAt: new Date().toISOString(),
+                };
+        return { ...fresh, noProgress: streak };
+    });
+    return streak.consecutiveCount >= NO_PROGRESS_THRESHOLD ? streak : null;
+}
+function dispenseNextStep(root, dir, runId, state, step, noProgress) {
+    // Read the pre-step baselines (git and package.json reads) before the
+    // lock; the dispense transition and the baselines then apply to the fresh
+    // state in one write.
+    const baselines = {
+        gitRefBefore: (0, git_utils_1.getLatestCommitSha)(root) ?? undefined,
+        treeCleanAtDispense: (0, git_utils_1.getWorkingTreeStatus)(root) === 'clean',
+        depsHashAtDispense: (0, util_1.depsHash)(root),
+    };
+    let advancedElsewhere = false;
+    let held;
+    const current = (0, state_lock_1.updateRunState)(dir, (fresh) => {
+        // A concurrent init or reconcile may have dispensed (or further advanced)
+        // this step since the caller's read; reclassify against the fresh state
+        // below instead of failing the duplicate transition.
+        if (fresh.steps.find((s) => s.id === step.id)?.status !== 'pending') {
+            advancedElsewhere = true;
+            return null;
+        }
+        // A checkpoint in flight would capture the dispensed step's changes;
+        // checked in the write that dispenses, since it can start after any
+        // earlier read.
+        held = (0, broker_1.liveTreeOperation)(fresh);
+        if (held)
+            return null;
+        const dispensed = applyEventOrThrow(fresh, dispenseEvent(step));
+        return setDispenseBaselines(dispensed, step.id, baselines);
+    });
+    if (advancedElsewhere) {
+        // Terminates: step statuses only advance, so each re-entry observes
+        // strictly later state and lands in a non-pending branch of the dispatch.
+        advanceAndDispense(root, dir, runId);
+        return;
+    }
+    if (held) {
+        emitHeld(root, runId, current, step, held, noProgress);
+        return;
+    }
+    const dispensed = current.steps.find((s) => s.id === step.id);
+    (0, migrate_analytics_1.reportMigrateOrchestratorStepDispensed)({
+        attempt: dispensed.attempt,
+        ordinal: (0, state_machine_1.runTallies)(current).dispenseCount,
+    });
+    switch (dispensed.kind) {
+        case 'migration':
+            emitNextStep(root, runId, current, dispensed, noProgress);
+            break;
+        case 'final-validation':
+            emitAwaitPrompt(root, dir, runId, dispensed, noProgress);
+            break;
+        default: {
+            const exhaustive = dispensed;
+            throw new Error(`Unrecognized step: ${JSON.stringify(exhaustive)}`);
+        }
+    }
+}
+function dispenseEvent(step) {
+    switch (step.kind) {
+        case 'migration':
+            return { type: 'dispense', stepId: step.id };
+        case 'final-validation':
+            // No worker runs the pass, so its dispense parks it for the agent.
+            return {
+                type: 'parkForFinalValidation',
+                stepId: step.id,
+                finishedAt: (0, util_1.nowIso)(),
+            };
+        default: {
+            const exhaustive = step;
+            throw new Error(`Unrecognized step: ${JSON.stringify(exhaustive)}`);
+        }
+    }
+}
+function emitNextStep(root, runId, state, step, noProgress) {
+    let migrationId;
+    switch (step.kind) {
+        case 'migration':
+            migrationId = step.migrationId;
+            break;
+        case 'final-validation':
+            // Parked straight from 'pending', so it is never 'dispensed'.
+            throw new Error(`Step '${step.id}' is the final validation pass, which has no worker command.`);
+        default: {
+            const exhaustive = step;
+            throw new Error(`Unrecognized step: ${JSON.stringify(exhaustive)}`);
+        }
+    }
+    emit(root, runId, state, step, 'next-step', {
+        command: workerCommand(root, migrationId, runId),
+        next: reconcileCommand(root, runId),
+        instructionLines: [
+            `Apply migration ${migrationId} by running the command below, then run the "next" command to record the outcome and get the next step.`,
+            ...(0, issues_1.renderIssueDigestLines)(state, step.id, runId),
+        ],
+    }, noProgress);
+}
+function emitRetryFailed(root, runId, state, step, noProgress) {
+    let subject;
+    switch (step.kind) {
+        case 'migration':
+            subject = `Migration ${step.migrationId}`;
+            break;
+        case 'final-validation':
+            subject = 'The final validation pass';
+            break;
+        default: {
+            const exhaustive = step;
+            throw new Error(`Unrecognized step: ${JSON.stringify(exhaustive)}`);
+        }
+    }
+    // A worker failure records its summary on the outcome; a prompt the agent
+    // reported as failed carries the agent's own reason on the prompt outcome.
+    const summary = step.outcome?.summary ?? step.promptOutcome?.summary;
+    const head = (0, git_utils_1.getLatestCommitSha)(root);
+    const tree = dirtyTreeSummary(root);
+    const cleanRetry = (0, clean_retry_1.canOfferCleanRetry)(root, state, step, head);
+    const landed = lastCoveringLandedEntry(state, step);
+    const committed = (0, state_machine_1.commitMayBeInHistory)(state, step);
+    // A failure recorded before the generator marker can still have written to
+    // the tree (a direct fs or exec side effect, or a crash mid-flush); a
+    // marker means only the handed-back half (a prompt or a validation pass)
+    // or the install and commit are left, so plain retry is safe outright. So
+    // is retrying a step with no generator half to rerun.
+    const pending = generatorPending(step);
+    const retrySafety = pending
+        ? assessPreMarkerRetry(root, step)
+        : { kind: 'safe' };
+    const capReached = rearmCapReached(step);
+    const lines = [
+        `${subject} failed${summary ? `: ${summary}` : ''}.`,
+        `  started from: ${step.gitRefBefore ?? '(unknown)'}`,
+        `  current HEAD: ${head ?? '(unknown)'}`,
+        `  working tree: ${tree === null ? '(unknown)' : tree ? `\n${tree}` : '(clean)'}`,
+        ``,
+        retryBudgetLine(step, committed),
+        ``,
+        `Decide how to proceed and re-run reconcile with one of:`,
+        ...(capReached
+            ? []
+            : [retryOptionLine(retrySafety, reconcileCommand(root, runId, 'retry'))]),
+    ];
+    if (cleanRetry && !capReached) {
+        lines.push(`  retry-clean: reset the tree to ${step.gitRefBefore ?? 'the pre-migration ref'} (discarding its uncommitted tracked changes and the untracked files git does not ignore, ${types_1.MIGRATE_RUNS_RELATIVE_DIR} kept) and retry from that clean state by running: ${reconcileCommand(root, runId, 'retry-clean')}`);
+    }
+    lines.push(landed
+        ? `  adopt: keep the landed commit${landed.sha ? ` ${landed.sha}` : ''} and the current working-tree state as the ${(0, state_machine_1.stepNoun)(step)}'s result, then run: ${reconcileCommand(root, runId, 'adopt')}`
+        : `  adopt: ${committed
+            ? `a commit of this ${(0, state_machine_1.stepNoun)(step)}'s changes was started and never recorded`
+            : `the ${(0, state_machine_1.stepNoun)(step)} was ${step.kind === 'migration' ? 'applied' : 'done'} by hand`}; keep the current working-tree state as its result, then run: ${reconcileCommand(root, runId, 'adopt')}`);
+    // Refused by the state machine: the migration is, or may be, committed.
+    if (!committed) {
+        lines.push(`  skip:  ${reconcileCommand(root, runId, 'skip')}`, unresolvedOptionLine(root, runId, state, step, unresolvedResetsTree(state, step, cleanRetry)));
+    }
+    if (pending) {
+        lines.push(UNVERIFIABLE_WRITES_LINE);
+    }
+    // No preselected retry while the generator may still run: git cannot vouch
+    // for every write. Past the cap no retry is offered or accepted.
+    emit(root, runId, state, step, 'retry-failed', {
+        ...(pending || capReached
+            ? {}
+            : { next: reconcileCommand(root, runId, 'retry') }),
+        instructionLines: lines,
+    }, noProgress);
+}
+// Whether the step has used up its rearms: attempts beyond the first are all
+// rearms, whichever retry action produced them.
+function rearmCapReached(step) {
+    return step.attempt - 1 >= REARM_ESCALATION_CAP;
+}
+function retryBudgetLine(step, committed) {
+    if (rearmCapReached(step))
+        return rearmCapLine(step, committed);
+    const left = REARM_ESCALATION_CAP - (step.attempt - 1);
+    return `Retries left for this ${(0, state_machine_1.stepNoun)(step)}: ${left}. Diagnose the failure first and retry only with a plausible fix in hand; ${left === 1
+        ? 'this is the last one, so ask the user before using it'
+        : 'ask the user before using the last one'}. When no user can answer, ${committed
+        ? `adopt only once you have inspected the tree and finished the ${(0, state_machine_1.stepNoun)(step)}; otherwise stop and report`
+        : 'give the step up with unresolved and continue'}.`;
+}
+// Opens a capped dispense and is the reason a retry past the cap is refused.
+function rearmCapLine(step, committed) {
+    return `This ${(0, state_machine_1.stepNoun)(step)} has already been retried ${step.attempt - 1} times without completing, and no further retry is accepted. ${committed
+        ? `Adopt only once you have inspected the tree and finished the ${(0, state_machine_1.stepNoun)(step)}; otherwise ask the user how to proceed, or stop and report.`
+        : 'Choose adopt, skip or unresolved, or ask the user how to proceed.'}`;
+}
+// Whether the step's generator half may still have to run: it exists and no
+// attempt has recorded running it. Only then can a retry apply a generator
+// twice, so only then is a continuation withheld from `next`. A step with no
+// generator (prompt-only) is retried by re-prompting the agent over the tree
+// it already knows, which is the designed recovery; a step recorded before the
+// kind was persisted counts as having one.
+function generatorPending(step) {
+    return step.generatorCompleted !== true && step.hasGenerator !== false;
+}
+// Absent generatorMadeChanges (a marker an older nx wrote) counts as applied,
+// keeping that version's fold behavior.
+function generatorChangesApplied(step) {
+    return (step.generatorCompleted === true && step.generatorMadeChanges !== false);
+}
+// Appended to the failed and died dispenses of a step whose generator may rerun.
+const UNVERIFIABLE_WRITES_LINE = `None of these can be verified against writes git does not see (ignored paths, files outside the repository); if this migration writes there, inspect that state before choosing.`;
+function retryOptionLine(safety, command) {
+    switch (safety.kind) {
+        case 'safe':
+            return `  retry: re-run over the current tree: ${command}`;
+        case 'warned':
+            return `  retry: re-run over the current tree; without git nothing can verify what the failed attempt left, so inspect the tree first: ${command}`;
+        case 'unsafe':
+            return `  retry: re-run over the current tree; refused until the working tree is clean and HEAD is at the started-from ref: ${command}`;
+        default: {
+            const exhaustive = safety;
+            return exhaustive;
+        }
+    }
+}
+function assessPreMarkerRetry(root, step) {
+    const repo = (0, git_utils_1.getGitRepositoryStatus)(root);
+    if (repo === 'not-git') {
+        return {
+            kind: 'warned',
+            warning: `The workspace is not a git repository, so nothing can verify whether the failed attempt left partial changes in the tree. The retry reruns the generator over whatever is there; confirm the tree yourself first.`,
+        };
+    }
+    if (repo === 'unknown') {
+        return {
+            kind: 'unsafe',
+            reason: `the git repository state could not be determined, so nothing can verify whether the failed attempt left changes in the tree.`,
+        };
+    }
+    const head = (0, git_utils_1.getLatestCommitSha)(root);
+    if (!step.gitRefBefore || head !== step.gitRefBefore) {
+        return {
+            kind: 'unsafe',
+            reason: `HEAD is at ${head ?? '(unreadable)'} rather than the ${step.gitRefBefore ?? '(unrecorded)'} this migration started from, so the failed attempt's changes may already be committed and rerunning the generator could apply them twice.`,
+        };
+    }
+    if ((0, git_utils_1.getWorkingTreeStatus)(root) !== 'clean') {
+        return {
+            kind: 'unsafe',
+            reason: `the working tree is not verifiably clean, and the failed attempt may have written to it before failing; rerunning the generator over those changes could apply them twice.`,
+        };
+    }
+    return { kind: 'safe' };
+}
+// Whichever attempt landed it, the commit is this migration's result.
+function lastCoveringLandedEntry(state, step) {
+    const entries = (0, state_machine_1.coveringLandedEntries)(state, step.id);
+    return entries.length > 0 ? entries[entries.length - 1] : null;
+}
+// The give-up option, worded for what happens to the tree: the reserved
+// reset, a partial commit, or the tree left as it stands.
+function unresolvedOptionLine(root, runId, state, step, resetTree) {
+    const command = reconcileCommand(root, runId, 'unresolved');
+    const recorded = `The failure is recorded as a run issue and listed in the completion report.`;
+    const noun = (0, state_machine_1.stepNoun)(step);
+    if (resetTree) {
+        return `  unresolved: give up on this ${noun}, resetting the tree to ${step.gitRefBefore ?? 'the pre-migration ref'} (discarding what the failed attempt left, ${types_1.MIGRATE_RUNS_RELATIVE_DIR} kept), then run: ${command}. ${recorded}`;
+    }
+    if (state.createCommits) {
+        return `  unresolved: give up on this ${noun}; its partial changes are committed under its name, marked unresolved, and the run moves on. Then run: ${command}. ${recorded}`;
+    }
+    return `  unresolved: give up on this ${noun}, leaving the tree as it stands, and move on. Then run: ${command}. ${recorded}`;
+}
+function emitDied(root, runId, state, step, noProgress) {
+    const label = (0, state_machine_1.stepLabel)(step);
+    const ref = step.gitRefBefore;
+    const head = (0, git_utils_1.getLatestCommitSha)(root);
+    const tree = dirtyTreeSummary(root);
+    const cleanRetry = (0, clean_retry_1.canOfferCleanRetry)(root, state, step, head);
+    const committed = (0, state_machine_1.commitMayBeInHistory)(state, step);
+    const resume = !generatorPending(step);
+    const capReached = rearmCapReached(step);
+    const lines = [
+        `The worker for ${label} died; its process is gone.`,
+        `  started from: ${ref ?? '(unknown)'}`,
+        `  current HEAD: ${head ?? '(unknown)'}`,
+        `  working tree: ${tree === null ? '(unknown)' : tree ? `\n${tree}` : '(clean)'}`,
+        ``,
+        retryBudgetLine(step, committed),
+        ``,
+    ];
+    const options = [];
+    if (resume && !capReached) {
+        options.push(`  retry: keep everything this migration already produced (its commit, if any, and the current tree) and run only the part that did not complete, then run: ${reconcileCommand(root, runId, 'retry')}`);
+    }
+    if (cleanRetry && !capReached) {
+        options.push(`  retry-clean: reset the tree to ${ref ?? 'the pre-migration ref'} (discarding its uncommitted tracked changes and the untracked files git does not ignore, ${types_1.MIGRATE_RUNS_RELATIVE_DIR} kept) and retry from that clean state by running: ${reconcileCommand(root, runId, 'retry-clean')}`);
+    }
+    else if (!capReached) {
+        lines.push(`A clean retry is unavailable: ${(0, clean_retry_1.cleanRetryUnavailableReason)(root, state, step, head)}`);
+    }
+    options.push(`  adopt: keep the current working-tree state as this migration's result, then run: ${reconcileCommand(root, runId, 'adopt')}`);
+    // Refused by the state machine: the migration is, or may be, committed.
+    if (!committed) {
+        options.push(`  skip: leave the tree as it stands and move on without this migration, then run: ${reconcileCommand(root, runId, 'skip')}`, unresolvedOptionLine(root, runId, state, step, unresolvedResetsTree(state, step, cleanRetry)));
+    }
+    lines.push(`Choose exactly one:`);
+    lines.push(...options);
+    if (!resume) {
+        lines.push(UNVERIFIABLE_WRITES_LINE);
+    }
+    // `retry` is preselected only when no generator remains to run and the cap
+    // allows it: a reset cannot be verified against writes git does not see, and
+    // adopting records a result nothing checked, so neither is automatic.
+    emit(root, runId, state, step, 'died', {
+        ...(resume && !capReached
+            ? { next: reconcileCommand(root, runId, 'retry') }
+            : {}),
+        instructionLines: lines,
+    }, noProgress);
+}
+function emitHeld(root, runId, state, step, held, noProgress) {
+    emit(root, runId, state, step, 'held', {
+        next: reconcileCommand(root, runId),
+        instructionLines: [(0, broker_1.treeBusyMessage)(held)],
+    }, noProgress);
+}
+function emitStillRunning(root, runId, state, step, held, noProgress) {
+    const ageMs = step.startedAt ? Date.now() - Date.parse(step.startedAt) : 0;
+    const lines = [
+        `The worker for ${(0, state_machine_1.stepLabel)(step)} (pid ${step.pid}) is still running. Wait for it to finish, then run the "next" command.`,
+    ];
+    // A holder pid other than the worker's is the session's parent process.
+    const parentOperation = held !== undefined && held.pid !== step.pid
+        ? (0, broker_1.treeOperationLabel)(held)
+        : undefined;
+    if (parentOperation) {
+        lines.push(`The nx process ${held.pid} is running ${parentOperation} for it; killing the worker does not stop that, and the step can be classified as died only once it finishes.`);
+    }
+    if (ageMs >= HANG_THRESHOLD_MS) {
+        const hung = `It has been running for ${Math.floor(ageMs / 60000)} minutes and may be hung.`;
+        lines.push(parentOperation
+            ? `${hung} Report this to the user: they can quit this session, then press Ctrl+C in the terminal to end ${parentOperation}, and resume the run afterwards.`
+            : `${hung} Verify pid ${step.pid}; either keep waiting, or kill it so the next reconcile can classify it as died.`);
+    }
+    emit(root, runId, state, step, 'still-running', {
+        next: reconcileCommand(root, runId),
+        instructionLines: lines,
+    }, noProgress);
+}
+function emitAwaitPrompt(root, dir, runId, step, noProgress) {
+    const filePath = (0, handoff_1.runStepHandoffPath)(dir, step.id);
+    // Recreated if the agent removed it, so the handed-over path always has its
+    // parent (an agent that has to `mkdir -p` pays a permission prompt).
+    const handoffsDir = (0, run_state_1.runHandoffsDir)(dir);
+    const handoffsDirIs = (0, handoff_1.handoffsDirState)(handoffsDir);
+    if (handoffsDirIs === 'missing') {
+        (0, fs_1.mkdirSync)(handoffsDir, { recursive: true });
+    }
+    // Claim only while fresh state still awaits this handoff. Steps that never
+    // park cannot report updates; serial dispensing fixes order, and stale
+    // attempts redispatch.
+    let advancedElsewhere = false;
+    const claimed = (0, state_lock_1.updateRunState)(dir, (fresh) => {
+        const freshStep = fresh.steps.find((s) => s.id === step.id);
+        if (freshStep?.status !== 'awaiting-prompt-outcome' ||
+            freshStep.attempt !== step.attempt) {
+            advancedElsewhere = true;
+            return null;
+        }
+        const next = (0, issues_1.claimIssuesForStep)(fresh, step.id, runId);
+        return next === fresh ? null : next;
+    });
+    if (advancedElsewhere) {
+        // Terminates like dispenseNextStep's redispatch: step state only
+        // advances, so each re-entry observes strictly later state.
+        advanceAndDispense(root, dir, runId);
+        return;
+    }
+    let lines;
+    switch (step.kind) {
+        case 'migration':
+            lines = awaitMigrationWorkLines(root, dir, claimed, step, filePath);
+            break;
+        case 'final-validation':
+            lines = awaitFinalValidationLines(root, dir, claimed, step, filePath);
+            break;
+        default: {
+            const exhaustive = step;
+            throw new Error(`Unrecognized step: ${JSON.stringify(exhaustive)}`);
+        }
+    }
+    lines.push(...(0, issues_1.renderIssueDigestLines)(claimed, step.id, runId));
+    // A handoff that exists but can't be read/parsed/validated is a rejection,
+    // not a still-awaited outcome. Naming why stops the run from re-emitting the
+    // same await forever while the agent leaves the bad file in place.
+    // A non-directory in the handoffs dir's place is never read through, so a
+    // rewritten handoff cannot cure it: name the replacement instead.
+    const rejection = handoffsDirIs === 'other'
+        ? [
+            `${handoffsDir} is not a directory, so no handoff can be read from it. Replace it with a directory, then write the handoff file and run the "next" command.`,
+        ]
+        : describeRejectedHandoff(dir, claimed, step);
+    if (rejection.length > 0) {
+        lines.push('', ...rejection);
+    }
+    emit(root, runId, claimed, step, 'await-prompt', {
+        next: reconcileCommand(root, runId),
+        instructionLines: lines,
+    }, noProgress);
+}
+// Re-hands a migration's prompt or validation work and returns the lines the
+// await-prompt dispense states it with.
+function awaitMigrationWorkLines(root, dir, claimed, step, filePath) {
+    const migrationId = step.migrationId;
+    const validating = step.awaitingKind === 'generator-validation';
+    // The plan's prompt path is the ground truth for a prompt park: a stored copy
+    // naming different instructions is rejected against it.
+    const planPrompt = validating
+        ? null
+        : planPromptPath(dir, claimed, migrationId);
+    // Re-emit the payload the worker stored when it parked the step, so a
+    // session that lost the original block gets the work restated. An awaiting
+    // step offers no retry action, so a dispense that only pointed backward
+    // could stall a valid run forever; only a plan that cannot name the prompt
+    // falls back to that pointer.
+    const payload = (0, agent_work_payload_1.readAgentWorkPayload)((0, agent_work_payload_1.agentWorkPayloadPath)(dir, step.id, step.attempt), {
+        migrationId,
+        kind: validating ? 'generator-validation' : 'migration-prompt',
+        ...(planPrompt === null ? {} : { promptPath: planPrompt }),
+    }) ??
+        (validating
+            ? { migrationId, kind: 'generator-validation' }
+            : planPrompt === null
+                ? null
+                : { migrationId, prompt: planPrompt });
+    if (payload) {
+        (0, agent_output_1.emitPromptBlock)(migrationId, payload);
+    }
+    const blockRef = payload
+        ? 'the <nx_migrate_prompt> block above'
+        : "the worker's earlier <nx_migrate_prompt> block";
+    const lines = validating
+        ? [
+            `Migration ${migrationId} ran its generator; its changes are awaiting your validation.`,
+            `Validate them (see ${blockRef} and the runbook's validation scope rules), then write the handoff file and run the "next" command.`,
+        ]
+        : [
+            `Migration ${migrationId} is a prompt-based migration awaiting your outcome.`,
+            `Apply the prompt (see ${blockRef}), then write the handoff file and run the "next" command.`,
+            // Resolved per dispense: an earlier step may have changed the formatter
+            // since the runbook was written.
+            `Format command: ${(0, format_command_1.resolveFormatCommand)(root, (0, util_1.pmExecPrefix)(root)) ??
+                'none (no configured formatter is installed)'}`,
+        ];
+    lines.push(`Handoff file: ${filePath}`, 
+    // The skipped outcome is offered only while nothing of the migration is in
+    // the tree: once a generator's changes are applied, the fold treats a
+    // skipped handoff as completed anyway.
+    validating
+        ? `Handoff JSON: ${(0, fragments_1.renderHandoffShapeInline)('what you verified')}. If validation does not apply here, use "status": "success" and say so in the summary.`
+        : generatorChangesApplied(step)
+            ? `Handoff JSON: ${(0, fragments_1.renderHandoffShapeInline)('what you did')}. If the prompt does not apply here, use "status": "success" and say so in the summary; the migration's generator changes are already applied.`
+            : `Handoff JSON: ${(0, fragments_1.renderHandoffShapeInline)('what you did')}. To mark the prompt not applicable, use "status": "success" with "outcome": "skipped".`);
+    return lines;
+}
+// Writes the pass's instructions file and emits the block pointing at it. The
+// file is derived from run state alone, so a re-emit after a restart, or after
+// the agent removed the file, rewrites it instead of re-reading a stored copy.
+function awaitFinalValidationLines(root, dir, state, step, filePath) {
+    const promptsDir = (0, path_1.join)(dir, types_1.PROMPTS_DIR_NAME, step.id);
+    (0, handoff_1.mkdirSafely)(promptsDir, 'prompt directory for the final validation pass');
+    const instructions = (0, instruction_files_1.writeInstructionsFile)(root, promptsDir, (0, final_validation_1.buildFinalValidationInstructions)({
+        runId: state.runId,
+        baseRef: state.gitRefAtInit ?? null,
+        checkpointRef: state.commits.find((c) => c.kind === 'checkpoint')?.sha ?? null,
+        nxInvocation: `${(0, util_1.pmExecPrefix)(root)} nx`,
+        handoffFileAbsolutePath: filePath,
+    }));
+    (0, agent_output_1.emitStepPromptBlock)(step.id, { kind: 'final-validation', instructions });
+    return [
+        `Every migration step is done; the run's final validation pass over the workspace is awaiting your outcome.`,
+        `Follow the instructions file named in the <nx_migrate_prompt> block above (${instructions}), then write the handoff file and run the "next" command.`,
+        `Handoff file: ${filePath}`,
+        `Handoff JSON: ${(0, fragments_1.renderHandoffShapeInline)('what you ran, fixed and left')}. If the workspace has nothing to validate, use "status": "success" and say so in the summary.`,
+    ];
+}
+// The prompt path the run's latest plan snapshot records for the migration.
+// Every failure lands on null, damaged-but-parseable snapshots included: this
+// runs while re-handing an awaiting step's work, and throwing here would keep
+// the run from re-dispensing that work at all. The snapshot name is validated
+// as a bare `plan-<round>.json` at state read, so the join cannot leave the run
+// directory.
+function planPromptPath(dir, state, migrationId) {
+    const round = (0, state_machine_1.latestRound)(state);
+    if (!round)
+        return null;
+    let migrations;
+    try {
+        migrations = (0, fileutils_1.readJsonFile)((0, path_1.join)(dir, round.planSnapshot)).migrations;
+    }
+    catch {
+        return null;
+    }
+    if (!Array.isArray(migrations))
+        return null;
+    for (const entry of migrations) {
+        if (typeof entry !== 'object' || entry === null)
+            continue;
+        const migration = entry;
+        if (`${migration.package}:${migration.name}` !== migrationId)
+            continue;
+        return typeof migration.prompt === 'string' ? migration.prompt : null;
+    }
+    return null;
+}
+// Wording mirrors the classic runner's ambiguous-outcome cause lines. A
+// readable handoff whose issue report is invalid is a rejection too: the fold
+// refused to consume it, and only this response can tell the agent why.
+function describeRejectedHandoff(dir, state, step) {
+    const result = readStepHandoff(dir, step.id);
+    const followUp = 'Rewrite the handoff file, then run the "next" command.';
+    if (result.ok === true) {
+        const issues = (0, issues_1.parseHandoffIssues)(result.handoff.extras, state, step);
+        if (issues.ok !== true) {
+            return [
+                `The handoff file was rejected: ${issues.reason}.`,
+                followUp,
+            ];
+        }
+        return [];
+    }
+    const { reason, detail } = result;
+    if (reason === 'missing')
+        return [];
+    switch (reason) {
+        case 'read-error':
+            return [
+                `The handoff file was rejected: it could not be read${detail ? ` (${detail})` : ''}.`,
+                followUp,
+            ];
+        case 'parse-error':
+            return [
+                `The handoff file was rejected: it contained invalid JSON${detail ? ` (${detail})` : ''}.`,
+                followUp,
+            ];
+        case 'shape-mismatch':
+            return [
+                'The handoff file was rejected: it was missing required fields or had an unexpected shape.',
+                followUp,
+            ];
+        default: {
+            const exhaustive = reason;
+            throw new Error(`Unrecognized handoff rejection reason '${exhaustive}'.`);
+        }
+    }
+}
+// A refused --step-action still exits 0: the tagged error block is the answer
+// to the request, and it carries the reconcile command to run next. A non-zero
+// exit would tell the driving agent that reconcile itself crashed, and it
+// would stop reading for the correction it is being handed.
+function emitError(root, runId, reason) {
+    // A rejected action is an active response like any dispense, so it carries
+    // the runbook footer: the master receiving it may have just lost its
+    // context. One sanitized array feeds both outputs, as in emit().
+    const lines = (0, agent_output_1.safeLines)([reason, ...runbookFooterLines(root, runId)]);
+    (0, agent_output_1.warnToAgent)({
+        title: 'The requested --step-action could not be applied.',
+        bodyLines: lines,
+    });
+    (0, agent_output_1.emitStepBlock)(runId, '-', 'error', {
+        next: reconcileCommand(root, runId),
+        instructions: lines.join('\n'),
+    });
+    (0, migrate_analytics_1.reportMigrateOrchestratorDispense)({ action: 'error', attempt: 0 });
+}
+/**
+ * What a completed run leaves behind for whoever reads its summary, one line
+ * group per warning: commit debt, uninstalled dependency changes, unresolved
+ * issues. Empty when nothing is left.
+ */
+function completionWarnings(root, runId, state) {
+    // The crash-refold window can strand a failed ledger entry whose diff was in
+    // fact absorbed; suppress the warning only on a verified-clean tree. A dirty
+    // tree can still be unrelated edits, so the warning only claims the changes
+    // "may remain".
+    const commitDebt = (0, state_machine_1.hasPendingCommitDebt)(state) && (0, git_utils_1.getWorkingTreeStatus)(root) !== 'clean';
+    const uninstalled = state.steps.filter((s) => s.installFailed);
+    const issueLines = (0, issues_1.renderUnresolvedIssueLines)(state, runId);
+    return [
+        ...(commitDebt
+            ? [
+                [
+                    'Some migration changes could not be committed and may remain in the working tree; review and commit them manually.',
+                ],
+            ]
+            : []),
+        ...(uninstalled.length > 0
+            ? [
+                [
+                    `The dependency changes made by ${uninstalled
+                        .map(state_machine_1.stepLabel)
+                        .join(', ')} were not installed; run \`${(0, util_1.pmInstallCommand)(root)}\` before using the workspace.`,
+                ],
+            ]
+            : []),
+        ...(issueLines.length > 0 ? [issueLines] : []),
+    ];
+}
+function completeRun(root, dir, runId, state) {
+    let current = state;
+    // Persist the terminal status and claim the watermark in one fresh-state
+    // write before emitting: a crash between the write and the output can't
+    // double-count the completion, and of two concurrent reconciles exactly one
+    // claims the report.
+    let shouldEmit = false;
+    if (current.status !== 'completed' || !current.analytics.completeEmitted) {
+        current = (0, state_lock_1.updateRunState)(dir, (fresh) => {
+            if (fresh.status === 'completed' && fresh.analytics.completeEmitted) {
+                return null;
+            }
+            shouldEmit = !fresh.analytics.completeEmitted;
+            return {
+                ...fresh,
+                status: 'completed',
+                analytics: { ...fresh.analytics, completeEmitted: true },
+            };
+        });
+    }
+    if (shouldEmit) {
+        (0, migrate_analytics_1.reportMigrateOrchestratorComplete)((0, state_machine_1.runTallies)(current));
+    }
+    const warnings = completionWarnings(root, runId, current);
+    for (const lines of warnings) {
+        (0, agent_output_1.warnToAgent)({ title: lines[0], bodyLines: lines.slice(1) });
+    }
+    const instructionLines = [
+        `Migrate run ${runId} is complete.`,
+        ...(0, state_machine_1.completionSummaryLines)(current),
+        ...warnings.flat(),
+    ];
+    (0, agent_output_1.logToAgent)({ title: 'nx migrate: complete', bodyLines: instructionLines });
+    (0, agent_output_1.emitStepBlock)(runId, '-', 'complete', {
+        instructions: instructionLines.join('\n'),
+    });
+}
+function emit(root, runId, state, step, action, payload, noProgress) {
+    // At the escalation threshold the whole response becomes the 'no-progress'
+    // action, with the step's own instructions kept below so acting on them stays
+    // possible. Never a step status: nothing durable changed, and a status would
+    // have to be walked back once the agent acts.
+    const escalated = noProgress !== null;
+    const effectiveAction = escalated ? 'no-progress' : action;
+    const { instructionLines, ...rest } = payload;
+    const allLines = escalated
+        ? [...noProgressLines(step, noProgress), ...(instructionLines ?? [])]
+        : instructionLines;
+    const withFooter = allLines
+        ? [...allLines, ...runbookFooterLines(root, runId)]
+        : undefined;
+    // One sanitized array feeds both, so the block payload says exactly what the
+    // human echo said.
+    const lines = withFooter ? (0, agent_output_1.safeLines)(withFooter) : undefined;
+    (0, agent_output_1.logToAgent)({ title: `nx migrate: ${effectiveAction}`, bodyLines: lines });
+    (0, agent_output_1.emitStepBlock)(runId, step.id, effectiveAction, {
+        ...rest,
+        ...(lines ? { instructions: lines.join('\n') } : {}),
+    });
+    (0, migrate_analytics_1.reportMigrateOrchestratorDispense)({
+        action: effectiveAction,
+        attempt: step.attempt,
+        ordinal: (0, state_machine_1.runTallies)(state).dispenseCount,
+    });
+}
+function noProgressLines(step, streak) {
+    let subject;
+    switch (step.kind) {
+        case 'migration':
+            subject = `migration ${step.migrationId}`;
+            break;
+        case 'final-validation':
+            subject = 'the final validation pass';
+            break;
+        default: {
+            const exhaustive = step;
+            throw new Error(`Unrecognized step: ${JSON.stringify(exhaustive)}`);
+        }
+    }
+    return [
+        `No progress: this is response ${streak.consecutiveCount} in a row for ${subject} with no change in the run's recorded state since ${streak.firstSeenAt}.`,
+        `Re-running the reconcile command changes nothing on its own; act on the instructions below. If something is blocking you from acting on them, stop looping and report the blocker to the user.`,
+        ``,
+    ];
+}
+// Append the runbook path to init, active and rejected responses so a
+// compacted, truncated or restarted session can recover the contract. Missing
+// or non-regular runbooks stand alone.
+function runbookFooterLines(root, runId) {
+    if (lstatRunbook((0, path_1.join)((0, run_state_1.runDir)(root, runId), runbook_1.RUNBOOK_FILE_NAME))?.isFile() !==
+        true) {
+        return [];
+    }
+    return [
+        ``,
+        `Runbook: ${types_1.MIGRATE_RUNS_RELATIVE_DIR}/${runId}/${runbook_1.RUNBOOK_FILE_NAME}. After a compaction or restart, re-read it and run \`${reconcileCommand(root, runId)}\`; never infer the run's progress from memory.`,
+    ];
+}
+// Raw argv is forwarded verbatim across the wrapper hops, so every flag is a
+// single `--flag=value` token. Interpolated values are validated shell-safe at
+// init (migration ids; resumed run ids are gated by the run-dir scan) and
+// reconcile entry (run id).
+function workerCommand(root, migrationId, runId) {
+    return `${(0, util_1.pmExecPrefix)(root)} nx migrate --run-migration=${migrationId} --run-id=${runId}`;
+}
+function reconcileCommand(root, runId, action) {
+    const base = `${(0, util_1.pmExecPrefix)(root)} nx migrate --run-id=${runId}`;
+    return action ? `${base} --step-action=${action}` : base;
+}
+// Records what the workspace looked like as this attempt starts. The git ref
+// and the tree state are re-captured per dispense, since a retry restarts from
+// wherever the tree is now. The dependency baseline is not: it tracks the last
+// dependencies that were actually installed, moving only when an install
+// lands, so a retry that only has the commit left to do still sees the
+// previous attempt's package.json edits as needing one.
+function setDispenseBaselines(state, stepId, baselines) {
+    const depsBaseline = state.steps.find((s) => s.id === stepId)?.depsHashAtDispense;
+    return {
+        ...state,
+        steps: state.steps.map((s) => s.id === stepId
+            ? {
+                ...s,
+                gitRefBefore: baselines.gitRefBefore,
+                treeCleanAtDispense: baselines.treeCleanAtDispense,
+                depsHashAtDispense: depsBaseline ?? baselines.depsHashAtDispense ?? undefined,
+            }
+            : s),
+    };
+}
+// Applies a step event to fresh state or throws the orchestrator's advance
+// error. Pure; callers persist the result via updateRunState.
+function applyEventOrThrow(state, event) {
+    const result = (0, state_machine_1.applyStepEvent)(state, event);
+    if (result.kind === 'error') {
+        throw new Error(`Orchestrator could not advance the run: ${result.reason}`);
+    }
+    return result.state;
+}
+function readStepHandoff(dir, stepId) {
+    return (0, handoff_1.readHandoffWithReason)((0, handoff_1.runStepHandoffPath)(dir, stepId), (0, run_state_1.runHandoffsDir)(dir));
+}
+// Probe-time guard: a handoffs dir the agent swapped for a symlink into a
+// directory holding a file of the step's fixed name would otherwise have the
+// orchestrator delete that file. A swap between the probe and the rm is not
+// caught. A probe failure skips the rm too; the next read reports it.
+function removeHandoff(dir, stepId) {
+    let state;
+    try {
+        state = (0, handoff_1.handoffsDirState)((0, run_state_1.runHandoffsDir)(dir));
+    }
+    catch {
+        return;
+    }
+    if (state === 'directory') {
+        (0, fs_1.rmSync)((0, handoff_1.runStepHandoffPath)(dir, stepId), { force: true });
+    }
+}
+// null means the probe itself failed; the death dispense renders that as
+// '(unknown)', because '(clean)' would invite a retry-clean reset over
+// evidence that was never gathered (getWorkingTreeStatus's contract).
+function dirtyTreeSummary(root) {
+    try {
+        return (0, child_process_1.execSync)('git status --porcelain', {
+            encoding: 'utf8',
+            cwd: root,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: true,
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}