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

package/dist/src/command-line/migrate/agentic/terminal-repair.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.restoreTermiosAfterAgent = restoreTermiosAfterAgent;
+const child_process_1 = require("child_process");
+function restoreTermiosAfterAgent() {
+    if (process.platform === 'win32')
+        return;
+    if (!process.stdin.isTTY)
+        return;
+    try {
+        // Not setRawMode(false): it short-circuits when libuv's per-handle mode
+        // is already NORMAL, even after the agent changed termios out-of-band.
+        // `stty sane` goes through the kernel instead.
+        (0, child_process_1.execSync)('stty sane < /dev/tty', {
+            stdio: ['ignore', 'ignore', 'ignore'],
+            windowsHide: true,
+        });
+        // Carriage-return + clear to end of screen, to wipe any agent TUI
+        // cells below our row that subsequent log lines won't overwrite
+        // (e.g. a status footer past where our text wraps).
+        process.stdout.write('\r\x1B[J');
+    }
+    catch {
+        // Best-effort: if stty isn't on PATH or /dev/tty isn't accessible, the
+        // worst case is the pre-existing staircase + cell-bleed output.
+    }
+}

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

@@ -10,14 +10,17 @@ export type { AgentId };
  */
 export declare const MIGRATE_RUNS_RELATIVE_DIR = ".nx/migrate-runs";
 /**
- * The one subtree of a run directory an agent writes: its handoff files.
- * Everything beside it is state Nx owns and reads back, the orchestrator's
- * run state and plan snapshots included, so the pre-authorized write scope
- * stops at this segment. Package names make up the rest of a handoff path,
- * so without it they would occupy the run directory's top level and leave Nx
- * no name it could add there safely.
+ * The one subtree of a run directory an agent writes; everything beside it is
+ * state Nx owns, so the pre-authorized write scope stops here. Handoff names
+ * derive from step ids or package and migration names, so flattening them into
+ * the run dir would leave Nx no name it could safely add.
  */
 export declare const HANDOFFS_DIR_NAME = "handoffs";
