nx 23.3.0-beta.2 → 23.3.0-beta.4

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

@@ -2,12 +2,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runOrchestratorInit = runOrchestratorInit;
 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 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");
@@ -81,7 +84,7 @@ function refuseUnsafeScratchExposure(exposure, thenWhat) {
     }
 }
 async function runOrchestratorInit(input) {
-    const { root, migrationsJson, createCommits, commitPrefix, skipInstall, installedNxVersion, validate, } = 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.
@@ -102,9 +105,9 @@ async function runOrchestratorInit(input) {
             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) {
-        resumeRun(root, active.runId, active.state);
-        return;
+        return resumeRun(root, active.runId, active.state, policy, emitAgentInstructions);
     }
     const runId = (0, run_id_1.createRunId)();
     const dir = (0, run_state_1.runDir)(root, runId);
@@ -200,10 +203,9 @@ async function runOrchestratorInit(input) {
         return null;
     });
     if (winner) {
-        resumeRun(root, winner.runId, winner.state);
-        return;
+        return resumeRun(root, winner.runId, winner.state, policy, emitAgentInstructions);
     }
-    finishInit(root, dir, runId, state, 'created');
+    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
@@ -240,7 +242,14 @@ function findActiveRunForPlan(root, planHash) {
 }
 // Shared resume tail for an active run found before or under the creation
 // lock, so the two discovery points cannot drift apart.
