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

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

@@ -0,0 +1,507 @@
+"use strict";
+// A master session's agent runs the dispensed `nx migrate` commands inside
+// its own sandbox, where a dependency install has no network and a commit
+// cannot write `.git`. The parent nx that spawned the session advertises
+// itself through NX_MIGRATE_BROKER, and a step then hands its install, and
+// its commit when one is due, over a request/result file pair under
+// <runDir>/broker/ instead of running them itself. Nothing here authorizes:
+// every file the parent could consult is writable from the sandbox, so the
+// parent's own invocation decides what it installs and commits.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MigrateCommitBroker = exports.TreeBusyError = exports.BrokerUnavailableError = exports.BrokerStaleRequestError = exports.BROKER_ENV_VAR = void 0;
+exports.acquireTreeOperation = acquireTreeOperation;
+exports.releaseTreeOperation = releaseTreeOperation;
+exports.liveTreeOperation = liveTreeOperation;
+exports.treeBusyMessage = treeBusyMessage;
+exports.treeOperationLabel = treeOperationLabel;
+exports.brokerDir = brokerDir;
+exports.commitStepTree = commitStepTree;
+exports.installStepTree = installStepTree;
+exports.resetStepTree = resetStepTree;
+const crypto_1 = require("crypto");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const native_1 = require("../../../native");
+const fileutils_1 = require("../../../utils/fileutils");
+const json_1 = require("../../../utils/json");
+const handoff_1 = require("../agentic/handoff");
+const deferred_output_1 = require("../deferred-output");
+const execute_migration_1 = require("../execute-migration");
+const migrate_commits_1 = require("../migrate-commits");
+const atomic_write_1 = require("./atomic-write");
+const run_state_1 = require("./run-state");
+const state_lock_1 = require("./state-lock");
+const state_machine_1 = require("./state-machine");
+const issues_1 = require("./issues");
+const clean_retry_1 = require("./clean-retry");
+const util_1 = require("./util");
+exports.BROKER_ENV_VAR = 'NX_MIGRATE_BROKER';
+const BROKER_DIR_NAME = 'broker';
+const CHILD_POLL_INTERVAL_MS = 250;
+/** The request no longer matches the step: another attempt owns it. */
+class BrokerStaleRequestError extends Error {
+}
+exports.BrokerStaleRequestError = BrokerStaleRequestError;
+/**
+ * The advertised parent could not accept the request, or went away before
+ * answering it. It may have landed the install or the commit; the tree and
+ * the run state say.
+ */
+class BrokerUnavailableError extends Error {
+}
+exports.BrokerUnavailableError = BrokerUnavailableError;
+/** Another live process holds the working tree for an operation of its own. */
+class TreeBusyError extends Error {
+}
+exports.TreeBusyError = TreeBusyError;
+/**
+ * Reserves the working tree for one operation in a single fresh-state write:
+ * the request must still be at its seam (else the attempt moved on and the
+ * request is stale), and no other live process may hold a reservation.
+ * A reservation whose owner process is gone holds nothing.
+ */
+function acquireTreeOperation(dir, request, owner = (0, crypto_1.randomBytes)(4).toString('hex')) {
+    // A commit marks its step as started; a mark already there belongs to an
+    // operation whose outcome is still unknown, and this one leaves it.
+    let marks = false;
+    (0, state_lock_1.updateRunState)(dir, (fresh) => {
+        if (!atSeam(fresh, request)) {
+            throw new BrokerStaleRequestError(`The request for this step no longer matches its attempt; nothing was installed or committed.`);
+        }
+        const held = liveTreeOperation(fresh, owner);
+        if (held)
+            throw new TreeBusyError(treeBusyMessage(held));
+        marks =
+            request.kind === 'commit' &&
+                fresh.steps.find((s) => s.id === request.stepId)?.commitStarted !== true;
+        return {
+            ...(marks ? (0, state_machine_1.markCommitStarted)(fresh, request.stepId) : fresh),
+            treeOperation: {
+                kind: request.kind,
+                ...(request.stepId !== undefined ? { stepId: request.stepId } : {}),
+                ...(request.attempt !== undefined ? { attempt: request.attempt } : {}),
+                owner,
+                pid: process.pid,
+            },
+        };
+    });
+    const lease = {
+        owner,
+        ...(marks ? { markedStepId: request.stepId } : {}),
+        release: () => releaseTreeOperation(dir, owner, lease.markedStepId),
+    };
+    return lease;
+}
+/**
+ * Owner-checked: a lease released late never drops a newer reservation, nor
+ * the mark it set.
+ */
+function releaseTreeOperation(dir, owner, markedStepId) {
+    (0, state_lock_1.updateRunState)(dir, (fresh) => {
+        if (fresh.treeOperation?.owner !== owner)
+            return null;
+        const released = { ...fresh, treeOperation: undefined };
+        return markedStepId ? (0, state_machine_1.clearCommitStarted)(released, markedStepId) : released;
+    });
+}
+/** The reservation a live process other than `owner` holds, if any. */
+function liveTreeOperation(state, owner) {
+    const held = state.treeOperation;
+    if (!held || held.owner === owner || !(0, util_1.isPidAlive)(held.pid))
+        return undefined;
+    return held;
+}
+function treeBusyMessage(held) {
+    return `The working tree is held by process ${held.pid} for ${treeOperationLabel(held)}; run the reconcile again once it finishes.`;
+}
+function treeOperationLabel(held) {
+    return held.kind === 'checkpoint'
+        ? 'the checkpoint commit'
+        : `the ${held.kind === 'commit' || held.kind === 'reset' ? held.kind : 'install'} of step '${held.stepId}'`;
+}
+function atSeam(state, request) {
+    if (request.kind === 'checkpoint') {
+        return (state.createCommits &&
+            state.checkpointFailed === true &&
+            state.steps.every((s) => s.status === 'pending'));
+    }
+    return (Object.hasOwn(SEAM_STATUSES, request.kind) &&
+        request.stepId !== undefined &&
+        request.attempt !== undefined &&
+        isAtSeam(state.steps.find((s) => s.id === request.stepId), request));
+}
+const SEAM_STATUSES = {
+    commit: new Set(['running', 'awaiting-prompt-outcome', 'died']),
+    install: new Set(['running']),
+    'fold-install': new Set(['awaiting-prompt-outcome']),
+    'action-install': new Set(['failed', 'died']),
+    reset: new Set(['failed', 'died']),
+};
+function isAtSeam(step, request) {
+    return (step !== undefined &&
+        step.attempt === request.attempt &&
+        SEAM_STATUSES[request.kind].has(step.status));
+}
+function brokerDir(runDirPath) {
+    return (0, path_1.join)(runDirPath, BROKER_DIR_NAME);
+}
+function lockPath(runDirPath, nonce) {
+    return (0, path_1.join)(brokerDir(runDirPath), `${nonce}.lock`);
+}
+function requestPath(runDirPath, id) {
+    return (0, path_1.join)(brokerDir(runDirPath), `${id}.request.json`);
+}
+function resultPath(runDirPath, id) {
+    return (0, path_1.join)(brokerDir(runDirPath), `${id}.result.json`);
+}
+// A request file lives in the agent-writable broker directory, so it could be
+// a planted symlink or FIFO; read it without reading a symlink's target or
+// blocking on a FIFO.
+function readRequestFile(filePath) {
+    return (0, json_1.parseJson)((0, handoff_1.readAtomicallyPublishedFile)(filePath, `${filePath} is not a regular file.`));
+}
+/**
+ * Runs the step's install and commit where they can land: in this process
+ * unless a parent session advertised its broker, in which case the request
+ * goes to the parent and the answer comes back with the output the parent
+ * collected, printed here. The absorbed step ids come from whichever side
+ * ran the commit, so the ledger entry names what its `git add -A` took.
+ */
+async function commitStepTree(dir, step, absorbedStepIds, commitInProcess, scope) {
+    const request = {
+        kind: 'commit',
+        stepId: step.id,
+        attempt: step.attempt,
+    };
+    const nonce = process.env[exports.BROKER_ENV_VAR];
+    if (!nonce) {
+        const lease = acquireTreeOperation(dir, request);
+        scope.lease = lease;
+        const result = await commitInProcess();
+        if (gitRan(result))
+            lease.markedStepId = undefined;
+        return { result, absorbedStepIds, recorded: false };
+    }
+    const answer = await ask(dir, nonce, request);
+    if (answer.kind !== 'commit') {
+        throw new Error(`Unexpected '${answer.kind}' answer to a commit request.`);
+    }
+    return {
+        result: answer.result,
+        absorbedStepIds: answer.absorbedStepIds,
+        recorded: true,
+    };
+}
+// Whether git may have written history for this result. A landed commit's
+// mark is the ledger entry's to clear, and a failure reported once git ran
+// (a hook's output overflowing the subprocess buffer after the commit) cannot
+// vouch that nothing landed, so only the other results release the mark.
+function gitRan(result) {
+    switch (result.status) {
+        case 'committed':
+        case 'failed':
+            return true;
+        case 'no-changes':
+        case 'disabled':
+            return false;
+        default: {
+            const exhaustive = result;
+            throw new Error(`Unhandled commit result: ${JSON.stringify(exhaustive)}`);
+        }
+    }
+}
+/**
+ * The same for a step that owes only its install: no commit is due, or the
+ * commit waits for a fold.
+ */
+async function installStepTree(dir, step, seam, installInProcess, scope) {
+    const request = {
+        kind: seam,
+        stepId: step.id,
+        attempt: step.attempt,
+    };
+    const nonce = process.env[exports.BROKER_ENV_VAR];
+    if (!nonce) {
+        scope.lease = acquireTreeOperation(dir, request);
+        return installInProcess();
+    }
+    const answer = await ask(dir, nonce, request);
+    if (answer.kind !== 'installed') {
+        throw new Error(`Unexpected '${answer.kind}' answer to an install request.`);
+    }
+}
+/**
+ * The same for the reset a clean retry of a failed or died step needs. Runs
+ * `resetInProcess` under the reservation, or asks the parent, which resets
+ * against the state it reads then; a reset that could not run throws.
+ */
+async function resetStepTree(dir, step, resetInProcess, scope) {
+    const request = {
+        kind: 'reset',
+        stepId: step.id,
+        attempt: step.attempt,
+        invocation: (0, crypto_1.randomBytes)(4).toString('hex'),
+    };
+    const nonce = process.env[exports.BROKER_ENV_VAR];
+    if (!nonce) {
+        scope.lease = acquireTreeOperation(dir, request);
+        return resetInProcess();
+    }
+    const answer = await ask(dir, nonce, request);
+    if (answer.kind !== 'reset') {
+        throw new Error(`Unexpected '${answer.kind}' answer to a reset request.`);
+    }
+}
+async function ask(dir, nonce, request) {
+    const id = `${nonce}-${request.stepId}-${request.attempt}-${request.kind}${request.invocation ? `-${request.invocation}` : ''}`;
+    const path = resultPath(dir, id);
+    // A repeat reads the first answer, whatever became of the session since.
+    if ((0, fs_1.existsSync)(path)) {
+        return settle((0, fileutils_1.readJsonFile)(path));
+    }
+    // No deadline: an install or a commit over a large tree takes as long as it
+    // takes; the poll ends with an answer or a released lock. The probe is built
+    // first so a request is never left unwatched, and once: each instance holds
+    // a descriptor, and `wait()` would pin this process until the session ends.
+    let lock = null;
+    try {
+        lock = native_1.IS_WASM ? null : new native_1.FileLock(lockPath(dir, nonce));
+    }
+    catch (e) {
+        if ((0, fs_1.existsSync)(path)) {
+            return settle((0, fileutils_1.readJsonFile)(path));
+        }
+        throw notAccepting(e);
+    }
+    try {
+        (0, atomic_write_1.publishFileAtomically)(requestPath(dir, id), (tmpPath) => (0, fileutils_1.writeJsonFile)(tmpPath, request));
+    }
+    catch (e) {
+        throw notAccepting(e);
+    }
+    for (;;) {
+        if ((0, fs_1.existsSync)(path)) {
+            return settle((0, fileutils_1.readJsonFile)(path));
+        }
+        if (lock && lockIsFree(lock)) {
+            // Answered and closed between the two checks: the answer stays on disk.
+            if ((0, fs_1.existsSync)(path))
+                continue;
+            throw new BrokerUnavailableError(`The nx migrate session that started this step ended before its request was answered. The install or the commit may still have landed; check the working tree and git log.`);
+        }
+        await new Promise((resolve) => setTimeout(resolve, CHILD_POLL_INTERVAL_MS));
+    }
+}
+function notAccepting(e) {
+    return new BrokerUnavailableError(`The nx migrate session that started this step is not accepting its request (${e instanceof Error ? e.message : String(e)}).`);
+}
+// A probe that fails says nothing about the parent; keep waiting.
+function lockIsFree(lock) {
+    try {
+        return !lock.check();
+    }
+    catch {
+        return false;
+    }
+}
+function settle(result) {
+    switch (result.kind) {
+        case 'commit':
+        case 'installed':
+            (0, deferred_output_1.replayDeferredOutput)(result.output);
+            return result;
+        case 'install-failed':
+            (0, deferred_output_1.replayDeferredOutput)(result.output);
+            // The CLI catch returns 1 on the typed error instead of logging again.
+            throw result.peerDeps
+                ? new execute_migration_1.NpmPeerDepsInstallError()
+                : new Error(result.message);
+        case 'reset':
+            if (result.error !== undefined)
+                throw new Error(result.error);
+            return result;
+        case 'stale':
+            throw new BrokerStaleRequestError(`The request for this step no longer matches its attempt; nothing was installed or committed.`);
+        default: {
+            const exhaustive = result;
+            throw new Error(`Unhandled broker result: ${JSON.stringify(exhaustive)}`);
+        }
+    }
+}
+/**
+ * The parent side. Holds one exclusive lock for the session's lifetime so a
+ * waiting step can tell a slow parent from a dead one, answers each request
+ * once, and removes its own requests on close; its answers stay for the steps
+ * still reading them. Requests carrying another session's nonce belong to
+ * that session and are never touched. Whether to install or commit comes from
+ * the policy the session started with, never from run state, which the
+ * agent's sandbox can write.
+ */
+class MigrateCommitBroker {
+    constructor(root, dir, reconcileCommand, policy) {
+        this.root = root;
+        this.dir = dir;
+        this.reconcileCommand = reconcileCommand;
+        this.policy = policy;
+        this.nonce = (0, crypto_1.randomBytes)(4).toString('hex');
+        this.handled = new Set();
+        this.inFlight = null;
+        (0, handoff_1.ensureRunSubdir)(brokerDir(dir), () => this.notADirectory());
+        this.lock = native_1.IS_WASM ? null : new native_1.FileLock(lockPath(dir, this.nonce));
+        this.lock?.lock();
+    }
+    /** The request whose operation this process is running right now. */
+    get requestInFlight() {
+        return this.inFlight;
+    }
+    /** Answers this session's unanswered requests, one at a time. */
+    async service() {
+        // Refused rather than followed: a symlink swapped in would send the reads
+        // and the answers wherever it points, or leave requests unanswered.
+        if ((0, handoff_1.handoffsDirState)(brokerDir(this.dir)) !== 'directory') {
+            throw this.notADirectory();
+        }
+        const prefix = `${this.nonce}-`;
+        const suffix = '.request.json';
+        for (const name of (0, fs_1.readdirSync)(brokerDir(this.dir))) {
+            if (!name.startsWith(prefix) || !name.endsWith(suffix))
+                continue;
+            const id = name.slice(0, -suffix.length);
+            if (this.handled.has(id))
+                continue;
+            const request = readRequestFile(requestPath(this.dir, id));
+            // Reserved before anything runs, released after the record is written.
+            // A tree held by another live process is left for a later pass, not
+            // marked handled; a request no longer at its seam is answered stale.
+            let lease = null;
+            try {
+                lease = acquireTreeOperation(this.dir, request, this.nonce);
+            }
+            catch (e) {
+                if (e instanceof TreeBusyError)
+                    continue;
+                if (!(e instanceof BrokerStaleRequestError))
+                    throw e;
+            }
+            this.handled.add(id);
+            let result;
+            try {
+                if (lease)
+                    this.inFlight = request;
+                result = lease ? await this.answer(request) : { kind: 'stale' };
+                // Recorded by the process that ran the commit, before the answer: the
+                // step reading it can die with the commit already in history. A failed
+                // record throws and ends the session rather than losing the entry.
+                if (result.kind === 'commit') {
+                    if (gitRan(result.result))
+                        lease.markedStepId = undefined;
+                    this.record(request, result);
+                }
+            }
+            finally {
+                this.inFlight = null;
+                lease?.release();
+            }
+            // Published after the release, so the step reading the answer never
+            // finds this request's reservation still standing over its own write.
+            (0, atomic_write_1.publishFileAtomically)(resultPath(this.dir, id), (tmpPath) => (0, fileutils_1.writeJsonFile)(tmpPath, result));
+        }
+    }
+    // Appends the entry and leaves the step a receipt for it, on the attempt the
+    // request named: a rearmed step owes nothing to the old attempt's commit.
+    record(request, result) {
+        const entry = (0, state_machine_1.commitResultToLedgerEntry)(result.result, request.stepId, result.absorbedStepIds);
+        if (!entry)
+            return;
+        (0, state_lock_1.updateRunState)(this.dir, (fresh) => {
+            const index = fresh.commits.length;
+            const next = (0, state_machine_1.appendCommit)(fresh, (0, issues_1.attachIssueIdsToCommitEntry)(fresh, entry));
+            return {
+                ...next,
+                steps: next.steps.map((s) => s.id === request.stepId && s.attempt === request.attempt
+                    ? { ...s, commitLedgerIndex: index }
+                    : s),
+            };
+        });
+    }
+    async answer(request) {
+        const state = (0, run_state_1.readRunState)(this.dir);
+        const step = state.steps.find((s) => s.id === request.stepId);
+        if (!Object.hasOwn(SEAM_STATUSES, request.kind) ||
+            !isAtSeam(step, request) ||
+            ((request.kind === 'commit' || request.kind === 'reset') &&
+                !this.policy.createCommits)) {
+            return { kind: 'stale' };
+        }
+        if (request.kind === 'reset') {
+            try {
+                (0, clean_retry_1.resetForCleanRetry)(this.root, this.dir, step.id);
+                return { kind: 'reset' };
+            }
+            catch (e) {
+                return {
+                    kind: 'reset',
+                    error: e instanceof Error ? e.message : String(e),
+                };
+            }
+        }
+        const output = new deferred_output_1.DeferredOutputCollector();
+        const install = () => (0, util_1.installDepsChangedSinceDispense)(this.root, this.dir, step, this.policy.skipInstall, this.reconcileCommand, output);
+        try {
+            if (request.kind !== 'commit') {
+                await install();
+                return { kind: 'installed', output: output.render('drop') };
+            }
+            const absorbedStepIds = (0, state_machine_1.uncoveredFailedStepIds)(state).filter((id) => id !== step.id);
+            const result = await (0, migrate_commits_1.commitMigrationIfRequested)(this.root, { name: (0, state_machine_1.splitMigrationId)(step.migrationId).name }, true, state.commitPrefix, install, (0, state_machine_1.stepsToPendingMigrations)(state, absorbedStepIds), undefined, output);
+            return {
+                kind: 'commit',
+                result,
+                absorbedStepIds,
+                output: output.render('drop'),
+            };
+        }
+        catch (e) {
+            // The install is the only thing that throws: the commit reports through
+            // its result, and the install's own bookkeeping never throws. Marked
+            // here, where the install ran, on the attempt it ran for: a reconcile
+            // may have rearmed the step meanwhile, and that attempt owes nothing.
+            (0, state_lock_1.updateRunState)(this.dir, (fresh) => isAtSeam(fresh.steps.find((s) => s.id === step.id), request)
+                ? (0, state_machine_1.markInstallFailed)(fresh, step.id)
+                : null);
+            return {
+                kind: 'install-failed',
+                message: e instanceof Error ? e.message : String(e),
+                peerDeps: e instanceof execute_migration_1.NpmPeerDepsInstallError,
+                // The package manager's own output: for pnpm, Yarn and Bun the error
+                // says only that the command failed.
+                output: output.render('keep'),
+            };
+        }
+    }
+    /** Releases the lock; call after the last `service` settled. */
+    close() {
+        this.lock?.unlock();
+        // A reservation this session still holds would only expire with its pid.
+        try {
+            releaseTreeOperation(this.dir, this.nonce);
+        }
+        catch { }
+        // Hygiene only; a file left behind is never read by another session.
+        try {
+            if ((0, handoff_1.handoffsDirState)(brokerDir(this.dir)) !== 'directory')
+                return;
+            for (const name of (0, fs_1.readdirSync)(brokerDir(this.dir))) {
+                if (name === `${this.nonce}.lock` ||
+                    (name.startsWith(`${this.nonce}-`) && name.endsWith('.request.json'))) {
+                    (0, fs_1.rmSync)((0, path_1.join)(brokerDir(this.dir), name), { force: true });
+                }
+            }
+        }
+        catch { }
+    }
+    notADirectory() {
+        return new Error(`The migrate run has something other than a directory at ${brokerDir(this.dir)}; remove it and try again.`);
+    }
+}
+exports.MigrateCommitBroker = MigrateCommitBroker;

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