+/**
+ * Sibling subtree holding the per-step prompt files Nx writes for the agent
+ * to read. They stay out of `handoffs/`, which is the agent's to write.
+ */
+export declare const PROMPTS_DIR_NAME = "prompts";
 export declare function isHandoffGitignoreMigration(m: {
     package: string;
     name: string;
@@ -38,10 +41,22 @@ export interface DetectedInstalledAgent {
  * Inputs the runner provides when asking an agent definition to build its
  * spawn arguments. Kept minimal — agent-specific quirks (e.g. transient agent
  * name for OpenCode) are encoded inside the definition, not here.
+ *
+ * Both prompts are written to disk (see `instruction-files.ts`) and reached
+ * through `systemPromptFilePath` / `instructionsPointer`. The inline fields
+ * below are the exception, for agents that cannot be pointed at a file.
  */
 export interface InvocationContext {
-    systemContext: string;
-    userPrompt: string;
+    /** Absolute path of the file holding the step's system prompt. */
+    systemPromptFilePath: string;
+    /** Verbatim system prompt, only for a step with no file-loading path. */
+    systemPrompt: string;
+    /** Single-line command-line text pointing the agent at its instructions. */
+    instructionsPointer: string;
+    /** Inline handoff contract and pointer to `systemPromptFilePath`. */
+    inlineSystemContext: string;
+    /** Shorter `inlineSystemContext`, substituted on Windows shim overflow. */
+    inlineSystemContextFallback: string;
     workspaceRoot: string;
     /**
      * Name of the run directory under `MIGRATE_RUNS_RELATIVE_DIR` holding this

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HANDOFFS_DIR_NAME = exports.MIGRATE_RUNS_RELATIVE_DIR = void 0;
+exports.PROMPTS_DIR_NAME = exports.HANDOFFS_DIR_NAME = exports.MIGRATE_RUNS_RELATIVE_DIR = void 0;
 exports.isHandoffGitignoreMigration = isHandoffGitignoreMigration;
 /**
  * Workspace-relative directory holding all migrate-run scratch: a run
@@ -12,14 +12,17 @@ exports.isHandoffGitignoreMigration = isHandoffGitignoreMigration;
  */
 exports.MIGRATE_RUNS_RELATIVE_DIR = '.nx/migrate-runs';
 /**
- * The one subtree of a run directory an agent writes: its handoff files.
- * Everything beside it is state Nx owns and reads back, the orchestrator's
- * run state and plan snapshots included, so the pre-authorized write scope
- * stops at this segment. Package names make up the rest of a handoff path,
- * so without it they would occupy the run directory's top level and leave Nx
- * no name it could add there safely.
+ * The one subtree of a run directory an agent writes; everything beside it is
+ * state Nx owns, so the pre-authorized write scope stops here. Handoff names
+ * derive from step ids or package and migration names, so flattening them into
+ * the run dir would leave Nx no name it could safely add.
  */
 exports.HANDOFFS_DIR_NAME = 'handoffs';
+/**
+ * Sibling subtree holding the per-step prompt files Nx writes for the agent
+ * to read. They stay out of `handoffs/`, which is the agent's to write.
+ */
+exports.PROMPTS_DIR_NAME = 'prompts';
 /**
  * Composite identity of the v23 migration that adds `.nx/migrate-runs` to
  * `.gitignore`. Hard-coded because the agentic preflight is a deliberate

package/dist/src/command-line/migrate/agentic/windows-cmd.d.ts

@@ -0,0 +1,33 @@
+import type { SpawnOptions } from 'child_process';
+export declare function quoteCmdArg(arg: string): string;
+export declare function caretEscape(quoted: string): string;
+/**
+ * Stops cmd.exe expanding `%VAR%` inside an argument. A caret cannot escape
+ * `%`, since expansion runs before caret processing, so each `%` becomes
+ * `%%cd:~,%`: `%cd:~,%` is a zero-length substring of a built-in and expands to
+ * nothing, leaving the leading `%`. Runs after the caret passes so the `,` it
+ * introduces stays uncareted, which the substring syntax requires.
+ */
+export declare function neutralizePercent(escaped: string): string;
+export declare const WINDOWS_COMMAND_LINE_LIMIT = 8191;
+export declare const WINDOWS_COMMAND_LINE_BUDGET: number;
+export interface AdaptedSpawn {
+    binary: string;
+    args: string[];
+    options: SpawnOptions;
+    /**
+     * Length of the command line Windows will receive. Set only on the `cmd.exe`
+     * wrapper path.
+     */
+    commandLineLength?: number;
+}
+export declare function withinCommandLineBudget(adapted: AdaptedSpawn): boolean;
+/**
+ * Node's `spawn` cannot directly execute `.cmd` / `.bat` shims on Windows;
+ * `which` resolves to those when an agent was installed via npm. Wrap them in
+ * a `cmd.exe /c` invocation with `windowsVerbatimArguments` so quoting follows
+ * the cmd.exe convention rather than Node's default cooking.
+ *
+ * On non-Windows or for non-shim binaries this is a passthrough.
+ */
+export declare function adaptSpawnForWindowsShim(binary: string, args: readonly string[], options: SpawnOptions): AdaptedSpawn;

package/dist/src/command-line/migrate/agentic/windows-cmd.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WINDOWS_COMMAND_LINE_BUDGET = exports.WINDOWS_COMMAND_LINE_LIMIT = void 0;
+exports.quoteCmdArg = quoteCmdArg;
+exports.caretEscape = caretEscape;
+exports.neutralizePercent = neutralizePercent;
+exports.withinCommandLineBudget = withinCommandLineBudget;
+exports.adaptSpawnForWindowsShim = adaptSpawnForWindowsShim;
+const path_1 = require("path");
+// Backslash-escape embedded quotes per MS C runtime convention, then wrap in
+// quotes. Callers caret-escape cmd.exe metacharacters on top.
+function quoteCmdArg(arg) {
+    return `"${arg.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\*)$/, '$1$1')}"`;
+}
+const CMD_META_CHARS = /([()\][!^"`<>&|;, ])/g;
+function caretEscape(quoted) {
+    return quoted.replace(CMD_META_CHARS, '^$1');
+}
+/**
+ * Stops cmd.exe expanding `%VAR%` inside an argument. A caret cannot escape
+ * `%`, since expansion runs before caret processing, so each `%` becomes
+ * `%%cd:~,%`: `%cd:~,%` is a zero-length substring of a built-in and expands to
+ * nothing, leaving the leading `%`. Runs after the caret passes so the `,` it
+ * introduces stays uncareted, which the substring syntax requires.
+ */
+function neutralizePercent(escaped) {
+    return escaped.replace(/%/g, '%%cd:~,%');
+}
+// "The maximum length of the string that you can use at the command prompt is
+// 8191 characters".
+// https://learn.microsoft.com/troubleshoot/windows-client/shell-experience/command-line-string-limitation
+exports.WINDOWS_COMMAND_LINE_LIMIT = 8191;
+// Absorbs cmd.exe's own accounting of the string, which cannot be measured
+// from here.
+const WINDOWS_COMMAND_LINE_RESERVE = 1000;
+exports.WINDOWS_COMMAND_LINE_BUDGET = exports.WINDOWS_COMMAND_LINE_LIMIT - WINDOWS_COMMAND_LINE_RESERVE;
+function withinCommandLineBudget(adapted) {
+    return (adapted.commandLineLength === undefined ||
+        adapted.commandLineLength <= exports.WINDOWS_COMMAND_LINE_BUDGET);
+}
+/**
+ * Node's `spawn` cannot directly execute `.cmd` / `.bat` shims on Windows;
+ * `which` resolves to those when an agent was installed via npm. Wrap them in
+ * a `cmd.exe /c` invocation with `windowsVerbatimArguments` so quoting follows
+ * the cmd.exe convention rather than Node's default cooking.
+ *
+ * On non-Windows or for non-shim binaries this is a passthrough.
+ */
+function adaptSpawnForWindowsShim(binary, args, options) {
+    if (process.platform !== 'win32') {
+        return { binary, args: [...args], options };
+    }
+    const ext = (0, path_1.extname)(binary).toLowerCase();
+    if (ext !== '.cmd' && ext !== '.bat') {
+        return { binary, args: [...args], options };
+    }
+    assertNoLineBreaks(binary, args);
+    const cmdLine = [escapeCmdCommand(binary), ...args.map(escapeCmdArg)].join(' ');
+    const comspec = process.env.comspec || 'cmd.exe';
+    // Both modes are set rather than inherited, since a machine-wide registry
+    // setting can flip either: `/e:on` for the `%cd:~,%` substring, `/v:off` so a
+    // `!` stays literal. The outer quotes stop `cmd.exe /c` stripping the inner
+    // ones around the binary path.
+    const cmdArgs = ['/e:on', '/v:off', '/d', '/s', '/c', `"${cmdLine}"`];
+    return {
+        binary: comspec,
+        args: cmdArgs,
+        options: { ...options, windowsVerbatimArguments: true },
+        // `windowsVerbatimArguments` makes the command line the argv joined by
+        // single spaces, so this is what CreateProcess and then cmd.exe see.
+        commandLineLength: [comspec, ...cmdArgs].join(' ').length,
+    };
+}
+// No escaping reproduces a line break on the other side, and cmd.exe truncates
+// the command line at it, so the call is refused.
+function assertNoLineBreaks(binary, args) {
+    const offending = [binary, ...args].find((value) => /[\r\n]/.test(value));
+    if (offending !== undefined) {
+        throw new Error(`Cannot pass a multi-line argument to "${binary}" on Windows: cmd.exe truncates the command line at the line break. Offending argument: ${JSON.stringify(offending.slice(0, 120))}`);
+    }
+}
+function escapeCmdArg(arg) {
+    return neutralizePercent(caretEscape(quoteCmdArg(arg)));
+}
+// cmd.exe parses the command portion twice, so it is caret-escaped twice.
+function escapeCmdCommand(arg) {
+    return neutralizePercent(caretEscape(caretEscape(quoteCmdArg(arg))));
+}

package/dist/src/command-line/migrate/command-object.d.ts

@@ -21,6 +21,7 @@ export interface MigrateArgs {
     runMigration?: string;
     runId?: string;
     stepAction?: StepAction;
+    startFresh?: boolean;
     include?: MigrateInclude;
     /**
      * nx.json `migrate.include` default. Consumed by `resolveInclude` only when the
@@ -34,6 +35,7 @@ export interface MigrateArgs {
     commitPrefix?: string;
     agentic?: AgenticArg;
     validate?: boolean;
+    finalValidation?: boolean;
     ifExists?: boolean;
     interactive?: boolean;
     [key: string]: any;

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

@@ -60,7 +60,7 @@ function withMigrationOptions(yargs) {
     })
         .option('runId', {
         // Hidden with the orchestrator itself.
-        describe: 'The orchestrated migrate run to record a single migration into, or to reconcile when given without --run-migration.',
+        describe: 'The orchestrated migrate run to record a single migration into, to continue with --run-migrations, or to reconcile when given alone.',
         type: 'string',
         hidden: true,
     })
@@ -69,6 +69,11 @@ function withMigrationOptions(yargs) {
         choices: step_actions_1.STEP_ACTIONS,
         type: 'string',
         hidden: true,
+    })
+        .option('startFresh', {
+        describe: 'With --run-migrations and --run-id=<id> under the orchestrator: delete the record of the active migrate run the id names and start a new run over the whole plan. Migrations the deleted run applied stay applied.',
+        type: 'boolean',
+        hidden: true,
     })
         .option('ifExists', {
         describe: `Run migrations only if the migrations file exists, if not continues successfully.`,
@@ -124,6 +129,11 @@ function withMigrationOptions(yargs) {
         .option('validate', {
         describe: 'When `--agentic` resolves to an enabled agent, run agent-driven validation after generator-only migrations that have no `prompt:` field. Defaults to on; pass `--no-validate` to opt out. Has no effect when `--agentic` is disabled, when running inside an outer agent, or when running non-interactively without an explicit agent.',
         type: 'boolean',
+    })
+        .option('finalValidation', {
+        describe: 'With --run-migrations under the orchestrator: end the run with an agent validation pass over the whole workspace once every migration has run. On by default; pass --no-final-validation to opt out.',
+        type: 'boolean',
+        hidden: true,
     })
         .check(({ createCommits, commitPrefix, from, excludeAppliedMigrations, include, agentic, }) => {
         // Only an explicit `--no-create-commits` is decidable here, before the

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

@@ -0,0 +1,44 @@
+export type NoticeLevel = 'log' | 'warn' | 'error';
+export type LineColor = 'dim' | 'yellow' | 'red';
+export interface MigrateOutputSink {
+    notice(level: NoticeLevel, message: {
+        title: string;
+        bodyLines?: string[];
+    }): void;
+    line(color: LineColor, text: string): void;
+    /** A chunk of a package manager's own output. */
+    raw(chunk: string): void;
+}
+export declare const terminalOutput: MigrateOutputSink;
+export type DeferredOutputRecord = {
+    kind: 'notice';
+    level: NoticeLevel;
+    title: string;
+    bodyLines?: string[];
+} | {
+    kind: 'line';
+    color: LineColor;
+    text: string;
+} | {
+    kind: 'raw';
+    text: string;
+};
+/**
+ * Collects the output as records that `replayDeferredOutput` prints later.
+ * The notices and lines are always kept; package manager output is bounded
+ * like generator output and rendered only on request. Render once the output
+ * is complete: a rendered collector accepts nothing more.
+ */
+export declare class DeferredOutputCollector implements MigrateOutputSink {
+    private readonly records;
+    private rendered;
+    private assertOpen;
+    notice(level: NoticeLevel, message: {
+        title: string;
+        bodyLines?: string[];
+    }): void;
+    line(color: LineColor, text: string): void;
+    raw(chunk: string): void;
+    render(rawOutput: 'keep' | 'drop'): DeferredOutputRecord[];
+}
+export declare function replayDeferredOutput(records: DeferredOutputRecord[], to?: MigrateOutputSink): void;

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

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeferredOutputCollector = exports.terminalOutput = void 0;
+exports.replayDeferredOutput = replayDeferredOutput;
+const tslib_1 = require("tslib");
+const pc = tslib_1.__importStar(require("picocolors"));
+const logger_1 = require("../../utils/logger");
+const output_1 = require("../../utils/output");
+exports.terminalOutput = {
+    notice: (level, message) => output_1.output[level](message),
+    line: (color, text) => logger_1.logger.info(pc[color](text)),
+    raw: (chunk) => process.stdout.write(chunk),
+};
+/**
+ * Collects the output as records that `replayDeferredOutput` prints later.
+ * The notices and lines are always kept; package manager output is bounded
+ * like generator output and rendered only on request. Render once the output
+ * is complete: a rendered collector accepts nothing more.
+ */
+class DeferredOutputCollector {
+    constructor() {
+        this.records = [];
+        this.rendered = false;
+    }
+    assertOpen() {
+        if (this.rendered) {
+            throw new Error('The deferred output was already rendered.');
+        }
+    }
+    notice(level, message) {
+        this.assertOpen();
+        this.records.push({ kind: 'notice', level, ...message });
+    }
+    line(color, text) {
+        this.assertOpen();
+        this.records.push({ kind: 'line', color, text });
+    }
+    raw(chunk) {
+        this.assertOpen();
+        let block = this.records[this.records.length - 1];
+        if (block?.kind !== 'raw-block') {
+            // Lazy: the non-agentic migrate path must not load the agentic chain.
+            const { BoundedChunks } = require('./agentic/capture-generator-output');
+            block = { kind: 'raw-block', buffer: new BoundedChunks() };
+            this.records.push(block);
+        }
+        block.buffer.append(chunk);
+    }
+    render(rawOutput) {
+        this.rendered = true;
+        const records = [];
+        for (const record of this.records) {
+            if (record.kind !== 'raw-block') {
+                records.push(record);
+                continue;
+            }
+            if (rawOutput === 'drop')
+                continue;
+            // The replay adds the final newline back.
+            const text = record.buffer.render();
+            records.push({
+                kind: 'raw',
+                text: text.endsWith('\n') ? text.slice(0, -1) : text,
+            });
+        }
+        return records;
+    }
+}
+exports.DeferredOutputCollector = DeferredOutputCollector;
+function replayDeferredOutput(records, to = exports.terminalOutput) {
+    for (const record of records) {
+        switch (record.kind) {
+            case 'notice':
+                to.notice(record.level, {
+                    title: record.title,
+                    bodyLines: record.bodyLines,
+                });
+                break;
+            case 'line':
+                to.line(record.color, record.text);
+                break;
+            case 'raw':
+                if (record.text)
+                    to.raw(`${record.text}\n`);
+                break;
+            default: {
+                const exhaustive = record;
+                throw new Error(`Unhandled output record: ${JSON.stringify(exhaustive)}`);
+            }
+        }
+    }
+}

package/dist/src/command-line/migrate/execute-migration.d.ts

@@ -1,12 +1,18 @@
 import { MigrationsJson } from '../../config/misc-interfaces';
 import { FileChange } from '../../generators/tree';
 import { ArrayPackageGroup, NxMigrationsConfiguration, PackageJson } from '../../utils/package-json';
+import { type MigrateOutputSink } from './deferred-output';
 interface PackageMigrationConfig extends NxMigrationsConfiguration {
     packageJson: PackageJson;
     packageGroup: ArrayPackageGroup;
 }
 export declare function readPackageMigrationConfig(packageName: string, dir: string): PackageMigrationConfig;
-export declare function runInstall(nxWorkspaceRoot?: string, phase?: MigrationInstallPhase, rerunCommand?: string): Promise<void>;
+/**
+ * With a `sink`, stdin is ignored and stdout and stderr are collected for a
+ * caller sharing the terminal. On POSIX the child stays in nx's process
+ * group. Without a sink, the install owns the terminal.
+ */
+export declare function runInstall(nxWorkspaceRoot?: string, phase?: MigrationInstallPhase, rerunCommand?: string, sink?: MigrateOutputSink): Promise<void>;
 export type MigrationInstallPhase = 'pre-migration' | 'post-migration';
 export declare class NpmPeerDepsInstallError extends Error {
     constructor();
@@ -20,8 +26,8 @@ export declare class NpmPeerDepsInstallError extends Error {
  */
 export declare function isNpmPeerDepsError(stderr: string): boolean;
 export declare function formatSingleMigrationRerunCommand(migrationId: string): string;
-export declare function logNpmPeerDepsError(phase: MigrationInstallPhase, rerunCommand?: string): void;
-export declare function logSkippedPostMigrationInstall(root: string): void;
+export declare function logNpmPeerDepsError(phase: MigrationInstallPhase, rerunCommand?: string, out?: MigrateOutputSink): void;
+export declare function logSkippedPostMigrationInstall(root: string, out?: MigrateOutputSink): void;
 export declare class ChangedDepInstaller {
     private readonly root;
     private readonly shouldSkipInstall;

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

@@ -20,6 +20,7 @@ exports.isAngularMigration = isAngularMigration;
 const tslib_1 = require("tslib");
 const pc = tslib_1.__importStar(require("picocolors"));
 const child_process_1 = require("child_process");
+const string_decoder_1 = require("string_decoder");
 const path_1 = require("path");
 const semver_1 = require("semver");
 const handle_import_1 = require("../../utils/handle-import");
@@ -29,12 +30,12 @@ const logger_1 = require("../../utils/logger");
 const text_1 = require("./text");
 const package_json_1 = require("../../utils/package-json");
 const package_manager_1 = require("../../utils/package-manager");
-const output_1 = require("../../utils/output");
 const fs_1 = require("fs");
 const installation_directory_1 = require("../../utils/installation-directory");
 const shell_quoting_1 = require("../../utils/shell-quoting");
 const project_graph_1 = require("../../project-graph/project-graph");
 const version_utils_1 = require("./version-utils");
+const deferred_output_1 = require("./deferred-output");
 function readPackageMigrationConfig(packageName, dir) {
     const { path: packageJsonPath, packageJson: json } = (0, package_json_1.readModulePackageJson)(packageName, (0, installation_directory_1.getNxRequirePaths)(dir));
     const config = (0, package_json_1.readNxMigrateConfig)(json);
@@ -61,32 +62,68 @@ function readPackageMigrationConfig(packageName, dir) {
         };
     }
 }
-function runInstall(nxWorkspaceRoot, phase = 'pre-migration', rerunCommand) {
+/**
+ * With a `sink`, stdin is ignored and stdout and stderr are collected for a
+ * caller sharing the terminal. On POSIX the child stays in nx's process
+ * group. Without a sink, the install owns the terminal.
+ */
+function runInstall(nxWorkspaceRoot, phase = 'pre-migration', rerunCommand, sink) {
     const cwd = nxWorkspaceRoot ?? process.cwd();
     const packageManager = (0, package_manager_1.detectPackageManager)(cwd);
     const pmCommands = (0, package_manager_1.getPackageManagerCommand)(packageManager, cwd);
+    const out = sink ?? deferred_output_1.terminalOutput;
     const installCommand = `${pmCommands.install} ${pmCommands.ignoreScriptsFlag ?? ''}`;
-    output_1.output.log({
+    out.notice('log', {
         title: `Running '${installCommand}' to make sure necessary packages are installed`,
     });
     return new Promise((resolve, reject) => {
-        // For npm, pipe stderr so we can detect peer dependency errors while still
-        // mirroring it live to the user's terminal. Other package managers inherit
-        // stderr directly since we don't need to inspect their output.
+        // npm's stderr is piped so peer dependency errors can be detected in it.
+        // Without a sink it is mirrored live and other package managers inherit
+        // stderr directly, since their output is not inspected.
         const shouldCaptureStderr = packageManager === 'npm';
         const child = (0, child_process_1.spawn)(installCommand, {
             shell: true,
-            stdio: ['inherit', 'inherit', shouldCaptureStderr ? 'pipe' : 'inherit'],
+            stdio: sink
+                ? ['ignore', 'pipe', 'pipe']
+                : ['inherit', 'inherit', shouldCaptureStderr ? 'pipe' : 'inherit'],
             windowsHide: true,
             cwd,
         });
+        // Decoded per stream: a chunk boundary can split a multi-byte character,
+        // and a sequence still incomplete at the end is what `end()` returns.
+        const stdoutText = new string_decoder_1.StringDecoder('utf8');
+        const stderrText = new string_decoder_1.StringDecoder('utf8');
+        child.stdout?.on('data', (chunk) => out.raw(stdoutText.write(chunk)));
+        child.stdout?.on('end', () => out.raw(stdoutText.end()));
         const stderrChunks = [];
         child.stderr?.on('data', (chunk) => {
-            process.stderr.write(chunk);
-            stderrChunks.push(chunk);
+            if (sink) {
+                out.raw(stderrText.write(chunk));
+            }
+            else {
+                process.stderr.write(chunk);
+            }
+            if (shouldCaptureStderr)
+                stderrChunks.push(chunk);
+        });
+        if (sink)
+            child.stderr.on('end', () => out.raw(stderrText.end()));
+        // With a sink the rejection waits for `close`, which follows the streams'
+        // `end`: a caller must be able to render what it collected on rejection.
+        let spawnError = null;
+        child.on('error', (error) => {
+            if (sink) {
+                spawnError = error;
+            }
+            else {
+                reject(error);
+            }
         });
-        child.on('error', reject);
         child.on('close', (code) => {
+            if (spawnError) {
+                reject(spawnError);
+                return;
+            }
             if (code === 0) {
                 resolve();
                 return;
@@ -98,7 +135,7 @@ function runInstall(nxWorkspaceRoot, phase = 'pre-migration', rerunCommand) {
                     // (CLI migrate, `nx repair`, single-migration runner, etc.) surfaces
                     // it consistently. Top-level callers catch `NpmPeerDepsInstallError`
                     // and return a non-zero exit code without re-logging.
-                    logNpmPeerDepsError(phase, rerunCommand);
+                    logNpmPeerDepsError(phase, rerunCommand, out);
                     reject(new NpmPeerDepsInstallError());
                     return;
                 }
@@ -143,7 +180,7 @@ function formatSingleMigrationRerunCommand(migrationId) {
         : migrationId;
     return `nx migrate --run-migration=${id}`;
 }
-function logNpmPeerDepsError(phase, rerunCommand = 'nx migrate --run-migrations') {
+function logNpmPeerDepsError(phase, rerunCommand = 'nx migrate --run-migrations', out = deferred_output_1.terminalOutput) {
     const peerDepsResolutionSteps = [
         'Recommended approaches (in order of preference):',
         '',
@@ -160,7 +197,7 @@ function logNpmPeerDepsError(phase, rerunCommand = 'nx migrate --run-migrations'
         `   ${rerunCommand} --skip-install`,
     ];
     if (phase === 'pre-migration') {
-        output_1.output.error({
+        out.notice('error', {
             title: 'You need to resolve the peer dependency conflicts before the migration can continue',
             bodyLines: [
                 ...peerDepsResolutionSteps,
@@ -173,7 +210,7 @@ function logNpmPeerDepsError(phase, rerunCommand = 'nx migrate --run-migrations'
         });
     }
     else {
-        output_1.output.error({
+        out.notice('error', {
             title: 'Some migrations have been applied, but installing the updated dependencies failed',
             bodyLines: [
                 ...peerDepsResolutionSteps,
@@ -187,10 +224,10 @@ function logNpmPeerDepsError(phase, rerunCommand = 'nx migrate --run-migrations'
         });
     }
 }
-function logSkippedPostMigrationInstall(root) {
+function logSkippedPostMigrationInstall(root, out = deferred_output_1.terminalOutput) {
     const packageManager = (0, package_manager_1.detectPackageManager)(root);
     const installCommand = (0, package_manager_1.getPackageManagerCommand)(packageManager, root).install;
-    output_1.output.warn({
+    out.notice('warn', {
         title: 'Migrations updated your dependencies, but the install was skipped',
         bodyLines: [`Run "${installCommand}" to install the updated dependencies.`],
     });

package/dist/src/command-line/migrate/migrate-analytics.d.ts

@@ -72,23 +72,48 @@ export declare function reportMigrateOrchestratorInit(opts: {
     createCommits: boolean;
 }): void;
 /**
- * One event per orchestrator dispense. The `action` (dispense case) is a
- * closed enum carried on a reused dimension, read conditioned on the event
- * name (the same multiplexing pattern as {@link reportMigratePrompt});
- * `attempt` rides the migration-count dimension.
+ * One event per dispense response, repeated on every reconcile until the
+ * step moves. The `action` (dispense case) is a closed enum carried on a
+ * reused dimension, read conditioned on the event name (the same
+ * multiplexing pattern as {@link reportMigratePrompt}); `attempt` rides the
+ * migration-count dimension and `ordinal` (the run's dispense count) the
+ * task-count one.
  */
 export declare function reportMigrateOrchestratorDispense(opts: {
     action: string;
     attempt: number;
+    ordinal?: number;
 }): void;
-/**
- * Terminal funnel event. The two step tallies and the total dispense count
- * ride reused numeric dimensions, read conditioned on the event name.
- */
-export declare function reportMigrateOrchestratorComplete(opts: {
+/** Once per durable dispense transition. */
+export declare function reportMigrateOrchestratorStepDispensed(opts: {
+    attempt: number;
+    ordinal: number;
+}): void;
+export interface MigrateOrchestratorTallies {
     completed: number;
     skipped: number;
+    unresolved: number;
     dispenseCount: number;
+}
+export declare function reportMigrateOrchestratorComplete(opts: MigrateOrchestratorTallies): void;
+/** The agent session nx spawned ended with the run still active. */
+export declare function reportMigrateOrchestratorAbandoned(opts: MigrateOrchestratorTallies & {
+    agentUsed: string;
+}): void;
+/**
+ * An explicit continue (`--run-migrations --run-id`, or "continue" at the
+ * master prompt) took up an active run; every resume reports. A bare
+ * `--run-id` reconcile is not a resume: nothing in run state marks the first
+ * call after a lost session.
+ */
+export declare function reportMigrateOrchestratorResume(opts: MigrateOrchestratorTallies): void;
+/**
+ * An invocation found an active run and started nothing. `activity` says
+ * whether another nx migrate process held the run; 'unknown' where nx cannot
+ * tell.
+ */
+export declare function reportMigrateOrchestratorExistingRun(opts: MigrateOrchestratorTallies & {
+    activity: 'idle' | 'held' | 'unknown';
 }): void;
 /**
  * Counts invocations, not completions: emitted as soon as the migration id