-function resumeRun(root, runId, state) {
+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.`);
+    }
     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:
@@ -254,13 +263,13 @@ function resumeRun(root, runId, state) {
     // contract must not first change git history or durable run state.
     const runbook = ensureRunbook(root, dir, runId, state);
     if (runbook === null) {
-        return;
+        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);
-    finishInit(root, dir, runId, resumed, 'resumed', runbook);
+    return finishInit(root, dir, runId, resumed, 'resumed', emitAgentInstructions, runbook);
 }
 function announceResume(runId, state) {
     const applied = state.steps.filter((s) => s.status === 'succeeded').length;
@@ -289,26 +298,43 @@ function ensureCheckpoint(root, dir, state) {
         return state;
     if (state.steps.some((s) => s.status !== 'pending'))
         return state;
-    // 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);
-    // 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;
-        }
-        const next = checkpoint ? appendCommit(fresh, checkpoint) : fresh;
-        return cleared ? { ...next, checkpointFailed: false } : next;
-    });
+    // 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);
+        // 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;
+            }
+            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.
@@ -331,7 +357,7 @@ function checkpointEntry(root, commitPrefix) {
 // 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, 
+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) {
@@ -358,7 +384,17 @@ runbook) {
     }
     const content = runbook ?? ensureRunbook(root, dir, runId, current);
     if (content === null) {
-        return;
+        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 = [
@@ -369,9 +405,10 @@ runbook) {
     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: reconcileCommand(root, runId),
+        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
@@ -484,128 +521,100 @@ async function runOrchestratorReconcile(input) {
     state = detectDeaths(dir, state);
     // (c) apply the decision relay to the single failed/died step.
     if (stepAction) {
-        const result = applyReconcileStepAction(root, state, stepAction);
-        if (result.kind === 'error') {
-            emitError(root, runId, result.reason);
-            return; // state untouched
-        }
-        const target = result.targetStep;
-        // An adopted death commits its working tree; that git side effect runs
-        // before the lock (locked sections must stay synchronous), then the
-        // transition and its ledger entry land in one fresh-state write so a
-        // crash can't leave the step succeeded unrecorded. As with a fold, that
-        // window is wide, and a rejected reapply after the commit landed is
-        // equivalent to commitForStep's crash-refold window: the commit stays in
-        // history, the ledger misses it, and the rejection names it below so the
-        // agent re-decides against the moved HEAD.
-        // Without commits the adopted tree is still this migration's result, and
-        // it can carry package.json edits the dead worker never installed; the
-        // install has to run here or the next dispense captures the modified
-        // dependencies as its own baseline and nothing is left to detect them.
-        // A skip leaves the tree as it stands too, so it owes the same install
-        // and, with commits on, the same debt record as a prompt that did not
-        // complete. Retries owe nothing: the rearmed attempt reconciles itself.
-        const { entry, installFailed } = stepAction === 'adopt'
-            ? state.createCommits
-                ? await commitForStep(root, dir, state, target)
-                : {
-                    entry: null,
-                    installFailed: await installFailedForStep(root, dir, state, target),
+        // 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.
+        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;
+            // 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 };
+            // 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);
                 }
-            : stepAction === 'skip'
-                ? await retainedTreeSideEffects(root, dir, state, target)
-                : { entry: null, installFailed: false };
-        // 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 that dropped the generator marker reruns the
-            // generator, so payloads stored by earlier attempts describe a run
-            // whose tree was reset away; remove them. Hygiene, not the correctness
-            // boundary: the lineage bound persisted with the next marker
-            // (generatorCompletedAtAttempt) is what keeps a later retry from
-            // re-handing a copy this best-effort removal missed. A plain retry
-            // keeps the files: its lineage is unbroken, and a retained retry
-            // re-hands the newest copy. Removed with the handoff, before the rearm
-            // is persisted: losing them without the rearm only costs a later
-            // emission its stored copy.
-            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 the transition against the fresh disk state: if a concurrent
-        // reconcile already resolved this step, surface the state machine's own
-        // rejection through the same emitError path rather than writing over it.
-        // The bound attempt keeps the acceptance checks above honest: they ran
-        // against `state`, and a step that was re-armed and failed again in
-        // between is a different attempt those checks never saw.
-        let freshRejection;
-        let reopenedIssueUpdates = [];
-        const written = (0, state_lock_1.updateRunState)(dir, (fresh) => {
-            const reapplied = (0, state_machine_1.applyStepEvent)(fresh, {
-                type: 'stepAction',
-                stepId: target.id,
-                action: stepAction,
-                attempt: 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;
+            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;
+                }
+                const next = installFailed
+                    ? (0, state_machine_1.markInstallFailed)(reapplied.state, target.id)
+                    : reapplied.state;
+                // 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 (reapplied.kind === 'error') {
-                freshRejection = reapplied.reason;
-                return null;
-            }
-            // The reset this action requires discarded the failed attempt's tree,
-            // so resolutions that attempt claimed and no landed commit carries are
-            // reverted with the rearm, in the same write.
-            let rearmed = reapplied.state;
-            if (stepAction === 'retry-clean') {
-                const reopened = (0, issues_1.reopenResolutionsForStep)(rearmed, target.id);
-                rearmed = reopened.state;
-                reopenedIssueUpdates = reopened.updates;
+            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;
             }
-            const next = installFailed
-                ? (0, state_machine_1.markInstallFailed)(rearmed, target.id)
-                : rearmed;
-            // An adopted commit absorbs uncovered failed steps the same way a fold
-            // commit does, so it carries their resolved issues too.
-            return entry
-                ? 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;
+            state = written;
         }
-        if (reopenedIssueUpdates.length > 0) {
-            // Best-effort: run.json records the reverted dispositions and stays
-            // authoritative, so a failed append loses only the archive's trail record
-            // of the revert. The sink survives a throw: a shell rebuilt before the
-            // failure is durable and reads healthy on retry, so this pass must warn
-            // it.
-            const revertApplication = {
-                state: written,
-                newIssues: [],
-                updates: reopenedIssueUpdates,
-            };
-            const revertReconstructedIds = [];
-            try {
-                (0, issues_1.archiveIssues)(dir, revertApplication, revertReconstructedIds);
-            }
-            catch (e) {
-                (0, agent_output_1.warnToAgent)({
-                    title: `The reverted issue resolutions for ${target.migrationId} could not be archived (${(0, util_1.summarizeError)(e)}).`,
-                    bodyLines: [
-                        `run.json stays authoritative for the dispositions; the archived files under the run's issues directory miss the revert records, so their last entries may still read resolved.`,
-                    ],
-                });
-            }
-            warnReconstructedArchives(revertReconstructedIds);
+        finally {
+            scope.lease?.release();
         }
-        state = written;
     }
     // (d) choose and emit the next dispense.
     advanceAndDispense(root, dir, runId);
@@ -621,17 +630,6 @@ function buildSteps(sortedMigrations) {
         hasGenerator: !(0, migration_shape_1.isPromptOnlyMigration)(m),
     }));
 }
