nx 23.3.0-beta.7 → 23.3.0-beta.9

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

@@ -1,12 +1,17 @@
 "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");
@@ -25,6 +30,7 @@ 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");
@@ -32,6 +38,7 @@ 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
@@ -44,11 +51,8 @@ const HANG_THRESHOLD_MS = 15 * 60 * 1000;
 // '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;
-// Rearms of one step before its failed/died dispense escalates: the retry
-// guidance flips against retrying and the preselected `next` is withheld, so
-// an agent that follows `next` blindly cannot retry forever. An explicit
-// retry is still honored; the cap never refuses.
-const REARM_ESCALATION_CAP = 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}'.`;
@@ -84,30 +88,50 @@ function refuseUnsafeScratchExposure(exposure, thenWhat) {
     }
 }
 async function runOrchestratorInit(input) {
-    const { root, migrationsJson, createCommits, commitPrefix, skipInstall, installedNxVersion, validate, emitAgentInstructions = true, } = input;
-    const planHash = (0, run_id_1.computePlanHash)(migrationsJson);
-    // 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.
-    // Same plan: resume it. Different plan: refuse rather than guess which plan
-    // the agent means. NewerRunStateFormatError propagates.
-    const active = findActiveRunForPlan(root, planHash);
-    // Dispensed commands interpolate migration ids verbatim, so every init
-    // (fresh or resumed) validates the incoming plan's ids. After the mismatch
-    // check: a plan that will be refused anyway should get the more actionable
-    // mismatch error, not this one.
+    const { root, migrationsJson, migrationsPath, createCommits, commitPrefix, skipInstall, installedNxVersion, validate, emitAgentInstructions = true, onExistingRun = 'report', replaceRunId, confirmStart, } = input;
     const migrations = (migrationsJson.migrations ?? []);
     const sorted = (0, sort_migrations_1.sortMigrations)(migrations.slice(), {
         hoistHandoffGitignore: true,
     });
-    for (const m of sorted) {
-        const id = `${m.package}:${m.name}`;
+    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.`);
         }
     }
-    const policy = { createCommits, skipInstall };
-    if (active) {
-        return resumeRun(root, active.runId, active.state, policy, emitAgentInstructions);
+    if (confirmStart && !(await confirmStart())) {
+        return { kind: 'refused' };
     }
     const runId = (0, run_id_1.createRunId)();
     const dir = (0, run_state_1.runDir)(root, runId);
@@ -144,12 +168,48 @@ async function runOrchestratorInit(input) {
         // .gitignore, Lerna without nx.json).
         refuseUnsafeScratchExposure((0, git_utils_1.getPathCommitExposure)(types_1.MIGRATE_RUNS_RELATIVE_DIR, root), INIT_CONTINUE_HINT);
     }
-    // Checkpoint pre-existing working-tree state BEFORE the run dir exists, so
-    // the checkpoint's `git add -A` can't track this run's scratch and 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; the next init re-checkpoints a
-    // now-clean tree as a no-op.
+    // 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.
     const checkpoint = createCommits ? checkpointEntry(root, commitPrefix) : null;
     // The preflight checkpoint swallows its own failures, so the tree itself is
     // the only reliable signal: anything still uncommitted here predates every
@@ -157,6 +217,7 @@ async function runOrchestratorInit(input) {
     // 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,
@@ -168,10 +229,10 @@ async function runOrchestratorInit(input) {
         ...(skipInstall ? { skipInstall: true } : {}),
         validate: validate !== false,
         runbookPath: runbook_1.RUNBOOK_FILE_NAME,
+        ...(branch ? { branch } : {}),
         rounds: [
             {
                 index: 0,
-                planHash,
                 planSnapshot: PLAN_SNAPSHOT_0,
             },
         ],
@@ -180,39 +241,77 @@ async function runOrchestratorInit(input) {
         ...(checkpointFailed ? { checkpointFailed: true } : {}),
         analytics: { startEmitted: false, completeEmitted: false },
     };
-    // The check/create boundary runs under the creation lock: without it, two
-    // concurrent inits could both observe no active run above and create
-    // competing runs against the same workspace. The git side effects above
-    // stay outside the lock (locked sections must remain synchronous); a losing
-    // init's checkpoint commit is the same orphan shape as the crash window
-    // above, and the fallback's .gitignore edit is idempotent.
-    const winner = (0, state_lock_1.withRunCreationLock)(root, () => {
-        const nowActive = findActiveRunForPlan(root, planHash);
-        if (nowActive) {
-            return nowActive;
-        }
-        // 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);
-        // The runbook gets the same 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, 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 null;
     });
-    if (winner) {
-        return resumeRun(root, winner.runId, winner.state, policy, emitAgentInstructions);
-    }
     return finishInit(root, dir, runId, state, 'created', emitAgentInstructions);
 }
-// Reads the newest active run, refusing one whose plan differs from the
-// incoming plan; 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 being resumed.
-// NewerRunStateFormatError propagates from the read.
-function findActiveRunForPlan(root, planHash) {
+/**
+ * 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';
@@ -221,11 +320,11 @@ function findActiveRunForPlan(root, planHash) {
         // 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) {
+        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} (removing a run directory abandons that run; migrations it already applied remain applied), then re-run the command.`,
+                `Fix or remove the listed ${noun}, then re-run the command.`,
             ].join('\n'));
         }
         (0, agent_output_1.warnToAgent)({
@@ -233,22 +332,123 @@ function findActiveRunForPlan(root, planHash) {
             bodyLines: details,
         });
     }
