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

package/dist/src/command-line/migrate/agentic/master/run-master-session.d.ts

@@ -0,0 +1,16 @@
+import { type RunOrchestratorInitInput } from '../../run';
+import type { DetectedInstalledAgent } from '../types';
+export interface RunMasterSessionInput extends Omit<RunOrchestratorInitInput, 'emitAgentInstructions' | 'onExistingRun'> {
+    agent: DetectedInstalledAgent;
+    interactive?: boolean;
+    runId?: string;
+    startFresh?: boolean;
+    confirmStart: () => Promise<boolean>;
+}
+/**
+ * Starts (or continues) an orchestrated run and hands it to one agent session
+ * that drives it through `--run-id` reconciles. Run state is the only
+ * authority on the outcome: the exit code follows what run.json says once the
+ * session ends, not what the agent process returned.
+ */
+export declare function runMasterSession(input: RunMasterSessionInput): Promise<number | undefined>;

package/dist/src/command-line/migrate/agentic/master/run-master-session.js

@@ -0,0 +1,175 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runMasterSession = runMasterSession;
+const output_1 = require("../../../../utils/output");
+const migrate_analytics_1 = require("../../migrate-analytics");
+const run_1 = require("../../run");
+const safe_prompt_1 = require("../../safe-prompt");
+const spawn_master_1 = require("./spawn-master");
+/**
+ * Starts (or continues) an orchestrated run and hands it to one agent session
+ * that drives it through `--run-id` reconciles. Run state is the only
+ * authority on the outcome: the exit code follows what run.json says once the
+ * session ends, not what the agent process returned.
+ */
+async function runMasterSession(input) {
+    const { agent, interactive, runId: requestedRunId, startFresh, ...init } = input;
+    // The invocation's policy; an interactive continue adopts the run's recorded
+    // one instead, shown in the report and the choice, so resume, broker and
+    // the resume hint agree with the run.
+    let policy = {
+        createCommits: init.createCommits,
+        skipInstall: init.skipInstall,
+    };
+    const resume = (runId) => (0, run_1.runOrchestratorResume)({
+        root: init.root,
+        runId,
+        policy,
+        emitAgentInstructions: false,
+    });
+    // With `replaceRunId`, starts fresh over that run only; the consent covers
+    // the run the user saw, and any other active run is reported instead.
+    const start = (replaceRunId) => (0, run_1.runOrchestratorInit)({
+        ...init,
+        emitAgentInstructions: false,
+        onExistingRun: replaceRunId === undefined ? 'report' : 'start-fresh',
+        replaceRunId,
+    });
+    let ready = requestedRunId !== undefined && !startFresh
+        ? resume(requestedRunId)
+        : await start(startFresh ? requestedRunId : undefined);
+    if (ready.kind === 'existing-run' && (0, safe_prompt_1.canPrompt)(interactive)) {
+        const decision = await decideExistingRun(ready, init.root);
+        if (decision === 'abort') {
+            output_1.output.log({
+                title: `Leaving migrate run ${ready.runId} as it is. ${continueHint(init.root, agent.id, ready.runId, ready.facts.policy)}`,
+            });
+            return;
+        }
+        if (decision === 'continue') {
+            policy = ready.facts.policy;
+            ready = resume(ready.runId);
+        }
+        else {
+            ready = await start(ready.runId);
+        }
+    }
+    if (ready.kind === 'existing-run') {
+        output_1.output.warn((0, run_1.renderExistingRunReport)(ready.facts, (0, run_1.renderExistingRunCommands)(init.root, ready.facts, init.migrationsPath, agent.id)));
+        return 1;
+    }
+    if (ready.kind === 'refused') {
+        return;
+    }
+    const { runId, runRoot, runbookPath, reconcileCommand } = ready;
+    const resumeHint = continueHint(init.root, agent.id, runId, policy);
+    output_1.output.log({
+        title: `Starting ${agent.displayName} to drive migrate run ${runId}.`,
+    });
+    const session = await (0, spawn_master_1.spawnMasterSession)({
+        agent,
+        runRoot,
+        runId,
+        runbookPath,
+        reconcileCommand,
+        policy,
+    });
+    if (session.kind === 'spawn-failed') {
+        output_1.output.error({
+            title: `Could not start ${agent.displayName}: ${session.error.message}`,
+            bodyLines: [`Migrate run ${runId} is still active. ${resumeHint}`],
+        });
+        (0, migrate_analytics_1.reportMigrateRunError)({ code: 'agentic', error: session.error });
+        return 1;
+    }
+    if (session.kind === 'broker-failed') {
+        // The broker itself reads run.json, so its failure can mean the state is
+        // unreadable; the read below decides whether a resume is safe to offer.
+        output_1.output.error({
+            title: `Closed the ${agent.displayName} session: a step's request could not be answered (${session.error.message}).`,
+        });
+        (0, migrate_analytics_1.reportMigrateRunError)({ code: 'agentic', error: session.error });
+    }
+    let state;
+    try {
+        state = (0, run_1.readRunState)((0, run_1.runDir)(runRoot, runId));
+    }
+    catch (error) {
+        // No resume hint: run discovery skips a directory whose run.json is
+        // missing, so a rerun could start a second run over the same plan.
+        output_1.output.error({
+            title: `Nx could not determine whether migrate run ${runId} completed.`,
+            bodyLines: [error instanceof Error ? error.message : String(error)],
+        });
+        return 1;
+    }
+    switch (state.status) {
+        case 'active':
+            (0, migrate_analytics_1.reportMigrateOrchestratorAbandoned)({
+                ...(0, run_1.runTallies)(state),
+                agentUsed: agent.id,
+            });
+            output_1.output.warn({
+                title: `Migrate run ${runId} is still active. ${resumeHint}`,
+            });
+            return 1;
+        case 'completed': {
+            const tally = (0, run_1.tallySteps)(state);
+            const migrations = state.steps.filter((s) => s.kind === 'migration');
+            output_1.output.log({
+                title: `Migrate run ${runId} is complete.`,
+                bodyLines: (0, run_1.completionSummaryLines)(state),
+            });
+            for (const lines of (0, run_1.completionWarnings)(runRoot, runId, state)) {
+                output_1.output.warn({ title: lines[0], bodyLines: lines.slice(1) });
+            }
+            (0, migrate_analytics_1.reportMigrateRunComplete)({
+                agenticOutcome: 'enabled',
+                agentUsed: agent.id,
+                migrationCount: migrations.length,
+                // The printed tally counts the pass; this metric counts migrations.
+                appliedCount: migrations.filter((s) => s.status === 'succeeded').length,
+            });
+            if (tally.unresolved.length > 0 || (0, run_1.hasUnresolvedIssues)(state)) {
+                output_1.output.warn({
+                    title: `Migrate run ${runId} left work unresolved; exiting with code 1.`,
+                });
+                return 1;
+            }
+            return;
+        }
+        default: {
+            const unhandled = state.status;
+            throw new Error(`Unhandled migrate run status: ${unhandled}`);
+        }
+    }
+}
+function continueHint(root, agentId, runId, policy) {
+    return `Run ${(0, run_1.renderContinueCommand)(root, runId, policy, agentId)}, with NX_MIGRATE_ORCHESTRATOR=true set in the environment, to continue it.`;
+}
+async function decideExistingRun(found, root) {
+    output_1.output.log((0, run_1.renderExistingRunReport)(found.facts));
+    // A held run leaves nothing to ask: continue would open a second session
+    // over the live one, and start fresh refuses. The continue's own gate
+    // throws the refusal; a holder gone since the report lets the prompt run.
+    if (found.facts.otherHolders === 'unknown' ||
+        found.facts.otherHolders.length > 0) {
+        (0, run_1.holdRunToContinue)(root, found.runId);
+    }
+    return (0, safe_prompt_1.migrateChoice)({
+        message: 'What do you want to do with the active migrate run?',
+        choices: [
+            {
+                value: 'continue',
+                label: 'Continue it',
+                hint: 'picks the run up where it stopped, keeping its recorded commit and install policy',
+            },
+            {
+                value: 'start-fresh',
+                label: 'Start fresh',
+                hint: 'deletes the run record only; the whole plan runs again',
+            },
+            { value: 'abort', label: 'Abort', hint: 'leaves the run as it is' },
+        ],
+    });
+}

