@ohos-ports/nx 23.2.1-beta.0 → 23.3.0-beta.0

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

@@ -0,0 +1,669 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NewerRunStateFormatError = exports.TREE_OPERATION_KINDS = exports.MIGRATE_ISSUE_DISPOSITIONS = exports.TERMINAL_STEP_STATUSES = exports.ISSUE_ID = exports.SHELL_SAFE_VALUE = exports.RUN_STATE_FILE_NAME = exports.CURRENT_RUN_STATE_FORMAT_VERSION = void 0;
+exports.issueFingerprint = issueFingerprint;
+exports.migrateRunsDir = migrateRunsDir;
+exports.runDir = runDir;
+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 atomic_write_1 = require("./atomic-write");
+const git_utils_1 = require("../../../utils/git-utils");
+const versions_1 = require("../../../utils/versions");
+const types_1 = require("../agentic/types");
+const handoff_1 = require("../agentic/handoff");
+const run_id_1 = require("./run-id");
+const text_1 = require("../text");
+exports.CURRENT_RUN_STATE_FORMAT_VERSION = 1;
+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{1,18}$/;
+// The id names the archived detail file in the run's issues directory, so a
+// tampered value must not resolve outside it. The suffix is bounded so the
+// allocator, which mints against this same pattern, can never produce an id
+// past the filesystem's component limit and then fail forever.
+exports.ISSUE_ID = /^issue-\d{1,18}$/;
+/**
+ * A resume joins this to the run directory and re-emits the file's bytes
+ * verbatim, so a tampered value naming a sibling (`run.json`, a plan
+ * snapshot) would leak that file's bytes past every line-safety check.
+ */
+const RUNBOOK_NAME = /^RUNBOOK\.md$/;
+// The terminators `singleLine` collapses. An embedded one could open a forged
+// block at a line start in the stdout the agent scans.
+const LINE_TERMINATORS = /[\r\n\u000b\u000c\u0085\u2028\u2029]/;
+// 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',
+    'unresolved',
+];
+// 'failed' and 'died' can be re-armed; 'unresolved' cannot.
+exports.TERMINAL_STEP_STATUSES = new Set([
+    'succeeded',
+    'skipped',
+    'unresolved',
+]);
+const PROMPT_OUTCOME_STATUSES = ['completed', 'skipped', 'failed'];
+const MIGRATE_STEP_AWAITING_KINDS = [
+    'migration-prompt',
+    'generator-validation',
+    'final-validation',
+];
+// What a step does when dispensed: 'migration' runs one planned migration,
+// 'final-validation' checks the whole workspace once every migration has run.
+const MIGRATE_STEP_KINDS = ['migration', 'final-validation'];
+const MIGRATE_COMMIT_KINDS = ['checkpoint', 'landed', 'failed'];
+/**
+ * Dedup key: the same underlying problem reported twice folds into one ledger
+ * entry. Derived from the normalized summary, so agent text never becomes a
+ * path or command fragment; the state reader re-checks the derivation on
+ * every persisted entry.
+ */
+function issueFingerprint(summary) {
+    return (0, crypto_1.createHash)('sha256')
+        .update(summary.toLowerCase().replace(/\s+/g, ' ').trim())
+        .digest('hex')
+        .slice(0, 16);
+}
+exports.MIGRATE_ISSUE_DISPOSITIONS = [
+    'recorded',
+    'resolved',
+    'deferred-final',
+];
+exports.TREE_OPERATION_KINDS = [
+    'commit',
+    'install',
+    'fold-install',
+    'action-install',
+    'reset',
+    'give-up',
+    'checkpoint',
+];
+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 isOptionalMatching(pattern, value) {
+    return (value === undefined || (typeof value === 'string' && pattern.test(value)));
+}
+function isLineSafeString(value) {
+    return typeof value === 'string' && !LINE_TERMINATORS.test(value);
+}
+function isStepIdArray(value) {
+    return (Array.isArray(value) &&
+        value.every((id) => typeof id === 'string' && STEP_ID.test(id)));
+}
+function isRoundShape(value) {
+    return (isPlainObject(value) &&
+        typeof value.index === 'number' &&
+        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 isStepKindShape(value) {
+    const kind = value.kind === undefined ? 'migration' : value.kind;
+    if (!isOneOf(MIGRATE_STEP_KINDS, kind))
+        return false;
+    switch (kind) {
+        case 'migration':
+            return (typeof value.migrationId === 'string' &&
+                exports.SHELL_SAFE_VALUE.test(value.migrationId));
+        case 'final-validation':
+            return value.migrationId === undefined;
+        default: {
+            const exhaustive = kind;
+            throw new Error(`Unhandled step kind '${exhaustive}'.`);
+        }
+    }
+}
+function isStepShape(value) {
+    return (isPlainObject(value) &&
+        typeof value.id === 'string' &&
+        STEP_ID.test(value.id) &&
+        typeof value.roundIndex === 'number' &&
+        isStepKindShape(value) &&
+        isOneOf(MIGRATE_STEP_STATUSES, value.status) &&
+        // The attempt is interpolated into the stored-payload file name and
+        // range-compared against it (agent-work-payload.ts), so a fractional or
+        // non-finite value (JSON's 1e400 parses to Infinity) must be refused here.
+        Number.isSafeInteger(value.attempt) &&
+        value.attempt >= 1 &&
+        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) &&
+        (value.awaitingKind === undefined ||
+            isOneOf(MIGRATE_STEP_AWAITING_KINDS, value.awaitingKind)) &&
+        isOptionalBoolean(value.commitStarted) &&
+        isOptionalBoolean(value.generatorCompleted) &&
+        // Bounded by the step's attempt: a higher value could not name one that
+        // exists.
+        (value.generatorCompletedAtAttempt === undefined ||
+            (Number.isSafeInteger(value.generatorCompletedAtAttempt) &&
+                value.generatorCompletedAtAttempt >= 1 &&
+                value.generatorCompletedAtAttempt <=
+                    value.attempt)) &&
+        (value.commitLedgerIndex === undefined ||
+            (Number.isSafeInteger(value.commitLedgerIndex) &&
+                value.commitLedgerIndex >= 0)) &&
+        isOptionalBoolean(value.agenticWaived) &&
+        isOptionalBoolean(value.validationOwed) &&
+        isOptionalBoolean(value.generatorMadeChanges) &&
+        isOptionalBoolean(value.installFailed) &&
+        isOptionalBoolean(value.adopted) &&
+        isOptionalMatching(exports.ISSUE_ID, value.unresolvedIssueId) &&
+        // Minted by the same write that gives the step up, so it never names a
+        // step in any other status.
+        (value.unresolvedIssueId === undefined || value.status === 'unresolved') &&
+        // 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) &&
+        isStepIdArray(value.stepIds) &&
+        isOptionalSha(value.sha) &&
+        (value.issueIds === undefined ||
+            (Array.isArray(value.issueIds) &&
+                value.issueIds.every((id) => typeof id === 'string' && exports.ISSUE_ID.test(id)))));
+}
+// The id names the archived `issues/<id>.json`, so a duplicate would alias two
+// entries onto one file. Runs after isIssueShape, so the ids are known strings.
+function hasUniqueIssueIds(issues) {
+    return (new Set(issues.map((issue) => issue.id)).size ===
+        issues.length);
+}
+// A duplicate would make every step lookup ambiguous, and a bare-package
+// report against it would write applicability this same reader rejects.
+function hasUniqueStepIds(steps) {
+    return (new Set(steps.map((step) => step.id)).size ===
+        steps.length);
+}
+// The fingerprint is the duplicate-report fold key; two entries sharing one
+// would make ledger order decide which entry a report folds into.
+function hasUniqueIssueFingerprints(issues) {
+    return (new Set(issues.map((issue) => issue.fingerprint)).size === issues.length);
+}
+// Cross-entry references, checked after the per-entry shapes so the casts
+// hold. nx never writes these violations, and the helpers that trust the
+// fields (routing, resolver credit, carried checks) cannot repair them.
+function hasSoundIssueRefs(parsed) {
+    const issues = parsed.issues;
+    const steps = parsed.steps;
+    const stepIds = new Set(steps.map((s) => s.id));
+    const stepOrder = new Map(steps.map((s, index) => [s.id, index]));
+    const commitCount = parsed.commits.length;
+    return issues.every((issue) => stepIds.has(issue.reportedByStepId) &&
+        (issue.applicableStepIds === 'unknown' ||
+            (issue.applicableStepIds.every((id) => stepIds.has(id)) &&
+                // Applicability is a plan-ordered set (mints and merges both emit it that
+                // way): a duplicate would read as newly supplied routing in the normalizing
+                // merge, and an unordered scope is a shape no transition writes.
+                issue.applicableStepIds.every((id, index) => index === 0 ||
+                    stepOrder.get(issue.applicableStepIds[index - 1]) <
+                        stepOrder.get(id)))) &&
+        (issue.claimedByStepId === undefined ||
+            (Array.isArray(issue.applicableStepIds) &&
+                issue.applicableStepIds.includes(issue.claimedByStepId))) &&
+        (issue.resolvedByStepId === undefined ||
+            stepIds.has(issue.resolvedByStepId)) &&
+        (issue.resolvedAtCommitCount === undefined ||
+            issue.resolvedAtCommitCount <= commitCount));
+}
+function isIssueShape(value) {
+    return (isPlainObject(value) &&
+        typeof value.id === 'string' &&
+        exports.ISSUE_ID.test(value.id) &&
+        isLineSafeString(value.summary) &&
+        // The derivation is enforced, not just the shape: a fingerprint detached from
+        // its summary would split one problem into independent histories.
+        value.fingerprint === issueFingerprint(value.summary) &&
+        typeof value.reportedByStepId === 'string' &&
+        STEP_ID.test(value.reportedByStepId) &&
+        // Reports carry 1+ identifiers and merges only widen, so [] is unproducible.
+        (value.applicableStepIds === 'unknown' ||
+            (isStepIdArray(value.applicableStepIds) &&
+                value.applicableStepIds.length > 0)) &&
+        isOneOf(exports.MIGRATE_ISSUE_DISPOSITIONS, value.disposition) &&
+        isOptionalMatching(STEP_ID, value.claimedByStepId) &&
+        isOptionalMatching(STEP_ID, value.resolvedByStepId) &&
+        // The helpers built on these (commit association, retry-clean reverts, update
+        // ownership) break on a state outside them.
+        (value.claimedByStepId === undefined || value.disposition === 'recorded') &&
+        (value.disposition === 'resolved') ===
+            (value.resolvedByStepId !== undefined) &&
+        // A resolution without a stamp has no carried-commit window; a stamp without
+        // a resolution fences nothing that exists.
+        (value.disposition === 'resolved') ===
+            (value.resolvedAtCommitCount !== undefined) &&
+        (value.resolvedAtCommitCount === undefined ||
+            (Number.isSafeInteger(value.resolvedAtCommitCount) &&
+                value.resolvedAtCommitCount >= 0)));
+}
+// The record drives the no-progress cutoff: a count outside the positive
+// integers (JSON's 1e400 parses to Infinity) could delay it forever, and an
+// empty fingerprint would collapse unrelated responses into one streak.
+function isNoProgressShape(value) {
+    return (value === undefined ||
+        (isPlainObject(value) &&
+            isLineSafeString(value.fingerprint) &&
+            value.fingerprint.length > 0 &&
+            Number.isSafeInteger(value.consecutiveCount) &&
+            value.consecutiveCount > 0 &&
+            typeof value.firstSeenAt === 'string' &&
+            ISO_TIMESTAMP.test(value.firstSeenAt)));
+}
+function isTreeOperationShape(value) {
+    return (value === undefined ||
+        (isPlainObject(value) &&
+            isOneOf(exports.TREE_OPERATION_KINDS, value.kind) &&
+            (value.stepId === undefined || typeof value.stepId === 'string') &&
+            (value.attempt === undefined ||
+                (Number.isSafeInteger(value.attempt) &&
+                    value.attempt >= 1)) &&
+            typeof value.owner === 'string' &&
+            value.owner.length > 0 &&
+            Number.isSafeInteger(value.pid) &&
+            value.pid > 0));
+}
+function isAnalyticsShape(value) {
+    return (isPlainObject(value) &&
+        typeof value.startEmitted === 'boolean' &&
+        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) &&
+        isOptionalBoolean(parsed.validate) &&
+        isOptionalSha(parsed.gitRefAtInit) &&
+        isOptionalMatching(RUNBOOK_NAME, parsed.runbookPath) &&
+        isOptionalString(parsed.branch) &&
+        parsed.rounds.every(isRoundShape) &&
+        parsed.steps.every(isStepShape) &&
+        hasUniqueStepIds(parsed.steps) &&
+        parsed.commits.every(isCommitLedgerEntryShape) &&
+        (parsed.issues === undefined ||
+            (Array.isArray(parsed.issues) &&
+                parsed.issues.every(isIssueShape) &&
+                hasUniqueIssueIds(parsed.issues) &&
+                hasUniqueIssueFingerprints(parsed.issues) &&
+                hasSoundIssueRefs(parsed))) &&
+        // Written only for issues that already existed: a dangling id could make a
+        // future issue's resolution look carried by a commit that predates it.
+        parsed.commits.every((c) => c.issueIds === undefined ||
+            c.issueIds.every((id) => hasIssueWithId(parsed, id))) &&
+        parsed.steps.every((s) => s.unresolvedIssueId === undefined ||
+            hasIssueWithId(parsed, s.unresolvedIssueId)) &&
+        isNoProgressShape(parsed.noProgress) &&
+        isTreeOperationShape(parsed.treeOperation) &&
+        isAnalyticsShape(parsed.analytics));
+}
+function hasIssueWithId(parsed, id) {
+    return (parsed.issues ?? []).some((i) => i.id === id);
+}
+function corruptRunStateError(filePath, reason) {
+    return new Error(`Corrupt run state at ${filePath}: ${reason}`);
+}
+/**
+ * Thrown for a run.json whose `formatVersion` is 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 a persisted closed set needs a
+ * `CURRENT_RUN_STATE_FORMAT_VERSION` bump only once a released Nx can read the
+ * run, or that Nx rejects the new value as corruption instead of asking 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} throws instead of being
+ * read best-effort; an older one is returned as-is.
+ */
+function readRunState(runDirPath) {
+    const filePath = (0, path_1.join)(runDirPath, exports.RUN_STATE_FILE_NAME);
+    // run.json lives in the agent-writable run directory, so it could be a
+    // planted symlink or FIFO; read it without reading a symlink's target or
+    // blocking on a FIFO, while still tolerating a concurrent tmp + rename
+    // publish. A non-regular file reads as corruption; ENOENT stays "no run".
+    const content = (0, handoff_1.readAtomicallyPublishedFile)(filePath, corruptRunStateError(filePath, 'is not a regular file.').message);
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    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.`);
+    }
+    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)))}.`);
+    }
+    // Steps written before they had a kind each ran a migration; naming it here
+    // keeps every reader on one shape.
+    const steps = parsed.steps.map((s) => s.kind === undefined ? { ...s, kind: 'migration' } : s);
+    return { ...parsed, steps };
+}
+/**
+ * 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);
+    (0, atomic_write_1.publishFileAtomically)(filePath, (tmpPath) => (0, fileutils_1.writeJsonFile)(tmpPath, state));
+}
+// 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 activeRunIds = [];
+    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;
+        }
+        activeRunIds.push(entry.name);
+        if (!newest || state.createdAt > newest.state.createdAt) {
+            newest = { runId: entry.name, state };
+        }
+    }
+    return { active: newest, activeRunIds, 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 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.
+        }
+    });
+}

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

@@ -0,0 +1,18 @@
+export declare const RUNBOOK_FILE_NAME = "RUNBOOK.md";
+export interface RunbookContext {
+    runId: string;
+    packageManager: string;
+    nxInvocation: string;
+    pmExec: string;
+    reconcileCommand: string;
+    createCommits: boolean;
+    validate: boolean;
+    finalValidation: boolean;
+}
+/**
+ * Every interpolated value is collapsed to a single line: the rendered content
+ * is written to disk and emitted verbatim inside a `<nx_migrate_runbook>`
+ * block, so a value carrying its own line break could otherwise open a forged
+ * block at a line start.
+ */
+export declare function renderRunbook(ctx: RunbookContext): string;