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

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

@@ -1,13 +1,22 @@
 "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;
+const crypto_1 = require("crypto");
 const fs_1 = require("fs");
 const path_1 = require("path");
 const semver_1 = require("semver");
@@ -56,14 +65,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 +76,166 @@ function sanitizeSegment(value) {
     }
     return sanitized || '_';
 }
+const STEP_NAME_PREFIX_MAX_BYTES = 64;
+// Truncates to a UTF-8 byte budget without splitting a code point.
+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));
+}
+/**
+ * `lstat`, not `stat`: a symlink in the handoffs dir's place would send every
+ * handoff read and removal wherever it points.
+ */
+function handoffsDirState(handoffsDir) {
+    try {
+        return (0, fs_1.lstatSync)(handoffsDir).isDirectory() ? 'directory' : 'other';
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT')
+            return 'missing';
+        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}`);
+        }
+    }
 }
 /**
- * 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.
+ * 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.
  */
-function readHandoffWithReason(filePath) {
+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
+ * 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 FileReplacedDuringReadError(replacedMessage);
+        }
+        return (0, fs_1.readFileSync)(fd, 'utf-8');
+    }
+    finally {
+        (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
+ * 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 +290,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 +302,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 +322,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,23 @@
+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;
+/** Writes `instructions.md` into an existing `promptsDir`; returns its path. */
+export declare function writeInstructionsFile(workspaceRoot: string, promptsDir: string, instructions: string): string;

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

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeStepInstructionFiles = writeStepInstructionFiles;
+exports.writeInstructionsFile = writeInstructionsFile;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const handoff_1 = require("./handoff");
+/**
+ * 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.
+ */
+function writeStepInstructionFiles(args) {
+    const { workspaceRoot, runDir, migration, systemPrompt, instructions } = args;
+    const promptsDir = (0, handoff_1.stepPromptsDir)(runDir, migration);
+    (0, handoff_1.mkdirSafely)(promptsDir, `prompt directory for ${migration.name}`);
+    const systemPromptFilePath = (0, path_1.join)(promptsDir, 'system.md');
+    writeStepFile(systemPromptFilePath, systemPrompt, 'system prompt');
+    const instructionsFilePath = writeInstructionsFile(workspaceRoot, promptsDir, instructions);
+    return {
+        systemPromptFilePath,
+        instructionsPointer: `Your instructions for this migration step are in the file ${instructionsFilePath} (path is relative to the workspace root). Read it in full, then follow it.`,
+    };
+}
+/** Writes `instructions.md` into an existing `promptsDir`; returns its path. */
+function writeInstructionsFile(workspaceRoot, promptsDir, instructions) {
+    const absolutePath = (0, path_1.join)(promptsDir, 'instructions.md');
+    writeStepFile(absolutePath, instructions, 'instructions');
+    // Workspace-relative: the agent resolves this one itself with its cwd pinned
+    // to the workspace root. Forward slashes because it is read as prose out of
+    // the agent's prompt, where a `\` is an escape.
+    return (0, path_1.relative)(workspaceRoot, absolutePath).replace(/\\/g, '/');
+}
+function writeStepFile(filePath, contents, purpose) {
+    try {
+        (0, fs_1.writeFileSync)(filePath, contents, 'utf-8');
+    }
+    catch (err) {
+        const code = err?.code;
+        throw new Error(`Could not write the step's ${purpose} to ${filePath}${code ? ` (${code})` : ''}: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+    }
+}

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;

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

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.masterInvariant = masterInvariant;
+exports.masterBootstrapPrompt = masterBootstrapPrompt;
+exports.buildMasterInvocation = buildMasterInvocation;
+const definitions_1 = require("../definitions");
+// One line with no `%`: the Windows shim refuses line breaks and the pinned
+// text is what its command-line budget is measured against.
+function masterInvariant(ctx) {
+    return `You are driving Nx migrate run ${ctx.runId}. Its state lives on disk and is owned by nx migrate; never infer its progress from this conversation. Whenever you are unsure what to do, after a compaction or restart, and after you finish any piece of work, run \`${ctx.reconcileCommand}\` and follow the step block it returns. The run's contract is the runbook at ${ctx.runbookPath}; re-read it whenever a step block says so. When a step block reports the run complete, tell the user the outcome, then create the file ${ctx.sentinelPath} as your last action; nx closes this session once it exists.`;
+}
+function masterBootstrapPrompt(ctx) {
+    return `Read the runbook at ${ctx.runbookPath} in full, then run \`${ctx.reconcileCommand}\` and follow the step block it returns.`;
+}
+const OPENCODE_AGENT_NAME = 'nx-migrate';
+// Keyed by agent id so a new agent fails to compile until it gets a builder.
+const builders = {
+    'claude-code': (ctx) => {
+        const allowedTools = (0, definitions_1.claudeCodeHandoffAllowedTools)(ctx.runId);
+        return {
+            // `--allowedTools` is variadic: the non-variadic flag between it and
+            // the positional prompt keeps the prompt from being read as a rule.
+            args: [
+                ...(allowedTools ? ['--allowedTools', allowedTools] : []),
+                '--append-system-prompt',
+                masterInvariant(ctx),
+                masterBootstrapPrompt(ctx),
+            ],
+        };
+    },
+    codex: (ctx) => ({
+        args: [
+            '-c',
+            `developer_instructions=${(0, definitions_1.encodeTomlString)(masterInvariant(ctx))}`,
+            masterBootstrapPrompt(ctx),
+        ],
+    }),
+    opencode: (ctx) => ({
+        args: [
+            '--agent',
+            OPENCODE_AGENT_NAME,
+            '--prompt',
+            masterBootstrapPrompt(ctx),
+        ],
+        env: {
+            OPENCODE_CONFIG_CONTENT: JSON.stringify({
+                agent: { [OPENCODE_AGENT_NAME]: { prompt: masterInvariant(ctx) } },
+            }),
+        },
+    }),
+};
+function buildMasterInvocation(agentId, ctx) {
+    return builders[agentId](ctx);
+}

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

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

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

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

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

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