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

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

@@ -0,0 +1,55 @@
+import { type AncestorStatus } from '../../../utils/git-utils';
+import { type MigrateCommitLedgerEntry, type MigrateRunPolicy, type MigrateRunState } from './run-state';
+import { type StepTally } from './state-machine';
+export declare function progressLine(tally: StepTally): string;
+export interface ExistingRunFacts {
+    runId: string;
+    createdAt: string;
+    recordedBranch: string | undefined;
+    currentBranch: string | null;
+    progress: StepTally;
+    unresolvedIssues: number;
+    policy: MigrateRunPolicy;
+    commits: {
+        recorded: number;
+        reachable: number;
+        unchecked: number;
+        newest: {
+            sha: string | null;
+            status: AncestorStatus;
+        } | null;
+    };
+    liveWorkers: {
+        pid: number;
+        stepId: string;
+        migrationId: string;
+    }[];
+    otherHolders: number[] | 'unknown';
+    otherActiveRuns: string[] | 'unknown';
+    appliedStillPlanned: number | undefined;
+    replacedRunId?: string;
+}
+export declare function collectExistingRunFacts(root: string, runId: string, state: MigrateRunState, plannedMigrationIds?: readonly string[]): ExistingRunFacts;
+export declare function liveWorkers(state: MigrateRunState): ExistingRunFacts['liveWorkers'];
+export declare function recordedCommits(state: MigrateRunState): MigrateCommitLedgerEntry[];
+export declare function renderContinueCommand(root: string, runId: string, policy: MigrateRunPolicy, agentId?: string): string;
+export interface ExistingRunCommands {
+    continueCommand: string;
+    startFresh: {
+        command: string;
+    } | {
+        migrationsPath: string;
+    };
+}
+export declare function renderExistingRunCommands(root: string, facts: ExistingRunFacts, migrationsPath: string | undefined, agentId?: string): ExistingRunCommands;
+/**
+ * Title plus body lines, in the shape the agent-output writers take. Every
+ * body line goes through `singleLine`: branch names and timestamps came from
+ * git and disk, and the lines end up on the stdout the agent scans for
+ * blocks. The title carries only the run id, which discovery validated.
+ */
+export declare function renderExistingRunReport(facts: ExistingRunFacts, commands?: ExistingRunCommands): {
+    title: string;
+    bodyLines: string[];
+};
+export declare function workersLine(workers: ExistingRunFacts['liveWorkers']): string;

package/dist/src/command-line/migrate/run/existing-run-report.js

