@depup/nx 23.2.1-depup.7 → 23.3.0-depup.0

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

@@ -6,11 +6,3 @@ export declare const RUN_ID_SAFE: RegExp;
  * 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

@@ -2,7 +2,6 @@
 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
@@ -25,32 +24,3 @@ function compactUtcTimestamp(date) {
         .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

@@ -9,17 +9,20 @@ export declare const RUN_STATE_FILE_NAME = "run.json";
  * with fails closed as corrupt instead of being dispensed.
  */
 export declare const SHELL_SAFE_VALUE: RegExp;
+export declare const ISSUE_ID: 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'];
+declare const MIGRATE_STEP_STATUSES: readonly ['pending', 'dispensed', 'running', 'awaiting-prompt-outcome', 'succeeded', 'failed', 'skipped', 'died', 'unresolved'];
 export type MigrateStepStatus = (typeof MIGRATE_STEP_STATUSES)[number];
+export declare const TERMINAL_STEP_STATUSES: ReadonlySet<MigrateStepStatus>;
 declare const PROMPT_OUTCOME_STATUSES: readonly ['completed', 'skipped', 'failed'];
 export type PromptOutcomeStatus = (typeof PROMPT_OUTCOME_STATUSES)[number];
+declare const MIGRATE_STEP_AWAITING_KINDS: readonly ['migration-prompt', 'generator-validation', 'final-validation'];
+export type MigrateStepAwaitingKind = (typeof MIGRATE_STEP_AWAITING_KINDS)[number];
 export interface MigrateStepOutcome {
     fileChanges?: string[];
     gitRefAfter?: string;
@@ -30,10 +33,16 @@ export interface MigrateStepPromptOutcome {
     status: PromptOutcomeStatus;
     summary?: string;
 }
-export interface MigrateStep {
+export type MigrateStepKindFields = {
+    kind: 'migration';
+    migrationId: string;
+} | {
+    kind: 'final-validation';
+};
+export type MigrateStep = MigrateStepBase & MigrateStepKindFields;
+export interface MigrateStepBase {
     id: string;
     roundIndex: number;
-    migrationId: string;
     status: MigrateStepStatus;
     attempt: number;
     dispenseCount: number;
@@ -46,7 +55,16 @@ export interface MigrateStep {
     depsHashAtDispense?: string;
     outcome?: MigrateStepOutcome;
     promptOutcome?: MigrateStepPromptOutcome;
+    adopted?: boolean;
+    unresolvedIssueId?: string;
+    awaitingKind?: MigrateStepAwaitingKind;
+    commitLedgerIndex?: number;
+    commitStarted?: boolean;
     generatorCompleted?: boolean;
+    generatorCompletedAtAttempt?: number;
+    agenticWaived?: boolean;
+    validationOwed?: boolean;
+    generatorMadeChanges?: boolean;
     installFailed?: boolean;
 }
 declare const MIGRATE_COMMIT_KINDS: readonly ['checkpoint', 'landed', 'failed'];
@@ -55,11 +73,41 @@ export interface MigrateCommitLedgerEntry {
     sha?: string;
     kind: MigrateCommitKind;
     stepIds: string[];
+    issueIds?: string[];
+}
+/**
+ * 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.
+ */
+export declare function issueFingerprint(summary: string): string;
+export declare const MIGRATE_ISSUE_DISPOSITIONS: readonly ['recorded', 'resolved', 'deferred-final'];
+export type MigrateIssueDisposition = (typeof MIGRATE_ISSUE_DISPOSITIONS)[number];
+export interface MigrateRunIssue {
+    id: string;
+    fingerprint: string;
+    summary: string;
+    reportedByStepId: string;
+    applicableStepIds: string[] | 'unknown';
+    disposition: MigrateIssueDisposition;
+    claimedByStepId?: string;
+    resolvedByStepId?: string;
+    resolvedAtCommitCount?: number;
 }
 export interface MigrateRunAnalytics {
     startEmitted: boolean;
     completeEmitted: boolean;
 }
+export interface MigrateRunNoProgress {
+    fingerprint: string;
+    consecutiveCount: number;
+    firstSeenAt: string;
+}
+export interface MigrateRunPolicy {
+    createCommits: boolean;
+    skipInstall: boolean;
+}
 export interface MigrateRunState {
     formatVersion: number;
     runId: string;
@@ -69,38 +117,49 @@ export interface MigrateRunState {
     createCommits: boolean;
     commitPrefix: string;
     skipInstall?: boolean;
+    validate?: boolean;
+    gitRefAtInit?: string;
+    runbookPath?: string;
+    branch?: string;
     rounds: MigrateRunRound[];
     steps: MigrateStep[];
     commits: MigrateCommitLedgerEntry[];
+    issues?: MigrateRunIssue[];
+    noProgress?: MigrateRunNoProgress;
     checkpointFailed?: boolean;
+    treeOperation?: MigrateTreeOperation;
     analytics: MigrateRunAnalytics;
 }
+export declare const TREE_OPERATION_KINDS: readonly ['commit', 'install', 'fold-install', 'action-install', 'reset', 'give-up', 'checkpoint'];
+export type MigrateTreeOperationKind = (typeof TREE_OPERATION_KINDS)[number];
+export interface MigrateTreeOperation {
+    kind: MigrateTreeOperationKind;
+    stepId?: string;
+    attempt?: number;
+    owner: string;
+    pid: number;
+}
 export declare function migrateRunsDir(root: string): string;
 export declare function runDir(root: string, runId: string): string;
 /** See `HANDOFFS_DIR_NAME` for why the subtree exists. */
 export declare function runHandoffsDir(runDirPath: string): string;
 /**
- * Thrown when a run.json declares a `formatVersion` newer than this Nx
+ * 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 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.
+ * 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.
  */
 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.
+ * 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.
  */
 export declare function readRunState(runDirPath: string): MigrateRunState;
 /**
@@ -140,6 +199,7 @@ export declare function findActiveRun(root: string): {
         runId: string;
         state: MigrateRunState;
     } | null;
+    activeRunIds: string[];
     uninterpretable: UninterpretableRunDir[];
 };
 /**

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

@@ -1,6 +1,7 @@
 "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.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;
@@ -13,9 +14,11 @@ 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;
@@ -48,7 +51,21 @@ const PLAN_SNAPSHOT_NAME = /^plan-\d+\.json$/;
  * 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+$/;
+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;
@@ -65,9 +82,50 @@ const MIGRATE_STEP_STATUSES = [
     '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',
@@ -127,10 +185,19 @@ 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.planHash === 'string' &&
         typeof value.planSnapshot === 'string' &&
         PLAN_SNAPSHOT_NAME.test(value.planSnapshot));
 }
@@ -148,15 +215,34 @@ function isPromptOutcomeShape(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' &&
-        typeof value.migrationId === 'string' &&
-        exports.SHELL_SAFE_VALUE.test(value.migrationId) &&
+        isStepKindShape(value) &&
         isOneOf(MIGRATE_STEP_STATUSES, value.status) &&
-        typeof value.attempt === 'number' &&
+        // 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) &&
@@ -167,8 +253,29 @@ function isStepShape(value) {
         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.
@@ -177,9 +284,110 @@ function isStepShape(value) {
 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));
+        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) &&
@@ -200,24 +408,45 @@ function hasValidRunStateShape(parsed) {
         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 when a run.json declares a `formatVersion` newer than this Nx
+ * 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 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.
+ * 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) {
@@ -227,17 +456,17 @@ class NewerRunStateFormatError extends Error {
 }
 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.
+ * 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);
-    const content = (0, fs_1.readFileSync)(filePath, 'utf-8');
+    // run.json lives in the agent-writable run directory, so it could be a
+    // planted symlink or FIFO; read it without reading a symlink's target or
+    // blocking on a FIFO, while still tolerating a concurrent tmp + rename
+    // publish. A non-regular file reads as corruption; ENOENT stays "no run".
+    const content = (0, handoff_1.readAtomicallyPublishedFile)(filePath, corruptRunStateError(filePath, 'is not a regular file.').message);
     let parsed;
     try {
         parsed = JSON.parse(content);
@@ -260,7 +489,7 @@ function readRunState(runDirPath) {
         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.`);
+        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)) {
@@ -276,7 +505,10 @@ function readRunState(runDirPath) {
         // 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;
+    // 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
@@ -288,9 +520,7 @@ function readRunState(runDirPath) {
  */
 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);
+    (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
@@ -345,6 +575,7 @@ function readRunDirState(candidateDir) {
  */
 function findActiveRun(root) {
     let newest = null;
+    const activeRunIds = [];
     const uninterpretable = [];
     for (const entry of readDirEntries(migrateRunsDir(root))) {
         if (!entry.isDirectory())
@@ -378,11 +609,12 @@ function findActiveRun(root) {
             });
             continue;
         }
+        activeRunIds.push(entry.name);
         if (!newest || state.createdAt > newest.state.createdAt) {
             newest = { runId: entry.name, state };
         }
     }
-    return { active: newest, uninterpretable };
+    return { active: newest, activeRunIds, uninterpretable };
 }
 /**
  * Creates a new run directory and writes its initial state, then prunes old
@@ -397,9 +629,8 @@ function findActiveRun(root) {
  */
 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.
+    // 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);