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

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

@@ -5,7 +5,16 @@ exports.runOrchestratorResume = runOrchestratorResume;
 exports.holdRunToContinue = holdRunToContinue;
 exports.activeRunToReplace = activeRunToReplace;
 exports.releaseRunToHandOff = releaseRunToHandOff;
+exports.activeRunForClassic = activeRunForClassic;
+exports.checkRunForStartFresh = checkRunForStartFresh;
+exports.deleteRunForStartFresh = deleteRunForStartFresh;
+exports.refuseNewRunAlongsideLiveRun = refuseNewRunAlongsideLiveRun;
+exports.checkRunsForSingleMigration = checkRunsForSingleMigration;
+exports.prepareSingleMigrationRun = prepareSingleMigrationRun;
+exports.removeSingleMigrationRun = removeSingleMigrationRun;
 exports.runOrchestratorReconcile = runOrchestratorReconcile;
+exports.dispenseSingleMigrationStep = dispenseSingleMigrationStep;
+exports.lastCoveringLandedEntry = lastCoveringLandedEntry;
 exports.completionWarnings = completionWarnings;
 const child_process_1 = require("child_process");
 const crypto_1 = require("crypto");
@@ -42,7 +51,7 @@ 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.
+// The migrate orchestrator: drives a durable run one dispense at a time.
 // An outer AI agent runs each dispensed command and re-invokes `nx migrate
 // --run-id=<id>` to reconcile; there is no long-lived process.
 const PLAN_SNAPSHOT_0 = 'plan-0.json';
@@ -55,7 +64,11 @@ const HANG_THRESHOLD_MS = 15 * 60 * 1000;
 const NO_PROGRESS_THRESHOLD = 3;
 // Two rearms per step: one for the diagnosed fix and one for its correction.
 const REARM_ESCALATION_CAP = 2;
-const INIT_CONTINUE_HINT = 're-run the command, or unset NX_MIGRATE_ORCHESTRATOR to use the standard migrate flow.';
+const INIT_CONTINUE_HINT = 're-run the command, or re-run it with --agentic=false to use the standard migrate flow.';
+const ID_PROBLEM_REFUSALS = {
+    'not-shell-safe': 'contains characters that are not shell-safe. Orchestrated runs require shell-safe migration ids.',
+    duplicate: 'is listed more than once in the plan. Orchestrated runs require each migration id once.',
+};
 function continueRunHint(runId) {
     return `re-run the command to continue run '${runId}'.`;
 }
@@ -90,20 +103,20 @@ function refuseUnsafeScratchExposure(exposure, thenWhat) {
     }
 }
 async function runOrchestratorInit(input) {
-    const { root, migrationsJson, migrationsPath, createCommits, commitPrefix, skipInstall, installedNxVersion, validate, finalValidation, emitAgentInstructions = true, onExistingRun = 'report', replaceRunId, confirmStart, } = input;
+    const { root, migrationsJson, migrationsPath, createCommits, commitPrefix, skipInstall, installedNxVersion, validate, finalValidation, emitAgentInstructions = true, onExistingRun = 'report', replaceRunId, confirmStart, singleMigration = false, } = input;
     const migrations = (migrationsJson.migrations ?? []);
-    const sorted = (0, sort_migrations_1.sortMigrations)(migrations.slice(), {
-        hoistHandoffGitignore: true,
-    });
+    const sorted = (0, sort_migrations_1.sortMigrations)(migrations.slice());
     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);
