nx 23.2.0-beta.6 → 23.2.0-beta.8

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

@@ -0,0 +1,16 @@
+export declare const RUN_ID_SAFE: RegExp;
+/**
+ * Creates a run id: a sortable, filesystem-safe UTC timestamp followed by a
+ * random suffix (e.g. `20260715T101530-3f9a1c02`). Never derived from
+ * package or Nx versions, so it stays stable across an Nx version bump
+ * mid-run.
+ */
+export declare function createRunId(): string;
+/**
+ * Hashes a migrations.json plan so a resumed run can detect whether the plan
+ * changed since a round was recorded. `nx-console` is stripped first since
+ * editors write to it without changing the plan; object keys are sorted
+ * recursively (arrays keep their order) so key reordering from a different
+ * JSON serializer doesn't change the hash.
+ */
+export declare function computePlanHash(migrationsJsonContent: string | object): string;

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

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RUN_ID_SAFE = void 0;
+exports.createRunId = createRunId;
+exports.computePlanHash = computePlanHash;
+const crypto_1 = require("crypto");
+// Orchestrator-generated run ids always match; anything else could smuggle
+// shell metacharacters into dispensed commands or a path out of the runs dir
+// (the leading alphanumeric also rejects '.' and '..').
+exports.RUN_ID_SAFE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/**
+ * Creates a run id: a sortable, filesystem-safe UTC timestamp followed by a
+ * random suffix (e.g. `20260715T101530-3f9a1c02`). Never derived from
+ * package or Nx versions, so it stays stable across an Nx version bump
+ * mid-run.
+ */
+function createRunId() {
+    return `${compactUtcTimestamp(new Date())}-${(0, crypto_1.randomBytes)(4).toString('hex')}`;
+}
+function compactUtcTimestamp(date) {
+    // '2026-07-15T10:15:30.123Z' -> '20260715T101530': strips separators and
+    // milliseconds so the id is filesystem-safe on every platform.
+    return date
+        .toISOString()
+        .replace(/[-:]/g, '')
+        .replace(/\.\d+Z$/, '');
+}
+/**
+ * Hashes a migrations.json plan so a resumed run can detect whether the plan
+ * changed since a round was recorded. `nx-console` is stripped first since
+ * editors write to it without changing the plan; object keys are sorted
+ * recursively (arrays keep their order) so key reordering from a different
+ * JSON serializer doesn't change the hash.
+ */
+function computePlanHash(migrationsJsonContent) {
+    const parsed = (typeof migrationsJsonContent === 'string'
+        ? JSON.parse(migrationsJsonContent)
+        : migrationsJsonContent);
+    const withoutNxConsole = Object.fromEntries(Object.entries(parsed).filter(([key]) => key !== 'nx-console'));
+    return (0, crypto_1.createHash)('sha256')
+        .update(JSON.stringify(canonicalize(withoutNxConsole)))
+        .digest('hex');
+}
+function canonicalize(value) {
+    if (Array.isArray(value)) {
+        return value.map(canonicalize);
+    }
+    if (value !== null && typeof value === 'object') {
+        const sorted = {};
+        for (const key of Object.keys(value).sort()) {
+            sorted[key] = canonicalize(value[key]);
+        }
+        return sorted;
+    }
+    return value;
+}

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