@@ -0,0 +1,225 @@
+"use strict";
+// The report on a run already active. Facts only: nothing here decides, and
+// anything that could not be established says so instead of guessing.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.progressLine = progressLine;
+exports.collectExistingRunFacts = collectExistingRunFacts;
+exports.liveWorkers = liveWorkers;
+exports.recordedCommits = recordedCommits;
+exports.renderContinueCommand = renderContinueCommand;
+exports.renderExistingRunCommands = renderExistingRunCommands;
+exports.renderExistingRunReport = renderExistingRunReport;
+exports.workersLine = workersLine;
+const git_utils_1 = require("../../../utils/git-utils");
+const text_1 = require("../text");
+const run_state_1 = require("./run-state");
+const issues_1 = require("./issues");
+const state_lock_1 = require("./state-lock");
+const state_machine_1 = require("./state-machine");
+const util_1 = require("./util");
+// The stalled count is a subset of `remaining`, called out separately: the
+// count alone would read as work that has not been reached yet. Adopted and
+// unresolved appear only when present, so the common line stays short.
+function progressLine(tally) {
+    return `${tally.applied} applied, ${tally.adopted > 0 ? `${tally.adopted} adopted, ` : ''}${tally.skipped} skipped, ${tally.unresolved.length > 0 ? `${tally.unresolved.length} unresolved, ` : ''}${tally.remaining} remaining${tally.stalled > 0 ? ` (${tally.stalled} awaiting a decision)` : ''}`;
+}
+function collectExistingRunFacts(root, runId, state, plannedMigrationIds) {
+    const head = (0, git_utils_1.getLatestCommitSha)(root);
+    // A landed entry may have lost its sha to a transient rev-parse failure;
+    // it still counts, as a commit that could not be checked.
+    const commits = recordedCommits(state);
+    const statuses = commits.map((entry) => entry.sha && head
+        ? (0, git_utils_1.getAncestorStatus)(entry.sha, head, root)
+        : 'unknown');
+    const newestIndex = commits.length - 1;
+    const planned = plannedMigrationIds ? new Set(plannedMigrationIds) : null;
+    return {
+        runId,
+        createdAt: state.createdAt,
+        recordedBranch: state.branch,
+        currentBranch: (0, git_utils_1.getGitCurrentBranch)(root),
+        progress: (0, state_machine_1.tallySteps)(state),
+        unresolvedIssues: (0, issues_1.unresolvedIssues)(state).length,
+        policy: {
+            createCommits: state.createCommits,
+            skipInstall: state.skipInstall === true,
+        },
+        commits: {
+            recorded: commits.length,
+            reachable: statuses.filter((s) => s === 'ancestor').length,
+            unchecked: statuses.filter((s) => s === 'unknown').length,
+            newest: newestIndex >= 0
+                ? {
+                    sha: commits[newestIndex].sha ?? null,
+                    status: statuses[newestIndex],
+                }
+                : null,
+        },
+        liveWorkers: liveWorkers(state),
+        otherHolders: (0, state_lock_1.liveRunActivityPids)((0, run_state_1.runDir)(root, runId)),
+        otherActiveRuns: otherActiveRuns(root, runId),
+        appliedStillPlanned: planned
+            ? state.steps.filter((s) => s.status === 'succeeded' && planned.has(s.migrationId)).length
+            : undefined,
+    };
+}
+// Only a step recorded as running can own a worker; a died or finished step's
+// pid may have been reused by an unrelated process since.
+function liveWorkers(state) {
+    return state.steps
+        .filter((s) => s.status === 'running' && s.pid !== undefined && (0, util_1.isPidAlive)(s.pid))
+        .map((s) => ({ pid: s.pid, stepId: s.id, migrationId: s.migrationId }));
+}
+// The commits the run made, in ledger order.
+function recordedCommits(state) {
+    return state.commits.filter((entry) => madeCommit(entry.kind));
+}
+function madeCommit(kind) {
+    switch (kind) {
+        case 'checkpoint':
+        case 'landed':
+            return true;
+        case 'failed':
+            return false;
+        default: {
+            const exhaustive = kind;
+            throw new Error(`Unhandled commit kind '${exhaustive}'.`);
+        }
+    }
+}
+function otherActiveRuns(root, runId) {
+    try {
+        return (0, run_state_1.findActiveRun)(root).activeRunIds.filter((id) => id !== runId);
+    }
+    catch (e) {
+        if (e instanceof run_state_1.NewerRunStateFormatError) {
+            return 'unknown';
+        }
+        throw e;
+    }
+}
+// The `--run-migrations --run-id` continue, the one entry that re-enters a
+// run on both paths. The policy flags are always explicit: a continue must
+// resolve to the run's recorded policy, and nx.json can flip the bare default
+// either way. `--agentic` names the agent to spawn; bare, inside an agent, it
+// only satisfies the parse and the run continues in place.
+function renderContinueCommand(root, runId, policy, agentId) {
+    return `${(0, util_1.pmExecPrefix)(root)} nx migrate --run-migrations --agentic${agentId === undefined ? '' : `=${agentId}`} --run-id=${runId} ${policy.createCommits ? '--create-commits' : '--no-create-commits'}${policy.skipInstall ? ' --skip-install' : ''}`;
+}
+function renderExistingRunCommands(root, facts, migrationsPath, agentId) {
+    const flag = migrationsPath === undefined
+        ? '--run-migrations'
+        : (0, util_1.runMigrationsFlag)(migrationsPath);
+    return {
+        continueCommand: renderContinueCommand(root, facts.runId, facts.policy, agentId),
+        startFresh: flag === null
+            ? { migrationsPath }
+            : {
+                command: `${(0, util_1.pmExecPrefix)(root)} nx migrate ${flag}${agentId === undefined ? '' : ` --agentic=${agentId}`} --start-fresh --run-id=${facts.runId}`,
+            },
+    };
+}
+/**
+ * Title plus body lines, in the shape the agent-output writers take. Every
+ * body line goes through `singleLine`: branch names and timestamps came from
+ * git and disk, and the lines end up on the stdout the agent scans for
+ * blocks. The title carries only the run id, which discovery validated.
+ */
+function renderExistingRunReport(facts, commands) {
+    const lines = [
+        ...(facts.replacedRunId !== undefined
+            ? [
+                `Not deleting ${facts.replacedRunId}: the newest active run is ${facts.runId}.`,
+            ]
+            : []),
+        `  run: ${facts.runId}`,
+        `  started: ${facts.createdAt} (${(0, text_1.formatAge)(facts.createdAt)})`,
+        `  branch: ${branchLine(facts)}`,
+        `  progress: ${progressLine(facts.progress)}`,
+        `  policy: per-migration commits ${facts.policy.createCommits ? 'on' : 'off'}, installs ${facts.policy.skipInstall ? 'skipped' : 'on'}`,
+        `  commits: ${commitsLine(facts.commits)}`,
+        `  worker: ${workersLine(facts.liveWorkers)}`,
+        `  activity: ${activityLine(facts.otherHolders)}`,
+    ];
+    if (facts.unresolvedIssues > 0) {
+        lines.push(`  issues: ${facts.unresolvedIssues} unresolved`);
+    }
+    if (facts.otherActiveRuns === 'unknown') {
+        lines.push(`  other active runs on disk: unknown (a run written by a newer nx is on disk)`);
+    }
+    else if (facts.otherActiveRuns.length > 0) {
+        lines.push(`  other active runs on disk: ${facts.otherActiveRuns.join(', ')}`);
+    }
+    if (facts.appliedStillPlanned !== undefined) {
+        lines.push(`  plan overlap: ${facts.appliedStillPlanned} of the applied migrations ${facts.appliedStillPlanned === 1 ? 'is' : 'are'} still in the plan; a new run applies ${facts.appliedStillPlanned === 1 ? 'it' : 'them'} again`);
+    }
+    if (commands) {
+        lines.push(``, `To continue the run: ${commands.continueCommand}`, `To start fresh (deletes the run record, then runs the whole plan again): ${'command' in commands.startFresh
+            ? commands.startFresh.command
+            : `re-run this command with --start-fresh --run-id=${facts.runId}, keeping the --run-migrations argument, which names ${displayPath(commands.startFresh.migrationsPath)}; that path cannot be rendered as a command for this shell`}`, `Run either command with NX_MIGRATE_ORCHESTRATOR=true set in the environment.`);
+    }
+    return {
+        title: `A migrate run is already active: ${facts.runId}`,
+        bodyLines: lines.map(text_1.singleLine),
+    };
+}
+// Prose, not a command, so a path goes out verbatim. A path with a line break
+// goes out JSON-escaped: singleLine below would otherwise turn the break into
+// a space and name a different path. JSON.stringify leaves U+0085, U+2028 and
+// U+2029 literal, so those are escaped by hand.
+function displayPath(migrationsPath) {
+    if (!(0, text_1.hasLineBreak)(migrationsPath)) {
+        return migrationsPath;
+    }
+    return JSON.stringify(migrationsPath).replace(/[\u0085\u2028\u2029]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+}
+// A null probe is 'unknown' on both sides: getGitCurrentBranch folds a
+// detached HEAD and a failed git call into one null.
+function branchLine(facts) {
+    const recorded = facts.recordedBranch ?? 'unknown';
+    const current = facts.currentBranch ?? 'unknown';
+    return recorded === current
+        ? recorded
+        : `started on ${recorded}, currently on ${current}`;
+}
+function commitsLine(commits) {
+    if (!commits.newest) {
+        return 'none recorded';
+    }
+    const newest = commits.newest.sha === null
+        ? 'newest recorded commit has no recorded sha and could not be checked'
+        : `newest recorded commit ${commits.newest.sha.slice(0, 10)} is ${describeStatus(commits.newest.status)}`;
+    const tally = `${commits.reachable} of ${commits.recorded} reachable${commits.unchecked > 0 ? `, ${commits.unchecked} could not be checked` : ''}`;
+    return `${newest} (${tally})`;
+}
+function describeStatus(status) {
+    switch (status) {
+        case 'ancestor':
+            return 'reachable from HEAD';
+        case 'not-ancestor':
+            return 'not reachable from HEAD';
+        case 'unknown':
+            return 'of unknown reachability from HEAD';
+        default: {
+            const exhaustive = status;
+            throw new Error(`Unhandled ancestor status '${exhaustive}'.`);
+        }
+    }
+}
+function activityLine(holders) {
+    if (holders === 'unknown') {
+        return 'unknown whether another nx migrate process is working on it';
+    }
+    if (holders.length === 0) {
+        return 'no other nx migrate process is working on it';
+    }
+    return (0, state_lock_1.describeHolders)(holders);
+}
+function workersLine(workers) {
+    if (workers.length === 0) {
+        return 'none running';
+    }
+    return workers
+        .map((w) => `pid ${w.pid} is still running ${w.stepId} (${w.migrationId})`)
+        .join('; ');
+}

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

@@ -0,0 +1,41 @@
+import { type CommitResult } from '../migrate-commits';
+import type { MigrateOutputSink } from '../deferred-output';
+import type { TreeLease } from './broker';
+import { type MigrateRunState, type MigrateStep } from './run-state';
+export type GiveUpOutcome = {
+    kind: 'given-up';
+    commit: CommitResult | {
+        status: 'install-failed';
+        reason: string;
+    };
+    archiveError?: string;
+} | {
+    kind: 'refused';
+    reason: string;
+};
+export interface GiveUpInput {
+    root: string;
+    dir: string;
+    step: MigrateStep;
+    lease: TreeLease;
+    skipInstall: boolean;
+    reconcileCommand: string;
+    output?: MigrateOutputSink;
+}
+export declare function giveUpWithCommit(input: GiveUpInput): Promise<GiveUpOutcome>;
+/**
+ * Mints the issue that carries a given-up step's failure and points the step
+ * at it, on state where the step is already unresolved. The archive file is
+ * best-effort: run.json is authoritative, and undoing the transition for a
+ * lost detail file would make the agent re-issue an action the run already
+ * took.
+ */
+export declare function recordUnresolvedIssue(dir: string, state: MigrateRunState, stepId: string): {
+    state: MigrateRunState;
+    archiveError?: string;
+};
+export declare function warnUnresolvedNotArchived(migrationId: string, archiveError: string): void;
+/** What the reconcile owes the agent for a give-up that went through. */
+export declare function warnAboutGiveUp(step: MigrateStep, outcome: Extract<GiveUpOutcome, {
+    kind: 'given-up';
+}>): void;

package/dist/src/command-line/migrate/run/give-up.js

@@ -0,0 +1,148 @@
+"use strict";
+// Giving a step up while the run commits is one operation under one tree
+// reservation, run by the process that holds the tree (a session's parent or
+// the reconcile): split across two, the transition would find the give-up's
+// own commit in the ledger and refuse it as a commit of the migration.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.giveUpWithCommit = giveUpWithCommit;
+exports.recordUnresolvedIssue = recordUnresolvedIssue;
+exports.warnUnresolvedNotArchived = warnUnresolvedNotArchived;
+exports.warnAboutGiveUp = warnAboutGiveUp;
+const migrate_commits_1 = require("../migrate-commits");
+const agent_output_1 = require("./agent-output");
+const issues_1 = require("./issues");
+const run_state_1 = require("./run-state");
+const state_lock_1 = require("./state-lock");
+const state_machine_1 = require("./state-machine");
+const util_1 = require("./util");
+async function giveUpWithCommit(input) {
+    const { root, dir, step, lease } = input;
+    const ownMark = lease.markedStepId === step.id;
+    const event = {
+        type: 'stepAction',
+        stepId: step.id,
+        action: 'unresolved',
+        attempt: step.attempt,
+    };
+    const state = (0, run_state_1.readRunState)(dir);
+    // Checked under the reservation, before git runs: a landed commit of the
+    // step, or a mark another operation left, refuses the give-up with nothing
+    // to undo. The mark this reservation set is not evidence against it.
+    const accepted = (0, state_machine_1.applyStepEvent)(ownMark ? (0, state_machine_1.clearCommitStarted)(state, step.id) : state, event);
+    if (accepted.kind === 'error') {
+        return { kind: 'refused', reason: accepted.reason };
+    }
+    const absorbedStepIds = (0, state_machine_1.uncoveredFailedStepIds)(state).filter((id) => id !== step.id);
+    let commit;
+    let entry;
+    try {
+        const result = await (0, migrate_commits_1.commitMigrationIfRequested)(root, { name: (0, state_machine_1.unresolvedCommitName)(step) }, true, state.commitPrefix, () => (0, util_1.installDepsChangedSinceDispense)(root, dir, step, input.skipInstall, input.reconcileCommand, input.output), (0, state_machine_1.stepsToPendingMigrations)(state, absorbedStepIds), undefined, input.output);
+        commit = result;
+        entry = (0, state_machine_1.commitResultToLedgerEntry)(result, step.id, absorbedStepIds);
+    }
+    catch (e) {
+        // The install is the only thrower: the commit reports through its result.
+        // 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.
+        commit = { status: 'install-failed', reason: (0, util_1.summarizeError)(e) };
+        entry = { kind: 'failed', stepIds: [step.id] };
+    }
+    const ran = commit.status !== 'install-failed' && (0, state_machine_1.gitRan)(commit);
+    if (ran)
+        lease.markedStepId = undefined;
+    let archiveError;
+    let refusal;
+    (0, state_lock_1.updateRunState)(dir, (fresh) => {
+        // Re-applied on fresh state. The reservation kept every other commit of
+        // the step out, so only run state edited from outside can refuse it now;
+        // the commit then stays unrecorded, with the mark standing for an adopt.
+        const applied = (0, state_machine_1.applyStepEvent)(ownMark ? (0, state_machine_1.clearCommitStarted)(fresh, step.id) : fresh, event);
+        if (applied.kind === 'error') {
+            refusal = applied.reason;
+            return null;
+        }
+        // A failure once git ran keeps the mark: only a landed entry accounts
+        // for the commit it may have made.
+        const recorded = recordUnresolvedIssue(dir, ownMark && commit.status === 'failed'
+            ? (0, state_machine_1.markCommitStarted)(applied.state, step.id)
+            : applied.state, step.id);
+        archiveError = recorded.archiveError;
+        const next = commit.status === 'install-failed'
+            ? (0, state_machine_1.markInstallFailed)(recorded.state, step.id)
+            : recorded.state;
+        return entry
+            ? (0, state_machine_1.appendCommit)(next, (0, issues_1.attachIssueIdsToCommitEntry)(next, entry))
+            : next;
+    });
+    if (refusal !== undefined) {
+        return {
+            kind: 'refused',
+            reason: entry?.kind === 'landed' && entry.sha
+                ? `${refusal} Note: this action's commit ${entry.sha} had already landed and stays in history; resolve the step against the tree as it stands now.`
+                : refusal,
+        };
+    }
+    return {
+        kind: 'given-up',
+        commit,
+        ...(archiveError !== undefined ? { archiveError } : {}),
+    };
+}
+/**
+ * Mints the issue that carries a given-up step's failure and points the step
+ * at it, on state where the step is already unresolved. The archive file is
+ * best-effort: run.json is authoritative, and undoing the transition for a
+ * lost detail file would make the agent re-issue an action the run already
+ * took.
+ */
+function recordUnresolvedIssue(dir, state, stepId) {
+    // Minted from the transitioned step: a died one only gains its failure in
+    // the transition.
+    const minted = (0, issues_1.mintUnresolvedIssue)(state, state.steps.find((s) => s.id === stepId));
+    let archiveError;
+    try {
+        (0, issues_1.archiveIssues)(dir, minted.application);
+    }
+    catch (e) {
+        archiveError = (0, util_1.summarizeError)(e);
+    }
+    return {
+        state: {
+            ...minted.application.state,
+            steps: minted.application.state.steps.map((s) => s.id === stepId ? { ...s, unresolvedIssueId: minted.issueId } : s),
+        },
+        ...(archiveError !== undefined ? { archiveError } : {}),
+    };
+}
+function warnUnresolvedNotArchived(migrationId, archiveError) {
+    (0, agent_output_1.warnToAgent)({
+        title: `The issue recording that ${migrationId} was left unresolved could not be archived (${archiveError}).`,
+        bodyLines: [
+            `run.json stays authoritative: the step is unresolved and the issue is in its ledger; only the archived file under the run's issues directory is missing.`,
+        ],
+    });
+}
+/** What the reconcile owes the agent for a give-up that went through. */
+function warnAboutGiveUp(step, outcome) {
+    const name = (0, state_machine_1.unresolvedCommitName)(step);
+    switch (outcome.commit.status) {
+        case 'install-failed':
+            (0, util_1.warnCommitFailed)(name, outcome.commit.reason);
+            break;
+        case 'failed':
+            (0, util_1.warnCommitFailed)(name);
+            break;
+        case 'committed':
+        case 'no-changes':
+        case 'disabled':
+            break;
+        default: {
+            const exhaustive = outcome.commit;
+            throw new Error(`Unhandled commit result: ${JSON.stringify(exhaustive)}`);
+        }
+    }
+    if (outcome.archiveError !== undefined) {
+        warnUnresolvedNotArchived(step.migrationId, outcome.archiveError);
+    }
+}

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

@@ -1,10 +1,12 @@
 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 { applyStepEvent, completionSummaryLines, hasPendingCommitDebt, latestRound, runTallies, tallySteps, } from './state-machine';
+export { hasUnresolvedIssues } from './issues';
 export type { StepAction, StepEvent, ApplyStepEventResult, } from './state-machine';
-export { createRunId, computePlanHash } from './run-id';
+export { createRunId } from './run-id';
 export { runSingleMigrationWorker } from './worker';
 export type { RunSingleMigrationWorkerInput } from './worker';
-export { completionWarnings, runOrchestratorInit, runOrchestratorReconcile, } from './orchestrator';
-export type { RunOrchestratorInitInput, RunOrchestratorReconcileInput, } from './orchestrator';
+export { activeRunToReplace, completionWarnings, holdRunToContinue, releaseRunToHandOff, runOrchestratorInit, runOrchestratorReconcile, runOrchestratorResume, } from './orchestrator';
+export type { OrchestratorInitResult, RunOrchestratorInitInput, RunOrchestratorReconcileInput, } from './orchestrator';
+export { renderContinueCommand, renderExistingRunCommands, renderExistingRunReport, } from './existing-run-report';
 export { BROKER_ENV_VAR, MigrateCommitBroker, treeOperationLabel, } from './broker';

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-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;
+exports.treeOperationLabel = exports.MigrateCommitBroker = exports.BROKER_ENV_VAR = exports.renderExistingRunReport = exports.renderExistingRunCommands = exports.renderContinueCommand = exports.runOrchestratorResume = exports.runOrchestratorReconcile = exports.runOrchestratorInit = exports.releaseRunToHandOff = exports.holdRunToContinue = exports.completionWarnings = exports.activeRunToReplace = exports.runSingleMigrationWorker = exports.createRunId = exports.hasUnresolvedIssues = exports.tallySteps = exports.runTallies = exports.latestRound = exports.hasPendingCommitDebt = exports.completionSummaryLines = 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; } });
@@ -13,16 +13,29 @@ Object.defineProperty(exports, "findActiveRun", { enumerable: true, get: functio
 Object.defineProperty(exports, "createRun", { enumerable: true, get: function () { return run_state_1.createRun; } });
 var state_machine_1 = require("./state-machine");
 Object.defineProperty(exports, "applyStepEvent", { enumerable: true, get: function () { return state_machine_1.applyStepEvent; } });
+Object.defineProperty(exports, "completionSummaryLines", { enumerable: true, get: function () { return state_machine_1.completionSummaryLines; } });
 Object.defineProperty(exports, "hasPendingCommitDebt", { enumerable: true, get: function () { return state_machine_1.hasPendingCommitDebt; } });
+Object.defineProperty(exports, "latestRound", { enumerable: true, get: function () { return state_machine_1.latestRound; } });
+Object.defineProperty(exports, "runTallies", { enumerable: true, get: function () { return state_machine_1.runTallies; } });
+Object.defineProperty(exports, "tallySteps", { enumerable: true, get: function () { return state_machine_1.tallySteps; } });
+var issues_1 = require("./issues");
+Object.defineProperty(exports, "hasUnresolvedIssues", { enumerable: true, get: function () { return issues_1.hasUnresolvedIssues; } });
 var run_id_1 = require("./run-id");
 Object.defineProperty(exports, "createRunId", { enumerable: true, get: function () { return run_id_1.createRunId; } });
-Object.defineProperty(exports, "computePlanHash", { enumerable: true, get: function () { return run_id_1.computePlanHash; } });
 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, "activeRunToReplace", { enumerable: true, get: function () { return orchestrator_1.activeRunToReplace; } });
 Object.defineProperty(exports, "completionWarnings", { enumerable: true, get: function () { return orchestrator_1.completionWarnings; } });
+Object.defineProperty(exports, "holdRunToContinue", { enumerable: true, get: function () { return orchestrator_1.holdRunToContinue; } });
+Object.defineProperty(exports, "releaseRunToHandOff", { enumerable: true, get: function () { return orchestrator_1.releaseRunToHandOff; } });
 Object.defineProperty(exports, "runOrchestratorInit", { enumerable: true, get: function () { return orchestrator_1.runOrchestratorInit; } });
 Object.defineProperty(exports, "runOrchestratorReconcile", { enumerable: true, get: function () { return orchestrator_1.runOrchestratorReconcile; } });
+Object.defineProperty(exports, "runOrchestratorResume", { enumerable: true, get: function () { return orchestrator_1.runOrchestratorResume; } });
+var existing_run_report_1 = require("./existing-run-report");
+Object.defineProperty(exports, "renderContinueCommand", { enumerable: true, get: function () { return existing_run_report_1.renderContinueCommand; } });
+Object.defineProperty(exports, "renderExistingRunCommands", { enumerable: true, get: function () { return existing_run_report_1.renderExistingRunCommands; } });
+Object.defineProperty(exports, "renderExistingRunReport", { enumerable: true, get: function () { return existing_run_report_1.renderExistingRunReport; } });
 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; } });

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

