nx 23.3.0-beta.2 → 23.3.0-beta.3

package/dist/bin/init-local.js

@@ -9,6 +9,7 @@ const client_1 = require("../src/daemon/client/client");
 const prompt_helpers_1 = require("../src/utils/prompt-helpers");
 const output_1 = require("../src/utils/output");
 const analytics_1 = require("../src/analytics");
+const is_ci_1 = require("../src/utils/is-ci");
 /**
  * Nx is being run inside a workspace.
  *
@@ -119,6 +120,11 @@ function shouldDelegateToAngularCLI() {
     return commands.indexOf(command) > -1;
 }
 async function ensureNxConsoleInstalledViaDaemon() {
+    // Asking the daemon makes a fresh daemon install nx@latest in the background,
+    // so skip it whenever the prompt could not be shown anyway.
+    if (!process.stdout.isTTY || (0, is_ci_1.isCI)()) {
+        return;
+    }
     // Only proceed if daemon is available
     if (!client_1.daemonClient.enabled() || !(await client_1.daemonClient.isServerAvailable())) {
         return;
@@ -126,7 +132,7 @@ async function ensureNxConsoleInstalledViaDaemon() {
     // Get status from daemon
     const status = await client_1.daemonClient.getNxConsoleStatus();
     // If we should prompt the user
-    if (status.shouldPrompt && process.stdout.isTTY) {
+    if (status.shouldPrompt) {
         output_1.output.log({
             title: "Install Nx's official editor extension to:",
             bodyLines: [

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

@@ -49,12 +49,16 @@ async function installPackage(pkgName, version, nxJson) {
         // pnpm 11+ fails the install when the plugin's own dependency tree
         // carries unacknowledged build scripts, and the plugin's generators can
         // only record allowBuilds decisions after this install. Warn and skip
-        // for this one install, like pnpm 10 did.
+        // for this one install, like pnpm 10 did. pnpm 12 gave `--config` a
+        // meaning of its own and takes the setting from the environment instead.
+        const env = { ...process.env };
         if (pm === 'pnpm' && (0, semver_1.gte)(pmv, '11.0.0')) {
             command += ' --config.strictDepBuilds=false';
+            env.PNPM_CONFIG_STRICT_DEP_BUILDS = 'false';
         }
         await new Promise((resolve) => (0, child_process_1.exec)(command, {
             windowsHide: true,
+            env,
         }, (error, stdout, stderr) => {
             if (error) {
                 spinner.fail();

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

@@ -252,13 +252,17 @@ function updateGitIgnore(root) {
 }
 function runInstall(repoRoot, packageManager = (0, package_manager_1.detectPackageManager)(repoRoot), pmc = (0, package_manager_1.getPackageManagerCommand)(packageManager)) {
     let command = pmc.install;
+    const env = { ...process.env };
     // Plugins added during init can pull build-script deps whose allowBuilds
     // entries are only recorded by their init generators after this install;
-    // warn and skip for this one install, like pnpm 10 did.
+    // warn and skip for this one install, like pnpm 10 did. pnpm 12 gave
+    // `--config` a meaning of its own and takes the setting from the
+    // environment instead.
     if (packageManager === 'pnpm') {
         try {
             if ((0, semver_1.gte)((0, package_manager_1.getPackageManagerVersion)('pnpm', repoRoot), '11.0.0')) {
                 command += ' --config.strictDepBuilds=false';
+                env.PNPM_CONFIG_STRICT_DEP_BUILDS = 'false';
             }
         }
         catch {
@@ -271,6 +275,7 @@ function runInstall(repoRoot, packageManager = (0, package_manager_1.detectPacka
             encoding: 'utf8',
             cwd: repoRoot,
             windowsHide: true,
+            env,
         });
     }
     catch (e) {

package/dist/src/command-line/migrate/agentic/capture-generator-output.d.ts

@@ -3,11 +3,36 @@
  * preserving the original behavior. Does not intercept
  * `process.{stdout,stderr}.write` — those bypass `console` and would also
  * pick up unrelated framework output. Restoration is idempotent.
+ *
+ * `flush()` returns at most `MAX_GENERATOR_OUTPUT_BYTES`: up to the first
+ * `HEAD_BYTES` of output, a marker with the omitted byte count, and the most
+ * recent output. The terminal still receives everything through the tee.
  */
 export interface GeneratorOutputCapture {
     flush(): string;
     restore(): void;
 }