@@ -0,0 +1,12 @@
+import type { MigrateRunState, MigrateStep } from './run-state';
+export declare function canOfferCleanRetry(root: string, state: MigrateRunState, step: MigrateStep, head: string | null): boolean;
+export declare function cleanRetryUnavailableReason(root: string, state: MigrateRunState, step: MigrateStep, head: string | null): string;
+/**
+ * The reset a clean retry of `stepId` needs, run with the tree reserved. The
+ * retry is re-checked against the state read then, and the attempt's
+ * generator run and the fixes its resolutions claimed are forgotten in a
+ * write of their own before git runs, so a reset that fails midway leaves
+ * the plain retry gated. Throws the reason when the retry is no longer
+ * available, or what git said when the reset fails.
+ */
+export declare function resetForCleanRetry(root: string, dir: string, stepId: string): void;

package/dist/src/command-line/migrate/run/clean-retry.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canOfferCleanRetry = canOfferCleanRetry;
+exports.cleanRetryUnavailableReason = cleanRetryUnavailableReason;
+exports.resetForCleanRetry = resetForCleanRetry;
+const git_utils_1 = require("../../../utils/git-utils");
+const types_1 = require("../agentic/types");
+const agent_output_1 = require("./agent-output");
+const issues_1 = require("./issues");
+const state_lock_1 = require("./state-lock");
+const state_machine_1 = require("./state-machine");
+const util_1 = require("./util");
+// A clean retry resets the tree to the step's `gitRefBefore`, discarding
+// everything the ref does not account for. It is offered only when it does
+// account for the whole tree: every prior diff committed, the tree clean when
+// the step was dispensed, and HEAD still at the ref. An absent or unreadable
+// value is no restore point, never a clean one. The debt check is run-wide:
+// the reset discards every step's uncommitted work, not only this one's.
+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 entry covering the step whose commit a reset to the step's
+// `gitRefBefore` would discard: one that is not a verified ancestor of it.
+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;
+}
+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.`;
+}
+// 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.
+function archiveReopenedResolutions(dir, state, updates, migrationId) {
+    if (updates.length === 0)
+        return;
+    const reconstructedIds = [];
+    try {
+        (0, issues_1.archiveIssues)(dir, { state, newIssues: [], updates }, reconstructedIds);
+    }
+    catch (e) {
+        (0, agent_output_1.warnToAgent)({
+            title: `The reverted issue resolutions for ${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.`,
+            ],
+        });
+    }
+    (0, issues_1.warnReconstructedArchives)(reconstructedIds);
+}
+/**
+ * The reset a clean retry of `stepId` needs, run with the tree reserved. The
+ * retry is re-checked against the state read then, and the attempt's
+ * generator run and the fixes its resolutions claimed are forgotten in a
+ * write of their own before git runs, so a reset that fails midway leaves
+ * the plain retry gated. Throws the reason when the retry is no longer
+ * available, or what git said when the reset fails.
+ */
+function resetForCleanRetry(root, dir, stepId) {
+    const head = (0, git_utils_1.getLatestCommitSha)(root);
+    let step;
+    let updates = [];
+    const prepared = (0, state_lock_1.updateRunState)(dir, (fresh) => {
+        step = fresh.steps.find((s) => s.id === stepId);
+        if (!step)
+            throw new Error(`step '${stepId}' is not in the run.`);
+        if (!canOfferCleanRetry(root, fresh, step, head)) {
+            throw new Error(cleanRetryUnavailableReason(root, fresh, step, head));
+        }
+        const reopened = (0, issues_1.reopenResolutionsForStep)((0, state_machine_1.discardGeneratorRun)(fresh, stepId), stepId);
+        updates = reopened.updates;
+        return reopened.state;
+    });
+    archiveReopenedResolutions(dir, prepared, updates, step.migrationId);
+    (0, git_utils_1.resetWorkingTree)(step.gitRefBefore, [types_1.MIGRATE_RUNS_RELATIVE_DIR], root);
+}

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

@@ -1,9 +1,10 @@
-export { CURRENT_RUN_STATE_FORMAT_VERSION, NewerRunStateFormatError, migrateRunsDir, runDir, readRunState, writeRunState, findActiveRun, createRun, } from './run-state';
-export type { MigrateRunStatus, MigrateRunRound, MigrateStepStatus, PromptOutcomeStatus, MigrateStepAwaitingKind, MigrateStepOutcome, MigrateStepPromptOutcome, MigrateStep, MigrateCommitKind, MigrateCommitLedgerEntry, MigrateIssueDisposition, MigrateRunIssue, MigrateRunAnalytics, MigrateRunNoProgress, MigrateRunState, } from './run-state';
+export { CURRENT_RUN_STATE_FORMAT_VERSION, NewerRunStateFormatError, migrateRunsDir, runDir, runHandoffsDir, readRunState, writeRunState, findActiveRun, createRun, } from './run-state';
+export type { MigrateRunStatus, MigrateRunRound, MigrateStepStatus, PromptOutcomeStatus, MigrateStepAwaitingKind, MigrateStepOutcome, MigrateStepPromptOutcome, MigrateStep, MigrateCommitKind, MigrateCommitLedgerEntry, MigrateIssueDisposition, MigrateRunIssue, MigrateRunAnalytics, MigrateRunNoProgress, MigrateRunPolicy, MigrateRunState, } from './run-state';
 export { applyStepEvent, hasPendingCommitDebt } from './state-machine';
 export type { StepAction, StepEvent, ApplyStepEventResult, } from './state-machine';
 export { createRunId, computePlanHash } from './run-id';
 export { runSingleMigrationWorker } from './worker';
 export type { RunSingleMigrationWorkerInput } from './worker';
-export { runOrchestratorInit, runOrchestratorReconcile } from './orchestrator';
+export { completionWarnings, runOrchestratorInit, runOrchestratorReconcile, } from './orchestrator';
 export type { RunOrchestratorInitInput, RunOrchestratorReconcileInput, } from './orchestrator';
+export { BROKER_ENV_VAR, MigrateCommitBroker, treeOperationLabel, } from './broker';

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

@@ -1,11 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.runOrchestratorReconcile = exports.runOrchestratorInit = exports.runSingleMigrationWorker = exports.computePlanHash = exports.createRunId = exports.hasPendingCommitDebt = exports.applyStepEvent = exports.createRun = exports.findActiveRun = exports.writeRunState = exports.readRunState = exports.runDir = exports.migrateRunsDir = exports.NewerRunStateFormatError = exports.CURRENT_RUN_STATE_FORMAT_VERSION = void 0;
+exports.treeOperationLabel = exports.MigrateCommitBroker = exports.BROKER_ENV_VAR = exports.runOrchestratorReconcile = exports.runOrchestratorInit = exports.completionWarnings = exports.runSingleMigrationWorker = exports.computePlanHash = exports.createRunId = exports.hasPendingCommitDebt = exports.applyStepEvent = exports.createRun = exports.findActiveRun = exports.writeRunState = exports.readRunState = exports.runHandoffsDir = exports.runDir = exports.migrateRunsDir = exports.NewerRunStateFormatError = exports.CURRENT_RUN_STATE_FORMAT_VERSION = void 0;
 var run_state_1 = require("./run-state");
 Object.defineProperty(exports, "CURRENT_RUN_STATE_FORMAT_VERSION", { enumerable: true, get: function () { return run_state_1.CURRENT_RUN_STATE_FORMAT_VERSION; } });
 Object.defineProperty(exports, "NewerRunStateFormatError", { enumerable: true, get: function () { return run_state_1.NewerRunStateFormatError; } });
 Object.defineProperty(exports, "migrateRunsDir", { enumerable: true, get: function () { return run_state_1.migrateRunsDir; } });
 Object.defineProperty(exports, "runDir", { enumerable: true, get: function () { return run_state_1.runDir; } });
+Object.defineProperty(exports, "runHandoffsDir", { enumerable: true, get: function () { return run_state_1.runHandoffsDir; } });
 Object.defineProperty(exports, "readRunState", { enumerable: true, get: function () { return run_state_1.readRunState; } });
 Object.defineProperty(exports, "writeRunState", { enumerable: true, get: function () { return run_state_1.writeRunState; } });
 Object.defineProperty(exports, "findActiveRun", { enumerable: true, get: function () { return run_state_1.findActiveRun; } });
@@ -19,5 +20,10 @@ Object.defineProperty(exports, "computePlanHash", { enumerable: true, get: funct
 var worker_1 = require("./worker");
 Object.defineProperty(exports, "runSingleMigrationWorker", { enumerable: true, get: function () { return worker_1.runSingleMigrationWorker; } });
 var orchestrator_1 = require("./orchestrator");
+Object.defineProperty(exports, "completionWarnings", { enumerable: true, get: function () { return orchestrator_1.completionWarnings; } });
 Object.defineProperty(exports, "runOrchestratorInit", { enumerable: true, get: function () { return orchestrator_1.runOrchestratorInit; } });
 Object.defineProperty(exports, "runOrchestratorReconcile", { enumerable: true, get: function () { return orchestrator_1.runOrchestratorReconcile; } });
+var broker_1 = require("./broker");
+Object.defineProperty(exports, "BROKER_ENV_VAR", { enumerable: true, get: function () { return broker_1.BROKER_ENV_VAR; } });
+Object.defineProperty(exports, "MigrateCommitBroker", { enumerable: true, get: function () { return broker_1.MigrateCommitBroker; } });
+Object.defineProperty(exports, "treeOperationLabel", { enumerable: true, get: function () { return broker_1.treeOperationLabel; } });