nx 23.3.0-beta.0 → 23.3.0-beta.1

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

@@ -18,15 +18,6 @@ const ignore_1 = require("../../utils/ignore");
 const object_sort_1 = require("../../utils/object-sort");
 const output_1 = require("../../utils/output");
 const workspace_root_1 = require("../../utils/workspace-root");
-/**
- * A table, not a `switch`: this lookup sits inside a `try` whose `catch`
- * reports "configured but not installed", and a `never` arm would throw into
- * that catch and be misreported. A missing member is a compile error here.
- */
-const resolveFormatterBin = {
-    oxfmt: oxfmt_1.getOxfmtBinPath,
-    prettier: prettier_1.getPrettierPath,
-};
 async function format(command, args) {
     const formatterType = (0, formatters_1.detectFormatter)(workspace_root_1.workspaceRoot);
     if (!formatterType) {
@@ -41,7 +32,7 @@ async function format(command, args) {
     // node_modules. Resolving now turns a raw MODULE_NOT_FOUND into something
     // actionable.
     try {
-        resolveFormatterBin[formatterType]();
+        formatters_1.resolveFormatterBin[formatterType]();
     }
     catch {
         output_1.output.error({
@@ -53,19 +44,12 @@ async function format(command, args) {
         process.exit(1);
     }
     const { nxArgs } = (0, command_line_utils_1.splitArgsIntoNxArgsAndOverrides)(args, 'affected', { printWarnings: false }, (0, configuration_1.readNxJson)());
-    // Patterns are kept raw here. Prettier is invoked through a shell so it
-    // quotes them at the call site; oxfmt is invoked with execFile and needs
-    // the unquoted paths.
     const patterns = await getPatterns(formatterType, {
         ...args,
         ...nxArgs,
     });
     // Chunkify the patterns array to prevent crashing the windows terminal.
-    // The prettier path quotes each pattern on its way to the shell, so size the
-    // chunks against that; oxfmt goes through execFile and gets them raw.
-    const chunkList = (0, chunkify_1.chunkify)(patterns, undefined, formatterType === 'prettier'
-        ? (pattern) => (0, prettier_1.quoteForShell)(pattern).length
-        : undefined);
+    const chunkList = (0, chunkify_1.chunkify)(patterns);
     switch (command) {
         case 'write':
             if (nxArgs.sortRootTsconfigPaths) {

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

@@ -850,17 +850,51 @@ async function getExpandedTaskInputs(depGraphClientResponse, expandedTaskInputsC
     expandedTaskInputsCache.set(taskId, result);
     return result;
 }
+// A brace group ({a,b}.json) carries commas, so a glob list joined with
+// commas can only be split at brace depth zero.
+function splitGlobGroup(group) {
+    const globs = [];
+    let current = '';
+    let depth = 0;
+    for (const char of group) {
+        if (char === '{') {
+            depth++;
+        }
+        else if (char === '}' && depth > 0) {
+            depth--;
+        }
+        if (char === ',' && depth === 0) {
+            globs.push(current);
+            current = '';
+        }
+        else {
+            current += char;
+        }
+    }
+    globs.push(current);
+    // An unbalanced `{` would swallow the rest of the list; a plain split is
+    // the better guess then.
+    return depth === 0 ? globs : group.split(',');
+}
 function expandInputs(inputs, project, allWorkspaceFiles, depGraphClientResponse) {
     const projectNames = depGraphClientResponse.projects.map((p) => p.name);
     const workspaceRootInputs = [];
     const projectRootInputs = [];
     const externalInputs = [];
     const otherInputs = [];
+    const filesInputs = [];
     inputs.forEach((input) => {
         // grouped workspace inputs look like workspace:[pattern,otherPattern]
         if (input.startsWith('workspace:[')) {
-            const inputs = input.substring(11, input.length - 1).split(',');
-            workspaceRootInputs.push(...inputs);
+            workspaceRootInputs.push(...splitGlobGroup(input.substring(11, input.length - 1)));
+            return;
+        }
+        // Disk-backed groups look like files:[glob,!otherGlob]. They expand on
+        // disk, so they must be matched before the `:` catch-all below classifies
+        // them as external dependencies.
+        const diskBacked = /^files:\[(.*)\]$/.exec(input);
+        if (diskBacked) {
+            filesInputs.push(splitGlobGroup(diskBacked[1]));
             return;
         }
         const maybeProjectName = input.split(':')[0];
@@ -881,6 +915,7 @@ function expandInputs(inputs, project, allWorkspaceFiles, depGraphClientResponse
         }
     });
     const workspaceRootsExpanded = getExpandedWorkspaceRoots(workspaceRootInputs, allWorkspaceFiles);
+    const filesExpanded = filesInputs.flatMap((globs) => (0, native_1.expandFilesInput)(workspace_root_1.workspaceRoot, globs));
     const otherInputsExpanded = otherInputs.map((input) => {
         if (input === 'TsConfig') {
             return (0, node_path_1.relative)(workspace_root_1.workspaceRoot, (0, typescript_1.getRootTsConfigPath)());
@@ -908,7 +943,11 @@ function expandInputs(inputs, project, allWorkspaceFiles, depGraphClientResponse
         return acc;
     }, {});
     return {
-        general: [...workspaceRootsExpanded, ...otherInputsExpanded],
+        general: [
+            ...workspaceRootsExpanded,
+            ...filesExpanded,
+            ...otherInputsExpanded,
+        ],
         ...projectRootsExpanded,
         external: externalInputs,
     };

package/dist/src/command-line/init/implementation/format.js

@@ -72,8 +72,7 @@ command = 'nx init') {
     // already finished.
     //
     // Chunked as `nx format` chunks: the Angular flow records a `project.json`
-    // per project. The prettier path is sized against its quoted length; oxfmt
-    // goes through execFile and gets raw paths.
+    // per project.
     let formatter = null;
     try {
         formatter = (0, formatters_1.detectFormatter)(repoRoot);
@@ -93,7 +92,7 @@ command = 'nx init') {
             // batch, but exits 2 on one unsupported file, which would end a
             // successful init with a spurious warning and prettier's own stderr.
             const supported = await (0, prettier_1.filterToPrettierSupportedFiles)(files);
-            for (const chunk of (0, chunkify_1.chunkify)(supported, undefined, (pattern) => (0, prettier_1.quoteForShell)(pattern).length)) {
+            for (const chunk of (0, chunkify_1.chunkify)(supported)) {
                 if (chunk.length) {
                     (0, prettier_1.writeWithPrettier)(chunk, repoRoot);
                 }

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

@@ -4,6 +4,7 @@ exports.AGENT_DEFINITIONS = exports.opencodeDefinition = exports.codexDefinition
 exports.getAgentDefinition = getAgentDefinition;
 const os_1 = require("os");
 const path_1 = require("path");
+const smol_toml_1 = require("smol-toml");
 const types_1 = require("./types");
 // --- Claude Code ---------------------------------------------------------
 function claudeCodeWellKnownPaths() {
@@ -49,15 +50,14 @@ function claudeCodeHandoffAllowedTools(runDirName) {
 function claudeCodeBuildInteractive(ctx) {
     const allowedTools = claudeCodeHandoffAllowedTools(ctx.runDirName);
     return {
-        // `--allowedTools` is variadic (space/comma separated): a positional
-        // placed right after its value gets swallowed as another rule. The rules
-        // must stay in one comma-joined element with a non-variadic flag
-        // (`--system-prompt`) between them and the user prompt.
+        // `--allowedTools` is variadic, so a positional right after it is read as
+        // another rule: keep the rules in one comma-joined element and a flag
+        // between them and the instructions pointer.
         args: [
             ...(allowedTools ? ['--allowedTools', allowedTools] : []),
-            '--system-prompt',
-            ctx.systemContext,
-            ctx.userPrompt,
+            '--system-prompt-file',
+            ctx.systemPromptFilePath,
+            ctx.instructionsPointer,
         ],
         cwd: ctx.workspaceRoot,
     };
@@ -74,14 +74,41 @@ function codexWellKnownPaths() {
     return [];
 }
 // No handoff permission flag: codex's default sandbox already allows writes
-// inside the cwd tree without prompting, and a user-hardened read-only config
-// is a deliberate choice we don't override.
+// inside the cwd tree, and a user-hardened read-only config is theirs to keep.
+//
+// `-c model_instructions_file` replaces codex's built-in instructions rather
+// than adding this context to them, so the context stays on the command line,
+// reduced rather than the full prompt.
 function codexBuildInteractive(ctx) {
     return {
-        args: ['-c', `developer_instructions=${ctx.systemContext}`, ctx.userPrompt],
+        args: [
+            '-c',
+            `developer_instructions=${encodeTomlString(ctx.inlineSystemContext)}`,
+            ctx.instructionsPointer,
+        ],
         cwd: ctx.workspaceRoot,
     };
 }
+/**
+ * Encodes a single-line TOML string for codex overrides. Codex treats a parse
+ * failure as literal text instead of reporting it, so the result is parsed
+ * back before it reaches the command line.
+ */
+function encodeTomlString(value) {
+    // JSON escapes every control TOML rejects except DEL, which it leaves raw.
+    const encoded = JSON.stringify(value).replace(/\x7f/g, '\\u007F');
+    let decoded;
+    try {
+        decoded = (0, smol_toml_1.parse)(`value = ${encoded}`).value;
+    }
+    catch (err) {
+        throw new Error(`Could not encode the agent's system context as TOML for OpenAI Codex: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+    }
+    if (decoded !== value) {
+        throw new Error(`Encoding the agent's system context as TOML for OpenAI Codex did not round-trip; refusing to run the agent on altered instructions.`);
+    }
+    return encoded;
+}
 exports.codexDefinition = {
     id: 'codex',
     displayName: 'OpenAI Codex',
@@ -110,25 +137,54 @@ function opencodeWellKnownPaths() {
     return candidates;
 }
 // No handoff permission config: opencode's `edit` permission defaults to
-// allow, and injecting one would clobber (not merge with) a user's own
-// permission patterns.
+// allow, and injecting one would clobber a user's own patterns rather than
+// merge with them.
+//
+// The config travels through OPENCODE_CONFIG_CONTENT rather than
+// OPENCODE_CONFIG. Both merge with the user's own config, but the runner
+// spreads `env` over `process.env`, so the latter would overwrite a value the
+// user had set.
 function opencodeBuildInteractive(ctx) {
-    const config = {
-        agent: {
-            [OPENCODE_TRANSIENT_AGENT_NAME]: { prompt: ctx.systemContext },
-        },
-    };
     return {
         args: [
             '--agent',
             OPENCODE_TRANSIENT_AGENT_NAME,
             '--prompt',
-            ctx.userPrompt,
+            ctx.instructionsPointer,
         ],
-        env: { OPENCODE_CONFIG_CONTENT: JSON.stringify(config) },
+        env: { OPENCODE_CONFIG_CONTENT: opencodeConfigContent(ctx) },
         cwd: ctx.workspaceRoot,
     };
 }
+/**
+ * Escapes inline prompt patterns before opencode's pre-JSON substitution pass.
+ * Excludes generator instructions from the config; cmd.exe drops inherited
+ * variables longer than 8191 characters.
+ */
+function opencodeConfigContent(ctx) {
+    // Windows separators become `/`, which its APIs accept just as well.
+    // Elsewhere a `\` belongs to the file name.
+    const filePath = process.platform === 'win32'
+        ? ctx.systemPromptFilePath.replace(/\\/g, '/')
+        : ctx.systemPromptFilePath;
+    const prompt = isSubstitutionSafePath(filePath)
+        ? JSON.stringify(`{file:${filePath}}`)
+        : // `\u007b` starts no pattern and JSON decodes it back to `{`, so the
+            // prompt survives expansion whatever the workspace path put in it.
+            JSON.stringify(ctx.systemPrompt).replace(/\{/g, '\\u007b');
+    // Assembled rather than serialized whole: `JSON.stringify` over the object
+    // would re-escape the backslashes the `\u007b` encoding introduced.
+    return `{"agent":{${JSON.stringify(OPENCODE_TRANSIENT_AGENT_NAME)}:{"prompt":${prompt}}}}`;
+}
+/**
+ * Whether opencode would read back the path nx wrote. A `}` closes the
+ * reference early, and a character JSON escapes arrives escaped. Braces are
+ * rejected wholesale rather than matched against `{env:` and `{file:`, since a
+ * pattern opening inside the path swallows the reference's closing brace.
+ */
+function isSubstitutionSafePath(filePath) {
+    return (!/[{}]/.test(filePath) && JSON.stringify(filePath).slice(1, -1) === filePath);
+}
 exports.opencodeDefinition = {
     id: 'opencode',
     displayName: 'OpenCode',

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

@@ -0,0 +1,14 @@
+import { FormatterType } from '../../../utils/formatters';
+/**
+ * The command the agent runs over the files it changed, with a `<paths>`
+ * placeholder. `--` keeps a path that starts with `-` from being read as an
+ * option.
+ */
+export declare function formatCommandFor(formatter: FormatterType, pmExec: string): string;
+/**
+ * Resolved per dispense so a migration's formatter change takes effect; the
+ * scope rules name the replacement commands for the step that made it. `null`
+ * when no formatter is configured or its binary cannot be resolved: under npm
+ * the command would otherwise make `npx` download it.
+ */
+export declare function resolveFormatCommand(root: string, pmExec: string): string | null;

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

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatCommandFor = formatCommandFor;
+exports.resolveFormatCommand = resolveFormatCommand;
+const formatters_1 = require("../../../utils/formatters");
+/**
+ * The command the agent runs over the files it changed, with a `<paths>`
+ * placeholder. `--` keeps a path that starts with `-` from being read as an
+ * option.
+ */
+function formatCommandFor(formatter, pmExec) {
+    switch (formatter) {
+        case 'prettier':
+            // --ignore-unknown skips files prettier has no parser for.
+            return `${pmExec} prettier --write --ignore-unknown -- <paths>`;
+        case 'oxfmt':
+            // oxfmt exits 2 when every path was skipped; the flag makes that
+            // success. Unlike prettier it skips unparseable files on its own.
+            return `${pmExec} oxfmt --no-error-on-unmatched-pattern -- <paths>`;
+        default: {
+            const unhandled = formatter;
+            throw new Error(`Unhandled formatter: ${unhandled}`);
+        }
+    }
+}
+/**
+ * Resolved per dispense so a migration's formatter change takes effect; the
+ * scope rules name the replacement commands for the step that made it. `null`
+ * when no formatter is configured or its binary cannot be resolved: under npm
+ * the command would otherwise make `npx` download it.
+ */
+function resolveFormatCommand(root, pmExec) {
+    const formatter = (0, formatters_1.detectFormatter)(root);
+    if (formatter === null) {
+        return null;
+    }
+    try {
+        formatters_1.resolveFormatterBin[formatter]();
+    }
+    catch {
+        return null;
+    }
+    return formatCommandFor(formatter, pmExec);
+}

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

@@ -1,8 +1,8 @@
 /**
  * Both the agentic runner and the orchestrator write per-run scratch under
- * `.nx/migrate-runs/<run-id>/`: handoff files in both cases, plus the durable
- * run state and its plan snapshots for the orchestrator. The v23 migration
- * `23-0-0-add-migrate-runs-to-git-ignore` adds `.nx/migrate-runs` to
+ * `.nx/migrate-runs/<run-id>/`: handoff and prompt files in both cases, plus
+ * the durable run state and its plan snapshots for the orchestrator. The v23
+ * migration `23-0-0-add-migrate-runs-to-git-ignore` adds `.nx/migrate-runs` to
  * `.gitignore`; in its declared slot (typically late) earlier per-migration
  * commits would absorb the scratch into the user-visible diff.
  *

package/dist/src/command-line/migrate/agentic/handoff-gitignore.js

@@ -11,9 +11,9 @@ const logger_1 = require("../../../utils/logger");
 const types_1 = require("./types");
 /**
  * Both the agentic runner and the orchestrator write per-run scratch under
- * `.nx/migrate-runs/<run-id>/`: handoff files in both cases, plus the durable
- * run state and its plan snapshots for the orchestrator. The v23 migration
- * `23-0-0-add-migrate-runs-to-git-ignore` adds `.nx/migrate-runs` to
+ * `.nx/migrate-runs/<run-id>/`: handoff and prompt files in both cases, plus
+ * the durable run state and its plan snapshots for the orchestrator. The v23
+ * migration `23-0-0-add-migrate-runs-to-git-ignore` adds `.nx/migrate-runs` to
  * `.gitignore`; in its declared slot (typically late) earlier per-migration
  * commits would absorb the scratch into the user-visible diff.
  *

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

@@ -1,3 +1,4 @@
+import { type BigIntStats } from 'fs';
 import { HandoffFile } from './types';
 /** Returns the run directory for a given workspace + run id (target version). */
 export declare function runDirPath(workspaceRoot: string, runId: string): string;
@@ -19,19 +20,16 @@ export declare function mkdirSafely(dir: string, purpose: string): void;
  * inspection.
  */
 export declare function initRunDir(workspaceRoot: string, runId: string): string;
-/**
- * Absolute path of the handoff file for a migration step within a run, under
- * the run directory's `handoffs/` subtree: the pre-authorized write scope
- * stops there, so a handoff placed anywhere else costs an approval prompt.
- * The package's scope (if any) becomes a real subdirectory so the package name
- * stays readable; two packages can ship a migration with the same name without
- * colliding because they land in different package subdirectories. Each
- * segment is sanitized so the path is always writable on every platform.
- */
 export declare function stepHandoffPath(runDir: string, migration: {
     package: string;
     name: string;
 }): string;
+/** Handoff path for a run step. No hash needed: step ids are unique within the run. */
+export declare function runStepHandoffPath(runDir: string, stepId: string): string;
+export declare function stepPromptsDir(runDir: string, migration: {
+    package: string;
+    name: string;
+}): string;
 export type HandoffReadFailureReason = 'missing' | 'read-error' | 'parse-error' | 'shape-mismatch';
 export type HandoffReadResult = {
     ok: true;
@@ -42,19 +40,31 @@ export type HandoffReadResult = {
     detail?: string;
 };
 /**
- * Reads and validates a handoff file written by an agent. Returns a tagged
- * result so callers (the in-loop poller and the post-exit resolver) can
- * distinguish "file not yet written" from "file written but garbage" — the
- * latter is surfaced to the user instead of being collapsed into the same
- * generic ambiguous-outcome prompt.
+ * `lstat`, not `stat`: a symlink in the handoffs dir's place would send every
+ * handoff read and removal wherever it points.
+ */
+export declare function handoffsDirState(handoffsDir: string): 'directory' | 'missing' | 'other';
+/**
+ * Reads the file `stat` describes, refusing a symlink swapped in after the
+ * caller's lstat: O_NOFOLLOW fails the open with ELOOP, and O_NONBLOCK keeps a
+ * planted FIFO from blocking it. Windows has neither flag, so there the inode
+ * comparison is what catches a followed symlink. It does not guard against an
+ * unlink and recreate reusing the inode number. Read errors propagate: a file
+ * the agent cannot read must not pass.
+ */
+export declare function readInspectedFile(filePath: string, stat: BigIntStats, replacedMessage: string): string;
+/**
+ * Splits "not written yet" from "written but garbage" so callers can surface a
+ * malformed handoff instead of collapsing it into the generic
+ * ambiguous-outcome prompt.
  */
-export declare function readHandoffWithReason(filePath: string): HandoffReadResult;
+export declare function readHandoffWithReason(filePath: string, handoffsDir: string): HandoffReadResult;
 /**
  * Convenience wrapper preserving the original null-on-any-failure contract.
  * Used by the polling loop (`waitForValidHandoff`) where every failure mode
  * is "keep waiting" — the file may be missing, mid-write, or being rewritten.
  */
-export declare function readHandoff(filePath: string): HandoffFile | null;
+export declare function readHandoff(filePath: string, handoffsDir: string): HandoffFile | null;
 /**
  * Polls for a valid handoff file. Resolves once `readHandoff` accepts the
  * file's contents. Used to detect when the agent has finished its work so the
@@ -63,7 +73,7 @@ export declare function readHandoff(filePath: string): HandoffFile | null;
  *
  * Rejects with the abort reason when `options.signal` is aborted.
  */
-export declare function waitForValidHandoff(handoffFilePath: string, options?: {
+export declare function waitForValidHandoff(handoffFilePath: string, handoffsDir: string, options?: {
     intervalMs?: number;
     signal?: AbortSignal;
 }): Promise<void>;

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

@@ -5,9 +5,14 @@ exports.resolveAgenticRunId = resolveAgenticRunId;
 exports.mkdirSafely = mkdirSafely;
 exports.initRunDir = initRunDir;
 exports.stepHandoffPath = stepHandoffPath;
+exports.runStepHandoffPath = runStepHandoffPath;
+exports.stepPromptsDir = stepPromptsDir;
+exports.handoffsDirState = handoffsDirState;
+exports.readInspectedFile = readInspectedFile;
 exports.readHandoffWithReason = readHandoffWithReason;
 exports.readHandoff = readHandoff;
 exports.waitForValidHandoff = waitForValidHandoff;
+const crypto_1 = require("crypto");
 const fs_1 = require("fs");
 const path_1 = require("path");
 const semver_1 = require("semver");
@@ -56,14 +61,10 @@ function initRunDir(workspaceRoot, runId) {
 // a migration named `CON` would otherwise produce a `CON.json` that the
 // agent can't write to.
 const WINDOWS_RESERVED_NAMES = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\..*)?$/i;
-/**
- * The bare `.` / `..` check must come first — otherwise a malformed migration
- * name of exactly `..` would let the handoff write escape the run directory.
- */
 function sanitizeSegment(value) {
     if (value === '.' || value === '..')
         return '_';
-    let sanitized = value.replace(/[\x00-\x1f<>:"/\\|?*]/g, '_');
+    let sanitized = value.replace(/[\x00-\x1f<>:"/\\|?*+]/g, '_');
     // Windows forbids trailing dots/spaces on file/directory names.
     sanitized = sanitized.replace(/[. ]+$/, '');
     if (WINDOWS_RESERVED_NAMES.test(sanitized)) {
@@ -71,29 +72,111 @@ function sanitizeSegment(value) {
     }
     return sanitized || '_';
 }
+const STEP_NAME_PREFIX_MAX_BYTES = 64;
+// Cuts on code points so a multibyte character is never split, and counts
+// UTF-8 bytes because the filesystem limit is per byte, not per character.
+function truncateUtf8(value, maxBytes) {
+    let out = '';
+    let used = 0;
+    for (const ch of value) {
+        const bytes = Buffer.byteLength(ch);
+        if (used + bytes > maxBytes)
+            break;
+        out += ch;
+        used += bytes;
+    }
+    return out;
+}
 /**
- * Absolute path of the handoff file for a migration step within a run, under
- * the run directory's `handoffs/` subtree: the pre-authorized write scope
- * stops there, so a handoff placed anywhere else costs an approval prompt.
- * The package's scope (if any) becomes a real subdirectory so the package name
- * stays readable; two packages can ship a migration with the same name without
- * colliding because they land in different package subdirectories. Each
- * segment is sanitized so the path is always writable on every platform.
+ * The name a step's own files are keyed by, bounded to fit one path component.
+ * Sanitizing folds many characters to `_` and the prefix is cut to fit, so the
+ * SHA-256 of the raw package and name is what keeps two migrations apart.
  */
+function stepStem(migration) {
+    const prefix = truncateUtf8([...migration.package.split('/'), migration.name]
+        .map(sanitizeSegment)
+        .join('+'), STEP_NAME_PREFIX_MAX_BYTES);
+    const hash = (0, crypto_1.createHash)('sha256')
+        .update(JSON.stringify([migration.package, migration.name]))
+        .digest('hex');
+    return `${prefix}-${hash}`;
+}
 function stepHandoffPath(runDir, migration) {
-    return (0, path_1.join)(runDir, types_1.HANDOFFS_DIR_NAME, ...migration.package.split('/').map(sanitizeSegment), `${sanitizeSegment(migration.name)}.json`);
+    return (0, path_1.join)(runDir, types_1.HANDOFFS_DIR_NAME, `${stepStem(migration)}.json`);
+}
+/** Handoff path for a run step. No hash needed: step ids are unique within the run. */
+function runStepHandoffPath(runDir, stepId) {
+    return (0, path_1.join)(runDir, types_1.HANDOFFS_DIR_NAME, `${sanitizeSegment(stepId)}.json`);
+}
+function stepPromptsDir(runDir, migration) {
+    return (0, path_1.join)(runDir, types_1.PROMPTS_DIR_NAME, stepStem(migration));
 }
 /**
- * Reads and validates a handoff file written by an agent. Returns a tagged
- * result so callers (the in-loop poller and the post-exit resolver) can
- * distinguish "file not yet written" from "file written but garbage" — the
- * latter is surfaced to the user instead of being collapsed into the same
- * generic ambiguous-outcome prompt.
+ * `lstat`, not `stat`: a symlink in the handoffs dir's place would send every
+ * handoff read and removal wherever it points.
  */
-function readHandoffWithReason(filePath) {
+function handoffsDirState(handoffsDir) {
+    try {
+        return (0, fs_1.lstatSync)(handoffsDir).isDirectory() ? 'directory' : 'other';
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT')
+            return 'missing';
+        throw err;
+    }
+}
+/**
+ * Reads the file `stat` describes, refusing a symlink swapped in after the
+ * caller's lstat: O_NOFOLLOW fails the open with ELOOP, and O_NONBLOCK keeps a
+ * planted FIFO from blocking it. Windows has neither flag, so there the inode
+ * comparison is what catches a followed symlink. It does not guard against an
+ * unlink and recreate reusing the inode number. Read errors propagate: a file
+ * the agent cannot read must not pass.
+ */
+function readInspectedFile(filePath, stat, replacedMessage) {
+    const fd = (0, fs_1.openSync)(filePath, fs_1.constants.O_RDONLY |
+        (fs_1.constants.O_NOFOLLOW ?? 0) |
+        (fs_1.constants.O_NONBLOCK ?? 0));
+    try {
+        const fdStat = (0, fs_1.fstatSync)(fd, { bigint: true });
+        if (!fdStat.isFile() ||
+            fdStat.dev !== stat.dev ||
+            fdStat.ino !== stat.ino) {
+            throw new Error(replacedMessage);
+        }
+        return (0, fs_1.readFileSync)(fd, 'utf-8');
+    }
+    finally {
+        (0, fs_1.closeSync)(fd);
+    }
+}
+/**
+ * Splits "not written yet" from "written but garbage" so callers can surface a
+ * malformed handoff instead of collapsing it into the generic
+ * ambiguous-outcome prompt.
+ */
+function readHandoffWithReason(filePath, handoffsDir) {
     let raw;
     try {
-        raw = (0, fs_1.readFileSync)(filePath, 'utf-8');
+        switch (handoffsDirState(handoffsDir)) {
+            case 'missing':
+                return { ok: false, reason: 'missing' };
+            case 'other':
+                return {
+                    ok: false,
+                    reason: 'read-error',
+                    detail: `${handoffsDir} is not a directory`,
+                };
+        }
+        const stat = (0, fs_1.lstatSync)(filePath, { bigint: true });
+        if (!stat.isFile()) {
+            return {
+                ok: false,
+                reason: 'read-error',
+                detail: `${filePath} is not a regular file`,
+            };
+        }
+        raw = readInspectedFile(filePath, stat, `${filePath} was replaced while being read`);
     }
     catch (err) {
         const code = err?.code;
@@ -148,8 +231,8 @@ function readHandoffWithReason(filePath) {
  * Used by the polling loop (`waitForValidHandoff`) where every failure mode
  * is "keep waiting" — the file may be missing, mid-write, or being rewritten.
  */
-function readHandoff(filePath) {
-    const result = readHandoffWithReason(filePath);
+function readHandoff(filePath, handoffsDir) {
+    const result = readHandoffWithReason(filePath, handoffsDir);
     return result.ok ? result.handoff : null;
 }
 /**
@@ -160,7 +243,7 @@ function readHandoff(filePath) {
  *
  * Rejects with the abort reason when `options.signal` is aborted.
  */
-function waitForValidHandoff(handoffFilePath, options = {}) {
+function waitForValidHandoff(handoffFilePath, handoffsDir, options = {}) {
     const intervalMs = options.intervalMs ?? 500;
     const { signal } = options;
     return new Promise((resolve, reject) => {
@@ -180,7 +263,7 @@ function waitForValidHandoff(handoffFilePath, options = {}) {
                 onAbort();
                 return;
             }
-            if (readHandoff(handoffFilePath) !== null) {
+            if (readHandoff(handoffFilePath, handoffsDir) !== null) {
                 signal?.removeEventListener('abort', onAbort);
                 resolve();
                 return;

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

@@ -0,0 +1,21 @@
+export interface StepInstructionFiles {
+    /** Absolute path: config loaders resolve it, not the agent from its cwd. */
+    systemPromptFilePath: string;
+    /** Single-line command-line text pointing the agent at its instructions. */
+    instructionsPointer: string;
+}
+export interface WriteStepInstructionFilesArgs {
+    workspaceRoot: string;
+    runDir: string;
+    migration: {
+        package: string;
+        name: string;
+    };
+    systemPrompt: string;
+    instructions: string;
+}
+/**
+ * Writes prompts as files on every platform to keep one delivery path.
+ * Windows npm shims cannot carry multi-line prompts within cmd.exe's limit.
+ */
+export declare function writeStepInstructionFiles(args: WriteStepInstructionFilesArgs): StepInstructionFiles;