nx 23.3.0-beta.2 → 23.3.0-beta.3

package/dist/src/command-line/migrate/run/run-state.d.ts

@@ -51,6 +51,8 @@ export interface MigrateStep {
     outcome?: MigrateStepOutcome;
     promptOutcome?: MigrateStepPromptOutcome;
     awaitingKind?: MigrateStepAwaitingKind;
+    commitLedgerIndex?: number;
+    commitStarted?: boolean;
     generatorCompleted?: boolean;
     generatorCompletedAtAttempt?: number;
     agenticWaived?: boolean;
@@ -95,6 +97,10 @@ export interface MigrateRunNoProgress {
     consecutiveCount: number;
     firstSeenAt: string;
 }
+export interface MigrateRunPolicy {
+    createCommits: boolean;
+    skipInstall: boolean;
+}
 export interface MigrateRunState {
     formatVersion: number;
     runId: string;
@@ -112,8 +118,18 @@ export interface MigrateRunState {
     issues?: MigrateRunIssue[];
     noProgress?: MigrateRunNoProgress;
     checkpointFailed?: boolean;
+    treeOperation?: MigrateTreeOperation;
     analytics: MigrateRunAnalytics;
 }
+export declare const TREE_OPERATION_KINDS: readonly ['commit', 'install', 'fold-install', 'action-install', 'reset', 'checkpoint'];
+export type MigrateTreeOperationKind = (typeof TREE_OPERATION_KINDS)[number];
+export interface MigrateTreeOperation {
+    kind: MigrateTreeOperationKind;
+    stepId?: string;
+    attempt?: number;
+    owner: string;
+    pid: number;
+}
 export declare function migrateRunsDir(root: string): string;
 export declare function runDir(root: string, runId: string): string;
 /** See `HANDOFFS_DIR_NAME` for why the subtree exists. */

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NewerRunStateFormatError = exports.MIGRATE_ISSUE_DISPOSITIONS = exports.TERMINAL_STEP_STATUSES = exports.ISSUE_ID = exports.SHELL_SAFE_VALUE = exports.RUN_STATE_FILE_NAME = exports.CURRENT_RUN_STATE_FORMAT_VERSION = void 0;
+exports.NewerRunStateFormatError = exports.TREE_OPERATION_KINDS = exports.MIGRATE_ISSUE_DISPOSITIONS = exports.TERMINAL_STEP_STATUSES = exports.ISSUE_ID = exports.SHELL_SAFE_VALUE = exports.RUN_STATE_FILE_NAME = exports.CURRENT_RUN_STATE_FORMAT_VERSION = void 0;
 exports.issueFingerprint = issueFingerprint;
 exports.migrateRunsDir = migrateRunsDir;
 exports.runDir = runDir;
@@ -18,6 +18,7 @@ const atomic_write_1 = require("./atomic-write");
 const git_utils_1 = require("../../../utils/git-utils");
 const versions_1 = require("../../../utils/versions");
 const types_1 = require("../agentic/types");
+const handoff_1 = require("../agentic/handoff");
 const run_id_1 = require("./run-id");
 const text_1 = require("../text");
 exports.CURRENT_RUN_STATE_FORMAT_VERSION = 1;
@@ -111,6 +112,14 @@ exports.MIGRATE_ISSUE_DISPOSITIONS = [
     'resolved',
     'deferred-final',
 ];
+exports.TREE_OPERATION_KINDS = [
+    'commit',
+    'install',
+    'fold-install',
+    'action-install',
+    'reset',
+    'checkpoint',
+];
 const REQUIRED_TOP_LEVEL_FIELDS = [
     'formatVersion',
     'runId',
@@ -226,6 +235,7 @@ function isStepShape(value) {
         isPromptOutcomeShape(value.promptOutcome) &&
         (value.awaitingKind === undefined ||
             isOneOf(MIGRATE_STEP_AWAITING_KINDS, value.awaitingKind)) &&
+        isOptionalBoolean(value.commitStarted) &&
         isOptionalBoolean(value.generatorCompleted) &&
         // Bounded by the step's attempt: a higher value could not name one that
         // exists.
@@ -234,6 +244,9 @@ function isStepShape(value) {
                 value.generatorCompletedAtAttempt >= 1 &&
                 value.generatorCompletedAtAttempt <=
                     value.attempt)) &&
+        (value.commitLedgerIndex === undefined ||
+            (Number.isSafeInteger(value.commitLedgerIndex) &&
+                value.commitLedgerIndex >= 0)) &&
         isOptionalBoolean(value.agenticWaived) &&
         isOptionalBoolean(value.validationOwed) &&
         isOptionalBoolean(value.generatorMadeChanges) &&
@@ -338,6 +351,19 @@ function isNoProgressShape(value) {
             typeof value.firstSeenAt === 'string' &&
             ISO_TIMESTAMP.test(value.firstSeenAt)));
 }
+function isTreeOperationShape(value) {
+    return (value === undefined ||
+        (isPlainObject(value) &&
+            isOneOf(exports.TREE_OPERATION_KINDS, value.kind) &&
+            (value.stepId === undefined || typeof value.stepId === 'string') &&
+            (value.attempt === undefined ||
+                (Number.isSafeInteger(value.attempt) &&
+                    value.attempt >= 1)) &&
+            typeof value.owner === 'string' &&
+            value.owner.length > 0 &&
+            Number.isSafeInteger(value.pid) &&
+            value.pid > 0));
+}
 function isAnalyticsShape(value) {
     return (isPlainObject(value) &&
         typeof value.startEmitted === 'boolean' &&
@@ -374,6 +400,7 @@ function hasValidRunStateShape(parsed) {
         parsed.commits.every((c) => c.issueIds === undefined ||
             c.issueIds.every((id) => (parsed.issues ?? []).some((i) => i.id === id))) &&
         isNoProgressShape(parsed.noProgress) &&
+        isTreeOperationShape(parsed.treeOperation) &&
         isAnalyticsShape(parsed.analytics));
 }
 function corruptRunStateError(filePath, reason) {
@@ -404,7 +431,11 @@ exports.NewerRunStateFormatError = NewerRunStateFormatError;
  */
 function readRunState(runDirPath) {
     const filePath = (0, path_1.join)(runDirPath, exports.RUN_STATE_FILE_NAME);
-    const content = (0, fs_1.readFileSync)(filePath, 'utf-8');
+    // run.json lives in the agent-writable run directory, so it could be a
+    // planted symlink or FIFO; read it without reading a symlink's target or
+    // blocking on a FIFO, while still tolerating a concurrent tmp + rename
+    // publish. A non-regular file reads as corruption; ENOENT stays "no run".
+    const content = (0, handoff_1.readAtomicallyPublishedFile)(filePath, corruptRunStateError(filePath, 'is not a regular file.').message);
     let parsed;
     try {
         parsed = JSON.parse(content);

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

@@ -8,6 +8,9 @@ exports.renderRunbook = renderRunbook;
 const fragments_1 = require("../agentic/prompts/fragments");
 const types_1 = require("../agentic/types");
 const text_1 = require("../text");
+// A resume without a commit flag takes its policy from nx.json and refuses
+// the run when it differs from the recorded one.
+const NX_JSON_MIGRATE_RULE = `  - Do not edit the \`migrate\` section of nx.json.`;
 exports.RUNBOOK_FILE_NAME = 'RUNBOOK.md';
 /**
  * Every interpolated value is collapsed to a single line: the rendered content
@@ -78,12 +81,13 @@ function renderRunbook(ctx) {
         ...(0, fragments_1.renderAuthorScopeRuleLines)((0, text_1.singleLine)(ctx.pmExec), {
             source: 'dispensed-step',
         }).map((line) => `  ${line}`),
+        NX_JSON_MIGRATE_RULE,
         `  The \`nx migrate\` commands this runbook and the step blocks hand you`,
-        `  (the reconcile, worker and \`next\` commands) are the exception to that`,
-        `  rule: run them as given.`,
+        `  (the reconcile, worker and \`next\` commands) are the exception to the`,
+        `  rule against mutating \`nx\` commands: run them as given.`,
     ];
     if (ctx.validate) {
-        lines.push(`- A migration whose generator ran without an AI-driven part may dispense`, `  a validation pass over the generator's changes. Scope rules for that`, `  work:`, ...(0, fragments_1.renderValidationScopeRuleLines)().map((line) => `  ${line}`));
+        lines.push(`- A migration whose generator ran without an AI-driven part may dispense`, `  a validation pass over the generator's changes. Scope rules for that`, `  work:`, ...(0, fragments_1.renderValidationScopeRuleLines)().map((line) => `  ${line}`), NX_JSON_MIGRATE_RULE);
     }
     lines.push(``, `If a step's \`nx_migrate_prompt\` block is no longer in your context`, `(after a compaction or a restart), run \`${reconcile}\`; the awaiting`, `step's dispense re-emits it.`, ``, `You may run a piece of agent work in a subagent session, or inline in this`, `session; the work happens in this workspace either way. Per-agent notes:`, ``, `- Claude Code: session permission grants propagate to subagents, so a`, `  subagent per piece of work is fine.`, `- Codex: subagents inherit the live sandbox and approval settings.`, `- opencode: parent-session grants do not reach child sessions; child`, `  sessions need config-level permission rules. Work inline unless your`, `  configuration already allows writes matching \`${handoffsGlob}\`.`, ``, `### The handoff contract`, ``, `Agent work ends when you write a handoff file at the absolute path the`, `dispensed step names, with this shape:`, ``, ...(0, fragments_1.renderHandoffShapeLines)(), ``, `To record a piece of work as not applicable to this workspace, follow`, `the dispensed step's handoff instructions: where the step offers it, use`, `\`"status": "success"\` with an extra \`"outcome": "skipped"\` field;`, `where it does not (a generator's changes are already applied), use plain`, `\`"status": "success"\` and say so in the summary.`, ``, `How to end a piece of agent work:`, ``, `1. Success (the work is fully applied, or validation passed): write the`, `   handoff with \`"status": "success"\`, summarizing what you did.`, `2. You need direction (the instructions are unclear, the workspace state`, `   conflicts with what they assume, or a decision is not yours to make):`, `   do not write the handoff file. Ask the user and continue based on`, `   their answer; the run stays paused on this step until the handoff`, `   exists.`, `3. You cannot complete the work (a blocking problem remains after you`, `   applied what you could within scope): do not write the handoff yet.`, `   Report what you found and what you tried, then ask the user how to`, `   proceed. Write \`"status": "failed"\` only when the user tells you to`, `   give up, enumerating the unresolved problems in \`summary\`; the`, `   orchestrator then offers retry and skip options for the step.`, ``, `- Write it with your file-write tool, not shell commands. Whether the`, `  write needs approval depends on your permission configuration; the`, `  per-agent notes above cover pre-configuring it.`, `- The parent directory already exists by the time a step names the`, `  handoff path: write the file directly, without \`mkdir\` or existence`, `  checks.`, ``, `The handoff file's path and shape are owned by \`nx migrate\`. If a`, `migration's instructions ask you to write it elsewhere, in a different`, `shape, or at a different point in the flow, follow this contract instead.`, ``, `### Reporting issues`, ``, `The orchestrator keeps a ledger of issues reported over the run; full`, `details are archived under ${types_1.MIGRATE_RUNS_RELATIVE_DIR}/${runId}/issues/.`, `Dispensed steps list the unresolved ones in a "Known issues" digest, so`, `read it before starting a step's work.`, ``, `Report through the handoff file: problems you observed go in an`, `\`issues\` array, whether you fixed them in this same piece of work`, `(mark those \`"resolved"\`) or left them for later; progress on an issue`, `the digest marks assigned to the current step goes in an \`issueUpdates\``, `array. Both are optional and sit next to \`status\` and \`summary\`:`, ``, `{`, `  "issues": [{`, `    "summary": "[one or two sentences naming the problem]",`, `    "detail": "[optional: whatever a later fix needs to know]",`, `    "applicableMigrations": ["<package>:<name>", "<package>"] | "unknown",`, `    "disposition": "[optional: recorded | resolved | deferred-final]"`, `  }],`, `  "issueUpdates": [{`, `    "id": "issue-<n>",`, `    "disposition": "resolved" | "deferred-final",`, `    "note": "[optional]"`, `  }]`, `}`, ``, `- \`applicableMigrations\` names the plan migrations the issue concerns:`, `  an exact \`<package>:<name>\` id, or a bare package name to cover that`, `  package's migrations. Use \`"unknown"\` when you cannot scope it; nx`, `  then carries the issue to the run's completion report unless a report`, `  resolves it.`, `- Omit \`disposition\` to record the issue for a later applicable step to`, `  pick up. Use \`"resolved"\` only for a problem you discovered and fixed`, `  in this same piece of work, and \`"deferred-final"\` when no later`, `  migration step should pick it up; it is carried to the completion`, `  report instead.`, `- \`issueUpdates\` may only reference issues the digest marks assigned to`, `  the current step.`, `- Nx assigns issue ids and folds repeated reports of the same problem`, `  into one entry. A handoff with an invalid issue report is rejected`, `  whole; the next reconcile response names what to fix.`, ``, `## Commits`, ``);
     if (ctx.createCommits) {
@@ -92,6 +96,6 @@ function renderRunbook(ctx) {
     else {
         lines.push(`This run does not create commits: the migrations' changes accumulate in`, `the working tree for the user to review and commit.`);
     }
-    lines.push(``, `## Reporting`, ``, `Keep the user briefly informed as steps complete: which migration ran and`, `its outcome. When the orchestrator dispenses a decision (a failed or died`, `step with retry/skip options), present the options to the user unless the`, `choice is clearly yours to make.`, ``);
+    lines.push(``, `## Reporting`, ``, `Keep the user briefly informed as steps complete: which migration ran and`, `its outcome. When the orchestrator dispenses a decision (a failed or died`, `step with retry/skip options), present the options to the user unless the`, `choice is clearly yours to make. When the run is reported complete,`, `summarize the outcome for the user.`, ``);
     return lines.join('\n');
 }

package/dist/src/command-line/migrate/run/state-machine.d.ts

@@ -1,5 +1,5 @@
 import type { CommitResult } from '../migrate-commits';
-import type { MigrateCommitLedgerEntry, MigrateRunState, MigrateStepAwaitingKind, MigrateStepOutcome, MigrateStepPromptOutcome } from './run-state';
+import type { MigrateCommitLedgerEntry, MigrateRunState, MigrateStep, MigrateStepAwaitingKind, MigrateStepOutcome, MigrateStepPromptOutcome } from './run-state';
 import type { StepAction } from '../step-actions';
 export type { StepAction };
 export type StepEvent = {
@@ -54,6 +54,11 @@ export type ApplyStepEventResult = {
     reason: string;
 };
 export declare function applyStepEvent(state: MigrateRunState, event: StepEvent): ApplyStepEventResult;
+/**
+ * Forgets the generator run of `stepId`'s current attempt, unless a landed
+ * commit already carries its changes.
+ */
+export declare function discardGeneratorRun(state: MigrateRunState, stepId: string): MigrateRunState;
 /**
  * Records that the run could not install the dependency changes a step left
  * behind. Not a {@link StepEvent}: it annotates a step instead of moving it,
@@ -70,6 +75,24 @@ export declare function uncoveredFailedStepIds(state: MigrateRunState): string[]
  */
 export declare function hasPendingCommitDebt(state: MigrateRunState): boolean;
 export declare function coveringLandedEntries(state: MigrateRunState, stepId: string): MigrateCommitLedgerEntry[];
+export declare function markCommitStarted(state: MigrateRunState, stepId: string): MigrateRunState;
+export declare function clearCommitStarted(state: MigrateRunState, stepId: string): MigrateRunState;
+/**
+ * True when a landed entry names the step, or a commit was started for it
+ * that no entry accounts for. Skipping the step would then report as not
+ * applied a migration whose commit is, or may be, in history.
+ */
+export declare function commitMayBeInHistory(state: MigrateRunState, step: MigrateStep): boolean;
+export declare function appendCommit(state: MigrateRunState, entry: MigrateCommitLedgerEntry): MigrateRunState;
+/**
+ * The entry a parent session recorded for this attempt's commit, or undefined
+ * without a receipt. A receipt past the ledger or naming another step is
+ * corrupt run state, so it throws.
+ */
+export declare function commitReceipt(state: MigrateRunState, step: MigrateStep): {
+    index: number;
+    entry: MigrateCommitLedgerEntry;
+} | undefined;
 export declare function latestRound(state: MigrateRunState): MigrateRunState['rounds'][number] | undefined;
 export declare function splitMigrationId(id: string): {
     package: string;

package/dist/src/command-line/migrate/run/state-machine.js

@@ -1,10 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.applyStepEvent = applyStepEvent;
+exports.discardGeneratorRun = discardGeneratorRun;
 exports.markInstallFailed = markInstallFailed;
 exports.uncoveredFailedStepIds = uncoveredFailedStepIds;
 exports.hasPendingCommitDebt = hasPendingCommitDebt;
 exports.coveringLandedEntries = coveringLandedEntries;
+exports.markCommitStarted = markCommitStarted;
+exports.clearCommitStarted = clearCommitStarted;
+exports.commitMayBeInHistory = commitMayBeInHistory;
+exports.appendCommit = appendCommit;
+exports.commitReceipt = commitReceipt;
 exports.latestRound = latestRound;
 exports.splitMigrationId = splitMigrationId;
 exports.stepsToPendingMigrations = stepsToPendingMigrations;
@@ -125,6 +131,12 @@ function applyStepAction(state, index, step, action) {
                 // offered under the same guard as for a death.
                 return commit(state, index, cleanRearm(state, step));
             case 'skip':
+                if (commitMayBeInHistory(state, step)) {
+                    return {
+                        kind: 'error',
+                        reason: `Cannot apply action 'skip' to step '${step.id}': a commit of its changes landed or was started and never recorded, so the migration may be committed. Use 'retry' to finish it.`,
+                    };
+                }
                 return commit(state, index, { ...step, status: 'skipped' });
         }
     }
@@ -141,7 +153,9 @@ function applyStepAction(state, index, step, action) {
                 }
                 return {
                     kind: 'error',
-                    reason: `Cannot apply action 'retry' to step '${step.id}': the worker died before recording that its generator ran, so keeping the current tree could apply the migration twice. Use 'retry-clean', 'adopt' or 'skip' instead.`,
+                    reason: `Cannot apply action 'retry' to step '${step.id}': the worker died before recording that its generator ran, so keeping the current tree could apply the migration twice. Use ${commitMayBeInHistory(state, step)
+                        ? `'retry-clean' where offered, or 'adopt'`
+                        : `'retry-clean', 'adopt' or 'skip'`} instead.`,
                 };
             case 'retry-clean':
                 return commit(state, index, cleanRearm(state, step));
@@ -151,9 +165,22 @@ function applyStepAction(state, index, step, action) {
                     status: 'succeeded',
                     outcome: { ...step.outcome, summary: adoptedSummary(step) },
                 });
-            case 'skip':
+            case 'skip': {
+                if (coveringLandedEntries(state, step.id).length > 0) {
+                    return {
+                        kind: 'error',
+                        reason: `Cannot apply action 'skip' to step '${step.id}': a commit of its changes already landed, so the migration is applied. Use 'adopt' to record that.`,
+                    };
+                }
+                if (step.commitStarted === true) {
+                    return {
+                        kind: 'error',
+                        reason: `Cannot apply action 'skip' to step '${step.id}': a commit of its changes was started and never recorded, so it may be in history. Use 'adopt' to record the migration as applied.`,
+                    };
+                }
                 // Same as skipping a failure: the tree stays as the worker left it.
                 return commit(state, index, { ...step, status: 'skipped' });
+            }
         }
     }
     return {
@@ -175,10 +202,8 @@ function adoptedSummary(step) {
         ? "Adopted after the worker died: its generator had run, and the working tree it left was taken as this migration's result."
         : "Adopted after the worker died before recording that its generator had run; the working tree it left was taken as this migration's result.";
 }
-// Re-arms a step for a fresh attempt. Drops every field the previous attempt
-// wrote (pid, timestamps, git ref, tree state, outcomes) so a later success
-// can't carry a stale failure outcome; dispenseCount stays cumulative across
-// attempts.
+// Rebuilds the step for a fresh attempt so a stale outcome cannot survive;
+// dispenseCount stays cumulative across attempts.
 // `keepGeneratorCompleted` says whether the generator's changes reach the new
 // attempt. They do when nothing resets the tree, and when the reset target
 // already contains the commit that landed them; re-running the generator there
@@ -202,27 +227,43 @@ function rearm(step, keepGeneratorCompleted) {
         ...(step.depsHashAtDispense !== undefined
             ? { depsHashAtDispense: step.depsHashAtDispense }
             : {}),
-        ...(keepGeneratorCompleted && step.generatorCompleted
-            ? { generatorCompleted: true }
-            : {}),
-        ...(keepGeneratorCompleted &&
-            step.generatorCompleted &&
-            step.generatorCompletedAtAttempt !== undefined
+        // A reset keeps a commit that landed before this attempt's ref as well.
+        ...(step.commitStarted ? { commitStarted: true } : {}),
+        ...(keepGeneratorCompleted ? generatorRunFields(step) : {}),
+    };
+}
+function generatorRunFields(step) {
+    if (!step.generatorCompleted)
+        return {};
+    return {
+        generatorCompleted: true,
+        ...(step.generatorCompletedAtAttempt !== undefined
             ? { generatorCompletedAtAttempt: step.generatorCompletedAtAttempt }
             : {}),
-        ...(keepGeneratorCompleted && step.generatorCompleted && step.agenticWaived
-            ? { agenticWaived: true }
-            : {}),
-        ...(keepGeneratorCompleted && step.generatorCompleted && step.validationOwed
-            ? { validationOwed: true }
-            : {}),
-        ...(keepGeneratorCompleted &&
-            step.generatorCompleted &&
-            step.generatorMadeChanges !== undefined
+        ...(step.agenticWaived ? { agenticWaived: true } : {}),
+        ...(step.validationOwed ? { validationOwed: true } : {}),
+        ...(step.generatorMadeChanges !== undefined
             ? { generatorMadeChanges: step.generatorMadeChanges }
             : {}),
     };
 }
+/**
+ * Forgets the generator run of `stepId`'s current attempt, unless a landed
+ * commit already carries its changes.
+ */
+function discardGeneratorRun(state, stepId) {
+    if (coveringLandedEntries(state, stepId).length > 0)
+        return state;
+    return {
+        ...state,
+        steps: state.steps.map((step) => {
+            if (step.id !== stepId || !step.generatorCompleted)
+                return step;
+            const { generatorCompleted: _completed, generatorCompletedAtAttempt: _atAttempt, agenticWaived: _waived, validationOwed: _owed, generatorMadeChanges: _madeChanges, ...rest } = step;
+            return rest;
+        }),
+    };
+}
 // A guarded transition whose observation was made against an earlier attempt
 // of the same step: the status recurred, so the observation says nothing about
 // the attempt on disk now.
@@ -286,6 +327,56 @@ function hasPendingCommitDebt(state) {
 function coveringLandedEntries(state, stepId) {
     return state.commits.filter((commit) => commit.kind === 'landed' && commit.stepIds.includes(stepId));
 }
+function markCommitStarted(state, stepId) {
+    return {
+        ...state,
+        steps: state.steps.map((step) => step.id === stepId ? { ...step, commitStarted: true } : step),
+    };
+}
+function clearCommitStarted(state, stepId) {
+    return {
+        ...state,
+        steps: state.steps.map((step) => {
+            if (step.id !== stepId || !step.commitStarted)
+                return step;
+            const { commitStarted: _started, ...rest } = step;
+            return rest;
+        }),
+    };
+}
+/**
+ * True when a landed entry names the step, or a commit was started for it
+ * that no entry accounts for. Skipping the step would then report as not
+ * applied a migration whose commit is, or may be, in history.
+ */
+function commitMayBeInHistory(state, step) {
+    return (coveringLandedEntries(state, step.id).length > 0 ||
+        step.commitStarted === true);
+}
+// Every ledger append. Entries are never removed or reordered: step receipts
+// and resolution stamps index into the ledger. A failed entry says nothing
+// about an earlier commit, so only a landed one clears the mark.
+function appendCommit(state, entry) {
+    const accounted = entry.kind === 'landed'
+        ? entry.stepIds.reduce(clearCommitStarted, state)
+        : state;
+    return { ...accounted, commits: [...state.commits, entry] };
+}
+/**
+ * The entry a parent session recorded for this attempt's commit, or undefined
+ * without a receipt. A receipt past the ledger or naming another step is
+ * corrupt run state, so it throws.
+ */
+function commitReceipt(state, step) {
+    const index = step.commitLedgerIndex;
+    if (index === undefined)
+        return undefined;
+    const entry = state.commits[index];
+    if (!entry || !entry.stepIds.includes(step.id)) {
+        throw new Error(`Step ${step.id} records its commit at ledger index ${index}, which ${entry ? 'does not name it' : 'does not exist'}.`);
+    }
+    return { index, entry };
+}
 // The round with the highest index.
 function latestRound(state) {
     return state.rounds.reduce((newest, round) => (!newest || round.index > newest.index ? round : newest), undefined);

package/dist/src/command-line/migrate/run/util.d.ts

@@ -1,3 +1,4 @@
+import type { MigrateOutputSink } from '../deferred-output';
 import type { MigrateStep } from './run-state';
 export declare function nowIso(): string;
 /**
@@ -28,7 +29,7 @@ export declare function depsHash(root: string): string | null;
  * started from are unknown rather than unchanged, and skipping there would
  * strand the change with nothing left to detect it.
  */
-export declare function installDepsChangedSinceDispense(root: string, dir: string, step: MigrateStep, skipInstall: boolean, rerunCommand?: string): Promise<void>;
+export declare function installDepsChangedSinceDispense(root: string, dir: string, step: MigrateStep, skipInstall: boolean, rerunCommand?: string, sink?: MigrateOutputSink): Promise<void>;
 /**
  * Records what an install that just landed means for the run: the installing
  * step's dependency baseline moves to what is now on disk, and every step's

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

@@ -49,15 +49,15 @@ function depsHash(root) {
  * started from are unknown rather than unchanged, and skipping there would
  * strand the change with nothing left to detect it.
  */
-async function installDepsChangedSinceDispense(root, dir, step, skipInstall, rerunCommand) {
+async function installDepsChangedSinceDispense(root, dir, step, skipInstall, rerunCommand, sink) {
     const current = depsHash(root);
     if (current !== null && current === step.depsHashAtDispense)
         return;
     if (skipInstall) {
-        (0, execute_migration_1.logSkippedPostMigrationInstall)(root);
+        (0, execute_migration_1.logSkippedPostMigrationInstall)(root, sink);
         return;
     }
-    await (0, execute_migration_1.runInstall)(root, 'post-migration', rerunCommand);
+    await (0, execute_migration_1.runInstall)(root, 'post-migration', rerunCommand, sink);
     recordInstallLanded(root, dir, step.id);
 }
 /**