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

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

@@ -30,6 +30,7 @@ const tar_1 = require("../../utils/tar");
 const write_formatted_json_file_1 = require("../../utils/write-formatted-json-file");
 const shell_quoting_1 = require("../../utils/shell-quoting");
 const logger_1 = require("../../utils/logger");
+const native_1 = require("../../native");
 const git_utils_1 = require("../../utils/git-utils");
 const package_json_1 = require("../../utils/package-json");
 const package_manager_1 = require("../../utils/package-manager");
@@ -709,13 +710,24 @@ async function parseTargetPackageAndVersion(args) {
 async function parseMigrationsOptions(options, fetch) {
     // A run recorded or reconciled via `--run-id` is driven by the outer agent;
     // spawning another agent from it would double-drive the run. Only the
-    // explicit "on" values conflict; the nx.json default is ignored for
-    // `--run-id` invocations instead.
+    // explicit "on" values conflict; the nx.json default is not applied to
+    // those invocations instead. The `--run-migrations` shape is the
+    // exception: there `--run-id` names the run a continue re-enters, or the
+    // one a `--start-fresh` replaces.
     if (options.runId !== undefined &&
         options.agentic !== undefined &&
-        options.agentic !== false) {
+        options.agentic !== false &&
+        options.runMigrations === undefined) {
         throw new Error(`Error: '--agentic' cannot be combined with '--run-id'.`);
     }
+    if (options.startFresh === true) {
+        if (options.runMigrations === undefined) {
+            throw new Error(`Error: '--start-fresh' requires '--run-migrations'.`);
+        }
+        if (options.runId === undefined) {
+            throw new Error(`Error: '--start-fresh' requires '--run-id=<id>' naming the run to replace; the report prints it.`);
+        }
+    }
     if (options.runMigration !== undefined) {
         if (options.runMigration === '') {
             throw new Error(`Error: '--run-migration' requires a migration id, e.g. '--run-migration=@nx/js:my-migration'.`);
@@ -754,8 +766,16 @@ async function parseMigrationsOptions(options, fetch) {
         if (options.runId === '') {
             throw new Error(`Error: '--run-id' requires the id of the migrate run to record into.`);
         }
-        if (options.runMigrations !== undefined) {
-            throw new Error(`Error: '--run-id' (reconcile an orchestrated run) cannot be combined with '--run-migrations' (run the whole migrations file).`);
+        // With `--run-migrations`, `--run-id` continues the named run, which needs
+        // `--agentic`; a start-fresh names the run it replaces instead.
+        if (options.runMigrations !== undefined &&
+            options.startFresh !== true &&
+            (options.agentic === undefined || options.agentic === false)) {
+            throw new Error(`Error: '--run-id' (reconcile an orchestrated run) cannot be combined with '--run-migrations' (run the whole migrations file). To continue the run, pass '--agentic' (or '--agentic=<agent>') as well.`);
+        }
+        if (options.runMigrations !== undefined &&
+            options.stepAction !== undefined) {
+            throw new Error(`Error: '--step-action' cannot be combined with '--run-migrations'.`);
         }
         // A bare '--run-id' reconciles the run it names. Ungated, unlike init:
         // the id has to name a run directory that exists, and only a gated init
@@ -765,13 +785,15 @@ async function parseMigrationsOptions(options, fetch) {
         if (options.stepAction !== undefined && !(0, step_actions_1.isStepAction)(options.stepAction)) {
             throw new Error(`Error: '--step-action' must be one of ${step_actions_1.STEP_ACTIONS.join(', ')}.`);
         }
-        return {
-            type: 'orchestratorReconcile',
-            runId: options.runId,
-            ...(options.stepAction !== undefined
-                ? { stepAction: options.stepAction }
-                : {}),
-        };
+        if (options.runMigrations === undefined) {
+            return {
+                type: 'orchestratorReconcile',
+                runId: options.runId,
+                ...(options.stepAction !== undefined
+                    ? { stepAction: options.stepAction }
+                    : {}),
+            };
+        }
     }
     if (options.stepAction !== undefined) {
         throw new Error(`Error: '--step-action' requires '--run-id'.`);
@@ -792,7 +814,10 @@ async function parseMigrationsOptions(options, fetch) {
             ifExists: options.ifExists,
             agentic: options.agentic,
             validate: options.validate,
+            finalValidation: options.finalValidation,
             interactive: options.interactive,
+            ...(options.runId !== undefined ? { runId: options.runId } : {}),
+            ...(options.startFresh === true ? { startFresh: true } : {}),
         };
     }
     assertOptionalIncludeFlagCompatibility(options);
@@ -1227,7 +1252,7 @@ async function getPackageMigrationsConfigFromRegistry(packageName, packageVersio
     if (!result) {
         return null;
     }
-    const json = JSON.parse(result);
+    const json = (0, package_manager_1.parseRegistryViewJson)(result);
     if (!json['nx-migrations'] && !json['ng-update']) {
         const registry = new node_url_1.URL('dist' in json ? json.dist.tarball : json.tarball)
             .hostname;
@@ -2092,6 +2117,9 @@ async function executeMigrations(root, migrations, isVerbose, shouldCreateCommit
         retainedAtSuccess: (0, migrate_output_1.retainedMigrations)(outcomes).map((p) => `${p.package}: ${p.name}`),
     };
 }
+function orchestratorFlagNeedsOrchestrator(flag) {
+    return `'${flag}' acts on an orchestrated migrate run (NX_MIGRATE_ORCHESTRATOR=true with an enabled agent), and this invocation is not orchestrated.`;
+}
 // nx is located at spawn time, after the gated pre-install, so the child runs
 // the bytes that install put in place.
 function handOffToLocalNx(args) {
@@ -2106,31 +2134,92 @@ function handOffToLocalNx(args) {
     return exitCode !== 0 ? exitCode : undefined;
 }
 async function runMigrations(root, opts, args, isVerbose, shouldCreateCommits, commitPrefix, shouldSkipInstall = false) {
+    // Both flags act on an orchestrated run: refuse them where none can run
+    // (an explicit --agentic=false outside an agent cannot reach one either),
+    // before the install and before --if-exists could return silently.
+    const orchestratorFlag = opts.startFresh === true
+        ? '--start-fresh'
+        : opts.runId !== undefined
+            ? '--run-id'
+            : undefined;
+    if (orchestratorFlag !== undefined &&
+        (process.env.NX_MIGRATE_ORCHESTRATOR !== 'true' ||
+            (opts.agentic === false && !(0, inception_1.isInsideAgent)()))) {
+        throw new Error(orchestratorFlagNeedsOrchestrator(orchestratorFlag));
+    }
+    const isContinue = opts.runId !== undefined && opts.startFresh !== true;
+    let continued;
+    if (isContinue) {
+        // Before the install: a concurrent start-fresh must not delete the run
+        // this command is about to continue.
+        const { holdRunToContinue } = require('./run');
+        continued = holdRunToContinue(root, opts.runId);
+    }
+    else if (opts.startFresh === true) {
+        // Before the install too: with no active run there is nothing to replace.
+        const { activeRunToReplace } = require('./run');
+        activeRunToReplace(root, opts.runId);
+    }
     if (!shouldSkipInstall && !process.env.NX_MIGRATE_SKIP_INSTALL) {
         await (0, execute_migration_1.runInstall)();
     }
     if (!__dirname.startsWith(workspace_root_1.workspaceRoot)) {
         // we are running from a temp installation with nx latest, switch to running
         // from local installation
+        if (isContinue) {
+            // The child holds the run itself and refuses while this process does.
+            const { releaseRunToHandOff } = require('./run');
+            releaseRunToHandOff(root, opts.runId);
+        }
         return handOffToLocalNx(args);
     }
-    const migrationsExists = (0, fileutils_1.fileExists)(opts.runMigrations);
-    if (opts.ifExists && !migrationsExists) {
-        output_1.output.log({
-            title: `Migrations file '${opts.runMigrations}' doesn't exist`,
-        });
-        return;
+    let migrationsJson;
+    if (isContinue) {
+        // A continue runs the plan the run recorded, not whatever the workspace's
+        // migrations file holds now (it may be gone, or belong to another plan).
+        const { latestRound, runDir } = require('./run');
+        const round = latestRound(continued);
+        if (!round) {
+            throw new Error(`Migrate run '${opts.runId}' records no plan.`);
+        }
+        migrationsJson = (0, fileutils_1.readJsonFile)((0, path_1.join)(runDir(root, opts.runId), round.planSnapshot));
     }
-    else if (!opts.ifExists && !migrationsExists) {
-        throw new Error(`File '${opts.runMigrations}' doesn't exist, can't run migrations. Use flag --if-exists to run migrations only if the file exists`);
+    else {
+        const migrationsExists = (0, fileutils_1.fileExists)(opts.runMigrations);
+        if (opts.ifExists && !migrationsExists) {
+            output_1.output.log({
+                title: `Migrations file '${opts.runMigrations}' doesn't exist`,
+            });
+            return;
+        }
+        else if (!opts.ifExists && !migrationsExists) {
+            throw new Error(`File '${opts.runMigrations}' doesn't exist, can't run migrations. Use flag --if-exists to run migrations only if the file exists`);
+        }
+        migrationsJson = (0, fileutils_1.readJsonFile)((0, path_1.join)(root, opts.runMigrations));
     }
-    const migrationsJson = (0, fileutils_1.readJsonFile)((0, path_1.join)(root, opts.runMigrations));
     const migrations = migrationsJson.migrations;
+    // Defer the nx package lookup until an orchestrated branch needs this payload.
+    const orchestratorInitInput = (createCommits) => ({
+        root,
+        migrationsJson,
+        migrationsPath: opts.runMigrations,
+        createCommits,
+        commitPrefix,
+        // The flag only, never NX_MIGRATE_SKIP_INSTALL: the wrapper's local
+        // re-exec sets that env var for its own hop, and it says nothing about
+        // what the user asked for.
+        skipInstall: shouldSkipInstall,
+        installedNxVersion: (0, package_json_1.readModulePackageJson)('nx', (0, installation_directory_1.getNxRequirePaths)(root))
+            .packageJson.version,
+        validate: opts.validate,
+        finalValidation: opts.finalValidation,
+    });
     // An outer agent drives the loop, so hand off to the orchestrator instead of
-    // the classic loop: init either starts a fresh run or resumes an already-
-    // active one. `--run-id` reconciles are dispatched separately and never
-    // reach here.
+    // the classic loop: init starts a fresh run or reports an already-active
+    // one; `--run-id` continues that run. Bare `--run-id` reconciles are
+    // dispatched separately and never reach here.
     if (process.env.NX_MIGRATE_ORCHESTRATOR === 'true' && (0, inception_1.isInsideAgent)()) {
+        const { runOrchestratorInit, runOrchestratorResume } = require('./run');
         // Orchestrated runs are agent-driven, so commits default on exactly as they
         // do under `--agentic=enabled`; the orchestrator replaces `resolveAgentic`.
         const { effective: effectiveCreateCommits, warning: createCommitsWarning, error: createCommitsError, } = (0, migrate_commits_1.resolveCreateCommits)({
@@ -2145,26 +2234,50 @@ async function runMigrations(root, opts, args, isVerbose, shouldCreateCommits, c
         if (createCommitsWarning) {
             output_1.output.warn({ title: createCommitsWarning });
         }
-        // The run commits on the user's behalf across many invocations, so the
-        // default-branch confirmation belongs here, once, before any of them.
-        if (effectiveCreateCommits &&
-            (0, safe_prompt_1.canPrompt)(opts.interactive) &&
-            !(await (0, migrate_commits_1.confirmMigrationCommitsOnDefaultBranch)(root, 'running migrations'))) {
+        if (isContinue) {
+            runOrchestratorResume({
+                root,
+                runId: opts.runId,
+                policy: {
+                    createCommits: effectiveCreateCommits,
+                    skipInstall: shouldSkipInstall,
+                },
+            });
             return;
         }
-        const { packageJson: orchestratorNxPackageJson } = (0, package_json_1.readModulePackageJson)('nx', (0, installation_directory_1.getNxRequirePaths)(root));
-        const { runOrchestratorInit } = require('./run');
-        return await runOrchestratorInit({
-            root,
-            migrationsJson,
-            createCommits: effectiveCreateCommits,
-            commitPrefix,
-            // The flag only, never NX_MIGRATE_SKIP_INSTALL: the wrapper's local
-            // re-exec sets that env var for its own hop, and it says nothing about
-            // what the user asked for.
-            skipInstall: shouldSkipInstall,
-            installedNxVersion: orchestratorNxPackageJson.version,
+        // The run commits on the user's behalf across many invocations and the
+        // agent driving it cannot answer a terminal prompt, so a commit policy the
+        // user never asked for stops the run on the default branch before any of
+        // them. `--create-commits` or nx.json `migrate.createCommits` is that ask.
+        // Asked by init only once it is about to start a run: an active run is
+        // reported instead, and keeps its own policy.
+        const refuseCommitsOnDefaultBranch = async () => {
+            if (!effectiveCreateCommits || shouldCreateCommits !== undefined) {
+                return true;
+            }
+            const defaultBranch = (0, migrate_commits_1.currentBranchIfDefault)(root);
+            if (!defaultBranch) {
+                return true;
+            }
+            output_1.output.log({
+                title: `Not starting the run: you are on the default branch '${defaultBranch}' and nx migrate would create a commit for each migration on it.`,
+                bodyLines: [
+                    'Ask the user how to proceed, then either:',
+                    '- re-run with --create-commits to commit on this branch for this run,',
+                    '- set "migrate": { "createCommits": true } in nx.json to always allow it, then re-run,',
+                    '- or switch to another branch and re-run.',
+                ],
+            });
+            return false;
+        };
+        const init = orchestratorInitInput(effectiveCreateCommits);
+        await runOrchestratorInit({
+            ...init,
+            onExistingRun: opts.startFresh === true ? 'start-fresh' : 'report',
+            ...(opts.startFresh === true ? { replaceRunId: opts.runId } : {}),
+            confirmStart: refuseCommitsOnDefaultBranch,
         });
+        return;
     }
     (0, migrate_analytics_1.reportMigrateRunStart)({
         createCommits: shouldCreateCommits ?? false,
@@ -2195,9 +2308,33 @@ async function runMigrations(root, opts, args, isVerbose, shouldCreateCommits, c
     if (createCommitsWarning) {
         output_1.output.warn({ title: createCommitsWarning });
     }
-    if (effectiveCreateCommits &&
-        (0, safe_prompt_1.canPrompt)(opts.interactive) &&
-        !(await (0, migrate_commits_1.confirmMigrationCommitsOnDefaultBranch)(root, 'running migrations'))) {
+    // Asked only for a run this invocation starts: the master session hands it
+    // to init, which asks once it is about to start one; a continued run keeps
+    // the policy it was started with.
+    const confirmNewRunCommits = async () => !effectiveCreateCommits ||
+        !(0, safe_prompt_1.canPrompt)(opts.interactive) ||
+        (0, migrate_commits_1.confirmMigrationCommitsOnDefaultBranch)(root, 'running migrations');
+    // Dark: with the env var set, the agent drives the whole run through the
+    // orchestrator from one session instead of being spawned per step. Not
+    // under WASM, where the broker has no native lock to detect a dead parent.
+    if (agentic.kind === 'enabled' &&
+        process.env.NX_MIGRATE_ORCHESTRATOR === 'true' &&
+        !native_1.IS_WASM) {
+        const init = orchestratorInitInput(effectiveCreateCommits);
+        const { runMasterSession } = require('./agentic/master/run-master-session');
+        return await runMasterSession({
+            ...init,
+            agent: agentic.selectedAgent,
+            interactive: opts.interactive,
+            runId: opts.runId,
+            startFresh: opts.startFresh,
+            confirmStart: confirmNewRunCommits,
+        });
+    }
+    if (orchestratorFlag !== undefined) {
+        throw new Error(orchestratorFlagNeedsOrchestrator(orchestratorFlag));
+    }
+    if (!(await confirmNewRunCommits())) {
         return;
     }
     const shouldRunValidation = resolveShouldRunValidation({
@@ -2412,7 +2549,7 @@ function stringifyCaught(e) {
         }
     }
 }
-// A resolver-based lookup (including `resolvePackageJsonWithoutCachePollution`,
+// A resolver-based lookup (including `resolveWithoutCachePollution`,
 // which does defeat Node's package self-reference) is the wrong tool here:
 // resolvers fall back to NODE_PATH after the explicit paths, and NODE_PATH
 // names the temp installation when this runs there. The scan below reads its

package/dist/src/command-line/migrate/resolve-package-version.js

@@ -15,6 +15,7 @@ const policy_1 = require("../../utils/min-release-age/policy");
 const pnpm_exclude_writer_1 = require("../../utils/min-release-age/pnpm-exclude-writer");
 const resolve_1 = require("../../utils/min-release-age/resolve");
 const safe_prompt_1 = require("./safe-prompt");
+const text_1 = require("./text");
 /**
  * Whether nx migrate should resolve versions via the npm registry (fast) rather
  * than via a real package-manager install. Precedence, highest first:
@@ -195,7 +196,7 @@ async function handleViolation(packageName, error, policy) {
     // sorted newest-first, so the resolver's pick is the last entry. Mirror the
     // loose path: prompt for, exclude, and return that one version.
     const resolved = error.blocked[error.blocked.length - 1];
-    const blockedLine = `  ${packageName}@${resolved.version} (published ${formatPublishAge(resolved.publishedAt)})`;
+    const blockedLine = `  ${packageName}@${resolved.version} (published ${(0, text_1.formatAge)(resolved.publishedAt)})`;
     // pnpm prompts once for the whole run; remember an approval for later picks.
     if (!strictApprovalGranted) {
         const approved = await (0, safe_prompt_1.migrateConfirm)({
@@ -225,21 +226,3 @@ async function handleViolation(packageName, error, policy) {
     ]);
     return resolved.version;
 }
-// Renders a registry ISO publish timestamp as a human age for the strict prompt
-// (e.g. "6 hours ago"), falling back to the raw value when it is not parseable.
-function formatPublishAge(publishedAt) {
-    const elapsedMs = Date.now() - Date.parse(publishedAt);
-    if (!Number.isFinite(elapsedMs) || elapsedMs < 0) {
-        return publishedAt;
-    }
-    const minutes = Math.floor(elapsedMs / 60_000);
-    if (minutes < 60) {
-        return `${minutes} minute${minutes === 1 ? '' : 's'} ago`;
-    }
-    const hours = Math.floor(elapsedMs / 3_600_000);
-    if (hours < 48) {
-        return `${hours} hour${hours === 1 ? '' : 's'} ago`;
-    }
-    const days = Math.floor(elapsedMs / 86_400_000);
-    return `${days} day${days === 1 ? '' : 's'} ago`;
-}

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

@@ -18,3 +18,14 @@ export declare function logToAgent(message: AgentMessage): void;
 export declare function warnToAgent(message: AgentMessage): void;
 export declare function emitStepBlock(runId: string, stepId: string, action: string, payload: object): void;
 export declare function emitPromptBlock(migrationId: string, payload: object): void;
+export declare function emitStepPromptBlock(stepId: string, payload: object): void;
+/**
+ * Markdown, not JSON: the block carries the runbook file's bytes, so the agent
+ * reads what a resume re-emits from disk. Every `<` opening or closing an
+ * `<nx_migrate_*>` tag is neutralized wherever it sits: a positional check
+ * (line starts plus a blank-character class) can be sidestepped by characters
+ * that render as nothing but match no enumerable class. The renderer never
+ * emits the literal sequence (runbook.spec pins that), so only tampered bytes
+ * change.
+ */
+export declare function emitRunbookBlock(runId: string, content: string): void;

package/dist/src/command-line/migrate/run/agent-output.js

@@ -15,6 +15,8 @@ exports.logToAgent = logToAgent;
 exports.warnToAgent = warnToAgent;
 exports.emitStepBlock = emitStepBlock;
 exports.emitPromptBlock = emitPromptBlock;
+exports.emitStepPromptBlock = emitStepPromptBlock;
+exports.emitRunbookBlock = emitRunbookBlock;
 const output_1 = require("../../../utils/output");
 const print_dropped_agent_context_1 = require("../agentic/print-dropped-agent-context");
 const text_1 = require("../text");
@@ -47,11 +49,11 @@ function blockPayload(payload) {
     return JSON.stringify(payload, null, 2).replace(/</g, '\\u003c');
 }
 // A bare newline pair frames the block so adjacent stdout cannot run into it.
-function writeBlock(tag, attrs, json) {
+function writeBlock(tag, attrs, body) {
     const attrText = attrs
         .map(([name, value]) => ` ${name}="${(0, print_dropped_agent_context_1.escapeXmlAttr)((0, text_1.singleLine)(value))}"`)
         .join('');
-    process.stdout.write(`\n<${tag}${attrText}>\n${json}\n</${tag}>\n\n`);
+    process.stdout.write(`\n<${tag}${attrText}>\n${body}\n</${tag}>\n\n`);
 }
 function emitStepBlock(runId, stepId, action, payload) {
     writeBlock('nx_migrate_step', [
@@ -63,3 +65,20 @@ function emitStepBlock(runId, stepId, action, payload) {
 function emitPromptBlock(migrationId, payload) {
     writeBlock('nx_migrate_prompt', [['migration', migrationId]], blockPayload(payload));
 }
+// For work that belongs to no migration (the final-validation step).
+function emitStepPromptBlock(stepId, payload) {
+    writeBlock('nx_migrate_prompt', [['step', stepId]], blockPayload(payload));
+}
+/**
+ * Markdown, not JSON: the block carries the runbook file's bytes, so the agent
+ * reads what a resume re-emits from disk. Every `<` opening or closing an
+ * `<nx_migrate_*>` tag is neutralized wherever it sits: a positional check
+ * (line starts plus a blank-character class) can be sidestepped by characters
+ * that render as nothing but match no enumerable class. The renderer never
+ * emits the literal sequence (runbook.spec pins that), so only tampered bytes
+ * change.
+ */
+function emitRunbookBlock(runId, content) {
+    const neutralized = content.replace(/<(?=\/?nx_migrate_)/gi, '\\u003c');
+    writeBlock('nx_migrate_runbook', [['run-id', runId]], neutralized);
+}

package/dist/src/command-line/migrate/run/agent-work-payload.d.ts

@@ -0,0 +1,37 @@
+import type { MigrateStepAwaitingKind } from './run-state';
+export declare function agentWorkPayloadPath(runDirPath: string, stepId: string, attempt: number): string;
+export interface ExpectedAgentWorkPayload {
+    migrationId: string;
+    kind: MigrateStepAwaitingKind;
+    promptPath?: string;
+}
+/**
+ * Failures propagate: the runbook promises a parked step's block is
+ * re-emitted, so a caller that cannot store the payload must fail the attempt
+ * rather than park.
+ */
+export declare function persistAgentWorkPayload(filePath: string, payload: object): void;
+/**
+ * The stored payload, or null when nothing usable is on disk: the file is
+ * missing (the park predates this mechanism), does not parse to a plain
+ * object, or does not match what the step awaits. Null is undifferentiated on
+ * purpose: every caller's remediation is the same freshly derived payload.
+ * The returned object is never re-emitted as text; both re-emission sites go
+ * back through the block writer's escaping, so a tampered file cannot break
+ * the framing.
+ */
+export declare function readAgentWorkPayload(filePath: string, expected: ExpectedAgentWorkPayload): Record<string, unknown> | null;
+/**
+ * Returns the newest payload from the current generator lineage, or null.
+ * `fromAttempt` excludes generator runs discarded by reset-backed retries; an
+ * absent boundary fails closed for states written by older Nx.
+ */
+export declare function latestStoredAgentWorkPayload(runDirPath: string, stepId: string, beforeAttempt: number, fromAttempt: number | undefined, expected: ExpectedAgentWorkPayload): Record<string, unknown> | null;
+/**
+ * Best effort per file: the callers run after the outcome or rearm is already
+ * decided, so an entry that cannot be removed (a permission failure, a
+ * directory planted at the path) is left to whole-run pruning rather than
+ * failing the reconcile. A planted directory is never re-handed either way:
+ * reading it fails, which the reader treats as no stored copy.
+ */
+export declare function removeAgentWorkPayloads(runDirPath: string, stepId: string, throughAttempt: number): void;

package/dist/src/command-line/migrate/run/agent-work-payload.js

@@ -0,0 +1,156 @@
+"use strict";
+// Internal to run/: deliberately not re-exported from ./index.
+//
+// Persists each parked payload by step and attempt, so a reconcile can re-emit
+// it after a compaction or restart without reusing payloads from discarded
+// attempts.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentWorkPayloadPath = agentWorkPayloadPath;
+exports.persistAgentWorkPayload = persistAgentWorkPayload;
+exports.readAgentWorkPayload = readAgentWorkPayload;
+exports.latestStoredAgentWorkPayload = latestStoredAgentWorkPayload;
+exports.removeAgentWorkPayloads = removeAgentWorkPayloads;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const atomic_write_1 = require("./atomic-write");
+const AGENT_WORK_DIR_NAME = 'agent-work';
+// Both segments are Nx-issued (`step-<n>` and the attempt counter), so the
+// name never carries untrusted path segments.
+function agentWorkPayloadPath(runDirPath, stepId, attempt) {
+    return (0, path_1.join)(runDirPath, AGENT_WORK_DIR_NAME, `${stepId}-attempt-${attempt}.json`);
+}
+/**
+ * Failures propagate: the runbook promises a parked step's block is
+ * re-emitted, so a caller that cannot store the payload must fail the attempt
+ * rather than park.
+ */
+function persistAgentWorkPayload(filePath, payload) {
+    (0, fs_1.mkdirSync)((0, path_1.dirname)(filePath), { recursive: true });
+    (0, atomic_write_1.publishFileAtomically)(filePath, (tmpPath) => (0, fs_1.writeFileSync)(tmpPath, JSON.stringify(payload, null, 2)));
+}
+/**
+ * The stored payload, or null when nothing usable is on disk: the file is
+ * missing (the park predates this mechanism), does not parse to a plain
+ * object, or does not match what the step awaits. Null is undifferentiated on
+ * purpose: every caller's remediation is the same freshly derived payload.
+ * The returned object is never re-emitted as text; both re-emission sites go
+ * back through the block writer's escaping, so a tampered file cannot break
+ * the framing.
+ */
+function readAgentWorkPayload(filePath, expected) {
+    let content;
+    try {
+        content = (0, fs_1.readFileSync)(filePath, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return null;
+    }
+    const payload = parsed;
+    if (payload.migrationId !== expected.migrationId) {
+        return null;
+    }
+    let matchesKind;
+    switch (expected.kind) {
+        case 'generator-validation':
+            matchesKind = payload.kind === 'generator-validation';
+            break;
+        case 'migration-prompt':
+            matchesKind =
+                payload.kind === undefined &&
+                    expected.promptPath !== undefined &&
+                    payload.prompt === expected.promptPath;
+            break;
+        case 'final-validation':
+            // Derived from run state at every dispense; nothing is stored.
+            throw new Error('The final validation pass stores no agent-work payload.');
+        default: {
+            const exhaustive = expected.kind;
+            throw new Error(`Unhandled awaiting kind '${exhaustive}'.`);
+        }
+    }
+    return matchesKind ? payload : null;
+}
+/**
+ * Returns the newest payload from the current generator lineage, or null.
+ * `fromAttempt` excludes generator runs discarded by reset-backed retries; an
+ * absent boundary fails closed for states written by older Nx.
+ */
+function latestStoredAgentWorkPayload(runDirPath, stepId, beforeAttempt, fromAttempt, expected) {
+    if (fromAttempt === undefined) {
+        return null;
+    }
+    // Enumerated from disk rather than counted down from `beforeAttempt`:
+    // attempts are persisted numbers, and a loop spanning their range would
+    // let a tampered-but-valid counter drive that many synchronous reads.
+    const candidates = storedAttemptsForStep(runDirPath, stepId)
+        .filter((attempt) => attempt >= fromAttempt && attempt < beforeAttempt)
+        .sort((a, b) => b - a);
+    for (const attempt of candidates) {
+        const payload = readAgentWorkPayload(agentWorkPayloadPath(runDirPath, stepId, attempt), expected);
+        if (payload) {
+            return payload;
+        }
+    }
+    return null;
+}
+// An unreadable directory reads as empty: the lookup falls back to a freshly
+// derived payload, and removal is best effort. The `-attempt-` infix keeps
+// `step-1` from matching `step-12`'s files.
+function storedAttemptsForStep(runDirPath, stepId) {
+    let entries;
+    try {
+        entries = (0, fs_1.readdirSync)((0, path_1.join)(runDirPath, AGENT_WORK_DIR_NAME));
+    }
+    catch {
+        return [];
+    }
+    const prefix = `${stepId}-attempt-`;
+    const suffix = '.json';
+    const attempts = [];
+    for (const name of entries) {
+        if (!name.startsWith(prefix) || !name.endsWith(suffix)) {
+            continue;
+        }
+        const middle = name.slice(prefix.length, -suffix.length);
+        if (!/^[1-9]\d*$/.test(middle)) {
+            continue;
+        }
+        const attempt = Number(middle);
+        if (Number.isSafeInteger(attempt)) {
+            attempts.push(attempt);
+        }
+    }
+    return attempts;
+}
+/**
+ * Best effort per file: the callers run after the outcome or rearm is already
+ * decided, so an entry that cannot be removed (a permission failure, a
+ * directory planted at the path) is left to whole-run pruning rather than
+ * failing the reconcile. A planted directory is never re-handed either way:
+ * reading it fails, which the reader treats as no stored copy.
+ */
+function removeAgentWorkPayloads(runDirPath, stepId, throughAttempt) {
+    // Enumerated for the same reason as the lookup: a tampered-but-valid attempt
+    // would otherwise drive that many synchronous removals.
+    for (const attempt of storedAttemptsForStep(runDirPath, stepId)) {
+        if (attempt > throughAttempt) {
+            continue;
+        }
+        try {
+            (0, fs_1.rmSync)(agentWorkPayloadPath(runDirPath, stepId, attempt), {
+                force: true,
+            });
+        }
+        catch { }
+    }
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Runs `write` against a unique sibling temp path, then renames it over
+ * `filePath`: a crash mid-write can only leave a stale temp file, never a
+ * half-written artifact, and rename replaces whatever sits at the destination
+ * without following it. The random suffix keeps concurrent writers apart; a
+ * pid would collide across PID namespaces sharing the workspace.
+ */
+export declare function publishFileAtomically(filePath: string, write: (tmpPath: string) => void): void;

package/dist/src/command-line/migrate/run/atomic-write.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.publishFileAtomically = publishFileAtomically;
+const crypto_1 = require("crypto");
+const fs_1 = require("fs");
+/**
+ * Runs `write` against a unique sibling temp path, then renames it over
+ * `filePath`: a crash mid-write can only leave a stale temp file, never a
+ * half-written artifact, and rename replaces whatever sits at the destination
+ * without following it. The random suffix keeps concurrent writers apart; a
+ * pid would collide across PID namespaces sharing the workspace.
+ */
+function publishFileAtomically(filePath, write) {
+    const tmpPath = `${filePath}~${(0, crypto_1.randomBytes)(4).toString('hex')}`;
+    write(tmpPath);
+    (0, fs_1.renameSync)(tmpPath, filePath);
+}