+    const active = singleMigration
+        ? null
+        : onExistingRun === 'start-fresh'
+            ? activeRunToReplace(root, replaceRunId)
+            : findActiveRunForInit(root);
     if (active &&
         (onExistingRun === 'report' ||
             (replaceRunId !== undefined && active.runId !== replaceRunId))) {
@@ -118,19 +131,19 @@ async function runOrchestratorInit(input) {
     }
     if ((0, fs_1.existsSync)((0, run_state_1.migrateRunsDir)(root))) {
         (0, state_lock_1.withRunCreationLock)(root, () => {
-            refuseLiveReservation(root);
+            refuseNewRunAlongsideLiveRun(root, singleMigration);
             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.`);
-        }
+    // Dispensed commands interpolate migration ids verbatim and a worker finds
+    // its step by id, 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.
+    const [idProblem] = (0, run_state_1.migrationIdProblems)(sorted);
+    if (idProblem !== undefined) {
+        throw new Error(`The migration id '${idProblem.id}' ${ID_PROBLEM_REFUSALS[idProblem.problem]} To run the plan without orchestration, re-run with --agentic=false.`);
     }
     if (confirmStart && !(await confirmStart())) {
         return { kind: 'refused' };
@@ -150,19 +163,11 @@ async function runOrchestratorInit(input) {
         refuseUnsafeScratchExposure(scratchExposure, INIT_CONTINUE_HINT);
     }
     // Applied before the checkpoint so the entry (when it can be added) already
-    // covers older scratch by the time the checkpoint's `git add -A` runs; the
-    // fallback's standalone commit is suppressed because that checkpoint
-    // carries the edit. Unlike the classic loop, a planned ignore migration
-    // can't be deferred to: the run dir is created below, before that
-    // migration runs.
+    // covers older scratch by the time the checkpoint's `git add -A` runs.
     await (0, handoff_gitignore_1.applyAgenticHandoffGitignoreFallback)({
         migrations: sorted,
         installedNxVersion,
-        effectiveCreateCommits: createCommits,
-        commitPrefix,
         root,
-        applyWhenPlanned: true,
-        commitStandalone: false,
     });
     if (scratchExposure === 'unignored') {
         // The fallback was the workspace's last chance at ignore coverage;
@@ -176,17 +181,21 @@ async function runOrchestratorInit(input) {
     // 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 (singleMigration) {
+            refuseNewRunAlongsideLiveRun(root, true);
         }
-        if (active) {
-            // Completed meanwhile (a reconcile finished it): nothing to replace.
-            if (!nowActive) {
-                throw new Error(noActiveRunToReplace(active.runId));
+        else {
+            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);
             }
-            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.
@@ -224,7 +233,7 @@ async function runOrchestratorInit(input) {
     // step's gitRefBefore and rules out clean retries for the whole run. A
     // failed probe counts as dirty: mistaking it for clean would let a later
     // retry-clean reset destroy the very work this flag exists to protect.
-    const checkpointFailed = createCommits && (0, git_utils_1.getWorkingTreeStatus)(root) !== 'clean';
+    const checkpointFailed = createCommits && (0, migrate_commits_1.migrateTreeStatus)(root) !== 'clean';
     const branch = (0, git_utils_1.getGitCurrentBranch)(root);
     const state = {
         formatVersion: run_state_1.CURRENT_RUN_STATE_FORMAT_VERSION,
@@ -248,6 +257,7 @@ async function runOrchestratorInit(input) {
         steps: buildSteps(sorted, finalValidation !== false),
         commits: checkpoint ? [checkpoint] : [],
         ...(checkpointFailed ? { checkpointFailed: true } : {}),
+        ...(singleMigration ? { singleMigration: true } : {}),
         analytics: { startEmitted: false, completeEmitted: false },
     };
     (0, state_lock_1.withRunCreationLock)(root, () => {
@@ -273,9 +283,9 @@ function runOrchestratorResume(input) {
  * 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.
+ * finished one, and while another process holds the run or works on a
+ * different 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)) {
@@ -314,52 +324,194 @@ function activeRunToReplace(root, runId) {
 function releaseRunToHandOff(root, runId) {
     (0, state_lock_1.releaseRunActivity)((0, run_state_1.runDir)(root, runId));
 }
+/**
+ * The active run a classic `--run-migrations` must not run over, held while
+ * the caller reports it or asks what to do; null when no run is active. Run
+ * directories that cannot be read refuse as they do for init.
+ */
+function activeRunForClassic(root, plannedIds) {
+    const active = findActiveRunForInit(root);
+    if (!active)
+        return null;
+    // Held before the facts are read, as init's report does.
+    (0, state_lock_1.holdRunActivity)(root, active.runId);
+    return {
+        runId: active.runId,
+        facts: (0, existing_run_report_1.collectExistingRunFacts)(root, active.runId, active.state, plannedIds),
+    };
+}
+/**
+ * Throws when a classic start fresh could not delete the active run `runId`.
+ * Run before the commit prompt, as init does, so the user is not asked for a
+ * run that is then refused; deleteRunForStartFresh repeats the checks.
+ */
+function checkRunForStartFresh(root, runId) {
+    (0, state_lock_1.withRunCreationLock)(root, () => {
+        const active = activeRunToDelete(root, runId);
+        refuseUndeletableRun(root, runId, active.state);
+    });
+}
+/**
+ * Deletes the record of the active run `runId` for a classic start fresh,
+ * under the refusals init applies before it replaces a run. The classic loop
+ * records no run of its own afterwards.
+ */
+function deleteRunForStartFresh(root, runId) {
+    const deleted = (0, state_lock_1.withRunCreationLock)(root, () => {
+        activeRunToDelete(root, runId);
+        return deleteRunRecord(root, runId);
+    });
+    if (deleted) {
+        removeDeletedRunDir(root, runId);
+    }
+}
+// Call under the creation lock. A run that became active since the user chose
+// is refused, never deleted in place of the one they saw.
+function activeRunToDelete(root, runId) {
+    const active = findActiveRunForInit(root, true);
+    if (!active) {
+        throw new Error(noActiveRunToReplace(runId));
+    }
+    if (active.runId !== runId) {
+        throw new Error(`Not starting fresh: migrate run '${active.runId}' became active while this command was starting. Re-run the command to see it.`);
+    }
+    return active;
+}
 // 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.
+// invocation 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. Refuses while another process works on a run it wouldn't
+// report.
 function findActiveRunForInit(root, refuseUninterpretable = false) {
+    refuseNewRunAlongsideLiveRun(root);
     const { active, uninterpretable } = (0, run_state_1.findActiveRun)(root);
     if (uninterpretable.length > 0) {
-        const noun = uninterpretable.length === 1 ? 'directory' : 'directories';
-        // A directory name is whatever is on disk and a reason quotes what it
-        // found, so neither can be trusted to stay on the line it is put on.
-        // Sanitized here rather than left to the gateway: these same lines are
-        // joined into the throw below, which leaves through handleErrors.
-        const details = uninterpretable.map((u) => `${types_1.MIGRATE_RUNS_RELATIVE_DIR}/${(0, text_1.singleLine)(u.dirName)}: ${(0, text_1.singleLine)(u.reason)}`);
         if (!active || refuseUninterpretable) {
+            const noun = uninterpretable.length === 1 ? 'directory' : 'directories';
             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,
+                `Whether a migrate run is still active could not be determined; running the plan could re-apply migrations an unfinished run already applied.`,
+                ...uninterpretableDetails(uninterpretable),
                 `Fix or remove the listed ${noun}, then re-run the command.`,
             ].join('\n'));
         }
+        warnIgnoredRunDirs(uninterpretable);
+    }
+    return active;
+}
+// A directory name is whatever is on disk and a reason quotes what it found,
+// so neither can be trusted to stay on the line it is put on. Sanitized here
+// rather than left to the gateway: these lines are also joined into a throw,
+// which leaves through handleErrors.
+function uninterpretableDetails(uninterpretable) {
+    return uninterpretable.map((u) => `${types_1.MIGRATE_RUNS_RELATIVE_DIR}/${(0, text_1.singleLine)(u.dirName)}: ${(0, text_1.singleLine)(u.reason)}`);
+}
+function warnIgnoredRunDirs(uninterpretable) {
+    const noun = uninterpretable.length === 1 ? 'directory' : 'directories';
+    (0, agent_output_1.warnToAgent)({
+        title: `Ignoring ${uninterpretable.length} migrate run ${noun} that could not be read.`,
+        bodyLines: uninterpretableDetails(uninterpretable),
+    });
+}
+/**
+ * Throws while another process works on a run that init wouldn't report: a
+ * `--run-migration` run, a run being started, or a run nx can't read. A new
+ * run would install and commit over its in-progress edits. An active
+ * `--run-migrations` run is reported instead, except to a `--run-migration`
+ * run, and records no process holds block nothing.
+ */
+function refuseNewRunAlongsideLiveRun(root, singleMigration = false) {
+    const live = (0, state_lock_1.findOtherLiveRuns)(root).find((run) => singleMigration || !run.state || (0, run_state_1.runKind)(run.state) !== 'active');
+    if (live) {
+        throw (0, state_lock_1.liveRunRefusal)(singleMigration
+            ? 'Not running the migration'
+            : 'Not running the migrations', live);
+    }
+}
+/**
+ * The refusals of prepareSingleMigrationRun alone, for the CLI to make before
+ * its install. Removes and warns about nothing.
+ */
+function checkRunsForSingleMigration(root) {
+    if (!(0, fs_1.existsSync)((0, run_state_1.migrateRunsDir)(root)))
+        return;
+    (0, state_lock_1.withRunCreationLock)(root, () => refuseNewRunAlongsideLiveRun(root, true));
+}
+/**
+ * The check every `--run-migration` run without a run id makes before it runs
+ * anything. Throws while another nx migrate process works on a run, removes
+ * `--run-migration` records no process holds, and warns about idle active
+ * runs, which do not record this migration.
+ */
+function prepareSingleMigrationRun(root) {
+    if (!(0, fs_1.existsSync)((0, run_state_1.migrateRunsDir)(root)))
+        return;
+    const idleRunIds = [];
+    const uninterpretable = [];
+    (0, state_lock_1.withRunCreationLock)(root, () => {
+        refuseNewRunAlongsideLiveRun(root, true);
+        // No other process holds what is left.
+        for (const run of (0, state_lock_1.listOtherRuns)(root)) {
+            if (run.starting)
+                continue;
+            if (run.state?.singleMigration === true) {
+                removeSingleMigrationRun(root, run.dirName);
+            }
+            else if (run.state) {
+                idleRunIds.push(run.dirName);
+            }
+            else if (!(run.readError instanceof run_state_1.NewerRunStateFormatError)) {
+                // A newer nx's run is that nx's to report.
+                uninterpretable.push({
+                    dirName: run.dirName,
+                    reason: (0, util_1.summarizeError)(run.readError),
+                });
+            }
+        }
+    });
+    if (uninterpretable.length > 0) {
+        warnIgnoredRunDirs(uninterpretable);
+    }
+    if (idleRunIds.length > 0) {
+        const runs = idleRunIds.map((id) => `'${(0, text_1.singleLine)(id)}'`).join(', ');
         (0, agent_output_1.warnToAgent)({
-            title: `Ignoring ${uninterpretable.length} migrate run ${noun} that could not be read.`,
-            bodyLines: details,
+            title: `This migration won't be recorded into the active migrate ${idleRunIds.length === 1 ? 'run' : 'runs'} ${runs}.`,
+            bodyLines: [
+                idleRunIds.length === 1
+                    ? 'Continuing that run may apply the migration again.'
+                    : 'Continuing one of those runs may apply the migration again.',
+            ],
         });
     }
-    return active;
 }