+export declare const MAX_GENERATOR_OUTPUT_BYTES = 16384;
+export declare const MARKER_BYTES: number;
+export declare class BoundedOutput {
+    private readonly head;
+    private headBytes;
+    private headOpen;
+    private headSplit;
+    private readonly tail;
+    private tailBytes;
+    private omitted;
+    append(record: string): void;
+    render(): string;
+}
+export declare class BoundedChunks {
+    private head;
+    private headOpen;
+    private tail;
+    private omitted;
+    append(chunk: string): void;
+    render(): string;
+}
 export declare function installGeneratorOutputCapture(): GeneratorOutputCapture;
 /**
  * Convenience wrapper that installs the capture, runs `fn`, restores on

package/dist/src/command-line/migrate/agentic/capture-generator-output.js

@@ -1,9 +1,127 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.BoundedChunks = exports.BoundedOutput = exports.MARKER_BYTES = exports.MAX_GENERATOR_OUTPUT_BYTES = void 0;
 exports.installGeneratorOutputCapture = installGeneratorOutputCapture;
 exports.withGeneratorOutputCapture = withGeneratorOutputCapture;
 const node_util_1 = require("node:util");
 const logger_1 = require("../../../utils/logger");
+const handoff_1 = require("./handoff");
+exports.MAX_GENERATOR_OUTPUT_BYTES = 16384;
+const HEAD_BYTES = 4096;
+const omittedMarker = (omitted) => `[nx migrate: ${omitted} bytes of output omitted]`;
+// Reserved at the widest number spelling so a growing count cannot push a
+// flush over the cap.
+exports.MARKER_BYTES = Buffer.byteLength(`\n${omittedMarker(Number.MAX_VALUE)}\n`);
+const TAIL_LIMIT = exports.MAX_GENERATOR_OUTPUT_BYTES - HEAD_BYTES - exports.MARKER_BYTES;
+// Keeps the last `maxBytes` of `value`, cut on a code point.
+function keepTailUtf8(value, maxBytes) {
+    let start = value.length;
+    let kept = 0;
+    while (start > 0) {
+        const low = value.charCodeAt(start - 1);
+        const high = start > 1 ? value.charCodeAt(start - 2) : 0;
+        const from = low >= 0xdc00 && low <= 0xdfff && high >= 0xd800 && high <= 0xdbff
+            ? start - 2
+            : start - 1;
+        const bytes = Buffer.byteLength(value.slice(from, start));
+        if (kept + bytes > maxBytes)
+            break;
+        kept += bytes;
+        start = from;
+    }
+    return value.slice(start);
+}
+// The head/marker/tail buffer behind `flush()` above.
+class BoundedOutput {
+    constructor() {
+        this.head = [];
+        this.headBytes = 0;
+        this.headOpen = true;
+        // The head ends mid-record, so no newline separates it from the tail.
+        this.headSplit = false;
+        this.tail = [];
+        this.tailBytes = 0;
+        this.omitted = 0;
+    }
+    append(record) {
+        if (this.headOpen) {
+            const separator = this.head.length ? 1 : 0;
+            const bytes = Buffer.byteLength(record);
+            if (this.headBytes + separator + bytes <= HEAD_BYTES) {
+                this.head.push(record);
+                this.headBytes += separator + bytes;
+                return;
+            }
+            this.headOpen = false;
+            const prefix = (0, handoff_1.truncateUtf8)(record, HEAD_BYTES - this.headBytes - separator);
+            if (prefix) {
+                this.head.push(prefix);
+                this.headBytes += separator + Buffer.byteLength(prefix);
+                this.headSplit = true;
+                record = record.slice(prefix.length);
+            }
+        }
+        // Each tail record is charged its bytes plus a following newline; the last
+        // record's unused newline is one byte of slack at render time.
+        const cost = Buffer.byteLength(record) + 1;
+        this.tail.push({ text: record, cost });
+        this.tailBytes += cost;
+        while (this.tailBytes > TAIL_LIMIT && this.tail.length > 1) {
+            const dropped = this.tail.shift().cost;
+            this.tailBytes -= dropped;
+            this.omitted += dropped;
+        }
+        if (this.tailBytes > TAIL_LIMIT) {
+            const text = keepTailUtf8(this.tail[0].text, TAIL_LIMIT - 1);
+            const kept = Buffer.byteLength(text) + 1;
+            this.omitted += this.tailBytes - kept;
+            this.tail[0] = { text, cost: kept };
+            this.tailBytes = kept;
+        }
+    }
+    render() {
+        const head = this.head.join('\n');
+        const tail = this.tail.map((record) => record.text).join('\n');
+        if (this.omitted > 0) {
+            return `${head}\n${omittedMarker(this.omitted)}\n${tail}`;
+        }
+        if (!this.tail.length)
+            return head;
+        return this.headSplit ? head + tail : `${head}\n${tail}`;
+    }
+}
+exports.BoundedOutput = BoundedOutput;
+// The same head/marker/tail bound over a byte stream: chunks carry no record
+// boundary, so the cuts land on code points wherever the budgets run out and
+// the result does not depend on how the stream was chunked.
+class BoundedChunks {
+    constructor() {
+        this.head = '';
+        this.headOpen = true;
+        this.tail = '';
+        this.omitted = 0;
+    }
+    append(chunk) {
+        if (this.headOpen) {
+            const prefix = (0, handoff_1.truncateUtf8)(chunk, HEAD_BYTES - Buffer.byteLength(this.head));
+            this.head += prefix;
+            chunk = chunk.slice(prefix.length);
+            if (!chunk)
+                return;
+            this.headOpen = false;
+        }
+        const joined = this.tail + chunk;
+        this.tail = keepTailUtf8(joined, TAIL_LIMIT);
+        this.omitted += Buffer.byteLength(joined) - Buffer.byteLength(this.tail);
+    }
+    render() {
+        if (this.omitted > 0) {
+            return `${this.head}\n${omittedMarker(this.omitted)}\n${this.tail}`;
+        }
+        return this.head + this.tail;
+    }
+}
+exports.BoundedChunks = BoundedChunks;
 const CONSOLE_METHODS = [
     'log',
     'warn',
@@ -20,15 +138,13 @@ const NOOP_CAPTURE = {
     restore: () => { },
 };
 function installGeneratorOutputCapture() {
-    // Refuse to layer if the previous install never restored. Returns a noop
-    // handle so callers' `flush()` / `restore()` calls remain safe.
     for (const method of CONSOLE_METHODS) {
         if (console[method][CAPTURED_MARKER]) {
             logger_1.logger.verbose(`nx migrate: refusing to layer a second generator-output capture; the previous one was not restored. This typically means a caller skipped its \`try/finally\`. The inner caller's \`flush()\` will return empty, but its console output is still being captured by the outer install.`);
             return NOOP_CAPTURE;
         }
     }
-    const buffer = [];
+    const buffer = new BoundedOutput();
     const originals = new Map();
     for (const method of CONSOLE_METHODS) {
         originals.set(method, console[method]);
@@ -36,7 +152,7 @@ function installGeneratorOutputCapture() {
         const wrapper = ((...args) => {
             original(...args);
             try {
-                buffer.push((0, node_util_1.format)(...args));
+                buffer.append((0, node_util_1.format)(...args));
             }
             catch {
                 // `format` is robust against the common pathologies but a user arg
@@ -55,7 +171,7 @@ function installGeneratorOutputCapture() {
     let restored = false;
     return {
         flush() {
-            return buffer.join('\n');
+            return buffer.render();
         },
         restore() {
             if (restored)

package/dist/src/command-line/migrate/agentic/close-agent-session.d.ts

@@ -0,0 +1,21 @@
+import { type ChildProcess } from 'child_process';
+export declare const AGENT_GRACEFUL_EXIT_MS = 5000;
+export declare const FORCE_KILL_WAIT_MS = 500;
+export interface ExitInfo {
+    code?: number | null;
+    signal?: NodeJS.Signals | null;
+    error?: Error;
+}
+export declare function waitForExit(child: ChildProcess): Promise<ExitInfo>;
+/**
+ * Stops a running agent process.
+ *
+ * POSIX: SIGINT, then SIGKILL after a bounded wait. SIGTERM is skipped so a
+ * child that ignored the first graceful signal does not get a second one.
+ *
+ * Windows: `taskkill /T /F`. `child.kill` is a `TerminateProcess` call whatever
+ * the signal name, which on the `cmd.exe` shim path would kill the shim and
+ * orphan the agent. `taskkill` failures are swallowed.
+ */
+export declare function closeAgentSession(child: ChildProcess, exitPromise: Promise<ExitInfo>, gracefulExitMs: number, forceKillWaitMs: number): Promise<void>;
+export declare function raceWithTimeout(promise: Promise<unknown>, timeoutMs: number): Promise<void>;

