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

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

@@ -8,13 +8,16 @@ const child_process_1 = require("../../../utils/child-process");
 const logger_1 = require("../../../utils/logger");
 const package_manager_1 = require("../../../utils/package-manager");
 const migrate_output_1 = require("../migrate-output");
+const format_command_1 = require("./format-command");
 const handoff_1 = require("./handoff");
+const instruction_files_1 = require("./instruction-files");
 const generic_validation_1 = require("./prompts/generic-validation");
 const hybrid_prompt_migration_1 = require("./prompts/hybrid-prompt-migration");
 const prompt_migration_1 = require("./prompts/prompt-migration");
 const system_prompt_1 = require("./prompts/system-prompt");
 const definitions_1 = require("./definitions");
 const runner_1 = require("./runner");
+const types_1 = require("./types");
 /**
  * Spawns the configured AI agent against a migration step, awaits its handoff,
  * and translates the outcome into a structured result the executor can branch
@@ -34,12 +37,19 @@ async function runAgenticPromptStep(input) {
     // prompt in agents like Claude Code every run).
     (0, handoff_1.mkdirSafely)((0, path_1.dirname)(handoffFilePath), `handoff directory for ${migration.name}`);
     const pm = (0, package_manager_1.detectPackageManager)(root);
-    const systemContext = (0, system_prompt_1.buildSystemPrompt)({
+    const pmCommand = (0, package_manager_1.getPackageManagerCommand)(pm, root);
+    const systemPrompt = (0, system_prompt_1.buildSystemPrompt)({
         workspaceRoot: root,
         handoffFileAbsolutePath: handoffFilePath,
         packageManager: pm,
-        nxInvocation: (0, child_process_1.getRunNxBaseCommand)((0, package_manager_1.getPackageManagerCommand)(pm, root), root),
+        nxInvocation: (0, child_process_1.getRunNxBaseCommand)(pmCommand, root),
         mode,
+        pmExec: pmCommand.exec,
+        // Validation prompts carry no format rule, so don't probe the workspace
+        // (detectFormatter can warn) for a command the prompt would discard.
+        formatCommand: mode === 'generic-validation'
+            ? null
+            : (0, format_command_1.resolveFormatCommand)(root, pmCommand.exec),
     });
     let userPrompt;
     if (mode === 'generic-validation') {
@@ -74,18 +84,32 @@ async function runAgenticPromptStep(input) {
     if (!definition) {
         throw new Error(`No agent definition registered for "${agentic.selectedAgent.id}".`);
     }
+    const { systemPromptFilePath, instructionsPointer } = (0, instruction_files_1.writeStepInstructionFiles)({
+        workspaceRoot: root,
+        runDir,
+        migration,
+        systemPrompt,
+        instructions: userPrompt,
+    });
     const phase = mode === 'generic-validation' ? 'Validating' : 'Running prompt';
     logger_1.logger.info(pc.dim(`→ ${phase} with ${agentic.selectedAgent.displayName}…`));
     const outcome = await (0, runner_1.runAgentic)({
         detected: agentic.selectedAgent,
         definition,
         invocationContext: {
-            systemContext,
-            userPrompt,
+            systemPrompt,
+            systemPromptFilePath,
+            instructionsPointer,
+            inlineSystemContext: (0, system_prompt_1.buildInlineSystemContext)({
+                handoffFileAbsolutePath: handoffFilePath,
+                systemPromptFilePath,
+            }),
+            inlineSystemContextFallback: (0, system_prompt_1.buildMinimalSystemContext)(systemPromptFilePath),
             workspaceRoot: root,
             runDirName: (0, path_1.basename)(runDir),
         },
         handoffFilePath,
+        handoffsDir: (0, path_1.join)(runDir, types_1.HANDOFFS_DIR_NAME),
     });
     // Some agent TUIs leave cursor/SGR state behind on exit. Reset before our
     // own log lines so the outcome line lands clean instead of overlaid on the

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

@@ -1,13 +1,14 @@
-import { SpawnOptions } from 'child_process';
 import { AgentDefinition, DetectedInstalledAgent, HandoffOutcome, InvocationContext } from './types';
 export interface RunAgenticArgs {
     detected: DetectedInstalledAgent;
     definition: AgentDefinition;
     invocationContext: InvocationContext;
     handoffFilePath: string;
+    /** Directory the handoff sits in; passing a parent instead skips the symlink guard. */
+    handoffsDir: string;
     /** Override the handoff-file poll interval (test seam). */
     handoffPollIntervalMs?: number;
