@ohos-ports/nx 23.3.0-beta.2 → 24.0.2-beta.0

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

@@ -1,9 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AGENT_DEFINITIONS = exports.opencodeDefinition = exports.codexDefinition = exports.claudeCodeDefinition = void 0;
+exports.AGENT_DEFINITIONS = exports.opencodeDefinition = exports.claudeCodeDefinition = void 0;
 exports.claudeCodeHandoffAllowedTools = claudeCodeHandoffAllowedTools;
 exports.encodeTomlString = encodeTomlString;
-exports.getAgentDefinition = getAgentDefinition;
 const os_1 = require("os");
 const path_1 = require("path");
 const smol_toml_1 = require("smol-toml");
@@ -20,10 +19,8 @@ function claudeCodeWellKnownPaths() {
  * The run directory names Nx will interpolate into a permission rule. A rule
  * is a gitignore pattern, which reads `*?[]\` as syntax, and `--allowedTools`
  * splits its value on commas and spaces, so a name carrying any of those
- * would change what the rule authorizes rather than what it names. Run
- * directory names derive from a migration's own version string, which nothing
- * upstream constrains to this alphabet. The leading character rejects `.`
- * and `..`.
+ * would change what the rule authorizes rather than what it names. The
+ * leading character rejects `.` and `..`.
  */
 const RULE_SAFE_RUN_DIR_NAME = /^[A-Za-z0-9][A-Za-z0-9._+-]*$/;
 /**
@@ -49,49 +46,16 @@ function claudeCodeHandoffAllowedTools(runDirName) {
     }
     return `Edit(${types_1.MIGRATE_RUNS_RELATIVE_DIR}/${runDirName}/${types_1.HANDOFFS_DIR_NAME}/**)`;
 }
-function claudeCodeBuildInteractive(ctx) {
-    const allowedTools = claudeCodeHandoffAllowedTools(ctx.runDirName);
-    return {
-        // `--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-file',
-            ctx.systemPromptFilePath,
-            ctx.instructionsPointer,
-        ],
-        cwd: ctx.workspaceRoot,
-    };
-}
 exports.claudeCodeDefinition = {
     id: 'claude-code',
     displayName: 'Claude Code',
     binaryNames: ['claude'],
     wellKnownPaths: claudeCodeWellKnownPaths,
-    buildInteractive: claudeCodeBuildInteractive,
 };
 // --- OpenAI Codex --------------------------------------------------------
 function codexWellKnownPaths() {
     return [];
 }
-// No handoff permission flag: codex's default sandbox already allows writes
-// 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,
-// reduced rather than the full prompt.
-function codexBuildInteractive(ctx) {
-    return {
-        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
@@ -112,15 +76,13 @@ function encodeTomlString(value) {
     }
     return encoded;
 }
-exports.codexDefinition = {
+const codexDefinition = {
     id: 'codex',
     displayName: 'OpenAI Codex',
     binaryNames: ['codex'],
     wellKnownPaths: codexWellKnownPaths,
-    buildInteractive: codexBuildInteractive,
 };
 // --- OpenCode ------------------------------------------------------------
-const OPENCODE_TRANSIENT_AGENT_NAME = 'nx-migrate';
 function opencodeWellKnownPaths() {
     if (process.platform === 'win32') {
         return [];
@@ -139,69 +101,15 @@ function opencodeWellKnownPaths() {
     candidates.push((0, path_1.join)(home, '.opencode', 'bin', 'opencode'));
     return candidates;
 }
-// No handoff permission config: opencode's `edit` permission defaults to
-// 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) {
-    return {
-        args: [
-            '--agent',
-            OPENCODE_TRANSIENT_AGENT_NAME,
-            '--prompt',
-            ctx.instructionsPointer,
-        ],
-        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',
     binaryNames: ['opencode'],
     wellKnownPaths: opencodeWellKnownPaths,
-    buildInteractive: opencodeBuildInteractive,
 };
 // --- Registry ------------------------------------------------------------
 exports.AGENT_DEFINITIONS = [
     exports.claudeCodeDefinition,
-    exports.codexDefinition,
+    codexDefinition,
     exports.opencodeDefinition,
 ];
-const byId = new Map(exports.AGENT_DEFINITIONS.map((definition) => [definition.id, definition]));
-function getAgentDefinition(id) {
-    return byId.get(id);
-}

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

@@ -1,30 +1,12 @@
 /**
- * Both the agentic runner and the orchestrator write per-run scratch under
- * `.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.
- *
- * Two paths cover the leak, with no overlap:
- *
- *   1. HOIST: `sortMigrations`, which `executeMigrations` applies, sorts the
- *      v23 migration to position 0 when it is in the queue, so it runs first
- *      through the normal runner with its own log line and commit. A
- *      single-migration worker run needs no hoisting: the requested migration
- *      is the entire queue.
- *
- *   2. INLINE FALLBACK, this function. When the migration is NOT in the queue
- *      AND the highest target version is < v23 (intra-pre-v23 `--agentic`
- *      run) it will never run, so apply its body inline against an `FsTree`
- *      and commit it as a standalone preflight commit (or leave it in the
- *      working tree under `--no-create-commits`).
- *
- * Not in the queue AND target >= v23 means the user is already past v23. They
- * had the entry historically; if it is gone, that is a conscious removal we
- * respect.
+ * Applies the v23 migration `23-0-0-add-migrate-runs-to-git-ignore` inline:
+ * the orchestrator writes run scratch at init, before that migration runs, and
+ * the run's commits would otherwise absorb it. Commits nothing; the init
+ * checkpoint carries the edit when commits are on and the checkpoint succeeds.
+ * Skipped at nx v23 or later unless the v23 migration is planned: a missing
+ * entry is then a conscious removal.
  */
-export declare function applyAgenticHandoffGitignoreFallback({ migrations, installedNxVersion, effectiveCreateCommits, commitPrefix, root, applyWhenPlanned, commitStandalone, }: {
+export declare function applyAgenticHandoffGitignoreFallback({ migrations, installedNxVersion, root, }: {
     migrations: ReadonlyArray<{
         package: string;
         name: string;
@@ -37,25 +19,5 @@ export declare function applyAgenticHandoffGitignoreFallback({ migrations, insta
      * version is irrelevant to whether `nx` itself crossed v23.
      */
     installedNxVersion: string;
-    effectiveCreateCommits: boolean;
-    commitPrefix: string;
     root: string;
-    /**
-     * Apply the entry even when the hoisted migration is in the plan. The
-     * classic loop can defer to that migration because its run scratch appears
-     * only after migration 1 has run; the orchestrator creates its run dir at
-     * init, before any migration, so it needs the entry immediately. A planned
-     * migration also means the missing entry is not a conscious removal, so the
-     * v23 cutoff does not apply.
-     */
-    applyWhenPlanned?: boolean;
-    /**
-     * Commit the applied entry as its own preflight commit (the default). The
-     * orchestrator suppresses this: it applies the fallback before its init
-     * checkpoint so the checkpoint's `git add -A` cannot sweep in older
-     * scratch, and in that ordering a standalone commit here would carry the
-     * user's pre-existing changes along with the entry. The checkpoint that
-     * follows captures both instead.
-     */
-    commitStandalone?: boolean;
 }): Promise<void>;

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

@@ -6,44 +6,19 @@ const semver_1 = require("semver");
 const pc = tslib_1.__importStar(require("picocolors"));
 const add_migrate_runs_to_git_ignore_1 = tslib_1.__importDefault(require("../../../migrations/update-23-0-0/add-migrate-runs-to-git-ignore"));
 const tree_1 = require("../../../generators/tree");
-const git_utils_1 = require("../../../utils/git-utils");
 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 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.
- *
- * Two paths cover the leak, with no overlap:
- *
- *   1. HOIST: `sortMigrations`, which `executeMigrations` applies, sorts the
- *      v23 migration to position 0 when it is in the queue, so it runs first
- *      through the normal runner with its own log line and commit. A
- *      single-migration worker run needs no hoisting: the requested migration
- *      is the entire queue.
- *
- *   2. INLINE FALLBACK, this function. When the migration is NOT in the queue
- *      AND the highest target version is < v23 (intra-pre-v23 `--agentic`
- *      run) it will never run, so apply its body inline against an `FsTree`
- *      and commit it as a standalone preflight commit (or leave it in the
- *      working tree under `--no-create-commits`).
- *
- * Not in the queue AND target >= v23 means the user is already past v23. They
- * had the entry historically; if it is gone, that is a conscious removal we
- * respect.
+ * Applies the v23 migration `23-0-0-add-migrate-runs-to-git-ignore` inline:
+ * the orchestrator writes run scratch at init, before that migration runs, and
+ * the run's commits would otherwise absorb it. Commits nothing; the init
+ * checkpoint carries the edit when commits are on and the checkpoint succeeds.
+ * Skipped at nx v23 or later unless the v23 migration is planned: a missing
+ * entry is then a conscious removal.
  */
-async function applyAgenticHandoffGitignoreFallback({ migrations, installedNxVersion, effectiveCreateCommits, commitPrefix, root, applyWhenPlanned = false, commitStandalone = true, }) {
-    if (migrations.some(types_1.isHandoffGitignoreMigration)) {
-        if (!applyWhenPlanned) {
-            // The queue runs it itself: hoisted to the front by the sort comparator
-            // in a full run, or as the single requested migration in a worker run.
-            return;
-        }
-    }
-    else if ((0, semver_1.major)(installedNxVersion) >= 23) {
+async function applyAgenticHandoffGitignoreFallback({ migrations, installedNxVersion, root, }) {
+    if (!migrations.some(types_1.isHandoffGitignoreMigration) &&
+        (0, semver_1.major)(installedNxVersion) >= 23) {
         // User is past v23. Respect their `.gitignore` state — if the entry
         // is missing, that's a conscious removal.
         return;
@@ -58,21 +33,4 @@ async function applyAgenticHandoffGitignoreFallback({ migrations, installedNxVer
     }
     (0, tree_1.flushChanges)(root, changes);
     logger_1.logger.info(pc.dim(`- Added ${types_1.MIGRATE_RUNS_RELATIVE_DIR} to .gitignore so this run's scratch state is ignored.`));
-    if (!effectiveCreateCommits || !commitStandalone)
-        return;
-    if (!(0, git_utils_1.hasUncommittedChanges)(root))
-        return;
-    try {
-        const sha = (0, git_utils_1.tryCommitChanges)(`${commitPrefix}add ${types_1.MIGRATE_RUNS_RELATIVE_DIR} to .gitignore`, root, [types_1.MIGRATE_RUNS_RELATIVE_DIR]);
-        if (sha) {
-            logger_1.logger.info(pc.dim(`  Commit: ${sha}`));
-        }
-        // `null` return = commit landed but `git rev-parse HEAD` raced. The
-        // diff cleared from the working tree; nothing more to say.
-    }
-    catch (err) {
-        const reason = err instanceof Error ? err.message : String(err);
-        logger_1.logger.info(pc.yellow(`Could not create the agentic preflight commit:\n${reason}\n` +
-            `The .gitignore change remains in the working tree; commit it manually or it will be absorbed into the first per-migration commit.`));
-    }
 }

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

@@ -1,36 +1,13 @@
 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;
-/** The version-derived run id: the highest target version in the plan. */
-export declare function resolveAgenticRunId(migrations: ReadonlyArray<{
-    version: string;
-}>): string;
 /**
  * `mkdir -p` with a contextual error wrapper. Without this, the raw
  * ENOSPC/EACCES/EROFS surfaces with no indication of which directory the
  * migrate orchestrator was trying to create.
  */
 export declare function mkdirSafely(dir: string, purpose: string): void;
-/**
- * Wipes any prior contents for this run id and recreates an empty directory.
- *
- * Scope of the wipe is intentionally narrow (only `<run-id>/`) so that handoff
- * artifacts from prior runs targeting different versions remain on disk for
- * 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;
-}): 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;
@@ -78,25 +55,6 @@ export declare function readInspectedFile(filePath: string, stat: BigIntStats, r
 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
- * ambiguous-outcome prompt.
+ * malformed handoff instead of treating it as not written.
  */
 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, 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
- * orchestrator can close the agent's session without depending on the agent
- * exiting on its own.
- *
- * Rejects with the abort reason when `options.signal` is aborted.
- */
-export declare function waitForValidHandoff(handoffFilePath: string, handoffsDir: string, options?: {
-    intervalMs?: number;
-    signal?: AbortSignal;
-}): Promise<void>;

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

@@ -1,35 +1,17 @@
 "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");
-const version_utils_1 = require("../version-utils");
 const types_1 = require("./types");
-/** Returns the run directory for a given workspace + run id (target version). */
-function runDirPath(workspaceRoot, runId) {
-    return (0, path_1.join)(workspaceRoot, types_1.MIGRATE_RUNS_RELATIVE_DIR, runId);
-}
-/** The version-derived run id: the highest target version in the plan. */
-function resolveAgenticRunId(migrations) {
-    return (0, semver_1.rsort)(migrations.map((m) => (0, version_utils_1.normalizeVersion)(m.version)))[0];
-}
 /**
  * `mkdir -p` with a contextual error wrapper. Without this, the raw
  * ENOSPC/EACCES/EROFS surfaces with no indication of which directory the
@@ -48,35 +30,6 @@ function mkdirSafely(dir, purpose) {
         throw new Error(`Could not create ${purpose} at ${dir}${code ? ` (${code})` : ''}: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
     }
 }
-/**
- * Wipes any prior contents for this run id and recreates an empty directory.
- *
- * Scope of the wipe is intentionally narrow (only `<run-id>/`) so that handoff
- * artifacts from prior runs targeting different versions remain on disk for
- * inspection.
- */
-function initRunDir(workspaceRoot, runId) {
-    const dir = runDirPath(workspaceRoot, runId);
-    (0, fs_1.rmSync)(dir, { recursive: true, force: true });
-    mkdirSafely(dir, 'nx migrate run directory');
-    return dir;
-}
-// Windows reserved device names fail to open even with an extension —
-// 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;
-function sanitizeSegment(value) {
-    if (value === '.' || value === '..')
-        return '_';
-    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)) {
-        sanitized = `_${sanitized}`;
-    }
-    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 = '';
@@ -90,29 +43,9 @@ function truncateUtf8(value, maxBytes) {
     }
     return out;
 }
-/**
- * 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, `${stepStem(migration)}.json`);
-}
-/** Handoff path for a run step. No hash needed: step ids are unique within the run. */
+// Step ids match run-state's STEP_ID (`step-<n>`), so they are safe file names.
 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));
+    return (0, path_1.join)(runDir, types_1.HANDOFFS_DIR_NAME, `${stepId}.json`);
 }
 /**
  * `lstat`, not `stat`: a symlink in the handoffs dir's place would send every
@@ -211,8 +144,7 @@ function readAtomicallyPublishedFile(filePath, notRegularMessage) {
 }
 /**
  * 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.
+ * malformed handoff instead of treating it as not written.
  */
 function readHandoffWithReason(filePath, handoffsDir) {
     let raw;
@@ -285,51 +217,3 @@ function readHandoffWithReason(filePath, handoffsDir) {
     }
     return { ok: true, handoff };
 }
-/**
- * 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.
- */
-function readHandoff(filePath, handoffsDir) {
-    const result = readHandoffWithReason(filePath, handoffsDir);
-    return result.ok ? result.handoff : 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
- * orchestrator can close the agent's session without depending on the agent
- * exiting on its own.
- *
- * Rejects with the abort reason when `options.signal` is aborted.
- */
-function waitForValidHandoff(handoffFilePath, handoffsDir, options = {}) {
-    const intervalMs = options.intervalMs ?? 500;
-    const { signal } = options;
-    return new Promise((resolve, reject) => {
-        if (signal?.aborted) {
-            reject(signal.reason ?? new Error('aborted'));
-            return;
-        }
-        let timer;
-        const onAbort = () => {
-            if (timer)
-                clearTimeout(timer);
-            signal?.removeEventListener('abort', onAbort);
-            reject(signal.reason ?? new Error('aborted'));
-        };
-        const tick = () => {
-            if (signal?.aborted) {
-                onAbort();
-                return;
-            }
-            if (readHandoff(handoffFilePath, handoffsDir) !== null) {
-                signal?.removeEventListener('abort', onAbort);
-                resolve();
-                return;
-            }
-            timer = setTimeout(tick, intervalMs);
-        };
-        signal?.addEventListener('abort', onAbort);
-        timer = setTimeout(tick, intervalMs);
-    });
-}

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

@@ -1,23 +1,2 @@
-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

@@ -1,41 +1,20 @@
 "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');
+        (0, fs_1.writeFileSync)(absolutePath, instructions, '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 });
+        throw new Error(`Could not write the step's instructions to ${absolutePath}${code ? ` (${code})` : ''}: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
     }
+    // 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, '/');
 }

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

@@ -1,4 +1,4 @@
-import { type RunOrchestratorInitInput } from '../../run';
+import { type MigrateRunPolicy, type MigrateRunState, type OrchestratorInitResult, type RunOrchestratorInitInput } from '../../run';
 import type { DetectedInstalledAgent } from '../types';
 export interface RunMasterSessionInput extends Omit<RunOrchestratorInitInput, 'emitAgentInstructions' | 'onExistingRun'> {
     agent: DetectedInstalledAgent;
@@ -14,3 +14,21 @@ export interface RunMasterSessionInput extends Omit<RunOrchestratorInitInput, 'e
  * session ends, not what the agent process returned.
  */
 export declare function runMasterSession(input: RunMasterSessionInput): Promise<number | undefined>;
+/**
+ * Hands a ready run to one agent session and reads the run's state once the
+ * session ends. `migration` is set for a `--run-migration` run. Returns null
+ * once it has printed why the session could not start or why its outcome is
+ * unknown; `notStartedHint` tells the user what to do when it could not start.
+ */
+export declare function driveMasterSession(input: {
+    agent: DetectedInstalledAgent;
+    ready: Extract<OrchestratorInitResult, {
+        kind: 'ready';
+    }>;
+    policy: MigrateRunPolicy;
+    migration?: {
+        package: string;
+        name: string;
+    };
+    notStartedHint: string;
+}): Promise<MigrateRunState | null>;