package/dist/src/command-line/migrate/agentic/close-agent-session.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FORCE_KILL_WAIT_MS = exports.AGENT_GRACEFUL_EXIT_MS = void 0;
+exports.waitForExit = waitForExit;
+exports.closeAgentSession = closeAgentSession;
+exports.raceWithTimeout = raceWithTimeout;
+const child_process_1 = require("child_process");
+exports.AGENT_GRACEFUL_EXIT_MS = 5_000;
+// 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.
+exports.FORCE_KILL_WAIT_MS = 500;
+// Merge window so a paired exit + error both land in one ExitInfo. On
+// error-only paths like spawn ENOENT, where Node fires error but never exit,
+// this timer is the only 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();
+        });
+        child.on('error', (error) => {
+            info.error = error;
+            onFirst();
+        });
+    });
+}
+/**
+ * Stops a running agent process.
+ *
+ * POSIX: SIGINT, then SIGKILL after a bounded wait. SIGTERM is skipped so a
+ * child that ignored the first graceful signal does not get a second one.
+ *
+ * Windows: `taskkill /T /F`. `child.kill` is a `TerminateProcess` call whatever
+ * the signal name, which on the `cmd.exe` shim path would kill the shim and
+ * orphan the agent. `taskkill` failures are swallowed.
+ */
+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;
+    }
+    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;
+    try {
+        child.kill('SIGKILL');
+    }
+    catch {
+        /* child already gone */
+    }
+    await raceWithTimeout(exitPromise, forceKillWaitMs);
+}
+async function forceKillWindowsTree(child, exitPromise, forceKillWaitMs) {
+    const pid = child.pid;
+    // No pid means spawn itself failed, which the guard in `closeAgentSession`
+    // normally short-circuits. Without one there is nothing to taskkill.
+    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 */
+        }
+    }
+    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);
+    }
+}

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