-    /** Override the SIGINT-to-SIGTERM grace period (test seam). */
+    /** Override the SIGINT-to-SIGKILL grace period (test seam). */
     gracefulExitMs?: number;
     /** Override the post-force-kill safety bound (test seam). */
     forceKillWaitMs?: number;
@@ -18,16 +19,3 @@ export interface RunAgenticArgs {
  * the handoff file (or the user when the file is missing).
  */
 export declare function runAgentic(args: RunAgenticArgs): Promise<HandoffOutcome>;
-/**
- * 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 /d /s /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): {
-    binary: string;
-    args: string[];
-    options: SpawnOptions;
-};

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

@@ -1,32 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runAgentic = runAgentic;
-exports.adaptSpawnForWindowsShim = adaptSpawnForWindowsShim;
+const tslib_1 = require("tslib");
 const child_process_1 = require("child_process");
-const path_1 = require("path");
+const pc = tslib_1.__importStar(require("picocolors"));
+const logger_1 = require("../../../utils/logger");
 const output_1 = require("../../../utils/output");
 const migrate_analytics_1 = require("../migrate-analytics");
 const safe_prompt_1 = require("../safe-prompt");
+const close_agent_session_1 = require("./close-agent-session");
 const handoff_1 = require("./handoff");
-// How long to wait for the agent to exit gracefully after sending SIGINT once
-// a valid handoff has been written. Long enough for an interactive agent to
-// finish its current render and clean up; short enough that a frozen child
-// still gets escalated to SIGTERM in a sensible time.
-const AGENT_GRACEFUL_EXIT_MS = 5_000;
+const terminal_repair_1 = require("./terminal-repair");
+const windows_cmd_1 = require("./windows-cmd");
 /**
  * Spawns the selected agent with `stdio: 'inherit'`, swallows SIGINT while the
  * child is alive, waits for it to exit, and resolves the run's outcome from
  * the handoff file (or the user when the file is missing).
  */
 async function runAgentic(args) {
-    const { detected, definition, invocationContext, handoffFilePath, handoffPollIntervalMs, gracefulExitMs = AGENT_GRACEFUL_EXIT_MS, forceKillWaitMs = FORCE_KILL_WAIT_MS, } = args;
-    const spec = definition.buildInteractive(invocationContext);
-    const adapted = adaptSpawnForWindowsShim(detected.binary, spec.args, {
-        stdio: 'inherit',
-        cwd: spec.cwd ?? invocationContext.workspaceRoot,
-        env: spec.env ? { ...process.env, ...spec.env } : process.env,
-        windowsHide: true,
-    });
+    const { detected, definition, invocationContext, handoffFilePath, handoffsDir, handoffPollIntervalMs, gracefulExitMs = close_agent_session_1.AGENT_GRACEFUL_EXIT_MS, forceKillWaitMs = close_agent_session_1.FORCE_KILL_WAIT_MS, } = args;
+    const adapted = adaptWithinCommandLineBudget(detected, definition, invocationContext);
     let child;
     // Local alias so `@nx/workspace-require-windows-hide` recognizes the
     // options arg as a tracked Identifier rather than giving up on a
@@ -36,7 +29,7 @@ async function runAgentic(args) {
         child = (0, child_process_1.spawn)(adapted.binary, adapted.args, spawnOptions);
     }
     catch (err) {
-        return resolveFromHandoffOrPrompt(handoffFilePath, false, {
+        return resolveFromHandoffOrPrompt(handoffFilePath, handoffsDir, false, {
             spawnError: err instanceof Error ? err.message : String(err),
         });
     }
@@ -52,8 +45,8 @@ async function runAgentic(args) {
     };
     process.on('SIGINT', swallowSigint);
     const handoffWatchAbort = new AbortController();
-    const exitPromise = waitForExit(child);
-    const handoffPromise = (0, handoff_1.waitForValidHandoff)(handoffFilePath, {
+    const exitPromise = (0, close_agent_session_1.waitForExit)(child);
+    const handoffPromise = (0, handoff_1.waitForValidHandoff)(handoffFilePath, handoffsDir, {
         signal: handoffWatchAbort.signal,
         intervalMs: handoffPollIntervalMs,
     });
@@ -70,19 +63,57 @@ async function runAgentic(args) {
             handoffPromise.then(() => 'handoff', () => 'exit'),
         ]);
         if (winner === 'handoff') {
-            await closeAgentSession(child, exitPromise, gracefulExitMs, forceKillWaitMs);
+            await (0, close_agent_session_1.closeAgentSession)(child, exitPromise, gracefulExitMs, forceKillWaitMs);
             // Extra safety bound so the orchestrator can't hang if the child
             // stays stuck after SIGKILL / taskkill (e.g. D-state on a hung NFS
             // read, or taskkill returning before the process actually exits).
-            await raceWithTimeout(exitPromise, forceKillWaitMs);
+            await (0, close_agent_session_1.raceWithTimeout)(exitPromise, forceKillWaitMs);
         }
     }
     finally {
         handoffWatchAbort.abort();
         process.removeListener('SIGINT', swallowSigint);
-        restoreTermiosAfterAgent();
+        (0, terminal_repair_1.restoreTermiosAfterAgent)();
+    }
+    return resolveFromHandoffOrPrompt(handoffFilePath, handoffsDir, userInterruptCount > 0, exitInfoToCause(exitInfo));
+}
+/**
+ * Builds Windows shim arguments within budget, trying the shorter context
+ * before aborting. Rejects overflow to avoid truncated instructions.
+ * Leaves command lines unmeasured off the shim path.
+ */
+function adaptWithinCommandLineBudget(detected, definition, invocationContext) {
+    const adapt = (ctx) => {
+        const spec = definition.buildInteractive(ctx);
+        return (0, windows_cmd_1.adaptSpawnForWindowsShim)(detected.binary, spec.args, {
+            stdio: 'inherit',
+            cwd: spec.cwd ?? ctx.workspaceRoot,
+            env: spec.env ? { ...process.env, ...spec.env } : process.env,
+            windowsHide: true,
+        });
+    };
+    const adapted = adapt(invocationContext);
+    if ((0, windows_cmd_1.withinCommandLineBudget)(adapted)) {
+        return adapted;
     }
-    return resolveFromHandoffOrPrompt(handoffFilePath, userInterruptCount > 0, exitInfoToCause(exitInfo));
+    const reduced = adapt({
+        ...invocationContext,
+        inlineSystemContext: invocationContext.inlineSystemContextFallback,
+    });
+    if ((0, windows_cmd_1.withinCommandLineBudget)(reduced)) {
+        logger_1.logger.info(pc.dim(`  Passing the agent a reduced system context. The full one does not fit on a Windows command line alongside these paths.`));
+        return reduced;
+    }
+    output_1.output.error({
+        title: `${detected.displayName} cannot be started for this migration step`,
+        bodyLines: [
+            `Launching it needs a ${reduced.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.`,
+            `The length is paths: the workspace root, at ${invocationContext.workspaceRoot.length} characters, and the migration's package and name, each repeated across several of them.`,
+            ``,
+            `Re-run with \`--agentic=false\` to apply the remaining migrations yourself. Moving the workspace to a shorter path can help too, but only for agents that put it on the command line.`,
+        ],
+    });
+    throw new Error(`Cannot start ${detected.displayName}: the command line exceeds the Windows limit.`);
 }
 function exitInfoToCause(info) {
     const cause = {};
@@ -101,172 +132,8 @@ function exitInfoToCause(info) {
         cause.exitError = info.error.message;
     return cause;
 }
-function restoreTermiosAfterAgent() {
-    if (process.platform === 'win32')
-        return;
-    if (!process.stdin.isTTY)
-        return;
-    try {
-        // `stty sane` resets termios to a known cooked state via the kernel —
-        // independent of Node's libuv mode tracking (Node's setRawMode(false)
-        // short-circuits when libuv's per-handle mode is already NORMAL, even
-        // if the OS-level termios was changed out-of-band by the agent).
-        (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.
-    }
-}
-// Safety bound after force-kill. SIGKILL normally reaps in microseconds;
-// the bound exists for uninterruptible kernel calls or taskkill returning
-// before the process actually exits.
-const FORCE_KILL_WAIT_MS = 500;
-/**
- * Stops the agent process after a successful handoff. Platform-branched:
- *
- * - POSIX: SIGINT (graceful, equivalent to user Ctrl+C) → wait
- *   `gracefulExitMs` for the child to exit → SIGKILL → wait
- *   `FORCE_KILL_WAIT_MS` (bounded) → return. SIGTERM is intentionally
- *   skipped: a process that ignores SIGINT for 5s will hit the same
- *   handler on SIGTERM, the extra step only delays the inevitable.
- *
- * - Windows: skip SIGINT entirely. `child.kill('*')` on Windows is a
- *   `TerminateProcess` call regardless of the signal name (Windows has
- *   no POSIX signals), and on the `cmd.exe /d /s /c "..."` shim path it
- *   would terminate cmd.exe while leaving the agent orphaned (parent
- *   death doesn't cascade to children on Windows). `taskkill /T /F`
- *   walks the process tree and kills cmd.exe AND the agent atomically;
- *   that's the only reliable shutdown path here. `taskkill` failures
- *   (binary missing, race with already-dead pid) are swallowed; the
- *   safety bound returns regardless.
- */
-async function closeAgentSession(child, exitPromise, gracefulExitMs, forceKillWaitMs) {
-    if (child.exitCode !== null || child.signalCode !== null)
-        return;
-    if (process.platform === 'win32') {
-        await forceKillWindowsTree(child, exitPromise, forceKillWaitMs);
-        return;
-    }
-    // POSIX path.
-    try {
-        child.kill('SIGINT');
-    }
-    catch {
-        // child already gone between the check above and here
-        return;
-    }
-    let escalation;
-    try {
-        await Promise.race([
-            exitPromise,
-            new Promise((resolve) => {
-                escalation = setTimeout(resolve, gracefulExitMs);
-            }),
-        ]);
-    }
-    finally {
-        if (escalation)
-            clearTimeout(escalation);
-    }
-    if (child.exitCode !== null || child.signalCode !== null)
-        return;
-    // Graceful timeout elapsed without the agent exiting. SIGKILL is
-    // uncatchable; bound the post-kill wait so a pathological uninterruptible
-    // syscall can't hang us forever.
-    try {
-        child.kill('SIGKILL');
-    }
-    catch {
-        /* child already gone */
-    }
-    await raceWithTimeout(exitPromise, forceKillWaitMs);
-}
-async function forceKillWindowsTree(child, exitPromise, forceKillWaitMs) {
-    const pid = child.pid;
-    // `child.pid` is undefined only when spawn itself failed; the early-return
-    // guard in `closeAgentSession` should short-circuit that path. Reaching
-    // here without a pid means a narrow race between handoff-detection and
-    // error-event propagation — without a pid we can't taskkill, so wait
-    // briefly and return.
-    if (pid !== undefined) {
-        try {
-            (0, child_process_1.execSync)(`taskkill /T /F /PID ${pid}`, {
-                stdio: 'ignore',
-                windowsHide: true,
-                // Bound so a hung Windows shell can't block the orchestrator.
-                timeout: 2_000,
-            });
-        }
-        catch {
-            /* taskkill missing, pid already dead, or timed out — fall through */
-        }
-    }
-    await raceWithTimeout(exitPromise, forceKillWaitMs);
-}
-async function raceWithTimeout(promise, timeoutMs) {
-    let timer;
-    try {
-        await Promise.race([
-            promise,
-            new Promise((resolve) => {
-                timer = setTimeout(resolve, timeoutMs);
-            }),
-        ]);
-    }
-    finally {
-        if (timer)
-            clearTimeout(timer);
-    }
-}
-// Merge window so a paired exit + error both land in the same ExitInfo
-// (e.g. error from IPC followed by exit when the process actually
-// terminates). For error-only paths like spawn ENOENT — where Node fires
-// error but never exit — this timer is the SOLE settlement mechanism.
-const EXIT_MERGE_WINDOW_MS = 10;
-function waitForExit(child) {
-    return new Promise((resolve) => {
-        const info = {};
-        let pending = null;
-        let settled = false;
-        const settle = () => {
-            if (settled)
-                return;
-            settled = true;
-            if (pending)
-                clearTimeout(pending);
-            resolve(info);
-        };
-        const onFirst = () => {
-            if (settled || pending)
-                return;
-            pending = setTimeout(settle, EXIT_MERGE_WINDOW_MS);
-        };
-        child.on('exit', (code, signal) => {
-            info.code = code;
-            info.signal = signal;
-            onFirst();
-        });
-        // `error` fires when spawn itself fails (e.g. binary disappeared between
-        // detection and run) OR alongside `exit` when the process started but
-        // emitted an error event later. Treat both as exit with no handoff so
-        // the ambiguous flow kicks in; field-merge so we don't drop the loser's
-        // contribution when both fire.
-        child.on('error', (error) => {
-            info.error = error;
-            onFirst();
-        });
-    });
-}
-async function resolveFromHandoffOrPrompt(handoffFilePath, userInterrupted = false, cause = {}) {
-    const read = (0, handoff_1.readHandoffWithReason)(handoffFilePath);
+async function resolveFromHandoffOrPrompt(handoffFilePath, handoffsDir, userInterrupted = false, cause = {}) {
+    const read = (0, handoff_1.readHandoffWithReason)(handoffFilePath, handoffsDir);
     if (read.ok === true) {
         return {
             kind: read.handoff.status,
@@ -286,18 +153,8 @@ async function resolveFromHandoffOrPrompt(handoffFilePath, userInterrupted = fal
         // unverified, so the skip stays. The orchestrator's standard failure
         // cascade surfaces the abort outcome.
         //
-        // Forward the underlying cause as pre-rendered summary lines so the
-        // caller can log it before "Aborted by user" — a Ctrl+C that masked
-        // a SEPARATE crash still needs to show the user what crashed. Scrub
-        // fields that are just the Ctrl+C itself reverberating: exit code
-        // 130 (SIGINT) / 143 (SIGTERM from our escalation) and signals
-        // SIGINT / SIGTERM reflect the user's own keystroke (and our
-        // graceful-exit handling of it); surfacing them as "agent crashed"
-        // would be noise. Anything else — code 1, code 137 (OOM), an
-        // unrelated signal — is a separate diagnostic worth keeping. Note
-        // that `spawnError` is structurally impossible here: the spawn-throw
-        // path returns directly without registering the SIGINT listener, so
-        // `userInterrupted` can never be true on that branch.
+        // After user interruption, suppress conventional stop statuses and retain
+        // independent failure diagnostics for the caller to display.
         const exitWasCtrlC = cause.exitCode === 130 ||
             cause.exitCode === 143 ||
             cause.exitSignal === 'SIGINT' ||
@@ -318,45 +175,6 @@ async function resolveFromHandoffOrPrompt(handoffFilePath, userInterrupted = fal
     }
     return promptAmbiguous(fullCause);
 }
-/**
- * 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 /d /s /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 };
-    }
-    const cmdLine = [escapeCmdCommand(binary), ...args.map(escapeCmdArg)].join(' ');
-    return {
-        binary: process.env.comspec || 'cmd.exe',
-        // Outer pair of quotes is required so cmd.exe /c does not strip the inner
-        // quotes around the binary path.
-        args: ['/d', '/s', '/c', `"${cmdLine}"`],
-        options: { ...options, windowsVerbatimArguments: true },
-    };
-}
-const CMD_META_CHARS = /([()\][%!^"`<>&|;, ])/g;
-// Backslash-escape embedded quotes per MS C runtime convention, wrap in
-// quotes, then caret-escape cmd.exe metacharacters.
-function escapeCmdArg(arg) {
-    const quoted = `"${arg
-        .replace(/(\\*)"/g, '$1$1\\"')
-        .replace(/(\\*)$/, '$1$1')}"`;
-    return quoted.replace(CMD_META_CHARS, '^$1');
-}
-function escapeCmdCommand(arg) {
-    // cmd.exe interprets the command portion through an extra parsing pass;
-    // apply the caret-escape twice so the .cmd shim sees the original.
-    return escapeCmdArg(arg).replace(CMD_META_CHARS, '^$1');
-}
 async function promptAmbiguous(cause) {
     // stderr blank line so the spacer lands in the same stream as output.warn
     // and the prompt — buffered stdout could otherwise reorder it and glue the

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

@@ -0,0 +1 @@
+export declare function restoreTermiosAfterAgent(): void;

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;