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

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

@@ -0,0 +1,228 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRegistryResolutionEnabled = isRegistryResolutionEnabled;
+exports.resetResolvePackageVersionState = resetResolvePackageVersionState;
+exports.resolvePackageVersionRespectingMinReleaseAge = resolvePackageVersionRespectingMinReleaseAge;
+const configuration_1 = require("../../config/configuration");
+const is_ci_1 = require("../../utils/is-ci");
+const logger_1 = require("../../utils/logger");
+const output_1 = require("../../utils/output");
+const catalog_1 = require("../../utils/catalog");
+const package_manager_1 = require("../../utils/package-manager");
+const workspace_root_1 = require("../../utils/workspace-root");
+const errors_1 = require("../../utils/min-release-age/errors");
+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:
+ *
+ * 1. `NX_MIGRATE_USE_REGISTRY_RESOLUTION` ('true' -> enabled, 'false' -> disabled)
+ * 2. legacy `NX_MIGRATE_SKIP_REGISTRY_FETCH` (deprecated, removed in Nx 24;
+ *    'true' -> disabled, 'false' -> enabled)
+ * 3. nx.json `migrate.useRegistryResolution`
+ * 4. default: enabled
+ */
+function isRegistryResolutionEnabled(root = workspace_root_1.workspaceRoot) {
+    warnIfLegacyRegistryEnvVarSet();
+    const explicit = parseBooleanFlag(process.env.NX_MIGRATE_USE_REGISTRY_RESOLUTION);
+    if (explicit !== undefined) {
+        return explicit;
+    }
+    // Legacy env is inverted: SKIP_REGISTRY_FETCH=true disables resolution.
+    const legacy = parseBooleanFlag(process.env.NX_MIGRATE_SKIP_REGISTRY_FETCH);
+    if (legacy !== undefined) {
+        return !legacy;
+    }
+    return (0, configuration_1.readNxJson)(root)?.migrate?.useRegistryResolution ?? true;
+}
+function parseBooleanFlag(value) {
+    return value === 'true' ? true : value === 'false' ? false : undefined;
+}
+// NX_MIGRATE_SKIP_REGISTRY_FETCH is the inverted, legacy predecessor of
+// NX_MIGRATE_USE_REGISTRY_RESOLUTION: deprecated in Nx 23, removed in Nx 24.
+// Warn once whenever it is present (even when the new var overrides it) so users
+// migrate off it and clean up configs where it lingers - a dormant value would
+// silently re-activate if the new var were later removed.
+function warnIfLegacyRegistryEnvVarSet() {
+    if (legacyRegistryEnvVarDeprecationWarned ||
+        process.env.NX_MIGRATE_SKIP_REGISTRY_FETCH === undefined) {
+        return;
+    }
+    legacyRegistryEnvVarDeprecationWarned = true;
+    const bodyLines = [
+        'Use NX_MIGRATE_USE_REGISTRY_RESOLUTION (or migrate.useRegistryResolution in nx.json) instead, then remove NX_MIGRATE_SKIP_REGISTRY_FETCH from your environment.',
+    ];
+    if (process.env.NX_MIGRATE_USE_REGISTRY_RESOLUTION !== undefined) {
+        bodyLines.push('It is currently being overridden by NX_MIGRATE_USE_REGISTRY_RESOLUTION.');
+    }
+    output_1.output.warn({
+        title: 'NX_MIGRATE_SKIP_REGISTRY_FETCH is deprecated and will be removed in Nx 24.',
+        bodyLines,
+    });
+}
+// The cooldown policy is constant for a migrate run; read it once.
+let cachedPolicyPromise;
+// Dedup the "resolved X instead of Y" notice across repeated specs.
+const reportedChangedOutcomes = new Set();
+// Strict-mode approval is a once-per-run decision (mirrors pnpm prompting once).
+let strictApprovalGranted = false;
+// The deprecated NX_MIGRATE_SKIP_REGISTRY_FETCH heads-up is shown once per run.
+let legacyRegistryEnvVarDeprecationWarned = false;
+/** Test-only: clear the module-level caches between cases. */
+function resetResolvePackageVersionState() {
+    cachedPolicyPromise = undefined;
+    reportedChangedOutcomes.clear();
+    strictApprovalGranted = false;
+    legacyRegistryEnvVarDeprecationWarned = false;
+}
+function getPolicy() {
+    cachedPolicyPromise ??= (0, policy_1.readMinReleaseAgePolicy)();
+    return cachedPolicyPromise;
+}
+/**
+ * The single resolution entry point for ALL nx migrate version resolutions. It
+ * resolves a package spec to a concrete version while honoring the effective
+ * minimum-release-age (cooldown) policy of the user's package manager, matching
+ * how that PM at its detected version would resolve. Falls back to a real PM
+ * install when the policy can't be reasoned about, or when registry resolution
+ * is opted out.
+ */
+async function resolvePackageVersionRespectingMinReleaseAge(packageName, version, options) {
+    // A speculative lookup (e.g. populating multi-major prompt choices) sets this
+    // to false so resolving a version the user has not chosen yet never prompts,
+    // writes pnpm excludes, or triggers a real install.
+    const applySideEffects = options?.applySideEffects ?? true;
+    // A probe can never install, so the registry-resolution opt-out (which only
+    // picks install vs. registry for the real resolution) does not apply to it: it
+    // is always registry-based. Resolve read-only while still reproducing an active
+    // cooldown so the probe predicts the same version a real install would accept.
+    if (!applySideEffects) {
+        return resolveProbe(packageName, version);
+    }
+    if (!isRegistryResolutionEnabled()) {
+        return (0, package_manager_1.resolvePackageVersionUsingInstallation)(packageName, version);
+    }
+    const result = await getPolicy();
+    if (result.outcome === 'inactive') {
+        return (0, package_manager_1.resolvePackageVersionUsingRegistry)(packageName, version);
+    }
+    if (result.outcome === 'ambiguous') {
+        logger_1.logger.verbose(`Cannot determine the minimum-release-age policy (${result.reason}); falling back to a package-manager install to resolve ${packageName}@${version}.`);
+        return (0, package_manager_1.resolvePackageVersionUsingInstallation)(packageName, version);
+    }
+    return resolveWithPolicy(packageName, version, result.policy, true);
+}
+/**
+ * Read-only resolution for speculative lookups (never installs, never prompts,
+ * never writes excludes). Reproduces an active cooldown policy off the registry
+ * so the probe's pick matches what a real install would accept. Degrades to the
+ * raw latest-in-range when there is no policy to reproduce (inactive) or it
+ * cannot be reasoned about (ambiguous) - the same read-only answer the real
+ * resolution would refine via a package-manager install.
+ */
+async function resolveProbe(packageName, version) {
+    const result = await getPolicy();
+    if (result.outcome !== 'active') {
+        return (0, package_manager_1.resolvePackageVersionUsingRegistry)(packageName, version);
+    }
+    return resolveWithPolicy(packageName, version, result.policy, false);
+}
+async function resolveWithPolicy(packageName, version, policy, applySideEffects) {
+    try {
+        const spec = (0, catalog_1.resolveCatalogReferenceIfNeeded)(packageName, version);
+        const outcome = await (0, resolve_1.resolveCompliantVersion)(packageName, spec, policy);
+        if (applySideEffects && outcome.version !== outcome.unconstrained) {
+            reportChangedOutcome(packageName, spec, outcome.version, outcome.unconstrained, policy);
+        }
+        // An immature loose pick is returned as-is. nx does not write the
+        // minimumReleaseAgeExclude entry here: migrate does not replace the install,
+        // so the real `pnpm install` (>=11.1.3) auto-writes it itself.
+        return outcome.version;
+    }
+    catch (e) {
+        // A side-effect-free probe never installs/prompts/writes, so any failure -
+        // a violation or an unknown error - just means the version is unavailable.
+        if (!applySideEffects) {
+            throw e;
+        }
+        if (e instanceof errors_1.MinReleaseAgeViolationError) {
+            return handleViolation(packageName, e, policy);
+        }
+        // Unknown failure (registry hiccup, parse error): try a real install, but
+        // surface the original error if that also fails.
+        try {
+            return await (0, package_manager_1.resolvePackageVersionUsingInstallation)(packageName, version);
+        }
+        catch {
+            throw e;
+        }
+    }
+}
+function reportChangedOutcome(packageName, spec, picked, unconstrained, policy) {
+    const key = `${packageName}@${spec}`;
+    if (reportedChangedOutcomes.has(key)) {
+        return;
+    }
+    reportedChangedOutcomes.add(key);
+    output_1.output.log({
+        title: `Resolved ${packageName}@${picked} instead of ${unconstrained}: ${policy.sourceDescription}.`,
+    });
+}
+async function handleViolation(packageName, error, policy) {
+    const isPnpmStrict = policy.behavior.packageManager === 'pnpm' &&
+        policy.behavior.strict &&
+        policy.behavior.writesExcludes;
+    if (!isPnpmStrict) {
+        throw error;
+    }
+    // An unknown tag yields a violation with no blocked candidates (nothing to
+    // approve); surface the original no-matching-version error rather than
+    // prompting over an empty list.
+    if (error.blocked.length === 0) {
+        throw error;
+    }
+    // pnpm gates its prompt on stdin (the surface enquirer reads); match that
+    // rather than stdout, which diverges when output is piped.
+    const canPrompt = !!process.stdin.isTTY && !(0, is_ci_1.isCI)();
+    if (!canPrompt) {
+        throw error;
+    }
+    // pnpm's loose resolver picks the lowest in-range version (a single exact/tag
+    // target otherwise); strict fails on exactly that pick. error.blocked is
+    // 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 ${(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)({
+            initial: false,
+            message: `The following version does not meet the ${policy.sourceDescription} constraint:\n${blockedLine}\nInstall anyway and add it to minimumReleaseAgeExclude in pnpm-workspace.yaml?`,
+        });
+        if (!approved) {
+            // Deny must surface as a violation: migrate.ts only rethrows
+            // MinReleaseAgeViolationError, so a plain Error would silently fall back
+            // to a real PM install and defeat the deny gate. Shape it like pnpm's
+            // ERR_PNPM_MINIMUM_RELEASE_AGE_DENIED.
+            throw new errors_1.MinReleaseAgeViolationError({
+                packageManager: error.packageManager,
+                packageName: error.packageName,
+                spec: error.spec,
+                pmShapedDetail: 'Aborted: the immature versions were not approved.',
+                blocked: error.blocked,
+                remediation: [
+                    `Add ${packageName} (optionally with a version) to minimumReleaseAgeExclude in pnpm-workspace.yaml, or re-run without minimumReleaseAgeStrict to allow these versions.`,
+                ],
+            });
+        }
+        strictApprovalGranted = true;
+    }
+    (0, pnpm_exclude_writer_1.appendMinimumReleaseAgeExcludes)(workspace_root_1.workspaceRoot, [
+        `${packageName}@${resolved.version}`,
+    ]);
+    return resolved.version;
+}

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