package/dist/src/command-line/migrate/agentic/master/spawn-master.d.ts

@@ -0,0 +1,31 @@
+import { type MigrateRunPolicy } from '../../run';
+import type { DetectedInstalledAgent } from '../types';
+export interface SpawnMasterSessionInput {
+    agent: DetectedInstalledAgent;
+    runRoot: string;
+    runId: string;
+    runbookPath: string;
+    reconcileCommand: string;
+    policy: MigrateRunPolicy;
+    sentinelPollIntervalMs?: number;
+    gracefulExitMs?: number;
+    forceKillWaitMs?: number;
+}
+export type SpawnMasterSessionResult = {
+    kind: 'exited';
+} | {
+    kind: 'spawn-failed';
+    error: Error;
+} | {
+    kind: 'broker-failed';
+    error: Error;
+};
+/**
+ * Spawns the agent once, with the run's pinned invariant and bootstrap prompt,
+ * and waits for the session to end, closing it once the agent writes the
+ * session-complete sentinel. Meanwhile it answers the install and commit
+ * requests the steps the agent runs hand out of its sandbox. Every failure
+ * before the process starts is returned as `spawn-failed`; what the session
+ * did is read from run state by the caller, never from the exit code.
+ */
+export declare function spawnMasterSession(input: SpawnMasterSessionInput): Promise<SpawnMasterSessionResult>;