-// --- reconcile phases -------------------------------------------------------
-// The runbook points every later consumer at issues/<id>.json for the full
-// details, so a rebuild from run-state fields (the reported detail is gone
-// with the lost file) must not stay silent.
-function warnReconstructedArchives(issueIds) {
-    if (issueIds.length === 0)
-        return;
-    (0, agent_output_1.warnToAgent)({
-        title: `The archived details for ${issueIds.join(', ')} were missing or unreadable and were rebuilt from the run state; the originally reported detail is lost.`,
-    });
-}
 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
@@ -668,6 +666,9 @@ async function foldHandoffs(root, dir, state) {
             });
             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;
@@ -683,7 +684,7 @@ async function foldHandoffs(root, dir, state) {
             }
             ready = true;
         });
-        warnReconstructedArchives(reconstructedIssueIds);
+        (0, issues_1.warnReconstructedArchives)(reconstructedIssueIds);
         if (archiveError !== null) {
             (0, agent_output_1.warnToAgent)({
                 title: `The issue details reported by ${step.migrationId} could not be archived (${(0, util_1.summarizeError)(archiveError)}).`,
@@ -694,73 +695,85 @@ async function foldHandoffs(root, dir, state) {
         }
         if (!ready)
             continue;
-        // Phase 2: the commit and the install are side effects, so they happen
-        // outside the lock; the transition, the issue application, and the
-        // ledger entry then land in one fresh-state write. A crash cannot leave
-        // the step settled with its commit forgotten.
-        const { entry, installFailed } = await foldLedgerEntry(root, dir, current, step, promptOutcome);
-        // The write re-validates against fresh disk state, on the attempt this
-        // handoff was read for. That window is wide (a git commit plus a package
-        // install), and 'awaiting-prompt-outcome' recurs, so without the attempt
-        // check a concurrent reconcile's retry could take this outcome as its own.
-        // A dropped fold is equivalent to the crash-refold window: the commit
-        // landed but the ledger misses it.
-        // Written through the lock directly so the issue application is re-archived
-        // on the state the write actually lands on: a claim assigned between the
-        // phases can add an update record phase 1 never saw.
+        // 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 = [];
-        current = (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 fresh;
-            const issues = (0, issues_1.parseHandoffIssues)(result.handoff.extras, fresh, step);
-            if (issues.ok !== true)
-                return fresh;
-            const application = (0, issues_1.applyReportedIssues)(applied.state, step, issues.issues, issues.updates);
-            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;
+        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);
                 }
-                updateArchiveError = e;
-                archivesDegraded = intact !== true;
-            }
-            folded = true;
-            const 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: the folding step's own resolutions, and those of absorbed steps
-            // whose failed commit attempts left them unattached.
-            const written = entry
-                ? appendCommit(next, (0, issues_1.attachIssueIdsToCommitEntry)(next, entry))
-                : next;
-            (0, run_state_1.writeRunState)(dir, written);
-            return written;
-        });
-        warnReconstructedArchives(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 ${step.migrationId} could not be archived (${(0, util_1.summarizeError)(detailArchiveError)}).`,
@@ -797,54 +810,50 @@ async function foldHandoffs(root, dir, state) {
     }
     return current;
 }
-// What a folded prompt outcome owes the run state. A completed prompt with
-// commits on is committed and its result classified as usual, the install
-// riding in on the commit path. Every other outcome still reconciles the
-// dependencies itself: the prompt (or the generator half before it) can have
-// edited package.json whether or not it completed, and skipping the install
-// there strands that change with nothing left to detect it, since the next
-// step's dispense captures the already-modified state as its own baseline.
-//
-// A failed or skipped prompt is not committed, but it can still have left
-// edits behind, so a tree that is not verifiably clean records debt: the
-// changes then read as pending for a later commit to absorb, and the
-// completion warning knows about them. A failed probe counts as dirty,
-// matching every other retry-safety decision in this file; debt a later landed
-// entry covers costs nothing.
-async function foldLedgerEntry(root, dir, state, step, promptOutcome) {
+// 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);
+            return commitForStep(root, dir, state, step, scope);
         }
         return {
             entry: null,
-            installFailed: await installFailedForStep(root, dir, state, step),
+            installFailed: await installFailedForStep(root, dir, state, step, 'fold-install', scope),
         };
     }
-    return retainedTreeSideEffects(root, dir, state, step);
+    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) {
-    const installFailed = await installFailedForStep(root, dir, state, step);
+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 do it (the fold of a prompt outcome that lands no commit, or a
-// non-commit adopt), returning whether the install failed. A failure is
-// recorded rather than thrown: reconcile still owes the agent a dispense, and
-// a warning alone dies with this process.
-async function installFailedForStep(root, dir, state, step) {
+// 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, util_1.installDepsChangedSinceDispense)(root, dir, step, state.skipInstall === true, reconcileCommand(root, state.runId));
+        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 ${step.migrationId} could not be installed (${(0, util_1.summarizeError)(e)}).`,
             bodyLines: [`Run \`${(0, util_1.pmInstallCommand)(root)}\` before continuing.`],
@@ -878,6 +887,10 @@ function detectDeaths(dir, state) {
         // 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,
@@ -888,7 +901,7 @@ function detectDeaths(dir, state) {
     }
     return current;
 }
-function applyReconcileStepAction(root, state, action) {
+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 {
@@ -903,29 +916,51 @@ function applyReconcileStepAction(root, state, action) {
         };
     }
     const step = candidates[0];
+    const held = (0, broker_1.liveTreeOperation)(state);
+    if (held) {
+        return { kind: 'error', reason: (0, broker_1.treeBusyMessage)(held) };
+    }
     // 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'
-            ? `Use 'adopt' or 'skip' instead.`
-            : `Use 'retry' or 'skip' instead.`;
-        if (!canOfferCleanRetry(root, state, step, head)) {
+            ? (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.`;
+        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}': ${cleanRetryUnavailableReason(root, state, step, head)} ${fallback}`,
+                reason: `Cannot apply action 'retry-clean' to step '${step.id}': the reset to ${step.gitRefBefore} failed: ${e instanceof Error ? e.message : String(e)} ${fallback}`,
             };
         }
-        // The reset itself is delegated to the caller, and every check above
-        // passes identically whether or not it ran, so only the tree can say
-        // whether the reset actually happened. Anything but a verified-clean tree
-        // is refused: accepting would drop the generator marker and rerun the
+        // 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, so the reset this action requires has not happened. Run \`git reset --hard ${step.gitRefBefore}\` then \`git clean -fd -e ${types_1.MIGRATE_RUNS_RELATIVE_DIR}\` first, then re-run it. ${fallback}`,
+                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}`,
             };
         }
     }
@@ -940,7 +975,7 @@ function applyReconcileStepAction(root, state, action) {
         if (safety.kind === 'unsafe') {
             return {
                 kind: 'error',
-                reason: `Cannot apply action 'retry' to step '${step.id}': ${safety.reason} Use 'retry-clean' where offered, 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) ? '' : `, or 'skip'`}.`,
             };
         }
         if (safety.kind === 'warned') {
@@ -962,46 +997,45 @@ function applyReconcileStepAction(root, state, action) {
     return { kind: 'ok', state: applied.state, targetStep: step };
 }
 // Commits the working tree left by a folded prompt outcome or an adopted
-// death, returning the ledger entry the caller persists together with the
-// step transition (null when there was nothing to commit). The worker's
-// recorded-commit path classifies through the same commitResultToLedgerEntry.
-//
-// Remaining narrow window: a crash after the git commit but before the state
-// write refolds on the next reconcile, where the commit attempt sees a clean
-// tree ('no-changes') and the ledger simply misses that landed entry; the
-// changes themselves are never lost. A lost landed entry can also strand the
-// failed entries it had absorbed, which is why completion double-checks the
-// tree before warning about debt.
-async function commitForStep(root, dir, state, step) {
+// death. 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) {
     const { name } = (0, state_machine_1.splitMigrationId)(step.migrationId);
     const absorbedStepIds = (0, state_machine_1.uncoveredFailedStepIds)(state).filter((id) => id !== step.id);
-    let result;
+    const skipInstall = state.skipInstall === true;
+    let commit;
     try {
-        result = await (0, migrate_commits_1.commitMigrationIfRequested)(root, { name }, true, state.commitPrefix, () => (0, util_1.installDepsChangedSinceDispense)(root, dir, step, state.skipInstall === true, reconcileCommand(root, state.runId)), (0, state_machine_1.stepsToPendingMigrations)(state, absorbedStepIds));
+        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);
     }
     catch (e) {
-        // The dependency install is the only thing that throws here: the commit
-        // attempt itself reports through result.status, and the install's own
-        // bookkeeping never throws. Both consequences are recorded, and neither
-        // aborts reconcile so the next dispense still fires. The debt cannot stand
-        // in for the install failure: a later step's commit absorbs this diff and
-        // lands an entry naming this step, which clears the debt while the
-        // dependencies are still missing.
+        // 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 (result.status === 'failed') {
+    if (commit.result.status === 'failed') {
         (0, util_1.warnCommitFailed)(name);
     }
     return {
-        entry: (0, state_machine_1.commitResultToLedgerEntry)(result, step.id, absorbedStepIds),
+        entry: (0, state_machine_1.commitResultToLedgerEntry)(commit.result, step.id, commit.absorbedStepIds),
         installFailed: false,
+        recorded: commit.recorded,
     };
 }
-// --- dispense ---------------------------------------------------------------
 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
@@ -1024,6 +1058,14 @@ function advanceAndDispense(root, dir, runId) {
     // 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, step, held, noProgress);
+        return;
+    }
     switch (step.status) {
         case 'pending':
             dispenseNextStep(root, dir, runId, state, step, noProgress);
@@ -1039,7 +1081,7 @@ function advanceAndDispense(root, dir, runId) {
             emitDied(root, runId, state, step, noProgress);
             break;
         case 'running':
-            emitStillRunning(root, runId, step, noProgress);
+            emitStillRunning(root, runId, step, held, noProgress);
             break;
         case 'awaiting-prompt-outcome':
             emitAwaitPrompt(root, dir, runId, step, noProgress);
@@ -1058,6 +1100,12 @@ function advanceAndDispense(root, dir, runId) {
         }
     }
 }
+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));
 }
@@ -1107,6 +1155,7 @@ function dispenseNextStep(root, dir, runId, state, step, noProgress) {
         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
@@ -1115,6 +1164,12 @@ function dispenseNextStep(root, dir, runId, state, step, noProgress) {
             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, {
             type: 'dispense',
             stepId: step.id,
@@ -1127,6 +1182,10 @@ function dispenseNextStep(root, dir, runId, state, step, noProgress) {
         advanceAndDispense(root, dir, runId);
         return;
     }
+    if (held) {
+        emitHeld(root, runId, step, held, noProgress);
+        return;
+    }
     emitNextStep(root, runId, current, current.steps.find((s) => s.id === step.id), noProgress);
 }
 function emitNextStep(root, runId, state, step, noProgress) {
@@ -1147,7 +1206,7 @@ function emitRetryFailed(root, runId, state, step, noProgress) {
     const summary = step.outcome?.summary ?? step.promptOutcome?.summary;
     const head = (0, git_utils_1.getLatestCommitSha)(root);
     const tree = dirtyTreeSummary(root);
-    const cleanRetry = canOfferCleanRetry(root, state, step, head);
+    const cleanRetry = (0, clean_retry_1.canOfferCleanRetry)(root, state, step, head);
     // 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)
@@ -1169,9 +1228,12 @@ function emitRetryFailed(root, runId, state, step, noProgress) {
         retryOptionLine(retrySafety, reconcileCommand(root, runId, 'retry')),
     ];
     if (cleanRetry) {
-        lines.push(`  retry-clean: restore the tree to ${step.gitRefBefore ?? 'the pre-migration ref'} first (e.g. \`git reset --hard ${step.gitRefBefore ?? '<ref>'}\` then \`git clean -fd -e ${types_1.MIGRATE_RUNS_RELATIVE_DIR}\`, keeping the run state out of the clean), then retry from that clean state by running: ${reconcileCommand(root, runId, 'retry-clean')}`);
+        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')}`);
+    }
+    // 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')}`);
     }