-// A run directory without run.json but with a live activity lock is an init
-// between reserving the directory and writing run.json: the checkpoint commit
-// is in flight and no run may start alongside it. Refused at once, never
-// waited for: a git hook re-entering nx migrate during that commit would
-// otherwise wait on the process waiting for the hook. An unlocked one is the
-// remains of an init that died, which discovery ignores like any other
-// directory without run.json. Call under the creation lock.
-function refuseLiveReservation(root) {
-    for (const entry of (0, fs_1.readdirSync)((0, run_state_1.migrateRunsDir)(root), {
-        withFileTypes: true,
-    })) {
-        if (!entry.isDirectory())
-            continue;
-        const dir = (0, path_1.join)((0, run_state_1.migrateRunsDir)(root), entry.name);
-        if ((0, run_state_1.hasRunState)(dir) || !(0, state_lock_1.hasAnyLiveRunActivity)(dir))
-            continue;
-        throw new Error(`Another nx migrate process is starting a run (${types_1.MIGRATE_RUNS_RELATIVE_DIR}/${(0, text_1.singleLine)(entry.name)}). Wait for it to finish, then re-run the command.`);
+/**
+ * Removes a `--run-migration` run's record. Call under the creation lock. Kept
+ * while another process still works on the run, such as a worker the agent
+ * left running: other runs refuse alongside it, and the next
+ * `--run-migration` removes it once none does. Otherwise best effort: what is
+ * left blocks nothing.
+ */
+function removeSingleMigrationRun(root, runId) {
+    const dir = (0, run_state_1.runDir)(root, runId);
+    const path = `${types_1.MIGRATE_RUNS_RELATIVE_DIR}/${runId}`;
+    try {
+        const deletion = deleteUnheldRunRecord(root, runId);
+        if (typeof deletion === 'object') {
+            (0, state_lock_1.releaseRunActivity)(dir);
+            (0, agent_output_1.warnToAgent)({
+                title: deletion.holders === 'unknown'
+                    ? `Kept ${path}: nx cannot tell whether another nx migrate process is still working on it. Make sure none is, then remove it.`
+                    : `Kept ${path}: ${(0, state_lock_1.describeHolders)(deletion.holders)}. Other nx migrate runs refuse until it ends, and the next --run-migration removes it.`,
+            });
+            return;
+        }
+        (0, fs_1.rmSync)(dir, { recursive: true, force: true });
+    }
+    catch (e) {
+        (0, agent_output_1.warnToAgent)({
+            title: `Could not remove ${path}: ${(0, util_1.summarizeError)(e)}. It blocks nothing; remove it when convenient.`,
+        });
     }
 }
 // The report for an init that found a run already active. On the agent path
@@ -405,7 +557,7 @@ function refuseUndeletableRun(root, runId, state) {
         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) {
+    if ((0, state_lock_1.isHeld)(holders)) {
         throw (0, state_lock_1.heldRunError)('deleting', runId, holders);
     }
     const workers = (0, existing_run_report_1.liveWorkers)(state);
@@ -421,19 +573,36 @@ function refuseUndeletableRun(root, runId, state) {
 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.
+// The refusals run again on fresh state: the early pass predates the prompt.
+// False when already gone.
 function deleteRunRecord(root, runId) {
+    const deletion = deleteUnheldRunRecord(root, runId, (state) => refuseUndeletableRun(root, runId, state));
+    if (deletion === 'deleted')
+        return true;
+    if (deletion === 'gone')
+        return false;
+    throw (0, state_lock_1.heldRunError)('deleting', runId, deletion.holders);
+}
+/**
+ * Removes run.json unless another process holds the run, and returns its
+ * holders instead. Call under the creation lock, which every claim takes, so
+ * no process starts holding the run between the check and the removal. The
+ * state lock keeps a reconcile or worker from starting against a directory
+ * about to disappear. `refuse` sees the state read under it.
+ */
+function deleteUnheldRunRecord(root, runId, refuse) {
     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.
+            return 'gone';
+        refuse?.((0, run_state_1.readRunState)(dir));
+        const holders = (0, state_lock_1.liveRunActivityPids)(dir);
+        if ((0, state_lock_1.isHeld)(holders))
+            return { holders };
+        // The hold's lock file is inside the directory removed afterwards.
         (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;
+        return 'deleted';
     });
 }
 // The rest of a deleted run's directory, removed outside the locks and best
@@ -518,7 +687,7 @@ function ensureCheckpoint(root, dir, state) {
         // 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';
+        const cleared = (0, migrate_commits_1.migrateTreeStatus)(root) === 'clean';
         if (!checkpoint && !cleared)
             return state;
         return (0, state_lock_1.updateRunState)(dir, (fresh) => {
@@ -548,7 +717,7 @@ function ensureCheckpoint(root, dir, state) {
 function checkpointEntry(root, commitPrefix, before) {
     // Skip only on a verified-clean tree; on a failed probe the commit attempt
     // below re-probes and may succeed once the transient failure passes.
-    if ((0, git_utils_1.getWorkingTreeStatus)(root) === 'clean') {
+    if ((0, migrate_commits_1.migrateTreeStatus)(root) === 'clean') {
         return null;
     }
     (0, migrate_commits_1.commitCheckpointBeforeMigrations)(root, commitPrefix);
@@ -566,7 +735,8 @@ function finishInit(root, dir, runId, state, origin, emitAgentInstructions,
 // which must fail before its git and state side effects).
 runbook) {
     let current = state;
-    if (!current.analytics.startEmitted) {
+    if (reportsOrchestratorAnalytics(current) &&
+        !current.analytics.startEmitted) {
         // Claim the watermark on the fresh state first: of two concurrent inits
         // exactly one flips it, and only that one reports.
         let claimed = false;
@@ -588,7 +758,7 @@ runbook) {
             });
         }
     }
-    if (origin === 'resumed') {
+    if (origin === 'resumed' && reportsOrchestratorAnalytics(current)) {
         (0, migrate_analytics_1.reportMigrateOrchestratorResume)((0, state_machine_1.runTallies)(current));
     }
     const content = runbook ?? ensureRunbook(root, dir, runId, current);
@@ -694,6 +864,7 @@ function runbookContext(root, runId, state) {
         // The pass guidance follows the plan: an opted-out run, or one recorded
         // before the pass existed, has no pass step to dispense.
         finalValidation: state.steps.some((s) => s.kind === 'final-validation'),
+        singleMigration: state.singleMigration === true,
     };
 }
 // Only the newest recorded commit is checked, so the warning stops on its own
@@ -760,7 +931,7 @@ async function runOrchestratorReconcile(input) {
         try {
             const result = await applyReconcileStepAction(root, dir, state, stepAction, scope);
             if (result.kind === 'error') {
-                emitError(root, runId, result.reason);
+                emitError(root, runId, state, result.reason);
                 return; // no transition was written
             }
             const target = result.targetStep;
@@ -772,10 +943,12 @@ async function runOrchestratorReconcile(input) {
                 !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);
+                    emitError(root, runId, state, outcome.reason);
                     return;
                 }
-                (0, give_up_1.warnAboutGiveUp)(target, outcome);
+                (0, give_up_1.warnAboutGiveUp)(target, outcome, (0, util_1.commitFailureRecovery)(state));
+                if (target.installFailed === true)
+                    warnInstallLeftToUser(root, target);
                 // Settled already; the dispense refuses a tree still held.
                 scope.lease?.release();
                 scope.lease = undefined;
@@ -786,8 +959,9 @@ async function runOrchestratorReconcile(input) {
             // sections stay synchronous); the transition and any unrecorded entry then
             // land in one write. Adopt and skip keep the tree, so the install they owe
             // runs here: the next dispense would take the changed deps as its baseline.
-            // Giving up keeps it the same way when the run does not commit. Retries
-            // owe nothing: the rearmed attempt reconciles itself.
+            // Giving up keeps it the same way when the run does not commit. An install
+            // that already failed is left to the step's mark instead. 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
@@ -855,7 +1029,7 @@ async function runOrchestratorReconcile(input) {
                     : next;
             });
             if (freshRejection) {
-                emitError(root, runId, entry?.kind === 'landed' && entry.sha
+                emitError(root, runId, state, 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;
@@ -863,6 +1037,11 @@ async function runOrchestratorReconcile(input) {
             if (unresolvedArchiveError !== undefined) {
                 (0, give_up_1.warnUnresolvedNotArchived)((0, state_machine_1.stepLabel)(target), unresolvedArchiveError);
             }
+            // A retry's rearm drops the mark: its next attempt installs.
+            if (target.installFailed === true &&
+                written.steps.find((s) => s.id === target.id)?.installFailed === true) {
+                warnInstallLeftToUser(root, target);
+            }
             state = written;
         }
         finally {
@@ -1103,7 +1282,7 @@ async function foldLedgerEntry(root, dir, state, step, promptOutcome, scope) {
 // is not verifiably clean (see foldLedgerEntry for why).
 async function retainedTreeSideEffects(root, dir, state, step, seam, scope) {
     const installFailed = await installFailedForStep(root, dir, state, step, seam, scope);
-    const entry = state.createCommits && (0, git_utils_1.getWorkingTreeStatus)(root) !== 'clean'
+    const entry = state.createCommits && (0, migrate_commits_1.migrateTreeStatus)(root) !== 'clean'
         ? { kind: 'failed', stepIds: [step.id] }
         : null;
     return { entry, installFailed };
@@ -1131,6 +1310,14 @@ async function installFailedForStep(root, dir, state, step, seam, scope) {
         return true;
     }
 }
+function warnInstallLeftToUser(root, step) {
+    (0, agent_output_1.warnToAgent)({
+        title: `The dependency changes made by ${(0, state_machine_1.stepLabel)(step)} are not installed.`,
+        bodyLines: [
+            `Run \`${(0, util_1.pmInstallCommand)(root)}\` once the cause of the failed install is fixed. The run's final report repeats this unless a later install covers them.`,
+        ],
+    });
+}
 // A failed handoff fails the prompt; a success handoff completes it, unless it
 // marks the prompt not applicable via `extras.outcome === 'skipped'`.
 function handoffToPromptOutcome(handoff) {
@@ -1232,7 +1419,7 @@ async function applyReconcileStepAction(root, dir, state, action, scope) {
         // 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') {
+        if ((0, migrate_commits_1.migrateTreeStatus)(root) !== 'clean') {
             return {
                 kind: 'error',
                 reason: `Cannot apply action 'retry-clean' to step '${step.id}': the working tree is not verifiably clean after the reset to ${step.gitRefBefore}. Inspect it with \`git status\`, then re-run it. ${fallback}`,
@@ -1261,7 +1448,7 @@ async function applyReconcileStepAction(root, dir, state, action, scope) {
                 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') {
+        if ((0, migrate_commits_1.migrateTreeStatus)(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.`,
@@ -1316,11 +1503,13 @@ function unresolvedResetsTree(state, step, cleanRetry) {
 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.
+            // A died worker's commit request is reused while nothing records its
+            // outcome, since the session may still answer it. Otherwise the adopt
+            // asks under its own request, or the old answer would be replayed.
             return state.createCommits
                 ? commitForStep(root, dir, state, step, scope, step.status === 'failed' ||
+                    step.commitLedgerIndex !== undefined ||
+                    step.installFailed === true ||
                     (0, state_machine_1.coveringLandedEntries)(state, step.id).length > 0
                     ? 'adopt'
                     : undefined)
@@ -1356,9 +1545,10 @@ async function commitForStep(root, dir, state, step, scope, commitAs) {
     const name = (0, state_machine_1.commitNameForStep)(step);
     const absorbedStepIds = (0, state_machine_1.uncoveredFailedStepIds)(state).filter((id) => id !== step.id);
     const skipInstall = state.skipInstall === true;
+    const recovery = (0, util_1.commitFailureRecovery)(state);
     let commit;
     try {
-        commit = await (0, broker_1.commitStepTree)(dir, step, absorbedStepIds, () => (0, migrate_commits_1.commitMigrationIfRequested)(root, { 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);
+        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), recovery), scope, commitAs);
     }
     catch (e) {
         // Nothing to record: the step moved on, another process holds the tree, or
@@ -1372,14 +1562,14 @@ async function commitForStep(root, dir, state, step, scope, commitAs) {
         // 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);
+        (0, util_1.warnCommitFailed)(name, recovery, e);
         return {
             entry: { kind: 'failed', stepIds: [step.id] },
             installFailed: true,
         };
     }
     if (commit.result.status === 'failed') {
-        (0, util_1.warnCommitFailed)(name);
+        (0, util_1.warnCommitFailed)(name, recovery);
     }
     return {
         entry: (0, state_machine_1.commitResultToLedgerEntry)(commit.result, step.id, commit.absorbedStepIds),
@@ -1501,11 +1691,7 @@ function dispenseNextStep(root, dir, runId, state, step, noProgress) {
     // Read the pre-step baselines (git and package.json reads) before the
     // lock; the dispense transition and the baselines then apply to the fresh
     // state in one write.
-    const baselines = {
-        gitRefBefore: (0, git_utils_1.getLatestCommitSha)(root) ?? undefined,
-        treeCleanAtDispense: (0, git_utils_1.getWorkingTreeStatus)(root) === 'clean',
-        depsHashAtDispense: (0, util_1.depsHash)(root),
-    };
+    const baselines = readDispenseBaselines(root);
     let advancedElsewhere = false;
     let held;
     const current = (0, state_lock_1.updateRunState)(dir, (fresh) => {
@@ -1536,10 +1722,12 @@ function dispenseNextStep(root, dir, runId, state, step, noProgress) {
         return;
     }
     const dispensed = current.steps.find((s) => s.id === step.id);
-    (0, migrate_analytics_1.reportMigrateOrchestratorStepDispensed)({
-        attempt: dispensed.attempt,
-        ordinal: (0, state_machine_1.runTallies)(current).dispenseCount,
-    });
+    if (reportsOrchestratorAnalytics(current)) {
+        (0, migrate_analytics_1.reportMigrateOrchestratorStepDispensed)({
+            attempt: dispensed.attempt,
+            ordinal: (0, state_machine_1.runTallies)(current).dispenseCount,
+        });
+    }
     switch (dispensed.kind) {
         case 'migration':
             emitNextStep(root, runId, current, dispensed, noProgress);
@@ -1553,6 +1741,25 @@ function dispenseNextStep(root, dir, runId, state, step, noProgress) {
         }
     }
 }
+function readDispenseBaselines(root) {
+    return {
+        gitRefBefore: (0, git_utils_1.getLatestCommitSha)(root) ?? undefined,
+        treeCleanAtDispense: (0, migrate_commits_1.migrateTreeStatus)(root) === 'clean',
+        depsHashAtDispense: (0, util_1.depsHash)(root),
+    };
+}
+/**
+ * Dispenses a `--run-migration` run's step without a response: the parent
+ * runs the step's first attempt itself, and an agent it starts afterwards
+ * gets the step from the "next" command.
+ */
+function dispenseSingleMigrationStep(root, runId) {
+    const baselines = readDispenseBaselines(root);
+    (0, state_lock_1.updateRunState)((0, run_state_1.runDir)(root, runId), (fresh) => {
+        const [step] = fresh.steps;
+        return setDispenseBaselines(applyEventOrThrow(fresh, dispenseEvent(step)), step.id, baselines);
+    });
+}
 function dispenseEvent(step) {
     switch (step.kind) {
         case 'migration':
@@ -1631,6 +1838,7 @@ function emitRetryFailed(root, runId, state, step, noProgress) {
         `  current HEAD: ${head ?? '(unknown)'}`,
         `  working tree: ${tree === null ? '(unknown)' : tree ? `\n${tree}` : '(clean)'}`,
         ``,
+        ...unfinishedOperationLines(root, state, step),
         retryBudgetLine(step, committed),
         ``,
         `Decide how to proceed and re-run reconcile with one of:`,
@@ -1639,13 +1847,17 @@ function emitRetryFailed(root, runId, state, step, noProgress) {
             : [retryOptionLine(retrySafety, reconcileCommand(root, runId, 'retry'))]),
     ];
     if (cleanRetry && !capReached) {
-        lines.push(`  retry-clean: reset the tree to ${step.gitRefBefore ?? 'the pre-migration ref'} (discarding its uncommitted tracked changes and the untracked files git does not ignore, ${types_1.MIGRATE_RUNS_RELATIVE_DIR} kept) and retry from that clean state by running: ${reconcileCommand(root, runId, 'retry-clean')}`);
-    }
+        lines.push(`  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, keeping ${KEPT_OWNED_PATHS}) and retry from that clean state by running: ${reconcileCommand(root, runId, 'retry-clean')}`);
+    }
+    // A failed commit is already named above the choices.
+    const adoptWhen = recordedCommitFailed(state, step)
+        ? ''
+        : committed
+            ? `a commit of this ${(0, state_machine_1.stepNoun)(step)}'s changes was started and never recorded; `
+            : `the ${(0, state_machine_1.stepNoun)(step)} was ${step.kind === 'migration' ? 'applied' : 'done'} by hand; `;
     lines.push(landed
         ? `  adopt: keep the landed commit${landed.sha ? ` ${landed.sha}` : ''} and the current working-tree state as the ${(0, state_machine_1.stepNoun)(step)}'s result, then run: ${reconcileCommand(root, runId, 'adopt')}`
-        : `  adopt: ${committed
-            ? `a commit of this ${(0, state_machine_1.stepNoun)(step)}'s changes was started and never recorded`
-            : `the ${(0, state_machine_1.stepNoun)(step)} was ${step.kind === 'migration' ? 'applied' : 'done'} by hand`}; keep the current working-tree state as its result, then run: ${reconcileCommand(root, runId, 'adopt')}`);
+        : `  adopt: ${adoptWhen}keep the current working-tree state as its result, then run: ${reconcileCommand(root, runId, 'adopt')}`);
     // Refused by the state machine: the migration is, or may be, committed.
     if (!committed) {
         lines.push(`  skip:  ${reconcileCommand(root, runId, 'skip')}`, unresolvedOptionLine(root, runId, state, step, unresolvedResetsTree(state, step, cleanRetry)));
@@ -1677,6 +1889,26 @@ function retryBudgetLine(step, committed) {
         ? `adopt only once you have inspected the tree and finished the ${(0, state_machine_1.stepNoun)(step)}; otherwise stop and report`
         : 'give the step up with unresolved and continue'}.`;
 }
+// A recorded failed commit with the mark standing withdraws skip and
+// unresolved, so every choice left commits.
+function unfinishedOperationLines(root, state, step) {
+    const lines = [];
+    if (step.installFailed === true) {
+        lines.push(`Its dependency install did not complete. A retry runs it again, so fix the cause first if it can be fixed. Any other choice settles the step without installing and leaves the install to you; the run's final report asks for \`${(0, util_1.pmInstallCommand)(root)}\`.`, ``);
+    }
+    if (recordedCommitFailed(state, step)) {
+        lines.push(`Its commit did not complete. Every choice below commits again.`, ``);
+    }
+    return lines;
+}
+function recordedCommitFailed(state, step) {
+    // Not commitReceipt, which throws on an index the ledger lacks: a dispense
+    // has to render whatever run.json holds.
+    const receipt = step.commitLedgerIndex === undefined
+        ? undefined
+        : state.commits[step.commitLedgerIndex];
+    return step.commitStarted === true && receipt?.kind === 'failed';
+}
 // Opens a capped dispense and is the reason a retry past the cap is refused.
 function rearmCapLine(step, committed) {
     return `This ${(0, state_machine_1.stepNoun)(step)} has already been retried ${step.attempt - 1} times without completing, and no further retry is accepted. ${committed
@@ -1734,7 +1966,7 @@ function assessPreMarkerRetry(root, step) {
             reason: `HEAD is at ${head ?? '(unreadable)'} rather than the ${step.gitRefBefore ?? '(unrecorded)'} this migration started from, so the failed attempt's changes may already be committed and rerunning the generator could apply them twice.`,
         };
     }
-    if ((0, git_utils_1.getWorkingTreeStatus)(root) !== 'clean') {
+    if ((0, migrate_commits_1.migrateTreeStatus)(root) !== 'clean') {
         return {
             kind: 'unsafe',
             reason: `the working tree is not verifiably clean, and the failed attempt may have written to it before failing; rerunning the generator over those changes could apply them twice.`,
@@ -1751,10 +1983,12 @@ function lastCoveringLandedEntry(state, step) {
 // reset, a partial commit, or the tree left as it stands.
 function unresolvedOptionLine(root, runId, state, step, resetTree) {
     const command = reconcileCommand(root, runId, 'unresolved');
-    const recorded = `The failure is recorded as a run issue and listed in the completion report.`;
+    const recorded = state.singleMigration === true
+        ? `The failure is listed in the completion report.`
+        : `The failure is recorded as a run issue and listed in the completion report.`;
     const noun = (0, state_machine_1.stepNoun)(step);
     if (resetTree) {
-        return `  unresolved: give up on this ${noun}, resetting the tree to ${step.gitRefBefore ?? 'the pre-migration ref'} (discarding what the failed attempt left, ${types_1.MIGRATE_RUNS_RELATIVE_DIR} kept), then run: ${command}. ${recorded}`;
+        return `  unresolved: give up on this ${noun}, resetting the tree to ${step.gitRefBefore ?? 'the pre-migration ref'} (discarding what the failed attempt left, keeping ${KEPT_OWNED_PATHS}), then run: ${command}. ${recorded}`;
     }
     if (state.createCommits) {
         return `  unresolved: give up on this ${noun}; its partial changes are committed under its name, marked unresolved, and the run moves on. Then run: ${command}. ${recorded}`;
@@ -1776,6 +2010,7 @@ function emitDied(root, runId, state, step, noProgress) {
         `  current HEAD: ${head ?? '(unknown)'}`,
         `  working tree: ${tree === null ? '(unknown)' : tree ? `\n${tree}` : '(clean)'}`,
         ``,
+        ...unfinishedOperationLines(root, state, step),
         retryBudgetLine(step, committed),
         ``,
     ];
@@ -1784,7 +2019,7 @@ 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 && !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')}`);
+        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, keeping ${KEPT_OWNED_PATHS}) and retry from that clean state by running: ${reconcileCommand(root, runId, 'retry-clean')}`);
     }
     else if (!capReached) {
         lines.push(`A clean retry is unavailable: ${(0, clean_retry_1.cleanRetryUnavailableReason)(root, state, step, head)}`);
@@ -1810,9 +2045,19 @@ function emitDied(root, runId, state, step, noProgress) {
     }, noProgress);
 }
 function emitHeld(root, runId, state, step, held, noProgress) {
+    const heldStep = state.steps.find((s) => s.id === held.stepId);
+    const heldStepName = heldStep && (0, state_machine_1.stepLabel)(heldStep);
     emit(root, runId, state, step, 'held', {
         next: reconcileCommand(root, runId),
-        instructionLines: [(0, broker_1.treeBusyMessage)(held)],
+        instructionLines: [
+            (0, broker_1.treeBusyMessage)(held, heldStepName),
+            // Quitting this session frees the terminal only for its own parent.
+            ...(held.owner === process.env[broker_1.BROKER_ENV_VAR]
+                ? [
+                    `If it seems stuck, the user can ${(0, broker_1.sessionOperationWayOut)((0, broker_1.treeOperationLabel)(held, heldStepName))}.`,
+                ]
+                : []),
+        ],
     }, noProgress);
 }
 function emitStillRunning(root, runId, state, step, held, noProgress) {
@@ -1830,7 +2075,7 @@ function emitStillRunning(root, runId, state, step, held, noProgress) {
     if (ageMs >= HANG_THRESHOLD_MS) {
         const hung = `It has been running for ${Math.floor(ageMs / 60000)} minutes and may be hung.`;
         lines.push(parentOperation
-            ? `${hung} Report this to the user: they can quit this session, then press Ctrl+C in the terminal to end ${parentOperation}, and resume the run afterwards.`
+            ? `${hung} Report this to the user: they can ${(0, broker_1.sessionOperationWayOut)(parentOperation)}.`
             : `${hung} Verify pid ${step.pid}; either keep waiting, or kill it so the next reconcile can classify it as died.`);
     }
     emit(root, runId, state, step, 'still-running', {
@@ -2004,9 +2249,8 @@ function planPromptPath(dir, state, migrationId) {
     }
     return null;
 }
-// Wording mirrors the classic runner's ambiguous-outcome cause lines. A
-// readable handoff whose issue report is invalid is a rejection too: the fold
-// refused to consume it, and only this response can tell the agent why.
+// A readable handoff whose issue report is invalid is a rejection too: the
+// fold refused to consume it, and only this response can tell the agent why.
 function describeRejectedHandoff(dir, state, step) {
     const result = readStepHandoff(dir, step.id);
     const followUp = 'Rewrite the handoff file, then run the "next" command.';
@@ -2049,7 +2293,7 @@ function describeRejectedHandoff(dir, state, step) {
 // to the request, and it carries the reconcile command to run next. A non-zero
 // exit would tell the driving agent that reconcile itself crashed, and it
 // would stop reading for the correction it is being handed.
-function emitError(root, runId, reason) {
+function emitError(root, runId, state, reason) {
     // A rejected action is an active response like any dispense, so it carries
     // the runbook footer: the master receiving it may have just lost its
     // context. One sanitized array feeds both outputs, as in emit().
@@ -2062,7 +2306,9 @@ function emitError(root, runId, reason) {
         next: reconcileCommand(root, runId),
         instructions: lines.join('\n'),
     });
-    (0, migrate_analytics_1.reportMigrateOrchestratorDispense)({ action: 'error', attempt: 0 });
+    if (reportsOrchestratorAnalytics(state)) {
+        (0, migrate_analytics_1.reportMigrateOrchestratorDispense)({ action: 'error', attempt: 0 });
+    }
 }
 /**
  * What a completed run leaves behind for whoever reads its summary, one line
@@ -2074,14 +2320,19 @@ function completionWarnings(root, runId, state) {
     // 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 debtStepIds = (0, state_machine_1.uncoveredFailedStepIds)(state);
+    const uncommitted = debtStepIds.length > 0 && (0, migrate_commits_1.migrateTreeStatus)(root) !== 'clean'
+        ? state.steps.filter((s) => debtStepIds.includes(s.id))
+        : [];
     const uninstalled = state.steps.filter((s) => s.installFailed);
     const issueLines = (0, issues_1.renderUnresolvedIssueLines)(state, runId);
     return [
-        ...(commitDebt
+        ...(uncommitted.length > 0
             ? [
                 [
-                    'Some migration changes could not be committed and may remain in the working tree; review and commit them manually.',
+                    `The changes made by ${uncommitted
+                        .map(state_machine_1.stepLabel)
+                        .join(', ')} could not be committed and may remain in the working tree; review and commit them manually.`,
                 ],
             ]
             : []),
@@ -2117,7 +2368,7 @@ function completeRun(root, dir, runId, state) {
             };
         });
     }
-    if (shouldEmit) {
+    if (shouldEmit && reportsOrchestratorAnalytics(current)) {
         (0, migrate_analytics_1.reportMigrateOrchestratorComplete)((0, state_machine_1.runTallies)(current));
     }
     const warnings = completionWarnings(root, runId, current);
@@ -2156,11 +2407,18 @@ function emit(root, runId, state, step, action, payload, noProgress) {
         ...rest,
         ...(lines ? { instructions: lines.join('\n') } : {}),
     });
-    (0, migrate_analytics_1.reportMigrateOrchestratorDispense)({
-        action: effectiveAction,
-        attempt: step.attempt,
-        ordinal: (0, state_machine_1.runTallies)(state).dispenseCount,
-    });
+    if (reportsOrchestratorAnalytics(state)) {
+        (0, migrate_analytics_1.reportMigrateOrchestratorDispense)({
+            action: effectiveAction,
+            attempt: step.attempt,
+            ordinal: (0, state_machine_1.runTallies)(state).dispenseCount,
+        });
+    }
+}
+// A `--run-migration` run reports its own events, so only `--run-migrations`
+// runs report orchestrator events.
+function reportsOrchestratorAnalytics(state) {
+    return state.singleMigration !== true;
 }
 function noProgressLines(step, streak) {
     let subject;
@@ -2254,12 +2512,18 @@ function removeHandoff(dir, stepId) {
         (0, fs_1.rmSync)((0, handoff_1.runStepHandoffPath)(dir, stepId), { force: true });
     }
 }
+const KEPT_OWNED_PATHS = `${migrate_commits_1.MIGRATE_OWNED_PATHS.slice(0, -1).join(', ')} and ${migrate_commits_1.MIGRATE_OWNED_PATHS[migrate_commits_1.MIGRATE_OWNED_PATHS.length - 1]}`;
 // null means the probe itself failed; the death dispense renders that as
 // '(unknown)', because '(clean)' would invite a retry-clean reset over
 // evidence that was never gathered (getWorkingTreeStatus's contract).
 function dirtyTreeSummary(root) {
     try {
-        return (0, child_process_1.execSync)('git status --porcelain', {
+        return (0, child_process_1.execFileSync)('git', [
+            'status',
+            '--porcelain',
+            '--',
+            ...(0, migrate_commits_1.migrateCommitExcludes)(root).map((path) => `:(exclude)${path}`),
+        ], {
             encoding: 'utf8',
             cwd: root,
             stdio: ['ignore', 'pipe', 'pipe'],