-    if (active && (0, state_machine_1.latestRound)(active.state)?.planHash !== planHash) {
-        throw new Error(`A migrate run '${active.runId}' is already active with a different plan. ` +
-            `Finish it first by running \`${reconcileCommand(root, active.runId)}\`, ` +
-            `or remove ${types_1.MIGRATE_RUNS_RELATIVE_DIR}/${active.runId} to abandon it.`);
-    }
     return active;
 }
-// Shared resume tail for an active run found before or under the creation
-// lock, so the two discovery points cannot drift apart.
+// 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, and from nx.json "migrate.createCommits" when the commit flag is omitted. ` +
-            `Re-run with explicit flags for the policy run '${runId}' started with, or remove ${types_1.MIGRATE_RUNS_RELATIVE_DIR}/${runId} to abandon it.`);
+            `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,
@@ -272,23 +472,16 @@ function resumeRun(root, runId, state, policy, emitAgentInstructions) {
     return finishInit(root, dir, runId, resumed, 'resumed', emitAgentInstructions, runbook);
 }
 function announceResume(runId, state) {
-    const applied = state.steps.filter((s) => s.status === 'succeeded').length;
-    const skipped = state.steps.filter((s) => s.status === 'skipped').length;
-    const remaining = state.steps.length - applied - skipped;
-    // A subset of `remaining`, called out separately: a run is resumed most often
-    // because one of these is waiting on a decision, and the count alone would
-    // read as work that has not been reached yet.
-    const stalled = state.steps.filter((s) => s.status === 'failed' || s.status === 'died').length;
     (0, agent_output_1.logToAgent)({
         title: `nx migrate: resuming run ${runId}`,
         bodyLines: [
             `  started: ${state.createdAt}`,
-            `  progress: ${applied} applied, ${skipped} skipped, ${remaining} remaining${stalled > 0 ? ` (${stalled} awaiting a decision)` : ''}`,
+            `  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 the run dir exists, so an unflagged run
+// 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 migration step has advanced (a late checkpoint would absorb an
@@ -382,6 +575,9 @@ runbook) {
             });
         }
     }
+    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' };
@@ -438,7 +634,7 @@ function ensureRunbook(root, dir, runId, state) {
     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), or remove ${types_1.MIGRATE_RUNS_RELATIVE_DIR}/${runId} to abandon the run (migrations it already applied remain applied).`,
+            `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', {
@@ -484,6 +680,24 @@ function runbookContext(root, runId, state) {
         validate: state.validate !== false,
     };
 }