@@ -0,0 +1,31 @@
+/**
+ * Lines are kept unjoined all the way here on purpose. Joining them and
+ * splitting them back turns an injected break into its own entry before this
+ * module sees it, indistinguishable from a line the caller meant to write, and
+ * nothing downstream can undo that.
+ */
+export interface AgentMessage {
+    title: string;
+    bodyLines?: string[];
+}
+/**
+ * The safe form of a set of lines. Exported so a caller that needs the same
+ * text twice, once for a human and once inside a block payload, derives both
+ * from one array instead of sanitizing one copy and not the other.
+ */
+export declare function safeLines(lines: readonly string[]): string[];
+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

@@ -0,0 +1,84 @@
+"use strict";
+// Internal to run/: deliberately not re-exported from ./index.
+//
+// The single writer for everything an orchestrated run puts on stdout. Human
+// lines and the `<nx_migrate_*>` blocks the driving agent parses share that one
+// stream, so a value carrying its own line break could open a forged block.
+//
+// Two boundaries: a thrown error leaves through handleErrors, which prints it
+// outside this guarantee; and migration code is not contained at all (nx
+// `require`s and runs it in process), so the guarantee is that data cannot
+// corrupt the framing, nothing more.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.safeLines = safeLines;
+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");
+/**
+ * The safe form of a set of lines. Exported so a caller that needs the same
+ * text twice, once for a human and once inside a block payload, derives both
+ * from one array instead of sanitizing one copy and not the other.
+ */
+function safeLines(lines) {
+    return lines.map(text_1.singleLine);
+}
+function safe(message) {
+    return {
+        title: (0, text_1.singleLine)(message.title),
+        bodyLines: safeLines(message.bodyLines ?? []),
+    };
+}
+function logToAgent(message) {
+    output_1.output.log(safe(message));
+}
+function warnToAgent(message) {
+    output_1.output.warn(safe(message));
+}
+/**
+ * Serializes a block payload. `<` becomes its JSON unicode escape so a raw one
+ * in a value cannot forge the closing tag, and the result stays valid JSON for
+ * the agent to parse.
+ */
+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, 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${body}\n</${tag}>\n\n`);
+}
+function emitStepBlock(runId, stepId, action, payload) {
+    writeBlock('nx_migrate_step', [
+        ['run-id', runId],
+        ['step', stepId],
+        ['action', action],
+    ], blockPayload(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);
+}