@@ -0,0 +1,157 @@
+export declare const CURRENT_RUN_STATE_FORMAT_VERSION = 1;
+export declare const RUN_STATE_FILE_NAME = "run.json";
+/**
+ * The charset a migration id must stay inside to be interpolated into a
+ * dispensed command. The outer agent executes those verbatim, so hostile ids
+ * are refused rather than quoted per-platform (POSIX quoting is no defense in
+ * cmd.exe). Enforced twice: on the incoming plan at init, so a bad id never
+ * starts a run, and here on read, so a run whose persisted ids were tampered
+ * with fails closed as corrupt instead of being dispensed.
+ */
+export declare const SHELL_SAFE_VALUE: RegExp;
+declare const MIGRATE_RUN_STATUSES: readonly ['active', 'completed'];
+export type MigrateRunStatus = (typeof MIGRATE_RUN_STATUSES)[number];
+export interface MigrateRunRound {
+    index: number;
+    planHash: string;
+    planSnapshot: string;
+}
+declare const MIGRATE_STEP_STATUSES: readonly ['pending', 'dispensed', 'running', 'awaiting-prompt-outcome', 'succeeded', 'failed', 'skipped', 'died'];
+export type MigrateStepStatus = (typeof MIGRATE_STEP_STATUSES)[number];
+declare const PROMPT_OUTCOME_STATUSES: readonly ['completed', 'skipped', 'failed'];
+export type PromptOutcomeStatus = (typeof PROMPT_OUTCOME_STATUSES)[number];
+export interface MigrateStepOutcome {
+    fileChanges?: string[];
+    gitRefAfter?: string;
+    nextSteps?: string[];
+    summary?: string;
+}
+export interface MigrateStepPromptOutcome {
+    status: PromptOutcomeStatus;
+    summary?: string;
+}
+export interface MigrateStep {
+    id: string;
+    roundIndex: number;
+    migrationId: string;
+    status: MigrateStepStatus;
+    attempt: number;
+    dispenseCount: number;
+    hasGenerator?: boolean;
+    pid?: number;
+    startedAt?: string;
+    finishedAt?: string;
+    gitRefBefore?: string;
+    treeCleanAtDispense?: boolean;
+    depsHashAtDispense?: string;
+    outcome?: MigrateStepOutcome;
+    promptOutcome?: MigrateStepPromptOutcome;
+    generatorCompleted?: boolean;
+    installFailed?: boolean;
+}
+declare const MIGRATE_COMMIT_KINDS: readonly ['checkpoint', 'landed', 'failed'];
+export type MigrateCommitKind = (typeof MIGRATE_COMMIT_KINDS)[number];
+export interface MigrateCommitLedgerEntry {
+    sha?: string;
+    kind: MigrateCommitKind;
+    stepIds: string[];
+}
+export interface MigrateRunAnalytics {
+    startEmitted: boolean;
+    completeEmitted: boolean;
+}
+export interface MigrateRunState {
+    formatVersion: number;
+    runId: string;
+    createdAt: string;
+    nxVersion: string;
+    status: MigrateRunStatus;
+    createCommits: boolean;
+    commitPrefix: string;
+    skipInstall?: boolean;
+    rounds: MigrateRunRound[];
+    steps: MigrateStep[];
+    commits: MigrateCommitLedgerEntry[];
+    checkpointFailed?: boolean;
+    analytics: MigrateRunAnalytics;
+}
+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. */
+export declare function runHandoffsDir(runDirPath: string): string;
+/**
+ * Thrown when a run.json declares a `formatVersion` newer than this Nx
+ * understands. Callers must not treat such a run as absent: an older Nx
+ * ignoring a newer active run would start a competing run on top of it.
+ *
+ * Adding a member to any persisted closed set (run status, step status,
+ * prompt-outcome status, commit kind) needs a
+ * `CURRENT_RUN_STATE_FORMAT_VERSION` bump: without it, an older Nx reading
+ * the new value would reject the run as corrupt (the closed-set validation
+ * fails) instead of refusing with this error's ask for a newer Nx.
+ */
+export declare class NewerRunStateFormatError extends Error {
+    constructor(message: string);
+}
+/**
+ * Reads and validates `run.json` from a run directory.
+ *
+ * A `formatVersion` newer than {@link CURRENT_RUN_STATE_FORMAT_VERSION} means
+ * the run was created by a newer Nx than the one currently running, so the
+ * shape may not be interpretable here; this throws rather than attempting a
+ * best-effort read. An older `formatVersion` is returned as-is: only v1
+ * exists today, so there is nothing to migrate yet.
+ */
+export declare function readRunState(runDirPath: string): MigrateRunState;
+/**
+ * Writes `run.json` atomically: serializes to a temp file in the same
+ * directory, then renames over the real path. A crash mid-write can only
+ * ever leave the stale temp file behind, never a half-written run.json.
+ *
+ * Rename gives per-write atomicity only. Serializing the read-modify-write
+ * sequences that concurrent nx migrate processes run is state-lock.ts's job.
+ */
+export declare function writeRunState(runDirPath: string, state: MigrateRunState): void;
+export declare function hasRunState(runDirPath: string): boolean;
+export interface UninterpretableRunDir {
+    dirName: string;
+    reason: string;
+}
+/**
+ * Scans for the newest active run. A dir that holds a run.json but could be an
+ * active run this caller cannot use is returned as `uninterpretable` instead
+ * of being silently skipped: treating it as absent would let a run-starting
+ * caller create a competing run that re-applies migrations the first run
+ * already applied. That covers unreadable or corrupt content, where whether
+ * the run is active cannot be determined, and an active run in a dir whose
+ * name fails {@link RUN_ID_SAFE}, which cannot be resumed either.
+ *
+ * A dir that reads cleanly as a finished run is skipped whatever its name is:
+ * it competes with nothing, and reporting it would block every future run
+ * with no way for retention to ever clear it.
+ *
+ * Throws {@link NewerRunStateFormatError} when any run dir holds a
+ * newer-format run.json: whether that run is active can't be determined
+ * here, and its remediation (a newer Nx) differs from the uninterpretable
+ * one (fix or remove).
+ */
+export declare function findActiveRun(root: string): {
+    active: {
+        runId: string;
+        state: MigrateRunState;
+    } | null;
+    uninterpretable: UninterpretableRunDir[];
+};
+/**
+ * Creates a new run directory and writes its initial state, then prunes old
+ * completed runs so `.nx/migrate-runs` doesn't grow unbounded: only the
+ * newest {@link MAX_RETAINED_COMPLETED_RUNS} completed runs are kept. Active
+ * runs, the run just created, and legacy per-version runner dirs (no
+ * run.json) are never pruned.
+ *
+ * Retention is best effort. A dir it cannot interpret or cannot remove is
+ * left in place: the run's state is already written by then, so failing here
+ * would abort a run that exists, and every retry would abort the same way.
+ */
+export declare function createRun(root: string, state: MigrateRunState): void;
+export {};

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