+// 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)) {
@@ -496,8 +710,10 @@ async function runOrchestratorReconcile(input) {
         // 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.
@@ -521,9 +737,9 @@ async function runOrchestratorReconcile(input) {
     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 or a
-        // skip's install takes, released once the transition that records it is
-        // written.
+        // 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);
@@ -532,21 +748,31 @@ async function runOrchestratorReconcile(input) {
                 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.
-            // Retries owe nothing: the rearmed attempt reconciles itself.
-            const { entry, installFailed, recorded } = stepAction === 'adopt'
-                ? state.createCommits
-                    ? await commitForStep(root, dir, state, target, scope)
-                    : {
-                        entry: null,
-                        installFailed: await installFailedForStep(root, dir, state, target, 'action-install', scope),
-                    }
-                : stepAction === 'skip'
-                    ? await retainedTreeSideEffects(root, dir, state, target, 'action-install', scope)
-                    : { entry: null, installFailed: false };
+            // 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
@@ -566,6 +792,7 @@ async function runOrchestratorReconcile(input) {
             // 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.
@@ -594,9 +821,16 @@ async function runOrchestratorReconcile(input) {
                     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)(reapplied.state, target.id)
-                    : reapplied.state;
+                    ? (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.
@@ -610,6 +844,9 @@ async function runOrchestratorReconcile(input) {
                     : freshRejection);
                 return;
             }
+            if (unresolvedArchiveError !== undefined) {
+                (0, give_up_1.warnUnresolvedNotArchived)(target.migrationId, unresolvedArchiveError);
+            }
             state = written;
         }
         finally {
@@ -920,18 +1157,23 @@ async function applyReconcileStepAction(root, dir, state, action, scope) {
     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 = step.status === 'died'
-            ? (0, state_machine_1.commitMayBeInHistory)(state, step)
-                ? `Use 'adopt' instead.`
-                : `Use 'adopt' or 'skip' instead.`
-            : (0, state_machine_1.commitMayBeInHistory)(state, step)
-                ? `Use 'retry' instead.`
-                : `Use 'retry' or 'skip' instead.`;
+        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',
@@ -964,6 +1206,35 @@ async function applyReconcileStepAction(root, dir, state, action, scope) {
             };
         }
     }
+    // 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
@@ -975,7 +1246,7 @@ async function applyReconcileStepAction(root, dir, state, action, scope) {
         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) ? '' : `, or 'skip'`}.`,
+                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') {
@@ -994,20 +1265,67 @@ async function applyReconcileStepAction(root, dir, state, action, scope) {
     if (applied.kind === 'error') {
         return applied;
     }
-    return { kind: 'ok', state: applied.state, targetStep: step };
+    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
-// death. The caller persists `entry` with the step transition unless
-// `recorded` says a session's parent already did; null when nothing to
+// 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; the refold then sees a clean tree.
-async function commitForStep(root, dir, state, step, scope) {
+// 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.splitMigrationId)(step.migrationId);
     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);
+        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
@@ -1063,7 +1381,7 @@ function advanceAndDispense(root, dir, runId) {
     // 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, step, held, noProgress);
+        emitHeld(root, runId, state, step, held, noProgress);
         return;
     }
     switch (step.status) {
@@ -1081,13 +1399,14 @@ function advanceAndDispense(root, dir, runId) {
             emitDied(root, runId, state, step, noProgress);
             break;
         case 'running':
-            emitStillRunning(root, runId, step, held, noProgress);
+            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.
@@ -1183,14 +1502,19 @@ function dispenseNextStep(root, dir, runId, state, step, noProgress) {
         return;
     }
     if (held) {
-        emitHeld(root, runId, step, held, noProgress);
+        emitHeld(root, runId, current, step, held, noProgress);
         return;
     }
-    emitNextStep(root, runId, current, current.steps.find((s) => s.id === step.id), noProgress);
+    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,
+    });
+    emitNextStep(root, runId, current, dispensed, noProgress);
 }
 function emitNextStep(root, runId, state, step, noProgress) {
     const migrationId = step.migrationId;
-    emit(root, runId, step, 'next-step', {
+    emit(root, runId, state, step, 'next-step', {
         command: workerCommand(root, migrationId, runId),
         next: reconcileCommand(root, runId),
         instructionLines: [
@@ -1207,6 +1531,8 @@ function emitRetryFailed(root, runId, state, step, noProgress) {
     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)
@@ -1223,27 +1549,31 @@ function emitRetryFailed(root, runId, state, step, noProgress) {
         `  current HEAD: ${head ?? '(unknown)'}`,
         `  working tree: ${tree === null ? '(unknown)' : tree ? `\n${tree}` : '(clean)'}`,
         ``,
-        ...(capReached ? [rearmCapLine(step), ``] : []),
+        retryBudgetLine(step, committed),
+        ``,
         `Decide how to proceed and re-run reconcile with one of:`,
-        retryOptionLine(retrySafety, reconcileCommand(root, runId, 'retry')),
+        ...(capReached
+            ? []
+            : [retryOptionLine(retrySafety, reconcileCommand(root, runId, 'retry'))]),
     ];
-    if (cleanRetry) {
+    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 migration's result, then run: ${reconcileCommand(root, runId, 'adopt')}`
+        : `  adopt: ${committed
+            ? "a commit of this migration's changes was started and never recorded"
+            : 'the migration was applied 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 (!(0, state_machine_1.commitMayBeInHistory)(state, step)) {
-        lines.push(`  skip:  ${reconcileCommand(root, runId, 'skip')}`);
+    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);
     }
-    // A step whose generator may still run gets no `next`, whichever retry the
-    // checks above would accept: git can vouch for the tracked tree only, and
-    // an agent that follows `next` blindly must not rerun a generator over
-    // writes nothing here could see. Choosing a retry has to be explicit. The
-    // rearm cap withholds it too: each rearm resets the response streak, so a
-    // blindly-followed retry `next` would loop past every escalation.
-    emit(root, runId, step, 'retry-failed', {
+    // 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') }),
@@ -1255,11 +1585,21 @@ function emitRetryFailed(root, runId, state, step, noProgress) {
 function rearmCapReached(step) {
     return step.attempt - 1 >= REARM_ESCALATION_CAP;
 }
-// No availability promise: which retry forms remain is the option list's to
-// say (a pre-marker death may offer none), and the cap itself withholds only
-// the preselected continuation.
-function rearmCapLine(step) {
-    return `This migration has already been retried ${step.attempt - 1} times without completing. Repeating an unchanged retry is unlikely to end differently: fix the underlying problem first, choose one of the non-retry options below, or ask the user how to proceed.`;
+function retryBudgetLine(step, committed) {
+    if (rearmCapReached(step))
+        return rearmCapLine(step, committed);
+    const left = REARM_ESCALATION_CAP - (step.attempt - 1);
+    return `Retries left for this migration: ${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 migration; 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 migration 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 migration; 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
@@ -1320,12 +1660,31 @@ function assessPreMarkerRetry(root, step) {
     }
     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.`;
+    if (resetTree) {
+        return `  unresolved: give up on this migration, 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 migration; 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 migration, leaving the tree as it stands, and move on. Then run: ${command}. ${recorded}`;
+}
 function emitDied(root, runId, state, step, noProgress) {
     const migrationId = step.migrationId;
     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 = [
@@ -1334,49 +1693,46 @@ function emitDied(root, runId, state, step, noProgress) {
         `  current HEAD: ${head ?? '(unknown)'}`,
         `  working tree: ${tree === null ? '(unknown)' : tree ? `\n${tree}` : '(clean)'}`,
         ``,
-        ...(capReached ? [rearmCapLine(step), ``] : []),
+        retryBudgetLine(step, committed),
+        ``,
     ];
     const options = [];
-    if (resume) {
+    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) {
+    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 {
+    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 (!(0, state_machine_1.commitMayBeInHistory)(state, step)) {
-        options.push(`  skip: leave the tree as it stands and move on without this migration, then run: ${reconcileCommand(root, runId, 'skip')}`);
+    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 wherever it is legal: it is the only resolution that
-    // neither discards work nor records a result the run never produced. While
-    // the generator may still run there is no `next` at all: a reset cannot be
-    // verified against writes git does not see, and adopting records a result
-    // nothing checked, so an agent that follows `next` blindly must land on
-    // neither. The rearm cap withholds it for the same reason as in
-    // emitRetryFailed.
-    emit(root, runId, step, 'died', {
+    // `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, step, held, noProgress) {
-    emit(root, runId, step, 'held', {
+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, step, held, noProgress) {
+function emitStillRunning(root, runId, state, step, held, noProgress) {
     const migrationId = step.migrationId;
     const ageMs = step.startedAt ? Date.now() - Date.parse(step.startedAt) : 0;
     const lines = [
@@ -1395,7 +1751,7 @@ function emitStillRunning(root, runId, step, held, noProgress) {
             ? `${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, step, 'still-running', {
+    emit(root, runId, state, step, 'still-running', {
         next: reconcileCommand(root, runId),
         instructionLines: lines,
     }, noProgress);
@@ -1493,7 +1849,7 @@ function emitAwaitPrompt(root, dir, runId, step, noProgress) {
     if (rejection.length > 0) {
         lines.push('', ...rejection);
     }
-    emit(root, runId, step, 'await-prompt', {
+    emit(root, runId, claimed, step, 'await-prompt', {
         next: reconcileCommand(root, runId),
         instructionLines: lines,
     }, noProgress);
@@ -1622,9 +1978,6 @@ function completionWarnings(root, runId, state) {
 }
 function completeRun(root, dir, runId, state) {
     let current = state;
-    const completed = current.steps.filter((s) => s.status === 'succeeded').length;
-    const skipped = current.steps.filter((s) => s.status === 'skipped').length;
-    const dispenseCount = current.steps.reduce((n, s) => n + s.dispenseCount, 0);
     // 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
@@ -1644,11 +1997,7 @@ function completeRun(root, dir, runId, state) {
         });
     }
     if (shouldEmit) {
-        (0, migrate_analytics_1.reportMigrateOrchestratorComplete)({
-            completed,
-            skipped,
-            dispenseCount,
-        });
+        (0, migrate_analytics_1.reportMigrateOrchestratorComplete)((0, state_machine_1.runTallies)(current));
     }
     const warnings = completionWarnings(root, runId, current);
     for (const lines of warnings) {
@@ -1656,8 +2005,7 @@ function completeRun(root, dir, runId, state) {
     }
     const instructionLines = [
         `Migrate run ${runId} is complete.`,
-        `  applied: ${completed}`,
-        `  skipped: ${skipped}`,
+        ...(0, state_machine_1.completionSummaryLines)(current),
         ...warnings.flat(),
     ];
     (0, agent_output_1.logToAgent)({ title: 'nx migrate: complete', bodyLines: instructionLines });
@@ -1665,7 +2013,7 @@ function completeRun(root, dir, runId, state) {
         instructions: instructionLines.join('\n'),
     });
 }
-function emit(root, runId, step, action, payload, noProgress) {
+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
@@ -1690,6 +2038,7 @@ function emit(root, runId, step, action, payload, noProgress) {
     (0, migrate_analytics_1.reportMigrateOrchestratorDispense)({
         action: effectiveAction,
         attempt: step.attempt,
+        ordinal: (0, state_machine_1.runTallies)(state).dispenseCount,
     });
 }
 function noProgressLines(step, streak) {