@@ -43,6 +43,18 @@ export interface IssueApplication {
     }[];
     updates: IssueArchiveUpdate[];
 }
+/**
+ * Mints the run issue carrying a given-up step's last failure to the completion
+ * report: unscoped and deferred, so no later step claims it, with the migration
+ * id in the summary so identical failures stay apart. A report with the same
+ * text is taken over, not merged: the fingerprint is derived from the summary,
+ * so the ledger cannot hold both, and a merge would keep the report's scope.
+ * Same locking contract as {@link applyReportedIssues}.
+ */
+export declare function mintUnresolvedIssue(state: MigrateRunState, step: MigrateStep): {
+    application: IssueApplication;
+    issueId: string;
+};
 /**
  * Pure. Must run on state read fresh inside the fold's locked write, or ids
  * collide and the claim checks test state that is no longer on disk.
@@ -94,6 +106,8 @@ export declare function settleUnclaimableIssues(state: MigrateRunState): Migrate
  */
 export declare function renderIssueDigestLines(state: MigrateRunState, currentStepId: string, runId: string): string[];
 export declare function renderUnresolvedIssueLines(state: MigrateRunState, runId: string): string[];
+export declare function unresolvedIssues(state: MigrateRunState): MigrateRunIssue[];
+export declare function hasUnresolvedIssues(state: MigrateRunState): boolean;
 export declare function issueArchivePath(runDirPath: string, issueId: string): string;
 export declare function warnReconstructedArchives(issueIds: string[]): void;
 /**

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

@@ -4,6 +4,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.issueFingerprint = void 0;
 exports.parseHandoffIssues = parseHandoffIssues;
+exports.mintUnresolvedIssue = mintUnresolvedIssue;
 exports.applyReportedIssues = applyReportedIssues;
 exports.issueIdsForCommit = issueIdsForCommit;
 exports.attachIssueIdsToCommitEntry = attachIssueIdsToCommitEntry;
@@ -13,10 +14,13 @@ exports.claimIssuesForStep = claimIssuesForStep;
 exports.settleUnclaimableIssues = settleUnclaimableIssues;
 exports.renderIssueDigestLines = renderIssueDigestLines;
 exports.renderUnresolvedIssueLines = renderUnresolvedIssueLines;
+exports.unresolvedIssues = unresolvedIssues;
+exports.hasUnresolvedIssues = hasUnresolvedIssues;
 exports.issueArchivePath = issueArchivePath;
 exports.warnReconstructedArchives = warnReconstructedArchives;
 exports.archiveIssues = archiveIssues;
 exports.applicationArchivesIntact = applicationArchivesIntact;
+const crypto_1 = require("crypto");
 const fs_1 = require("fs");
 const path_1 = require("path");
 const fileutils_1 = require("../../../utils/fileutils");
@@ -27,6 +31,8 @@ const agent_output_1 = require("./agent-output");
 const run_state_1 = require("./run-state");
 Object.defineProperty(exports, "issueFingerprint", { enumerable: true, get: function () { return run_state_1.issueFingerprint; } });
 const state_machine_1 = require("./state-machine");
+// Reserves summary space for the attempt count and the failure.
+const MAX_UNRESOLVED_ID_CHARS = 200;
 const ISSUES_DIR_NAME = 'issues';
 // Bounds on one agent-written handoff's issue report. A report over a bound is
 // rejected whole for the agent to fix, never trimmed.
@@ -241,6 +247,46 @@ function mappedStepIds(identifier, state) {
         .filter((s) => (0, state_machine_1.splitMigrationId)(s.migrationId).package === identifier)
         .map((s) => s.id);
 }
+/**
+ * Mints the run issue carrying a given-up step's last failure to the completion
+ * report: unscoped and deferred, so no later step claims it, with the migration
+ * id in the summary so identical failures stay apart. A report with the same
+ * text is taken over, not merged: the fingerprint is derived from the summary,
+ * so the ledger cannot hold both, and a merge would keep the report's scope.
+ * Same locking contract as {@link applyReportedIssues}.
+ */
+function mintUnresolvedIssue(state, step) {
+    const attempts = `${step.attempt} attempt${step.attempt === 1 ? '' : 's'}`;
+    const prefix = `Migration ${abbreviatedMigrationId(step.migrationId)} was left unresolved after ${attempts}: `;
+    const room = MAX_SUMMARY_CHARS - prefix.length;
+    const detail = (0, state_machine_1.unresolvedFailureDetail)(step);
+    const summary = prefix +
+        (detail.length > room ? `${detail.slice(0, room - 3)}...` : detail);
+    const ledger = state.issues ?? [];
+    const index = ledger.findIndex((i) => i.fingerprint === (0, run_state_1.issueFingerprint)(summary));
+    if (index === -1) {
+        const application = applyReportedIssues(state, step, [{ summary, applicableMigrations: 'unknown' }], []);
+        return { application, issueId: application.newIssues[0].entry.id };
+    }
+    const { claimedByStepId: _claim, resolvedByStepId: _credit, resolvedAtCommitCount: _fence, ...rest } = ledger[index];
+    const entry = {
+        ...rest,
+        applicableStepIds: 'unknown',
+        disposition: 'deferred-final',
+    };
+    const issues = [...ledger];
+    issues[index] = entry;
+    return {
+        application: {
+            state: { ...state, issues },
+            newIssues: [],
+            updates: [
+                { issueId: entry.id, stepId: step.id, disposition: 'deferred-final' },
+            ],
+        },
+        issueId: entry.id,
+    };
+}
 /**
  * Pure. Must run on state read fresh inside the fold's locked write, or ids
  * collide and the claim checks test state that is no longer on disk.
@@ -731,6 +777,9 @@ function renderUnresolvedIssueLines(state, runId) {
 function unresolvedIssues(state) {
     return (state.issues ?? []).filter((i) => i.disposition !== 'resolved');
 }
+function hasUnresolvedIssues(state) {
+    return unresolvedIssues(state).length > 0;
+}
 function stepDigestHeading(runId) {
     return `Known issues reported earlier in this run (details under ${issuesDirRef(runId)}):`;
 }
@@ -886,6 +935,16 @@ const NEW_ISSUE_ARCHIVE_KEYS = [
     'disposition',
     'detail',
 ];
+// Hashes the full id so ids sharing a visible prefix stay distinct.
+function abbreviatedMigrationId(migrationId) {
+    if (migrationId.length <= MAX_UNRESOLVED_ID_CHARS)
+        return migrationId;
+    const digest = (0, crypto_1.createHash)('sha256')
+        .update(migrationId)
+        .digest('hex')
+        .slice(0, 8);
+    return `${migrationId.slice(0, MAX_UNRESOLVED_ID_CHARS - 12)}...[${digest}]`;
+}
 // Shared by the write path and the intactness check so their shapes cannot
 // drift.
 function newIssueArchiveRecord(entry, report) {