@@ -1,5 +1,29 @@
 import { AgentDefinition, AgentId } from './types';
+/**
+ * Pre-authorizes the handoff write. Claude Code's default permission mode
+ * asks before a file write it has no allow rule for, so without this every
+ * step ends on an approval prompt for Nx's own handoff scratch.
+ *
+ * The rule reaches one run's handoffs and nothing else. Its own run
+ * directory also holds state Nx wrote and reads back, and the sibling
+ * directories belong to other runs, including an orchestrated run whose
+ * handoffs decide how its steps settle. `Edit` is the only tool name file
+ * rules are matched against, and it covers creating the file as well as
+ * correcting one already written. Prefix-less patterns resolve against the
+ * session cwd, which every caller pins to the workspace root.
+ *
+ * Returns null for a name it cannot express, which costs the approval prompt
+ * this exists to avoid. That beats widening the rule, and nothing narrower is
+ * available: Claude Code has no escape for a literal path.
+ */
+export declare function claudeCodeHandoffAllowedTools(runDirName: string): string | null;
 export declare const claudeCodeDefinition: AgentDefinition;
+/**
+ * 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.
+ */
+export declare function encodeTomlString(value: string): string;
 export declare const codexDefinition: AgentDefinition;
 export declare const opencodeDefinition: AgentDefinition;
 export declare const AGENT_DEFINITIONS: readonly AgentDefinition[];

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

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AGENT_DEFINITIONS = exports.opencodeDefinition = exports.codexDefinition = exports.claudeCodeDefinition = void 0;
+exports.claudeCodeHandoffAllowedTools = claudeCodeHandoffAllowedTools;
+exports.encodeTomlString = encodeTomlString;
 exports.getAgentDefinition = getAgentDefinition;
 const os_1 = require("os");
 const path_1 = require("path");