package/dist/src/command-line/migrate/agentic/master/spawn-master.js

@@ -0,0 +1,222 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.spawnMasterSession = spawnMasterSession;
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const logger_1 = require("../../../../utils/logger");
+const output_1 = require("../../../../utils/output");
+const migrate_output_1 = require("../../migrate-output");
+const run_1 = require("../../run");
+const close_agent_session_1 = require("../close-agent-session");
+const handoff_1 = require("../handoff");
+const terminal_repair_1 = require("../terminal-repair");
+const windows_cmd_1 = require("../windows-cmd");
+const invocations_1 = require("./invocations");
+// The wrapper's local re-exec sets the first two for its own hop and the user
+// sets the third to reach this path; inherited, they would change install or
+// routing behavior for every `nx migrate` the agent runs. CI exports the last
+// two for its own `nx affected` runs; inherited, they would replace the base
+// the run names and drop uncommitted files from the pass's selection. The
+// workspace's env files can still set them: every nx command loads those.
+const STRIPPED_ENV_VARS = [
+    'NX_MIGRATE_SKIP_INSTALL',
+    'NX_MIGRATE_USE_LOCAL',
+    'NX_MIGRATE_ORCHESTRATOR',
+    'NX_BASE',
+    'NX_HEAD',
+];
+// Under handoffs/ so claude's run-scoped Edit rule already admits the write;
+// nothing lists that directory. The nonce keeps a sentinel left by an earlier
+// session of the same run from closing this one.
+function sessionCompleteSentinel(runRoot, runId, nonce) {
+    return (0, path_1.join)((0, run_1.runHandoffsDir)((0, run_1.runDir)(runRoot, runId)), `session-complete-${nonce}`);
+}
+/**
+ * Spawns the agent once, with the run's pinned invariant and bootstrap prompt,
+ * and waits for the session to end, closing it once the agent writes the
+ * session-complete sentinel. Meanwhile it answers the install and commit
+ * requests the steps the agent runs hand out of its sandbox. Every failure
+ * before the process starts is returned as `spawn-failed`; what the session
+ * did is read from run state by the caller, never from the exit code.
+ */
+async function spawnMasterSession(input) {
+    const { agent, runRoot, runId, runbookPath, reconcileCommand, policy, sentinelPollIntervalMs = 500, gracefulExitMs = close_agent_session_1.AGENT_GRACEFUL_EXIT_MS, forceKillWaitMs = close_agent_session_1.FORCE_KILL_WAIT_MS, } = input;
+    let sentinelPath;
+    let child;
+    let broker;
+    try {
+        // Locked before the agent exists: a step must never find the lock free
+        // while its parent is alive.
+        broker = new run_1.MigrateCommitBroker(runRoot, (0, run_1.runDir)(runRoot, runId), reconcileCommand, policy);
+        sentinelPath = sessionCompleteSentinel(runRoot, runId, broker.nonce);
+        const spec = (0, invocations_1.buildMasterInvocation)(agent.id, {
+            runId,
+            reconcileCommand,
+            runbookPath: prosePath(runRoot, runbookPath),
+            sentinelPath: prosePath(runRoot, sentinelPath),
+        });
+        const env = { ...process.env, ...spec.env };
+        for (const name of STRIPPED_ENV_VARS) {
+            delete env[name];
+        }
+        env[run_1.BROKER_ENV_VAR] = broker.nonce;
+        const adapted = (0, windows_cmd_1.adaptSpawnForWindowsShim)(agent.binary, spec.args, {
+            stdio: 'inherit',
+            cwd: runRoot,
+            env,
+            windowsHide: true,
+        });
+        assertWithinWindowsCommandLineBudget(adapted, agent, runId);
+        // A symlink here would send the agent's write and the poll below elsewhere.
+        const handoffsDir = (0, path_1.dirname)(sentinelPath);
+        (0, handoff_1.ensureRunSubdir)(handoffsDir, () => new Error(`Migrate run ${runId} has something other than a directory at ${handoffsDir}; remove it and try again.`));
+        // Local alias so `@nx/workspace-require-windows-hide` can track the
+        // options as an Identifier.
+        const spawnOptions = adapted.options;
+        child = (0, child_process_1.spawn)(adapted.binary, adapted.args, spawnOptions);
+    }
+    catch (error) {
+        broker?.close();
+        return { kind: 'spawn-failed', error: toError(error) };
+    }
+    // Ctrl+C belongs to the agent from the moment it exists.
+    const swallowSigint = () => { };
+    process.on('SIGINT', swallowSigint);
+    const sentinelWatch = new AbortController();
+    let brokerFailure;
+    // Settles when the poll aborts and the request in flight is answered, or
+    // early when a request could not be answered at all.
+    const brokerDone = serviceBrokerUntilAborted(broker, sentinelPollIntervalMs, sentinelWatch.signal).catch((error) => {
+        brokerFailure = toError(error);
+    });
+    let started = false;
+    try {
+        const exitPromise = (0, close_agent_session_1.waitForExit)(child);
+        // The usual missing-binary failure is an `error` event with no `exit`
+        // (ENOENT after detection); before `spawn` it is a failure to start, not
+        // a session that ended.
+        const spawnError = await new Promise((resolve) => {
+            child.once('spawn', () => resolve(null));
+            child.once('error', (error) => resolve(error));
+        });
+        if (spawnError) {
+            return { kind: 'spawn-failed', error: spawnError };
+        }
+        started = true;
+        let exit = {};
+        const winner = await Promise.race([
+            exitPromise.then((info) => {
+                exit = info;
+                return 'exit';
+            }),
+            waitForFile(sentinelPath, sentinelPollIntervalMs, sentinelWatch.signal).then(() => 'sentinel'),
+            brokerDone.then(() => 'broker-failed'),
+        ]);
+        if (winner !== 'exit') {
+            await (0, close_agent_session_1.closeAgentSession)(child, exitPromise, gracefulExitMs, forceKillWaitMs);
+            // The close can return on `exitCode` while `waitForExit` is still in
+            // its merge window; bounded so a stuck child cannot hold the run.
+            await (0, close_agent_session_1.raceWithTimeout)(exitPromise, forceKillWaitMs);
+        }
+        if (winner === 'sentinel') {
+            // Hygiene only; run state decides the outcome, not this removal.
+            try {
+                (0, fs_1.rmSync)(sentinelPath, { force: true });
+            }
+            catch (error) {
+                logger_1.logger.verbose(`Could not remove ${sentinelPath}: ${toError(error).message}`);
+            }
+        }
+        logger_1.logger.verbose(`${agent.displayName} session ended (code: ${exit.code ?? 'none'}, signal: ${exit.signal ?? 'none'}${exit.error ? `, error: ${exit.error.message}` : ''}).`);
+    }
+    finally {
+        sentinelWatch.abort();
+        // With the agent gone, the terminal is restored before the wait: an
+        // agent that left it raw would keep a Ctrl+C from reaching the operation
+        // in flight as a signal.
+        const exited = child.exitCode !== null || child.signalCode !== null;
+        if (started && exited) {
+            restoreTerminal();
+            warnOperationInFlight(broker);
+        }
+        // The request in flight settles before the lock is released.
+        await brokerDone;
+        broker.close();
+        process.removeListener('SIGINT', swallowSigint);
+        if (started && !exited)
+            restoreTerminal();
+    }
+    return brokerFailure
+        ? { kind: 'broker-failed', error: brokerFailure }
+        : { kind: 'exited' };
+}
+function restoreTerminal() {
+    (0, terminal_repair_1.restoreTermiosAfterAgent)();
+    (0, migrate_output_1.resetSgrAfterAgent)();
+}
+// With the agent gone a Ctrl+C reaches the operation's child process, and
+// nothing else tells the user one is still running.
+function warnOperationInFlight(broker) {
+    const request = broker.requestInFlight;
+    if (!request)
+        return;
+    output_1.output.warn({
+        title: `Still running ${(0, run_1.treeOperationLabel)(request)} for this migrate run. Press Ctrl+C to end it; the run can be resumed afterwards.`,
+    });
+}
+async function serviceBrokerUntilAborted(broker, intervalMs, signal) {
+    while (!signal.aborted) {
+        await broker.service();
+        await delayUnlessAborted(intervalMs, signal);
+    }
+}
+function delayUnlessAborted(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted) {
+            resolve();
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+function toError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+// Workspace-relative with forward slashes on every platform: prose the agent
+// reads, not a shell path.
+function prosePath(runRoot, path) {
+    return (0, path_1.relative)(runRoot, path).split(path_1.sep).join('/');
+}
+// Never settles after an abort; the race it feeds has settled by then.
+function waitForFile(path, intervalMs, signal) {
+    return new Promise((resolve) => {
+        let timer;
+        const tick = () => {
+            if (signal.aborted)
+                return;
+            if ((0, fs_1.existsSync)(path)) {
+                resolve();
+                return;
+            }
+            timer = setTimeout(tick, intervalMs);
+        };
+        signal.addEventListener('abort', () => clearTimeout(timer), { once: true });
+        timer = setTimeout(tick, intervalMs);
+    });
+}
+function assertWithinWindowsCommandLineBudget(adapted, agent, runId) {
+    if ((0, windows_cmd_1.withinCommandLineBudget)(adapted)) {
+        return;
+    }
+    throw new Error(`Launching ${agent.displayName} needs a ${adapted.commandLineLength}-character command line. cmd.exe runs at most ${windows_cmd_1.WINDOWS_COMMAND_LINE_LIMIT} characters, and nx stops at ${windows_cmd_1.WINDOWS_COMMAND_LINE_BUDGET} to leave room for what it cannot measure from here. ` +
+        `What varies is the cmd.exe path (${adapted.binary.length} characters), the agent path (${agent.binary.length} characters) and the run id (${runId.length} characters); shorten one of them.`);
+}

package/dist/src/command-line/migrate/agentic/print-dropped-agent-context.d.ts

@@ -0,0 +1,17 @@
+export interface DroppedAgentContextInput {
+    migration: {
+        package: string;
+        name: string;
+        prompt?: string;
+    };
+    agentContext: string[];
+}
+export declare function formatDroppedAgentContextForOuterAgent(input: DroppedAgentContextInput): string;
+export declare function escapeXmlAttr(value: string): string;
+/**
+ * Both the classic loop and the single-migration worker call this only under
+ * `agentic.kind === 'inside-agent'`. Under `enabled` the inner agent step
+ * consumes `agentContext` through the prompt builders; under `disabled` the
+ * run is human-driven and agent-targeted context is only noise.
+ */
+export declare function printDroppedAgentContextForOuterAgent(input: DroppedAgentContextInput): void;

package/dist/src/command-line/migrate/agentic/print-dropped-agent-context.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatDroppedAgentContextForOuterAgent = formatDroppedAgentContextForOuterAgent;
+exports.escapeXmlAttr = escapeXmlAttr;
+exports.printDroppedAgentContextForOuterAgent = printDroppedAgentContextForOuterAgent;
+const shared_rendering_1 = require("./prompts/shared-rendering");
+function formatDroppedAgentContextForOuterAgent(input) {
+    const entries = (0, shared_rendering_1.filterNonEmptyStrings)(input.agentContext);
+    if (entries.length === 0) {
+        return '';
+    }
+    const id = `${input.migration.package}:${input.migration.name}`;
+    // Migration metadata and agentContext entries are user-authored (migrations
+    // are published by third-party packages); escape any `<` / `&` so a hostile
+    // value can't break out of the surrounding XML-framed block. The agent
+    // reads `&lt;/agent_context&gt;` as literal text, not a closing tag.
+    const safeName = (0, shared_rendering_1.escapeXmlBody)(input.migration.name);
+    const safePrompt = input.migration.prompt
+        ? (0, shared_rendering_1.escapeXmlBody)(input.migration.prompt)
+        : undefined;
+    const preamble = safePrompt
+        ? `ℹ Hints from the ${safeName} generator for the AI agent driving this run, when applying ${safePrompt}:`
+        : `ℹ Hints from the ${safeName} generator for the AI agent driving this run:`;
+    return [
+        preamble,
+        ``,
+        `<agent_context migration="${escapeXmlAttr(id)}">`,
+        ...entries.map((entry) => (0, shared_rendering_1.renderListItem)((0, shared_rendering_1.escapeXmlBody)(entry))),
+        `</agent_context>`,
+    ].join('\n');
+}
+// Migration package/name come from arbitrary user-authored package.json /
+// migrations.json — a name with `"` / `<` / `>` / `&` would produce malformed
+// XML the outer agent can't parse. `'` is not strictly required for
+// double-quoted attribute values but is included for defense.
+function escapeXmlAttr(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+/**
+ * Both the classic loop and the single-migration worker call this only under
+ * `agentic.kind === 'inside-agent'`. Under `enabled` the inner agent step
+ * consumes `agentContext` through the prompt builders; under `disabled` the
+ * run is human-driven and agent-targeted context is only noise.
+ */
+function printDroppedAgentContextForOuterAgent(input) {
+    const block = formatDroppedAgentContextForOuterAgent(input);
+    if (block) {
+        // Bare newline pair frames the block so adjacent stdout (logger output,
+        // migration progress) doesn't run into the opening or closing tag.
+        process.stdout.write(`\n${block}\n\n`);
+    }
+}

package/dist/src/command-line/migrate/agentic/prompts/final-validation.d.ts

@@ -0,0 +1,13 @@
+export interface FinalValidationInstructionsContext {
+    runId: string;
+    baseRef: string | null;
+    checkpointRef: string | null;
+    nxInvocation: string;
+    handoffFileAbsolutePath: string;
+}
+/**
+ * The final-validation step's instructions file. The runbook already carries
+ * the handoff contract, so this states the task, the base ref and the scope
+ * rules.
+ */
+export declare function buildFinalValidationInstructions(ctx: FinalValidationInstructionsContext): string;

package/dist/src/command-line/migrate/agentic/prompts/final-validation.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildFinalValidationInstructions = buildFinalValidationInstructions;
+const text_1 = require("../../text");
+const fragments_1 = require("./fragments");
+const shared_rendering_1 = require("./shared-rendering");
+/**
+ * The final-validation step's instructions file. The runbook already carries
+ * the handoff contract, so this states the task, the base ref and the scope
+ * rules.
+ */
+function buildFinalValidationInstructions(ctx) {
+    const nx = (0, text_1.singleLine)(ctx.nxInvocation);
+    const base = ctx.baseRef === null ? null : (0, text_1.singleLine)(ctx.baseRef);
+    const checkpoint = ctx.checkpointRef === null ? null : (0, text_1.singleLine)(ctx.checkpointRef);
+    const selection = base === null
+        ? `The run could not record the commit it started from, so select every project: \`${nx} run-many -t <targets>\`. Expect this to take longer than an affected run.`
+        : `The run started from commit ${base}. Select the projects it touched with \`${nx} affected --base ${base} -t <targets>\`; \`${nx} show projects --affected --base ${base}\` lists them. Read the run's changes with \`git diff ${base}\` (the working tree included).${checkpoint === null
+            ? ''
+            : ` The commits from ${base} up to and including the checkpoint ${checkpoint} landed outside the run's steps: the checkpoint captured what was still uncommitted, normally the upgrade's package.json and lockfile changes, plus whatever else was in the tree.`}`;
+    const lines = [
+        `You are running the final validation pass of Nx migrate run ${(0, text_1.singleLine)(ctx.runId)}. Every migration step has run; their changes are committed or sitting in the working tree, as the run's commit policy decided. Check that the workspace still lints, builds and passes its unit tests, fix what the upgrade broke, and report what you could not attribute to it.`,
+        ``,
+        `<validation_instructions>`,
+        `1. ${selection}`,
+        `2. Discover the targets of the selected projects with \`${nx} show project <name> --json\`. Group them into three families: lint (\`lint\` and equivalents), build (\`build\`, or \`typecheck\` where a project has no build), and unit tests (\`test\` and equivalents). Note which projects have no target in a family; the handoff summary reports that.`,
+        `3. Run the families in order, lint first, then build, then unit tests, each over the whole selection in one run.`,
+        `4. For each failure, decide from the run's diff whether the upgrade caused it. Fix what it caused, within the scope rules, then rerun only the failed tasks. Mark each failure you report instead as possibly pre-existing.`,
+        `5. Work through the "Known issues" digest the dispense listed: those the run deferred to this step are yours to resolve where the scope rules allow, and each result goes in the handoff's \`issueUpdates\`.`,
+        `6. End the step per the handoff contract. On success, the summary lists which families ran, which projects had no target in a family, what you fixed, and what you left.`,
+        `</validation_instructions>`,
+        ``,
+        `<scope_rules>`,
+        ...(0, fragments_1.renderFinalValidationScopeRuleLines)(),
+        `</scope_rules>`,
+        ``,
+        `When you end the step per the handoff contract, your handoff path is:`,
+        ...(0, shared_rendering_1.renderHandoffPathFooter)(ctx.handoffFileAbsolutePath),
+    ];
+    return lines.join('\n');
+}

package/dist/src/command-line/migrate/agentic/prompts/fragments.d.ts

@@ -0,0 +1,17 @@
+export declare function renderNxInvocationNote(packageManager: string, nxInvocation: string): string;
+export declare function renderHandoffShapeInline(summaryHint: string): string;
+export declare function renderHandoffShapeLines(): string[];
+/**
+ * Where the formatter command comes from. A prompt built right before the
+ * agent runs carries the resolved command; the runbook outlives many steps,
+ * so it points at the `Format command:` line each dispensed step resolves.
+ */
+export type FormatInstruction = {
+    source: 'command';
+    command: string | null;
+} | {
+    source: 'dispensed-step';
+};
+export declare function renderAuthorScopeRuleLines(pmExec: string, format: FormatInstruction): string[];
+export declare function renderValidationScopeRuleLines(): string[];
+export declare function renderFinalValidationScopeRuleLines(): string[];