agentera 3.0.0-dev.41 → 3.0.0-dev.47

package/dist/upgrade/runtimeMigration.js

@@ -1,15 +1,11 @@
 import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
 import { createHash } from "node:crypto";
 import { isFile, pathExists, resolvePath } from "../core/paths.js";
-import { resolveSourceRoot } from "../core/sourceRoot.js";
-import { codexCopiedHooksAreAgenteraOnly, codexPluginHooksEnabled, retireCodexCopiedHookTrust, } from "../setup/codex.js";
 import { hasManagedMarker, opencodeConfigDir, } from "../setup/opencode.js";
 import { OPENCODE_SKILL_NAMES } from "../setup/opencodeConstants.js";
-import { resolveInvokedUpdateChannel } from "./channels.js";
 import { doctorRoots } from "./appModel.js";
-import { bindMigrationResource, removeBoundMigrationResource, updateBoundMigrationFile, verifyBoundMigrationResource, } from "./migrationPublication.js";
+import { bindMigrationResource, removeBoundMigrationResource, verifyBoundMigrationResource, } from "./migrationPublication.js";
 const PYTHON_MANAGED_PATTERNS = [
     /hooks\/validate_artifact\.py/,
     /hooks\/cursor_session_start\.py/,
@@ -36,190 +32,94 @@ export function projectHasProjectLevelRuntimeHooks(project) {
     return candidates.some((candidate) => isFile(candidate) || pathExists(candidate));
 }
 const OPENCODE_COMMAND_NAMES = ["agentera"];
-export function resolveNpxHookCommands(ctx, resolvedChannel) {
-    const env = ctx.env ?? process.env;
-    const home = ctx.home ?? env.HOME ?? os.homedir();
-    const sourceRoot = ctx.sourceRoot ?? resolveSourceRoot(env);
-    const channel = resolvedChannel ?? resolveInvokedUpdateChannel({
-        channel: ctx.channel ?? null,
-        env,
-        home,
-        sourceRoot,
-    });
-    const cliEntrypoint = channel.updateCommand.trim();
-    return {
-        cliEntrypoint,
-        validate: `${cliEntrypoint} hook validate-artifact`,
-        cursorSessionStart: `${cliEntrypoint} hook cursor-session-start`,
-        cursorSessionStop: `${cliEntrypoint} hook session-stop`,
-        cursorPreTool: `${cliEntrypoint} hook cursor-pre-tool-use`,
-    };
-}
 export function textUsesPythonManagedEntrypoint(text) {
     if (/AGENTERA_HOME\s*=/.test(text)) {
         return true;
     }
     return PYTHON_MANAGED_PATTERNS.some((pattern) => pattern.test(text));
 }
-const V3_NPX_ENTRYPOINT = /\bnpx\s+-y\s+agentera\b/;
-export function textUsesV3NpmEntrypoint(text) {
-    return V3_NPX_ENTRYPOINT.test(text);
-}
-export function rewireRuntimeText(text, runtime, commands) {
-    let next = text;
-    next = next.replace(/uv run\s+\\?"?\$\{AGENTERA_HOME\}\/hooks\/validate_artifact\.py\\?"?/g, commands.validate);
-    next = next.replace(/uv run\s+\\?"?\$\{AGENTERA_HOME\}\/app\/hooks\/validate_artifact\.py\\?"?/g, commands.validate);
-    next = next.replace(/uv run\s+\\?"?\$\{PLUGIN_ROOT\}\/hooks\/validate_artifact\.py\\?"?/g, commands.validate);
-    next = next.replace(/uv run\s+\\?"?\$\{AGENTERA_HOME\}\/(?:app\/scripts|(?:app\/)?hooks)\/cursor_session_start\.py\\?"?/g, `"${commands.cursorSessionStart}"`);
-    next = next.replace(/uv run\s+\\?"?\$\{AGENTERA_HOME\}\/(?:app\/)?hooks\/cursor_pre_tool_use\.py\\?"?/g, `"${commands.cursorPreTool}"`);
-    next = next.replace(/uv run\s+\\?"?\$\{AGENTERA_HOME\}\/(?:app\/)?hooks\/cursor_session_stop\.py\\?"?/g, `"${commands.cursorSessionStop}"`);
-    next = next.replace(/npx -y agentera hook /g, `${commands.cliEntrypoint} hook `);
-    next = next.replace(/npx -y agentera@latest hook /g, `${commands.cliEntrypoint} hook `);
-    if (runtime === "codex") {
-        next = next.replace(/AGENTERA_HOME\s*=\s*"[^"]*"/g, "");
-        next = next.replace(/AGENTERA_HOME\s*=\s*'[^']*'/g, "");
-        next = next.replace(/set\s*=\s*\{\s*,/g, "set = {");
-        next = next.replace(/,\s*,/g, ",");
-        next = next.replace(/,\s*\}/g, " }");
-        next = next.replace(/set\s*=\s*\{\s*\}/g, "set = { }");
+const RETIRED_NPX_HOOK = /\bnpx\s+-y\s+agentera(?:@(?:next|latest))?\s+hook\s+/;
+const V2_AGENTERA_HOOK = /(?:\buv(?:x|\s+run)\b[^"'\n]*(?:\$\{(?:AGENTERA_HOME|PLUGIN_ROOT)\}|hooks\/)\/[^"'\n]*\.py|\$\{AGENTERA_HOME\}\/(?:app\/scripts|(?:app\/)?hooks)\/[^"'\n]*\.py)/;
+function retiredHookCommands(value, commands = []) {
+    if (Array.isArray(value)) {
+        for (const entry of value)
+            retiredHookCommands(entry, commands);
+    }
+    else if (value !== null && typeof value === "object") {
+        for (const [key, entry] of Object.entries(value)) {
+            if (key === "command" && typeof entry === "string")
+                commands.push(entry);
+            else
+                retiredHookCommands(entry, commands);
+        }
     }
-    return next;
+    return commands;
 }
-function needsChannelNpxRewire(text, cliEntrypoint) {
-    if (/npx -y agentera hook /.test(text) && !text.includes(cliEntrypoint)) {
-        return true;
+function isRetiredAgenteraHookCommand(command) {
+    return V2_AGENTERA_HOOK.test(command) || RETIRED_NPX_HOOK.test(command);
+}
+/**
+ * Native hook files have no durable per-entry ownership record. Remove only a
+ * file whose every command is a retired Agentera invocation; mixed files are
+ * preserved for the owner to review rather than surgically rewritten.
+ */
+export function wholeResourceProvesV2HookOwnership(text) {
+    let document;
+    try {
+        document = JSON.parse(text);
     }
-    if (/npx -y agentera@latest hook /.test(text) && !text.includes(cliEntrypoint)) {
-        return true;
+    catch {
+        return false;
     }
-    return false;
+    const commands = retiredHookCommands(document);
+    return commands.length > 0 && commands.every(isRetiredAgenteraHookCommand);
 }
-function textHasAuthoritativeV2AgenteraEvidence(text) {
-    const variableReference = /\$\{AGENTERA_HOME\}\/(?:app\/scripts\/(?:agentera|cursor_session_start\.py)|(?:app\/)?hooks\/(?:validate_artifact|cursor_session_start|cursor_pre_tool_use|cursor_session_stop|session_start|session_stop)\.py)/;
-    if (variableReference.test(text))
-        return true;
-    if (/AGENTERA_HOME\s*=/.test(text))
-        return true;
-    if (/\[plugins\."agentera@agentera"\]/.test(text) && /AGENTERA_HOME\s*=/.test(text))
-        return true;
-    return false;
+function textContainsRetiredAgenteraHook(text) {
+    return textUsesPythonManagedEntrypoint(text) || RETIRED_NPX_HOOK.test(text);
 }
-function pushRewireItem(items, runtime, filePath, commands, allowedRoot) {
+function pushRetireHookItem(items, runtime, filePath, allowedRoot) {
     const text = fs.readFileSync(filePath, "utf8");
-    const needsBare = needsChannelNpxRewire(text, commands.cliEntrypoint);
-    const authoritative = hasManagedMarker(text)
-        || textHasAuthoritativeV2AgenteraEvidence(text)
-        || needsBare;
-    if (!authoritative) {
-        if (textUsesV3NpmEntrypoint(text)) {
-            items.push({
-                status: "noop",
-                action: "rewire-runtime",
-                runtime,
-                source: filePath,
-                message: "runtime config already references npm self-contained entrypoint",
-            });
-        }
-        // If the file has no Agentera content at all (no v2 Python, no v3 npm),
-        // it is not Agentera-managed. Do not push a blocked item — just return.
+    if (!textContainsRetiredAgenteraHook(text)) {
         return;
     }
-    const newText = rewireRuntimeText(text, runtime, commands);
-    const status = newText === text ? "blocked" : "pending";
     const item = {
-        status,
-        action: "rewire-runtime",
+        status: wholeResourceProvesV2HookOwnership(text) ? "pending" : "blocked",
+        action: "retire-hooks",
         runtime,
         source: filePath,
-        target: filePath,
-        newText,
-        message: status === "pending"
-            ? "will rewire runtime config from Python managed app-home to npm self-contained entrypoint"
-            : "runtime config uses Python managed paths but could not be rewritten safely",
+        message: wholeResourceProvesV2HookOwnership(text)
+            ? "will remove whole-resource-proven retired Agentera hook"
+            : "retired Agentera hook preserved: complete resource ownership is unproven; review and remove it manually",
     };
-    const evidenceError = bindMigrationResource(item, "target", filePath, [allowedRoot], "file");
+    if (item.status === "blocked") {
+        items.push(item);
+        return;
+    }
+    const evidenceError = bindMigrationResource(item, "source", filePath, [allowedRoot], "file");
     if (evidenceError) {
         item.status = "blocked";
-        item.message = `runtime config preserved: ${evidenceError}; review the unsafe path manually`;
+        item.message = `retired Agentera hook preserved: ${evidenceError}; review the unsafe path manually`;
     }
     items.push(item);
 }
-function planCodexItems(items, home, project, commands) {
+function planCodexItems(items, home, project) {
     for (const root of [project, home]) {
         const hooksPath = path.join(root, ".codex", "hooks", "codex-hooks.json");
-        const configPath = path.join(root, ".codex", "config.toml");
-        if (isFile(configPath)) {
-            const configText = fs.readFileSync(configPath, "utf8");
-            const pluginHooks = codexPluginHooksEnabled(configText);
-            if (pluginHooks && isFile(hooksPath)) {
-                let hooksText;
-                try {
-                    hooksText = fs.readFileSync(hooksPath, "utf8");
-                }
-                catch {
-                    hooksText = "";
-                }
-                if (codexCopiedHooksAreAgenteraOnly(hooksText)) {
-                    const rewiredConfig = rewireRuntimeText(configText, "codex", commands);
-                    const item = {
-                        status: "pending",
-                        action: "retire-hooks",
-                        runtime: "codex",
-                        source: hooksPath,
-                        target: configPath,
-                        newText: retireCodexCopiedHookTrust(rewiredConfig, hooksPath),
-                        message: "will remove Agentera-owned copied Codex hooks because plugin hooks are enabled",
-                    };
-                    const sourceError = bindMigrationResource(item, "source", hooksPath, [root], "file");
-                    const targetError = bindMigrationResource(item, "target", configPath, [root], "file");
-                    if (sourceError || targetError) {
-                        item.status = "blocked";
-                        item.message = `copied Codex hooks preserved: ${sourceError ?? targetError}; review the unsafe path manually`;
-                    }
-                    items.push(item);
-                    continue;
-                }
-                else if (hooksText.includes("validate_artifact") || hooksText.includes("hook validate-artifact")) {
-                    items.push({
-                        status: "blocked",
-                        action: "retire-hooks",
-                        runtime: "codex",
-                        source: hooksPath,
-                        target: configPath,
-                        message: "plugin hooks are enabled, but copied hook target needs manual review before retirement",
-                    });
-                    continue;
-                }
-            }
-            pushRewireItem(items, "codex", configPath, commands, root);
-        }
         if (isFile(hooksPath)) {
-            pushRewireItem(items, "codex", hooksPath, commands, root);
+            pushRetireHookItem(items, "codex", hooksPath, root);
         }
     }
 }
-function planCursorItems(items, home, project, commands) {
+function planCursorItems(items, home, project) {
     for (const [root, hooksPath] of [
         [project, path.join(project, ".cursor", "hooks.json")],
         [home, path.join(home, ".cursor", "hooks.json")],
     ]) {
         if (isFile(hooksPath)) {
-            pushRewireItem(items, "cursor", hooksPath, commands, root);
+            pushRetireHookItem(items, "cursor", hooksPath, root);
         }
     }
 }
-function planOpencodeItems(items, home, env, commands) {
-    const configDir = opencodeConfigDir(home, env);
-    const existingResources = [
-        path.join(configDir, "plugins", "agentera.js"),
-        ...OPENCODE_COMMAND_NAMES.map((name) => path.join(configDir, "commands", `${name}.md`)),
-        path.join(configDir, "agents", "agentera.md"),
-    ];
-    for (const resource of existingResources) {
-        if (isFile(resource))
-            pushRewireItem(items, "opencode", resource, commands, configDir);
-    }
-}
 function symlinkOwnership(linkPath, managedSkillsRoot) {
     let stat;
     let target;
@@ -382,10 +282,10 @@ function walkJsonHookFiles(dir) {
     walk(dir);
     return out;
 }
-function planCopilotItems(items, project, commands) {
+function planCopilotItems(items, project) {
     const hooksDir = path.join(project, ".github", "hooks");
     for (const hookFile of walkJsonHookFiles(hooksDir)) {
-        pushRewireItem(items, "copilot", hookFile, commands, project);
+        pushRetireHookItem(items, "copilot", hookFile, project);
     }
     if (!items.some((item) => item.runtime === "copilot")) {
         items.push({
@@ -396,26 +296,22 @@ function planCopilotItems(items, project, commands) {
         });
     }
 }
-export function planRuntimeMigrationItems(ctx, resolvedChannel) {
+export function planRuntimeMigrationItems(ctx) {
     if (!ctx.env) {
         throw new Error("MigrationContext.env is required for runtime migration planning; pass sandboxMigrationEnv(home, sourceRoot) in tests or an explicit env in callers.");
     }
     const home = resolvePath(ctx.home);
     const project = resolvePath(ctx.project);
     const env = ctx.env;
-    const sourceRoot = resolvePath(ctx.sourceRoot ?? resolveSourceRoot(env));
-    const commands = resolveNpxHookCommands({ ...ctx, home, env, sourceRoot }, resolvedChannel);
     const items = [];
-    planCodexItems(items, home, project, commands);
-    planCursorItems(items, home, project, commands);
-    planOpencodeItems(items, home, env, commands);
+    planCodexItems(items, home, project);
+    planCursorItems(items, home, project);
     planStaleCommandCleanupItems(ctx, items);
     planStaleSkillCleanupItems(ctx, items);
-    planCopilotItems(items, project, commands);
+    planCopilotItems(items, project);
     return items;
 }
 const RUNTIME_MIGRATION_ACTIONS = new Set([
-    "rewire-runtime",
     "retire-hooks",
     "remove-stale-command",
     "remove-stale-skill",
@@ -423,45 +319,22 @@ const RUNTIME_MIGRATION_ACTIONS = new Set([
 function isRuntimeMigrationAction(action) {
     return RUNTIME_MIGRATION_ACTIONS.has(action);
 }
-export function applyRuntimeMigrationItem(item, _commands) {
+export function applyRuntimeMigrationItem(item) {
     if (item.status !== "pending") {
         return;
     }
     try {
         switch (item.action) {
-            case "rewire-runtime": {
-                if (!item.target || item.newText === undefined) {
-                    item.status = "failed";
-                    item.message = "rewire-runtime missing target or newText";
-                    return;
-                }
-                updateBoundMigrationFile(item, "target", item.newText);
-                item.status = "applied";
-                item.message = "runtime config rewired to npm self-contained entrypoint";
-                break;
-            }
             case "retire-hooks": {
                 if (!item.source) {
                     item.status = "failed";
                     item.message = "retire-hooks missing source";
                     return;
                 }
-                if (!item.target) {
-                    item.status = "failed";
-                    item.message = "retire-hooks missing target";
-                    return;
-                }
                 verifyBoundMigrationResource(item, "source");
-                verifyBoundMigrationResource(item, "target");
-                if (item.newText === undefined) {
-                    item.status = "failed";
-                    item.message = "retire-hooks missing newText";
-                    return;
-                }
-                updateBoundMigrationFile(item, "target", item.newText);
                 removeBoundMigrationResource(item, "source");
                 item.status = "applied";
-                item.message = "retired Agentera-owned copied Codex hooks";
+                item.message = "retired whole-resource-proven Agentera hook";
                 break;
             }
             case "remove-stale-command": {
@@ -539,14 +412,13 @@ export function applyRuntimeMigrationItem(item, _commands) {
         item.message = `${item.action} preserved the resource: ${exc.message}; rerun migration and review it manually`;
     }
 }
-export function applyRuntimeMigrationItems(items, ctx) {
-    const commands = resolveNpxHookCommands(ctx);
+export function applyRuntimeMigrationItems(items, _ctx) {
     for (const item of items) {
         if (item.status !== "pending") {
             continue;
         }
         if (isRuntimeMigrationAction(item.action)) {
-            applyRuntimeMigrationItem(item, commands);
+            applyRuntimeMigrationItem(item);
         }
         else {
             item.status = "failed";
@@ -554,4 +426,3 @@ export function applyRuntimeMigrationItems(items, ctx) {
         }
     }
 }
-//# sourceMappingURL=runtimeMigration.js.map

package/dist/upgrade/upgradeCommands.js

@@ -12,6 +12,11 @@ export function fullEntityUpgradeCommand(project) {
         "npx", "-y", "agentera@next", "upgrade", "--channel", "development", "--project", project, "--yes",
     ]);
 }
+export function fullEntityUpgradePreviewCommand(project) {
+    return commandText([
+        "npx", "-y", "agentera@next", "upgrade", "--channel", "development", "--project", project, "--dry-run",
+    ]);
+}
 /** Channel-aware upgrade preview/apply commands (doctor, prime, orchestrator). */
 export function buildUpgradeCommands(args) {
     const base = args.channel.updateCommand.split(/\s+/).slice(0, 3);
@@ -46,4 +51,3 @@ export function buildUpgradeCommands(args) {
         applyCommand: commandText(applyParts),
     };
 }
-//# sourceMappingURL=upgradeCommands.js.map

package/dist/upgrade/upgradeLock.js

@@ -83,4 +83,3 @@ export function releaseUpgradeLock(lock) {
     fs.unlinkSync(lock.path);
     removeCreatedParent(path.dirname(lock.path), lock.createdParent);
 }
-//# sourceMappingURL=upgradeLock.js.map

package/dist/upgrade/upgradeOrchestrator.js

@@ -7,7 +7,7 @@ import { classifyUpgradeOutcome, isBlockedUpgradeOutcome, shouldIncludeCrossMajo
 import { resolveInvokedUpdateChannel } from "./channels.js";
 import { buildUpgradeCommands } from "./upgradeCommands.js";
 import { pendingRuntimeMigrationItems } from "./projectIntegration.js";
-import { planLegacyAgentCleanupItems, planLegacyCapabilityAgentCleanupItems, } from "./legacyAgentCleanup.js";
+import { REMOVE_LEGACY_AGENT_ACTION, planLegacyAgentCleanupItems, planLegacyCapabilityAgentCleanupItems, } from "./legacyAgentCleanup.js";
 import { MIGRATION_STATUSES, applyMigrationPhases, delegatePlanLifecycleToEntityCutover, detectV1ArtifactPairs, dryRunMigration, hasPendingPlanLifecycleMigration, } from "./migrateArtifactsV2ToV3.js";
 import { runLifecycleUpgrade, } from "./lifecycleUpgrade.js";
 import { acquireUpgradeLock, releaseUpgradeLock } from "./upgradeLock.js";
@@ -168,7 +168,7 @@ function entityReadinessPhase(project, sourceRoot, pendingV1Artifacts, selected,
                 action: empty ? "unsupported-state-source" : "entity-cutover",
                 message: empty
                     ? "marker-absent state has no recognized v2 entity input; preserve it and follow the manual source recovery instructions in UPGRADE.md"
-                    : `${cutover.entityCount} entity record(s) are ready for marker-last Git cutover`,
+                    : `${cutover.entityCount} entity record(s) are ready for marker-last Git cutover${cutover.todoReconciliation ? "; apply also journals TODO visible IDs, Markdown-owned public baselines, activation, canonical Markdown, and the authority marker" : ""}`,
             }]);
     }
     catch (error) {
@@ -196,6 +196,9 @@ function lifecyclePhase(result) {
         message: "summary only; selected native Agentera resource cleanup outcomes are reported under lifecycle.nativeResourceCleanup",
     };
 }
+function isIndependentLegacyAgentCollision(phase, item) {
+    return phase.name === "cleanup" && item.action === REMOVE_LEGACY_AGENT_ACTION && item.status === "blocked";
+}
 export function buildUpgradePlan(args) {
     if (args.runtime) {
         throw new Error(`--runtime ${args.runtime} is retired; use the shared skill at ~/.agents/skills/agentera plus the CLI and remove --runtime`);
@@ -255,6 +258,42 @@ function buildUpgradePlanUnlocked(args, home, project, activeUpgradeLockPaths) {
         channel,
     });
     const crossMajorBoundary = crossMajorBoundaryApplies(install, sourceRoot);
+    if (args.legacyCleanup) {
+        const lifecycle = runLifecycleUpgrade({
+            home,
+            appHome: installRoot,
+            apply: Boolean(args.yes),
+            resourceCleanup: args.legacyCleanup,
+        });
+        const phases = [lifecyclePhase(lifecycle)];
+        const summary = aggregateSummary(phases);
+        const status = workflowStatus(summary);
+        const commands = buildUpgradeCommands({
+            project,
+            installRoot: crossMajorBoundary ? installRoot : null,
+            channel,
+            legacyCleanup: args.legacyCleanup,
+            cwdDefault: true,
+        });
+        return {
+            schemaVersion: UPGRADE_PREVIEW_SCHEMA,
+            mode: args.yes ? "apply" : "plan",
+            status,
+            lifecycleStatus: lifecycleStatusFromWorkflow(status, args.yes ? "apply" : "plan"),
+            channel,
+            install,
+            upgradeOutcome,
+            crossMajorBoundary,
+            project,
+            appHome: installRoot,
+            home,
+            phases,
+            lifecycle,
+            summary,
+            dryRunCommand: summary.pending > 0 ? commands.dryRunCommand : null,
+            applyCommand: summary.pending > 0 ? commands.applyCommand : null,
+        };
+    }
     const phaseFilter = selectedPhases(args.only);
     const migrationCtx = {
         appHome: installRoot,
@@ -275,8 +314,10 @@ function buildUpgradePlanUnlocked(args, home, project, activeUpgradeLockPaths) {
         && channel.distributionMajor >= 3
         && !args.only
         && !args.legacyCleanup;
-    const pendingCleanup = planLegacyAgentCleanupItems(migrationCtx).some((i) => i.status === "pending") ||
-        planLegacyCapabilityAgentCleanupItems(migrationCtx).some((i) => i.status === "pending");
+    const pendingCleanup = [
+        ...planLegacyAgentCleanupItems(migrationCtx),
+        ...planLegacyCapabilityAgentCleanupItems(migrationCtx),
+    ].some((item) => item.status !== "noop");
     const runMigration = crossMajorMigration || projectEntityCutover || pendingRuntimeSync || pendingV1Artifacts || pendingPlanLifecycleMigration || pendingCleanup;
     const phases = [];
     if (phaseFilter.has("detect")) {
@@ -392,7 +433,7 @@ export function validateUpgradeApply(args, plan) {
     if (plan.crossMajorBoundary && args.only && args.only.length > 0) {
         return "cross-major v2→v3 apply must run as one full upgrade --yes; --only is preview-only at this boundary";
     }
-    if (isBlockedUpgradeOutcome(plan.upgradeOutcome)) {
+    if (!args.legacyCleanup && isBlockedUpgradeOutcome(plan.upgradeOutcome)) {
         return plan.upgradeOutcome.message ?? "upgrade blocked";
     }
     const appPhases = plan.phases.filter((phase) => phase.name !== "lifecycle");
@@ -400,11 +441,14 @@ export function validateUpgradeApply(args, plan) {
     const applyBlockingPhases = entityImportPending
         ? appPhases.filter((phase) => ["detect", "artifacts", "entities"].includes(phase.name))
         : appPhases;
-    if (applyBlockingPhases.some((phase) => phase.summary.blocked > 0 || phase.summary.failed > 0)) {
-        return applyBlockingPhases.flatMap((phase) => phase.items).find((item) => item.status === "blocked" || item.status === "failed")?.message
+    const blockingItems = applyBlockingPhases.flatMap((phase) => phase.items.filter((item) => (item.status === "blocked" || item.status === "failed") && !isIndependentLegacyAgentCollision(phase, item)));
+    if (blockingItems.length > 0) {
+        return blockingItems[0]?.message
             ?? "upgrade preflight is blocked; no changes were applied";
     }
-    if (plan.crossMajorBoundary &&
+    if (!args.legacyCleanup
+        &&
+            plan.crossMajorBoundary &&
         !shouldIncludeCrossMajorPlanItems(plan.channel, plan.upgradeOutcome)) {
         return ("cross-major v2→v3 migration requires the development channel while stable tracks 2.x; " +
             "run the same command with --dry-run on --channel development, then apply with --yes");
@@ -478,4 +522,3 @@ export function sortKeysDeep(value) {
     return value;
 }
 export { MAJOR_BOUNDARY_ITEM_TAG };
-//# sourceMappingURL=upgradeOrchestrator.js.map

package/dist/upgrade/v3CapabilitySurface.js

@@ -12,4 +12,3 @@ export function projectUsesV3CapabilityInstructionModules(projectRoot) {
     const root = path.resolve(projectRoot);
     return Object.keys(CAPABILITY_INSTRUCTIONS).every((name) => isFile(path.join(root, INSTRUCTION_MODULE_ROOT, name, "instructions.ts")));
 }
-//# sourceMappingURL=v3CapabilitySurface.js.map

package/dist/upgrade/versionResolution.js

@@ -184,4 +184,3 @@ export function isBlockedUpgradeOutcome(outcome) {
     return (outcome.kind === "blocked_downgrade_to_v2" ||
         outcome.kind === "blocked_downgrade_not_implemented");
 }
-//# sourceMappingURL=versionResolution.js.map