@@ -35,7 +37,7 @@ const RULE_SAFE_RUN_DIR_NAME = /^[A-Za-z0-9][A-Za-z0-9._+-]*$/;
  * handoffs decide how its steps settle. `Edit` is the only tool name file
  * rules are matched against, and it covers creating the file as well as
  * correcting one already written. Prefix-less patterns resolve against the
- * session cwd, pinned to the workspace root below.
+ * session cwd, which every caller pins to the workspace root.
  *
  * Returns null for a name it cannot express, which costs the approval prompt
  * this exists to avoid. That beats widening the rule, and nothing narrower is
@@ -74,7 +76,8 @@ function codexWellKnownPaths() {
     return [];
 }
 // No handoff permission flag: codex's default sandbox already allows writes
-// inside the cwd tree, and a user-hardened read-only config is theirs to keep.
+// inside the cwd tree (`.git` excepted), 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,

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

@@ -20,6 +20,7 @@ export declare function mkdirSafely(dir: string, purpose: string): void;
  * inspection.
  */
 export declare function initRunDir(workspaceRoot: string, runId: string): string;
+export declare function truncateUtf8(value: string, maxBytes: number): string;
 export declare function stepHandoffPath(runDir: string, migration: {
     package: string;
     name: string;
@@ -44,6 +45,18 @@ export type HandoffReadResult = {
  * handoff read and removal wherever it points.
  */
 export declare function handoffsDirState(handoffsDir: string): 'directory' | 'missing' | 'other';
+/**
+ * Non-recursive mkdir: the run dir exists, and a symlink created after the
+ * missing-path check fails with EEXIST instead of being followed.
+ */
+export declare function ensureRunSubdir(dir: string, notADirectory: () => Error): void;
+/**
+ * Thrown by {@link readInspectedFile} when the opened descriptor is not the
+ * file the caller's lstat described: a symlink followed on Windows, or an
+ * atomic replacement between the lstat and the open.
+ */
+export declare class FileReplacedDuringReadError extends Error {
+}
 /**
  * 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
@@ -53,6 +66,16 @@ export declare function handoffsDirState(handoffsDir: string): 'directory' | 'mi
  * the agent cannot read must not pass.
  */
 export declare function readInspectedFile(filePath: string, stat: BigIntStats, replacedMessage: string): string;
+/**
+ * Reads a file its owner publishes atomically (tmp + rename), with
+ * {@link readInspectedFile}'s refusal of a symlink or FIFO but tolerant of the
+ * publish: a rename swaps the inode between the lstat and the open, read as a
+ * replacement, so re-lstat and retry to read the new file. A pre-existing
+ * symlink or FIFO fails the isFile check before any open; a file that keeps
+ * changing past the retry budget is refused. Throws `notRegularMessage` for a
+ * non-regular file; ENOENT and ELOOP propagate.
+ */
+export declare function readAtomicallyPublishedFile(filePath: string, notRegularMessage: string): string;
 /**
  * Splits "not written yet" from "written but garbage" so callers can surface a
  * malformed handoff instead of collapsing it into the generic

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

@@ -1,14 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileReplacedDuringReadError = void 0;
 exports.runDirPath = runDirPath;
 exports.resolveAgenticRunId = resolveAgenticRunId;
 exports.mkdirSafely = mkdirSafely;
 exports.initRunDir = initRunDir;
+exports.truncateUtf8 = truncateUtf8;
 exports.stepHandoffPath = stepHandoffPath;
 exports.runStepHandoffPath = runStepHandoffPath;
 exports.stepPromptsDir = stepPromptsDir;
 exports.handoffsDirState = handoffsDirState;
+exports.ensureRunSubdir = ensureRunSubdir;
 exports.readInspectedFile = readInspectedFile;
+exports.readAtomicallyPublishedFile = readAtomicallyPublishedFile;
 exports.readHandoffWithReason = readHandoffWithReason;
 exports.readHandoff = readHandoff;
 exports.waitForValidHandoff = waitForValidHandoff;
@@ -73,8 +77,7 @@ 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.
+// Truncates to a UTF-8 byte budget without splitting a code point.
 function truncateUtf8(value, maxBytes) {
     let out = '';
     let used = 0;
@@ -125,6 +128,34 @@ function handoffsDirState(handoffsDir) {
         throw err;
     }
 }
+/**
+ * Non-recursive mkdir: the run dir exists, and a symlink created after the
+ * missing-path check fails with EEXIST instead of being followed.
+ */
+function ensureRunSubdir(dir, notADirectory) {
+    const state = handoffsDirState(dir);
+    switch (state) {
+        case 'directory':
+            return;
+        case 'missing':
+            (0, fs_1.mkdirSync)(dir);
+            return;
+        case 'other':
+            throw notADirectory();
+        default: {
+            const unhandled = state;
+            throw new Error(`Unhandled directory state: ${unhandled}`);
+        }
+    }
+}
+/**
+ * Thrown by {@link readInspectedFile} when the opened descriptor is not the
+ * file the caller's lstat described: a symlink followed on Windows, or an
+ * atomic replacement between the lstat and the open.
+ */
+class FileReplacedDuringReadError extends Error {
+}
+exports.FileReplacedDuringReadError = FileReplacedDuringReadError;
 /**
  * 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
@@ -142,7 +173,7 @@ function readInspectedFile(filePath, stat, replacedMessage) {
         if (!fdStat.isFile() ||
             fdStat.dev !== stat.dev ||
             fdStat.ino !== stat.ino) {
-            throw new Error(replacedMessage);
+            throw new FileReplacedDuringReadError(replacedMessage);
         }
         return (0, fs_1.readFileSync)(fd, 'utf-8');
     }
@@ -150,6 +181,34 @@ function readInspectedFile(filePath, stat, replacedMessage) {
         (0, fs_1.closeSync)(fd);
     }
 }
+const ATOMIC_READ_ATTEMPTS = 5;
+/**
+ * Reads a file its owner publishes atomically (tmp + rename), with
+ * {@link readInspectedFile}'s refusal of a symlink or FIFO but tolerant of the
+ * publish: a rename swaps the inode between the lstat and the open, read as a
+ * replacement, so re-lstat and retry to read the new file. A pre-existing
+ * symlink or FIFO fails the isFile check before any open; a file that keeps
+ * changing past the retry budget is refused. Throws `notRegularMessage` for a
+ * non-regular file; ENOENT and ELOOP propagate.
+ */
+function readAtomicallyPublishedFile(filePath, notRegularMessage) {
+    for (let attempt = 1;; attempt++) {
+        const stat = (0, fs_1.lstatSync)(filePath, { bigint: true });
+        if (!stat.isFile()) {
+            throw new Error(notRegularMessage);
+        }
+        try {
+            return readInspectedFile(filePath, stat, `${filePath} was replaced while being read.`);
+        }
+        catch (e) {
+            if (e instanceof FileReplacedDuringReadError &&
+                attempt < ATOMIC_READ_ATTEMPTS) {
+                continue;
+            }
+            throw e;
+        }
+    }
+}
 /**
  * Splits "not written yet" from "written but garbage" so callers can surface a
  * malformed handoff instead of collapsing it into the generic

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

@@ -0,0 +1,12 @@
+import type { AgentId, InvocationSpec } from '../types';
+export interface MasterInvocationContext {
+    runId: string;
+    reconcileCommand: string;
+    /** Workspace-relative with forward slashes: prose the agent reads, not a shell path. */
+    runbookPath: string;
+    /** Same form as `runbookPath`; its existence closes the session. */
+    sentinelPath: string;
+}
+export declare function masterInvariant(ctx: MasterInvocationContext): string;
+export declare function masterBootstrapPrompt(ctx: MasterInvocationContext): string;
+export declare function buildMasterInvocation(agentId: AgentId, ctx: MasterInvocationContext): InvocationSpec;