@@ -0,0 +1,438 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NewerRunStateFormatError = exports.SHELL_SAFE_VALUE = exports.RUN_STATE_FILE_NAME = exports.CURRENT_RUN_STATE_FORMAT_VERSION = void 0;
+exports.migrateRunsDir = migrateRunsDir;
+exports.runDir = runDir;
+exports.runHandoffsDir = runHandoffsDir;
+exports.readRunState = readRunState;
+exports.writeRunState = writeRunState;
+exports.hasRunState = hasRunState;
+exports.findActiveRun = findActiveRun;
+exports.createRun = createRun;
+const fs_1 = require("fs");
+const crypto_1 = require("crypto");
+const path_1 = require("path");
+const fileutils_1 = require("../../../utils/fileutils");
+const git_utils_1 = require("../../../utils/git-utils");
+const versions_1 = require("../../../utils/versions");
+const types_1 = require("../agentic/types");
+const run_id_1 = require("./run-id");
+const text_1 = require("../text");
+exports.CURRENT_RUN_STATE_FORMAT_VERSION = 1;
+exports.RUN_STATE_FILE_NAME = 'run.json';
+/**
+ * The charset a migration id must stay inside to be interpolated into a
+ * dispensed command. The outer agent executes those verbatim, so hostile ids
+ * are refused rather than quoted per-platform (POSIX quoting is no defense in
+ * cmd.exe). Enforced twice: on the incoming plan at init, so a bad id never
+ * starts a run, and here on read, so a run whose persisted ids were tampered
+ * with fails closed as corrupt instead of being dispensed.
+ */
+exports.SHELL_SAFE_VALUE = /^[A-Za-z0-9@/:._-]+$/;
+// `new Date().toISOString()`, the only shape Nx writes. Retention and active-run
+// selection compare these lexicographically, and the value is rendered into the
+// stdout the agent scans for blocks, so neither a different notation nor an
+// embedded newline can be tolerated.
+const ISO_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+/**
+ * A round's snapshot is a file Nx writes next to `run.json`, so the recorded
+ * name is a bare `plan-<round>.json`. Pinning the whole name is what keeps a
+ * tampered value from resolving outside the run directory when the worker
+ * joins it, and from reaching stdout with a line break in it when the worker
+ * reports the snapshot missing.
+ */
+const PLAN_SNAPSHOT_NAME = /^plan-\d+\.json$/;
+/**
+ * Nx numbers its steps off the plan, so a recorded id is a bare `step-<n>`.
+ * The state machine names the id back in the reason it rejects an illegal
+ * transition with, and the worker throws that reason, which puts it in front
+ * of the agent without passing the block-safe writer.
+ */
+const STEP_ID = /^step-\d+$/;
+// Keeps `.nx/migrate-runs` from growing unbounded across many `nx migrate`
+// invocations over the life of a workspace.
+const MAX_RETAINED_COMPLETED_RUNS = 5;
+// Closed sets are declared as const arrays so the derived types and the
+// runtime validation in `readRunState` cannot drift apart (same pattern as
+// STEP_ACTIONS in step-actions.ts).
+const MIGRATE_RUN_STATUSES = ['active', 'completed'];
+const MIGRATE_STEP_STATUSES = [
+    'pending',
+    'dispensed',
+    'running',
+    'awaiting-prompt-outcome',
+    'succeeded',
+    'failed',
+    'skipped',
+    'died',
+];
+const PROMPT_OUTCOME_STATUSES = ['completed', 'skipped', 'failed'];
+const MIGRATE_COMMIT_KINDS = ['checkpoint', 'landed', 'failed'];
+const REQUIRED_TOP_LEVEL_FIELDS = [
+    'formatVersion',
+    'runId',
+    'createdAt',
+    'nxVersion',
+    'status',
+    'createCommits',
+    'commitPrefix',
+    'rounds',
+    'steps',
+    'commits',
+    'analytics',
+];
+function migrateRunsDir(root) {
+    return (0, path_1.join)(root, types_1.MIGRATE_RUNS_RELATIVE_DIR);
+}
+function runDir(root, runId) {
+    return (0, path_1.join)(migrateRunsDir(root), runId);
+}
+/** See `HANDOFFS_DIR_NAME` for why the subtree exists. */
+function runHandoffsDir(runDirPath) {
+    return (0, path_1.join)(runDirPath, types_1.HANDOFFS_DIR_NAME);
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+const REQUIRED_ARRAY_FIELDS = [
+    'rounds',
+    'steps',
+    'commits',
+];
+const REQUIRED_STRING_FIELDS = [
+    'runId',
+    'createdAt',
+    'nxVersion',
+    'status',
+    'commitPrefix',
+];
+function isOneOf(values, value) {
+    return (typeof value === 'string' && values.includes(value));
+}
+function isOptionalString(value) {
+    return value === undefined || typeof value === 'string';
+}
+function isOptionalNumber(value) {
+    return value === undefined || typeof value === 'number';
+}
+function isOptionalBoolean(value) {
+    return value === undefined || typeof value === 'boolean';
+}
+// A recorded `git rev-parse` output. `RegExp.test` stringifies its argument,
+// so a numeric 1234 would pass the hex test without the type check.
+function isOptionalSha(value) {
+    return (value === undefined || (typeof value === 'string' && git_utils_1.GIT_SHA.test(value)));
+}
+function isOptionalStringArray(value) {
+    return (value === undefined ||
+        (Array.isArray(value) && value.every((item) => typeof item === 'string')));
+}
+function isRoundShape(value) {
+    return (isPlainObject(value) &&
+        typeof value.index === 'number' &&
+        typeof value.planHash === 'string' &&
+        typeof value.planSnapshot === 'string' &&
+        PLAN_SNAPSHOT_NAME.test(value.planSnapshot));
+}
+function isStepOutcomeShape(value) {
+    return (value === undefined ||
+        (isPlainObject(value) &&
+            isOptionalStringArray(value.fileChanges) &&
+            isOptionalSha(value.gitRefAfter) &&
+            isOptionalStringArray(value.nextSteps) &&
+            isOptionalString(value.summary)));
+}
+function isPromptOutcomeShape(value) {
+    return (value === undefined ||
+        (isPlainObject(value) &&
+            isOneOf(PROMPT_OUTCOME_STATUSES, value.status) &&
+            isOptionalString(value.summary)));
+}
+function isStepShape(value) {
+    return (isPlainObject(value) &&
+        typeof value.id === 'string' &&
+        STEP_ID.test(value.id) &&
+        typeof value.roundIndex === 'number' &&
+        typeof value.migrationId === 'string' &&
+        exports.SHELL_SAFE_VALUE.test(value.migrationId) &&
+        isOneOf(MIGRATE_STEP_STATUSES, value.status) &&
+        typeof value.attempt === 'number' &&
+        typeof value.dispenseCount === 'number' &&
+        isOptionalBoolean(value.hasGenerator) &&
+        isOptionalNumber(value.pid) &&
+        isOptionalString(value.startedAt) &&
+        isOptionalString(value.finishedAt) &&
+        isOptionalSha(value.gitRefBefore) &&
+        isOptionalBoolean(value.treeCleanAtDispense) &&
+        isOptionalString(value.depsHashAtDispense) &&
+        isStepOutcomeShape(value.outcome) &&
+        isPromptOutcomeShape(value.promptOutcome) &&
+        isOptionalBoolean(value.generatorCompleted) &&
+        isOptionalBoolean(value.installFailed) &&
+        // A cross-field invariant the rest of the loop relies on: a running step
+        // without a pid is never reclassified as died and no step action targets
+        // it, so it stalls the run forever.
+        (value.status === 'running' ? typeof value.pid === 'number' : true));
+}
+function isCommitLedgerEntryShape(value) {
+    return (isPlainObject(value) &&
+        isOneOf(MIGRATE_COMMIT_KINDS, value.kind) &&
+        Array.isArray(value.stepIds) &&
+        value.stepIds.every((id) => typeof id === 'string' && STEP_ID.test(id)) &&
+        isOptionalSha(value.sha));
+}
+function isAnalyticsShape(value) {
+    return (isPlainObject(value) &&
+        typeof value.startEmitted === 'boolean' &&
+        typeof value.completeEmitted === 'boolean');
+}
+// A field present with the wrong type must fail here, not reach a
+// `.find`/iteration deep in the worker or orchestrator as a raw TypeError.
+// That includes array elements (`steps: [null]`) and closed-set values: a
+// mangled `status` would otherwise read as neither active nor completed and
+// let a competing run start on top of this one.
+function hasValidRunStateShape(parsed) {
+    return (REQUIRED_ARRAY_FIELDS.every((field) => Array.isArray(parsed[field])) &&
+        REQUIRED_STRING_FIELDS.every((field) => typeof parsed[field] === 'string') &&
+        ISO_TIMESTAMP.test(parsed.createdAt) &&
+        typeof parsed.formatVersion === 'number' &&
+        typeof parsed.createCommits === 'boolean' &&
+        isOneOf(MIGRATE_RUN_STATUSES, parsed.status) &&
+        isOptionalBoolean(parsed.checkpointFailed) &&
+        isOptionalBoolean(parsed.skipInstall) &&
+        parsed.rounds.every(isRoundShape) &&
+        parsed.steps.every(isStepShape) &&
+        parsed.commits.every(isCommitLedgerEntryShape) &&
+        isAnalyticsShape(parsed.analytics));
+}
+function corruptRunStateError(filePath, reason) {
+    return new Error(`Corrupt run state at ${filePath}: ${reason}`);
+}
+/**
+ * Thrown when a run.json declares a `formatVersion` newer than this Nx
+ * understands. Callers must not treat such a run as absent: an older Nx
+ * ignoring a newer active run would start a competing run on top of it.
+ *
+ * Adding a member to any persisted closed set (run status, step status,
+ * prompt-outcome status, commit kind) needs a
+ * `CURRENT_RUN_STATE_FORMAT_VERSION` bump: without it, an older Nx reading
+ * the new value would reject the run as corrupt (the closed-set validation
+ * fails) instead of refusing with this error's ask for a newer Nx.
+ */
+class NewerRunStateFormatError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'NewerRunStateFormatError';
+    }
+}
+exports.NewerRunStateFormatError = NewerRunStateFormatError;
+/**
+ * Reads and validates `run.json` from a run directory.
+ *
+ * A `formatVersion` newer than {@link CURRENT_RUN_STATE_FORMAT_VERSION} means
+ * the run was created by a newer Nx than the one currently running, so the
+ * shape may not be interpretable here; this throws rather than attempting a
+ * best-effort read. An older `formatVersion` is returned as-is: only v1
+ * exists today, so there is nothing to migrate yet.
+ */
+function readRunState(runDirPath) {
+    const filePath = (0, path_1.join)(runDirPath, exports.RUN_STATE_FILE_NAME);
+    const content = (0, fs_1.readFileSync)(filePath, 'utf-8');
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch {
+        throw corruptRunStateError(filePath, 'not valid JSON.');
+    }
+    if (!isPlainObject(parsed)) {
+        throw corruptRunStateError(filePath, 'is missing required fields or has fields of an unexpected type.');
+    }
+    // Version refusal must precede shape validation: a newer format may change a
+    // field's type on purpose, and classifying that as corruption would surface
+    // it as a corrupt run to fix or remove, when the real remediation is
+    // re-running with the newer Nx that owns it.
+    if (typeof parsed.formatVersion === 'number' &&
+        parsed.formatVersion > exports.CURRENT_RUN_STATE_FORMAT_VERSION) {
+        // This refusal runs before the shape check, so `nxVersion` has not been
+        // validated yet and the error carrying it leaves through handleErrors,
+        // which prints the message's own lines rather than the block-safe writer.
+        const createdBy = typeof parsed.nxVersion === 'string'
+            ? `Nx ${(0, text_1.singleLine)(parsed.nxVersion)}`
+            : 'a newer version of Nx';
+        throw new NewerRunStateFormatError(`This migrate run was created with ${createdBy} (run state format v${parsed.formatVersion}), which is newer than the Nx version currently running, ${versions_1.nxVersion} (run state format v${exports.CURRENT_RUN_STATE_FORMAT_VERSION}). Re-run your migrate command with ${createdBy} or later to resume this run.`);
+    }
+    if (REQUIRED_TOP_LEVEL_FIELDS.some((field) => !(field in parsed)) ||
+        !hasValidRunStateShape(parsed)) {
+        throw corruptRunStateError(filePath, 'is missing required fields or has fields of an unexpected type.');
+    }
+    // The directory name is the run id every caller reached this state through,
+    // so a run.json naming a different one is not this run: the commands built
+    // from the persisted copy would send the agent somewhere else.
+    if (parsed.runId !== (0, path_1.basename)(runDirPath)) {
+        // Collapsed, then quoted: the rejected value is the untrusted one and this
+        // reason reaches the stdout the agent scans for blocks. Quoting alone
+        // would not do it, since JSON.stringify leaves the Unicode line separators
+        // literal.
+        throw corruptRunStateError(filePath, `declares run id ${JSON.stringify((0, text_1.singleLine)(parsed.runId))} but sits in a directory named ${JSON.stringify((0, text_1.singleLine)((0, path_1.basename)(runDirPath)))}.`);
+    }
+    return parsed;
+}
+/**
+ * Writes `run.json` atomically: serializes to a temp file in the same
+ * directory, then renames over the real path. A crash mid-write can only
+ * ever leave the stale temp file behind, never a half-written run.json.
+ *
+ * Rename gives per-write atomicity only. Serializing the read-modify-write
+ * sequences that concurrent nx migrate processes run is state-lock.ts's job.
+ */
+function writeRunState(runDirPath, state) {
+    const filePath = (0, path_1.join)(runDirPath, exports.RUN_STATE_FILE_NAME);
+    const tmpPath = `${filePath}~${(0, crypto_1.randomBytes)(4).toString('hex')}`;
+    (0, fileutils_1.writeJsonFile)(tmpPath, state);
+    (0, fs_1.renameSync)(tmpPath, filePath);
+}
+// ENOENT is the ordinary "no runs yet" answer. Any other failure (EACCES,
+// ENOTDIR) hides runs that may exist, so it propagates rather than reading
+// as an empty directory.
+function readDirEntries(dir) {
+    try {
+        return (0, fs_1.readdirSync)(dir, { withFileTypes: true });
+    }
+    catch (e) {
+        if (e?.code === 'ENOENT')
+            return [];
+        throw e;
+    }
+}
+// Whether a directory holds a run at all. False for a path that doesn't exist
+// (a run id the user made up) and for one that does but holds no run.json (a
+// legacy per-version agentic scratch dir).
+function hasRunState(runDirPath) {
+    return (0, fs_1.existsSync)((0, path_1.join)(runDirPath, exports.RUN_STATE_FILE_NAME));
+}
+// Corrupt run.json reads as null; a newer-format run.json propagates so
+// callers can't mistake an incompatible run for an absent one.
+function readRunDirState(candidateDir) {
+    if (!hasRunState(candidateDir))
+        return null;
+    try {
+        return readRunState(candidateDir);
+    }
+    catch (e) {
+        if (e instanceof NewerRunStateFormatError)
+            throw e;
+        return null;
+    }
+}
+/**
+ * Scans for the newest active run. A dir that holds a run.json but could be an
+ * active run this caller cannot use is returned as `uninterpretable` instead
+ * of being silently skipped: treating it as absent would let a run-starting
+ * caller create a competing run that re-applies migrations the first run
+ * already applied. That covers unreadable or corrupt content, where whether
+ * the run is active cannot be determined, and an active run in a dir whose
+ * name fails {@link RUN_ID_SAFE}, which cannot be resumed either.
+ *
+ * A dir that reads cleanly as a finished run is skipped whatever its name is:
+ * it competes with nothing, and reporting it would block every future run
+ * with no way for retention to ever clear it.
+ *
+ * Throws {@link NewerRunStateFormatError} when any run dir holds a
+ * newer-format run.json: whether that run is active can't be determined
+ * here, and its remediation (a newer Nx) differs from the uninterpretable
+ * one (fix or remove).
+ */
+function findActiveRun(root) {
+    let newest = null;
+    const uninterpretable = [];
+    for (const entry of readDirEntries(migrateRunsDir(root))) {
+        if (!entry.isDirectory())
+            continue;
+        const dir = (0, path_1.join)(migrateRunsDir(root), entry.name);
+        if (!hasRunState(dir))
+            continue;
+        let state;
+        try {
+            // Safe for any dir name: the path comes from the directory entry, never
+            // from a value interpolated into a command.
+            state = readRunState(dir);
+        }
+        catch (e) {
+            if (e instanceof NewerRunStateFormatError)
+                throw e;
+            uninterpretable.push({
+                dirName: entry.name,
+                reason: e instanceof Error ? e.message : String(e),
+            });
+            continue;
+        }
+        if (state.status !== 'active')
+            continue;
+        // Run ids are joined into paths and interpolated into dispensed commands,
+        // so a dir whose name fails the gate is never trusted as a resumable run.
+        if (!run_id_1.RUN_ID_SAFE.test(entry.name)) {
+            uninterpretable.push({
+                dirName: entry.name,
+                reason: 'its name is not a valid run id',
+            });
+            continue;
+        }
+        if (!newest || state.createdAt > newest.state.createdAt) {
+            newest = { runId: entry.name, state };
+        }
+    }
+    return { active: newest, uninterpretable };
+}
+/**
+ * Creates a new run directory and writes its initial state, then prunes old
+ * completed runs so `.nx/migrate-runs` doesn't grow unbounded: only the
+ * newest {@link MAX_RETAINED_COMPLETED_RUNS} completed runs are kept. Active
+ * runs, the run just created, and legacy per-version runner dirs (no
+ * run.json) are never pruned.
+ *
+ * Retention is best effort. A dir it cannot interpret or cannot remove is
+ * left in place: the run's state is already written by then, so failing here
+ * would abort a run that exists, and every retry would abort the same way.
+ */
+function createRun(root, state) {
+    const dir = runDir(root, state.runId);
+    // Created up front, and each step's package directory at dispense, so the
+    // agent never has to `mkdir -p`: that costs a workspace-permission prompt in
+    // agents like Claude Code, on every step.
+    (0, fs_1.mkdirSync)(runHandoffsDir(dir), { recursive: true });
+    writeRunState(dir, state);
+    pruneCompletedRuns(root, state.runId);
+}
+function pruneCompletedRuns(root, justCreatedRunId) {
+    const dir = migrateRunsDir(root);
+    const completed = [];
+    for (const entry of readDirEntries(dir)) {
+        if (!entry.isDirectory() || entry.name === justCreatedRunId)
+            continue;
+        let state;
+        try {
+            state = readRunDirState((0, path_1.join)(dir, entry.name));
+        }
+        catch {
+            // A newer-format run belongs to a newer Nx; leave it for that Nx to
+            // manage rather than pruning what can't be interpreted here.
+            continue;
+        }
+        if (state?.status === 'completed') {
+            completed.push({ runId: entry.name, createdAt: state.createdAt });
+        }
+    }
+    completed
+        .sort((a, b) => a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0)
+        .slice(MAX_RETAINED_COMPLETED_RUNS)
+        .forEach((stale) => {
+        try {
+            (0, fs_1.rmSync)((0, path_1.join)(dir, stale.runId), { recursive: true, force: true });
+        }
+        catch {
+            // Guarded per dir so one that cannot be removed (permissions, a file
+            // still held open) neither aborts the run nor stops the others.
+        }
+    });
+}