-    lines.push(`  skip:  ${reconcileCommand(root, runId, 'skip')}`);
     if (pending) {
         lines.push(UNVERIFIABLE_WRITES_LINE);
     }
@@ -1229,62 +1291,6 @@ function retryOptionLine(safety, command) {
         }
     }
 }
-// A clean retry resets the tree to the step's captured pre-migration ref.
-// That is only safe when every prior diff is already committed: without
-// per-migration commits the ref is the run's starting commit (the reset would
-// wipe all prior steps' uncommitted work); a failed init checkpoint or a
-// pending step commit means the ref predates diffs the reset would also
-// destroy; without a captured ref there is nothing to reset to; edits already
-// in the tree when this step was dispensed (the user's own, or an earlier
-// step's the checkpoint never saw) are not represented by the ref either; and
-// HEAD anywhere other than the ref means something was committed since the
-// step was dispensed that the reset would discard, whether that is this step's
-// own commit (recorded, or made in the window before the worker died writing
-// its ledger entry) or one the user made alongside the run.
-// Cleanliness and position both have to say so explicitly: a failed tree probe
-// records dirty, a run created before that field existed carries nothing to
-// check, and an unreadable HEAD is no ref at all, so none of the three can be
-// read as a restore point that exists.
-// The debt check is run-wide: a clean retry resets and cleans the whole tree,
-// which would discard every other failed step's uncommitted work as well.
-function canOfferCleanRetry(root, state, step, head) {
-    return (state.createCommits &&
-        !state.checkpointFailed &&
-        !(0, state_machine_1.hasPendingCommitDebt)(state) &&
-        !!step.gitRefBefore &&
-        head === step.gitRefBefore &&
-        step.treeCleanAtDispense === true &&
-        !endangeredLandedEntry(root, state, step));
-}
-// The last landed ledger entry covering the step whose commit a reset to the
-// step's gitRefBefore would discard. Entries from earlier attempts predate the
-// ref re-captured at re-dispense and survive the reset; only a commit that is
-// not an ancestor of the ref (or cannot be verified as one) is endangered.
-function endangeredLandedEntry(root, state, step) {
-    let endangered = null;
-    for (const entry of (0, state_machine_1.coveringLandedEntries)(state, step.id)) {
-        if (!entry.sha ||
-            !step.gitRefBefore ||
-            !(0, git_utils_1.isAncestorCommit)(entry.sha, step.gitRefBefore, root)) {
-            endangered = entry;
-        }
-    }
-    return endangered;
-}
-// Explains why retry-clean is withheld for a failed or died step; feeds the
-// death dispense and a rejected --step-action=retry-clean.
-function cleanRetryUnavailableReason(root, state, step, head) {
-    const endangered = endangeredLandedEntry(root, state, step);
-    if (endangered) {
-        return endangered.sha
-            ? `this migration's changes already landed in commit ${endangered.sha}, which a reset would discard.`
-            : `this migration's changes already landed in a commit, which a reset would discard.`;
-    }
-    if (step.gitRefBefore && head !== step.gitRefBefore) {
-        return `HEAD is at ${head ?? '(unreadable)'} rather than the ${step.gitRefBefore} this migration started from, so a reset would discard what was committed in between.`;
-    }
-    return `resetting the tree could discard uncommitted work that no restore point accounts for.`;
-}
 function assessPreMarkerRetry(root, step) {
     const repo = (0, git_utils_1.getGitRepositoryStatus)(root);
     if (repo === 'not-git') {
@@ -1319,7 +1325,7 @@ function emitDied(root, runId, state, step, noProgress) {
     const ref = step.gitRefBefore;
     const head = (0, git_utils_1.getLatestCommitSha)(root);
     const tree = dirtyTreeSummary(root);
-    const cleanRetry = canOfferCleanRetry(root, state, step, head);
+    const cleanRetry = (0, clean_retry_1.canOfferCleanRetry)(root, state, step, head);
     const resume = !generatorPending(step);
     const capReached = rearmCapReached(step);
     const lines = [
@@ -1335,15 +1341,16 @@ function emitDied(root, runId, state, step, noProgress) {
         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) {
-        options.push(
-        // Two commands rather than one `&&` chain: the agent runs these in its
-        // own shell, and not every shell joins statements that way.
-        `  retry-clean: restore the tree to ${ref ?? 'the pre-migration ref'} first (e.g. \`git reset --hard ${ref ?? '<ref>'}\` then \`git clean -fd -e ${types_1.MIGRATE_RUNS_RELATIVE_DIR}\`, keeping the run state out of the clean), then retry from that clean state by running: ${reconcileCommand(root, runId, 'retry-clean')}`);
+        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 {
-        lines.push(`A clean retry is unavailable: ${cleanRetryUnavailableReason(root, state, step, head)}`);
+        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')}`);
     }
-    options.push(`  adopt: keep the current working-tree state as this migration's result, then run: ${reconcileCommand(root, runId, 'adopt')}`, `  skip: leave the tree as it stands and move on without this migration, then run: ${reconcileCommand(root, runId, 'skip')}`);
     lines.push(`Choose exactly one:`);
     lines.push(...options);
     if (!resume) {
@@ -1363,14 +1370,30 @@ function emitDied(root, runId, state, step, noProgress) {
         instructionLines: lines,
     }, noProgress);
 }
-function emitStillRunning(root, runId, step, noProgress) {
+function emitHeld(root, runId, step, held, noProgress) {
+    emit(root, runId, step, 'held', {
+        next: reconcileCommand(root, runId),
+        instructionLines: [(0, broker_1.treeBusyMessage)(held)],
+    }, noProgress);
+}
+function emitStillRunning(root, runId, step, held, noProgress) {
     const migrationId = step.migrationId;
     const ageMs = step.startedAt ? Date.now() - Date.parse(step.startedAt) : 0;
     const lines = [
         `The worker for ${migrationId} (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) {
-        lines.push(`It has been running for ${Math.floor(ageMs / 60000)} minutes and may be hung. Verify pid ${step.pid}; either keep waiting, or kill it so the next reconcile can classify it as died.`);
+        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, step, 'still-running', {
         next: reconcileCommand(root, runId),
@@ -1564,16 +1587,44 @@ function emitError(root, runId, reason) {
     });
     (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((s) => s.migrationId)
+                        .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;
     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);
-    // 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)(current) && (0, git_utils_1.getWorkingTreeStatus)(root) !== 'clean';
     // 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
@@ -1599,30 +1650,15 @@ function completeRun(root, dir, runId, state) {
             dispenseCount,
         });
     }
-    const debtLine = 'Some migration changes could not be committed and may remain in the working tree; review and commit them manually.';
-    if (commitDebt) {
-        (0, agent_output_1.warnToAgent)({ title: debtLine });
-    }
-    const uninstalled = current.steps.filter((s) => s.installFailed);
-    const installLine = uninstalled.length > 0
-        ? `The dependency changes made by ${uninstalled
-            .map((s) => s.migrationId)
-            .join(', ')} were not installed; run \`${(0, util_1.pmInstallCommand)(root)}\` before using the workspace.`
-        : null;
-    if (installLine) {
-        (0, agent_output_1.warnToAgent)({ title: installLine });
-    }
-    const issueLines = (0, issues_1.renderUnresolvedIssueLines)(current, runId);
-    if (issueLines.length > 0) {
-        (0, agent_output_1.warnToAgent)({ title: issueLines[0], bodyLines: issueLines.slice(1) });
+    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.`,
         `  applied: ${completed}`,
         `  skipped: ${skipped}`,
-        ...(commitDebt ? [debtLine] : []),
-        ...(installLine ? [installLine] : []),
-        ...issueLines,
+        ...warnings.flat(),
     ];
     (0, agent_output_1.logToAgent)({ title: 'nx migrate: complete', bodyLines: instructionLines });
     (0, agent_output_1.emitStepBlock)(runId, '-', 'complete', {
@@ -1687,10 +1723,6 @@ function reconcileCommand(root, runId, action) {
     const base = `${(0, util_1.pmExecPrefix)(root)} nx migrate --run-id=${runId}`;
     return action ? `${base} --step-action=${action}` : base;
 }
-// --- helpers ----------------------------------------------------------------
-function appendCommit(state, entry) {
-    return { ...state, commits: [...state.commits, entry] };
-}
 // 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