agentera 3.0.0-dev.6 → 3.0.0-dev.69

package/dist/upgrade/nextMajorDoctor.js

@@ -58,12 +58,16 @@ let testSuccessorAnnouncedOverride = null;
 export function setSuccessorAnnouncedOverrideForTests(value) {
     testSuccessorAnnouncedOverride = value;
 }
-/** True when stable-channel successor metadata exists and is announced for doctor/prime. */
-export function isStableSuccessorAnnounced(sourceRoot) {
+/**
+ * True when the resolved channel's successor metadata exists and is announced
+ * for doctor/prime. Defaults to the stable channel so legacy callers that
+ * omit the argument behave identically to pre-fix behavior.
+ */
+export function isStableSuccessorAnnounced(sourceRoot, channel = "stable") {
     if (testSuccessorAnnouncedOverride !== null) {
         return testSuccessorAnnouncedOverride;
     }
-    const block = loadChannelNextMajor(sourceRoot, "stable");
+    const block = loadChannelNextMajor(sourceRoot, channel);
     return block?.announced === true;
 }
 export function loadChannelNextMajor(sourceRoot, channel) {
@@ -88,10 +92,23 @@ export function formatNextMajorDoctorLines(args) {
         args.block.irreversibleAdvisory,
     ];
 }
+function installTrackSkipsSuccessorBlock(install, sourceRoot) {
+    if (install?.kind === "v3_self_contained_npm") {
+        return true;
+    }
+    if (install?.kind === "source_checkout" && cliDistributionMajor(sourceRoot) >= 3) {
+        return true;
+    }
+    return false;
+}
 export function resolveNextMajorDoctorLines(ctx) {
     const env = ctx.env ?? process.env;
     const home = ctx.home;
     const sourceRoot = ctx.sourceRoot;
+    const install = ctx.install ?? null;
+    if (installTrackSkipsSuccessorBlock(install, sourceRoot)) {
+        return null;
+    }
     const selected = resolveSelectedChannel({
         channel: ctx.channel ?? null,
         env,
@@ -99,7 +116,10 @@ export function resolveNextMajorDoctorLines(ctx) {
         sourceRoot,
     });
     const currentChannel = selected.channel;
-    const runningDistributionMajor = ctx.runningDistributionMajor ?? cliDistributionMajor(sourceRoot);
+    const successorChannel = install?.kind === "v2_managed_app_home" ? "stable" : currentChannel;
+    const displayChannel = install?.kind === "v2_managed_app_home" ? "stable" : currentChannel;
+    const runningDistributionMajor = ctx.runningDistributionMajor ??
+        (install?.kind === "v2_managed_app_home" ? 2 : cliDistributionMajor(sourceRoot));
     if (runningDistributionMajor === 1) {
         const block = V1_NEXT_MAJOR_FALLBACK;
         return formatNextMajorDoctorLines({
@@ -108,22 +128,22 @@ export function resolveNextMajorDoctorLines(ctx) {
             block,
         });
     }
-    const authorityBlock = loadChannelNextMajor(sourceRoot, currentChannel);
+    const authorityBlock = loadChannelNextMajor(sourceRoot, successorChannel);
     if (!authorityBlock || !authorityBlock.announced) {
         return null;
     }
     const runningVersion = ctx.runningVersion ??
-        (ctx.install
+        (install
             ? resolveRunningVersion({
-                appHome: ctx.install.appHome,
+                appHome: install.appHome,
                 sourceRoot,
-                install: ctx.install,
+                install,
             })
             : null) ??
         `${runningDistributionMajor}.x`;
     return formatNextMajorDoctorLines({
         currentVersion: runningVersion,
-        currentChannel,
+        currentChannel: displayChannel,
         block: authorityBlock,
     });
 }
@@ -133,4 +153,3 @@ export function prependNextMajorDoctorSection(text, sectionLines) {
     }
     return `${sectionLines.join("\n")}\n\n${text}`;
 }
-//# sourceMappingURL=nextMajorDoctor.js.map

package/dist/upgrade/npxPlatformStatus.js

@@ -0,0 +1,22 @@
+import { expanduser } from "../core/paths.js";
+import { resolvePlatformAppHome } from "./appModel.js";
+import { buildDoctorStatus } from "./doctor.js";
+/** Shared npx platform app-home resolution for prime and projectIntegration. */
+export function resolveNpxPlatformStatus(opts) {
+    const env = { ...process.env, ...(opts.env ?? {}), HOME: expanduser(opts.home) };
+    const platformRoot = resolvePlatformAppHome(opts.home, env);
+    const doctorOpts = {
+        rootSource: "default",
+        sourceRoot: opts.sourceRoot,
+        home: opts.home,
+        project: opts.project,
+        expectedCommands: opts.expectedCommands ?? ["prime"],
+        skipNpxBundleShortCircuit: true,
+        env,
+    };
+    if (opts.expectedVersion !== undefined) {
+        doctorOpts.expectedVersion = opts.expectedVersion;
+    }
+    const platformStatus = buildDoctorStatus(platformRoot, doctorOpts);
+    return { platformRoot, platformStatus };
+}

package/dist/upgrade/projectIntegration.js

@@ -1,92 +1,38 @@
-import { expanduser, isFile, resolvePath } from "../core/paths.js";
+import { resolvePath } from "../core/paths.js";
 import { isNpxBundleRoot } from "../core/sourceRoot.js";
-import { APP_MANUAL_REVIEW_NEEDED, APP_MIGRATION_NEEDED, APP_OUTDATED, APP_REPAIR_NEEDED, APP_UP_TO_DATE, buildDoctorStatus, } from "./doctor.js";
+import { APP_MIGRATION_NEEDED, APP_MANUAL_REVIEW_NEEDED, APP_OUTDATED, APP_REPAIR_NEEDED, APP_UP_TO_DATE, } from "./doctor.js";
+import { resolveNpxPlatformStatus } from "./npxPlatformStatus.js";
 import { classifyInstall, crossMajorBoundaryApplies } from "./compatibility.js";
 import { resolveInvokedUpdateChannel } from "./channels.js";
-import fs from "node:fs";
-import { detectV1ArtifactPairs, planRuntimeRewirePhase, } from "./migrateArtifactsV2ToV3.js";
-import { projectHasProjectLevelRuntimeHooks, textUsesPythonManagedEntrypoint, } from "./runtimeMigration.js";
-import { resolvePlatformAppHome } from "./appModel.js";
-import { buildUpgradeCommands } from "./upgradeCommands.js";
+import { detectV1ArtifactPairs, planRuntimeRetirementPhase, } from "./migrateArtifactsV2ToV3.js";
+import { projectHasProjectLevelRuntimeHooks, } from "./runtimeMigration.js";
 import { isStableSuccessorAnnounced } from "./nextMajorDoctor.js";
-import { classifyUpgradeOutcome, shouldIncludeCrossMajorPlanItems, } from "./versionResolution.js";
-function migrationContext(args, channel) {
-    const home = resolvePath(expanduser(args.home));
-    const env = { ...(args.env ?? process.env), HOME: home };
-    return {
-        appHome: args.installRoot,
-        project: resolvePath(args.project),
-        home,
-        sourceRoot: args.sourceRoot,
-        channel: args.channel ?? channel.channel,
-        env,
-    };
+import { buildUpgradeCommands } from "./upgradeCommands.js";
+import { classifyIntegrationScenario, integrationScenarioMessage, integrationExit, integrationPhase, } from "./projectIntegrationDecision.js";
+import { classifyUpgradeOutcome, parseSemverMajor, resolveRunningVersion, shouldIncludeCrossMajorPlanItems, } from "./versionResolution.js";
+const MAJOR_BOUNDARY_BLOCK_MESSAGE_PREFIX = "v3 successor line is not announced yet; v2 managed app files remain current on the";
+function majorBoundaryBlockMessage(channelName) {
+    const label = channelName.trim() || "current";
+    return `${MAJOR_BOUNDARY_BLOCK_MESSAGE_PREFIX} ${label} channel`;
 }
-const RUNTIME_MIGRATION_ACTIONS = new Set([
-    "rewire-runtime",
-    "retire-hooks",
-    "copy-plugin",
-    "copy-agent",
-    "copy-command",
-    "link-skill",
-]);
 function isPendingRuntimeMigrationItem(item) {
     if (item.status !== "pending" || item.action === "configure") {
         return false;
     }
-    if (item.action === "retire-hooks") {
-        return true;
-    }
-    if (item.action === "rewire-runtime") {
-        if (!item.source) {
-            return false;
-        }
-        try {
-            return textUsesPythonManagedEntrypoint(fs.readFileSync(item.source, "utf8"));
-        }
-        catch {
-            return false;
-        }
-    }
-    return RUNTIME_MIGRATION_ACTIONS.has(item.action);
-}
-function isPythonManagedRewireItem(item) {
-    if (item.action === "retire-hooks") {
-        return item.status === "pending";
-    }
-    if (item.action !== "rewire-runtime" || item.status !== "pending" || !item.source) {
-        return false;
-    }
-    try {
-        return textUsesPythonManagedEntrypoint(fs.readFileSync(item.source, "utf8"));
-    }
-    catch {
-        return false;
-    }
+    return true;
 }
 function isGlobalStaleRuntimeItem(item, ctx) {
     const homeRoot = resolvePath(ctx.home);
     if (!item.source?.startsWith(homeRoot)) {
         return false;
     }
-    if (item.action === "rewire-runtime" || item.action === "retire-hooks") {
+    if (item.action === "retire-hooks") {
         return true;
     }
-    if (item.action === "copy-plugin" && item.target) {
-        try {
-            if (isFile(item.target)) {
-                return textUsesPythonManagedEntrypoint(fs.readFileSync(item.target, "utf8"));
-            }
-            return item.source ? textUsesPythonManagedEntrypoint(fs.readFileSync(item.source, "utf8")) : false;
-        }
-        catch {
-            return false;
-        }
-    }
     return false;
 }
-export function pendingRuntimeMigrationItems(ctx) {
-    const phase = planRuntimeRewirePhase(ctx);
+export function pendingRuntimeMigrationItems(ctx, resolvedChannel) {
+    const phase = planRuntimeRetirementPhase(ctx, resolvedChannel);
     const projectRoot = resolvePath(ctx.project);
     const hasProjectHooks = projectHasProjectLevelRuntimeHooks(ctx.project);
     return phase.items.filter((item) => {
@@ -99,11 +45,6 @@ export function pendingRuntimeMigrationItems(ctx) {
         return isGlobalStaleRuntimeItem(item, ctx);
     });
 }
-/** True when runtime hooks/config still need npm self-contained rewiring. */
-export function projectHasPendingRuntimeRewire(ctx) {
-    const phase = planRuntimeRewirePhase(ctx);
-    return phase.items.some((item) => isPythonManagedRewireItem(item));
-}
 function appNeedsUpgrade(bundleStatus) {
     return (bundleStatus === APP_OUTDATED ||
         bundleStatus === APP_REPAIR_NEEDED ||
@@ -115,27 +56,25 @@ function resolveIntegrationTargets(args) {
             installRoot: args.installRoot,
             bundleStatus: args.bundleStatus,
             crossMajorBoundary: args.crossMajorBoundary ?? false,
+            crossMajorBoundaryDetected: args.crossMajorBoundaryDetected ?? false,
         };
     }
-    const platformRoot = resolvePlatformAppHome(args.home, args.env);
-    const platformStatus = buildDoctorStatus(platformRoot, {
-        rootSource: "default",
-        sourceRoot: args.sourceRoot,
+    const { platformRoot, platformStatus } = resolveNpxPlatformStatus({
         home: args.home,
+        sourceRoot: args.sourceRoot,
         project: args.project,
-        expectedCommands: ["prime"],
-        probeCli: false,
-        skipNpxBundleShortCircuit: true,
         env: args.env,
     });
     return {
         installRoot: platformRoot,
         bundleStatus: args.bundleStatus,
+        platformBundleStatus: platformStatus.status,
         crossMajorBoundary: Boolean(platformStatus.crossMajorBoundary),
+        crossMajorBoundaryDetected: Boolean(platformStatus.crossMajorBoundaryDetected),
     };
 }
 function commandChannel(args, channel, crossMajor, upgradeOutcome) {
-    if (crossMajor && !shouldIncludeCrossMajorPlanItems(channel, upgradeOutcome)) {
+    if (crossMajor && upgradeOutcome && !shouldIncludeCrossMajorPlanItems(channel, upgradeOutcome)) {
         return resolveInvokedUpdateChannel({
             channel: "development",
             env: args.env,
@@ -145,132 +84,149 @@ function commandChannel(args, channel, crossMajor, upgradeOutcome) {
     }
     return channel;
 }
+function appPhaseBlockers(bundleStatus, majorBoundaryBlock) {
+    const blockers = [];
+    if (bundleStatus === APP_MANUAL_REVIEW_NEEDED) {
+        blockers.push("app: manual review is required before choosing an app write path");
+    }
+    if (majorBoundaryBlock)
+        blockers.push(`app: ${majorBoundaryBlock}`);
+    return blockers;
+}
+function retryGuidance(exit) {
+    switch (exit.meaning) {
+        case "no_changes_needed":
+            return "No retry is needed; project integration is converged.";
+        case "preview_required":
+            return "Apply the approved preview, then retry Agentera to re-observe project integration.";
+        case "preview_and_blockers":
+            return "Resolve the reported blockers, apply the approved preview, then retry Agentera.";
+        case "manual_review_required":
+            return "Complete the manual review, then retry Agentera to re-observe project integration.";
+    }
+}
 export function summarizeProjectIntegration(args) {
-    const channel = resolveInvokedUpdateChannel({
+    const channel = args.resolvedChannel ?? resolveInvokedUpdateChannel({
         channel: args.channel ?? null,
         env: args.env,
         home: args.home,
         sourceRoot: args.sourceRoot,
     });
     const integrationTargets = resolveIntegrationTargets(args);
-    const install = classifyInstall({ appHome: integrationTargets.installRoot, sourceRoot: args.sourceRoot });
-    const crossMajorDetected = args.crossMajorBoundary ??
-        integrationTargets.crossMajorBoundary ??
+    const install = args.installClassification ?? classifyInstall({ appHome: integrationTargets.installRoot, sourceRoot: args.sourceRoot });
+    const crossMajorDetected = args.crossMajorBoundaryDetected ??
         crossMajorBoundaryApplies(install, args.sourceRoot);
-    const crossMajor = crossMajorDetected && isStableSuccessorAnnounced(args.sourceRoot);
-    const upgradeOutcome = classifyUpgradeOutcome({
+    const successorAnnounced = args.successorAnnounced ?? isStableSuccessorAnnounced(args.sourceRoot, "stable");
+    const crossMajor = crossMajorDetected && successorAnnounced;
+    const runningMajor = crossMajorDetected
+        ? parseSemverMajor(resolveRunningVersion({
+            appHome: integrationTargets.installRoot,
+            sourceRoot: args.sourceRoot,
+            install,
+        })) ?? 0
+        : 0;
+    const majorBoundaryBlock = crossMajorDetected && !successorAnnounced && runningMajor > 0 && runningMajor < 3
+        ? majorBoundaryBlockMessage(channel.channel)
+        : null;
+    const upgradeOutcome = crossMajor
+        ? classifyUpgradeOutcome({
+            appHome: integrationTargets.installRoot,
+            sourceRoot: args.sourceRoot,
+            install,
+            channel,
+        })
+        : null;
+    const v1Artifacts = args.precomputedV1Artifacts ?? detectV1ArtifactPairs(args.project);
+    const pendingProjectMigration = pendingRuntimeMigrationItems({
         appHome: integrationTargets.installRoot,
+        project: args.project,
+        home: args.home,
+        force: false,
         sourceRoot: args.sourceRoot,
-        install,
-        channel,
+        channel: args.channel ?? null,
+        env: args.env,
+    }, channel);
+    const crossMajorMigration = crossMajor && upgradeOutcome !== null && shouldIncludeCrossMajorPlanItems(channel, upgradeOutcome);
+    const isNpx = isNpxBundleRoot(args.sourceRoot);
+    const classificationBundleStatus = isNpx && integrationTargets.platformBundleStatus !== undefined
+        ? integrationTargets.platformBundleStatus
+        : integrationTargets.bundleStatus;
+    const needsAppUpgrade = isNpx && integrationTargets.bundleStatus === APP_UP_TO_DATE
+        ? appNeedsUpgrade(integrationTargets.platformBundleStatus ?? APP_UP_TO_DATE)
+        : appNeedsUpgrade(classificationBundleStatus);
+    const appPending = v1Artifacts.length +
+        pendingProjectMigration.length +
+        (needsAppUpgrade ? 1 : 0) +
+        (crossMajorMigration ? 1 : 0);
+    const appBlockers = appPhaseBlockers(classificationBundleStatus, majorBoundaryBlock);
+    const appPhase = integrationPhase({
+        total: appPending + appBlockers.length,
+        pending: appPending,
+        blocked: appBlockers.length,
+        blockers: appBlockers,
     });
-    const ctx = migrationContext({ ...args, installRoot: integrationTargets.installRoot }, channel);
-    const v1Artifacts = detectV1ArtifactPairs(args.project);
-    const pending = pendingRuntimeMigrationItems(ctx);
-    const pendingRuntimes = [
-        ...new Set(pending.map((item) => item.runtime).filter((runtime) => Boolean(runtime))),
-    ];
-    const crossMajorMigration = crossMajor && shouldIncludeCrossMajorPlanItems(channel, upgradeOutcome);
-    const crossMajorNeedsPreview = crossMajor && !crossMajorMigration;
-    const needsAppUpgrade = isNpxBundleRoot(args.sourceRoot) && args.bundleStatus === APP_UP_TO_DATE
-        ? false
-        : appNeedsUpgrade(integrationTargets.bundleStatus);
-    const artifactsOnly = v1Artifacts.length > 0 && !crossMajorMigration && !crossMajorNeedsPreview && !needsAppUpgrade;
-    const runtimeOnly = pending.length > 0 &&
-        !artifactsOnly &&
-        !crossMajorMigration &&
-        !crossMajorNeedsPreview &&
-        !needsAppUpgrade;
-    if (integrationTargets.bundleStatus === APP_MANUAL_REVIEW_NEEDED &&
-        pending.length === 0 &&
-        v1Artifacts.length === 0 &&
-        !crossMajor) {
-        return {
-            recommendation: "stay",
-            message: "Agentera needs manual review for your app directory before this project can be upgraded safely.",
-            pending_runtime: 0,
-            pending_runtimes: [],
-            pending_artifacts: 0,
-            dry_run_command: null,
-            apply_command: null,
-            update_channel: channel.channel,
-        };
-    }
-    if (!artifactsOnly &&
-        !runtimeOnly &&
-        !crossMajorMigration &&
-        !crossMajorNeedsPreview &&
-        !needsAppUpgrade &&
-        integrationTargets.bundleStatus === APP_UP_TO_DATE &&
-        pending.length === 0 &&
-        v1Artifacts.length === 0) {
-        return {
-            recommendation: "stay",
-            message: "This project matches your current Agentera install; no upgrade is needed.",
-            pending_runtime: 0,
-            pending_runtimes: [],
-            pending_artifacts: 0,
-            dry_run_command: null,
-            apply_command: null,
-            update_channel: channel.channel,
-        };
-    }
+    const hasUpgradeWork = appPending > 0;
+    const hasBlockers = appBlockers.length > 0;
+    const aggregateStatus = hasUpgradeWork
+        ? "upgrade"
+        : hasBlockers
+            ? "blocked"
+            : "stay";
+    const scenarioFacts = {
+        bundleStatus: classificationBundleStatus,
+        pendingArtifactCount: v1Artifacts.length + pendingProjectMigration.length,
+        crossMajor,
+        crossMajorMigration,
+        crossMajorNeedsPreview: Boolean(majorBoundaryBlock) || (crossMajor && !crossMajorMigration),
+        needsAppUpgrade,
+    };
+    const scenario = classifyIntegrationScenario(scenarioFacts);
+    const guidanceMessage = appBlockers.length > 0
+        ? appBlockers.join("; ")
+        : hasUpgradeWork
+            ? "Preview the app or project-state upgrade, then apply the approved command."
+            : "No app or project-state upgrade is required.";
+    const exit = integrationExit(hasUpgradeWork, appBlockers.length > 0);
     const cmdsChannel = commandChannel(args, channel, crossMajor, upgradeOutcome);
-    const onlyPhases = artifactsOnly
-        ? ["artifacts"]
-        : runtimeOnly
-            ? ["runtime"]
-            : undefined;
-    const installRootForCommands = crossMajorMigration || crossMajorNeedsPreview || needsAppUpgrade ? integrationTargets.installRoot : null;
-    const cmds = buildUpgradeCommands({
-        project: args.project,
-        installRoot: installRootForCommands,
-        channel: cmdsChannel,
-        only: onlyPhases,
-        cwdDefault: true,
-    });
-    let message;
-    if (artifactsOnly) {
-        message =
-            "This project still uses v1 Markdown artifacts; preview migrating them to v2 YAML before continuing.";
-    }
-    else if (crossMajorMigration || crossMajorNeedsPreview) {
-        message =
-            "Your Agentera app copy is still on v2 while the CLI is on v3; preview the one-way v2→v3 migration before applying.";
-    }
-    else if (needsAppUpgrade) {
-        message = "Your Agentera app copy is out of date; preview the repair or upgrade before applying.";
-    }
-    else if (pending.length > 0) {
-        const runtimes = pendingRuntimes.length > 0 ? pendingRuntimes.join(", ") : "runtime configs";
-        message = projectHasProjectLevelRuntimeHooks(args.project)
-            ? `This project still uses older Agentera runtime wiring (${runtimes}); preview rewiring hooks to the current npm entrypoint.`
-            : `Your user-level Agentera runtime wiring (${runtimes}) is stale; preview rewiring hooks to the current npm entrypoint.`;
-    }
-    else {
-        message = "Preview Agentera upgrade changes for this project before applying.";
-    }
+    const cmds = hasUpgradeWork
+        ? buildUpgradeCommands({
+            project: args.project,
+            installRoot: null,
+            channel: cmdsChannel,
+            only: null,
+            cwdDefault: true,
+        })
+        : null;
+    const message = hasUpgradeWork
+        ? `${integrationScenarioMessage(scenario, scenarioFacts)} ${guidanceMessage}`
+        : guidanceMessage;
     return {
-        recommendation: "upgrade",
+        recommendation: aggregateStatus === "upgrade" ? "upgrade" : "stay",
         message,
-        pending_runtime: pending.length,
-        pending_runtimes: pendingRuntimes,
-        pending_artifacts: v1Artifacts.length,
-        dry_run_command: cmds.dryRunCommand,
-        apply_command: cmds.applyCommand,
-        update_channel: cmdsChannel.channel,
-        upgrade_only: onlyPhases,
+        pending_artifacts: v1Artifacts.length + pendingProjectMigration.length,
+        dry_run_command: cmds?.dryRunCommand ?? null,
+        apply_command: cmds?.applyCommand ?? null,
+        update_channel: hasUpgradeWork ? cmdsChannel.channel : channel.channel,
+        major_boundary_block: majorBoundaryBlock,
+        phases: {
+            app: appPhase,
+        },
+        aggregate_status: aggregateStatus,
+        exit,
+        retry: {
+            command: args.retryCommand ?? null,
+            guidance: retryGuidance(exit),
+        },
     };
 }
 export function projectIntegrationAttention(summary) {
-    if (summary.recommendation === "stay") {
+    if (summary.recommendation === "stay" && summary.aggregate_status === "stay") {
         return null;
     }
     const preview = summary.dry_run_command ? `\`${summary.dry_run_command}\`` : "the preview command";
-    const prefix = summary.pending_artifacts > 0 ||
-        (summary.pending_runtime > 0 && summary.upgrade_only?.includes("runtime"))
+    const prefix = summary.pending_artifacts > 0
         ? "normal"
         : "degraded";
-    return `${prefix}: ${summary.message} Preview ${preview}.`;
+    const previewText = summary.dry_run_command ? ` Preview ${preview}.` : "";
+    return `${prefix}: ${summary.message}${previewText}`;
 }
-//# sourceMappingURL=projectIntegration.js.map

package/dist/upgrade/projectIntegrationDecision.js

@@ -0,0 +1,50 @@
+import { APP_MANUAL_REVIEW_NEEDED, APP_UP_TO_DATE } from "./doctor.js";
+export function classifyIntegrationScenario(facts) {
+    if (facts.pendingArtifactCount === 0 &&
+        !facts.crossMajor &&
+        !facts.crossMajorMigration &&
+        !facts.crossMajorNeedsPreview &&
+        (facts.bundleStatus === APP_UP_TO_DATE || facts.bundleStatus === APP_MANUAL_REVIEW_NEEDED)) {
+        return "stay";
+    }
+    if (facts.crossMajorNeedsPreview) {
+        return "blocked";
+    }
+    return "upgrade";
+}
+export function integrationScenarioMessage(scenario, facts) {
+    if (scenario === "stay")
+        return "Your Agentera install is up to date.";
+    if (scenario === "blocked") {
+        return "Cross-major version boundary detected; v3 successor not yet announced. Stay on the current channel.";
+    }
+    const reasons = [];
+    if (facts.pendingArtifactCount > 0)
+        reasons.push("project state needs migration");
+    if (facts.needsAppUpgrade)
+        reasons.push("app bundle needs update");
+    if (facts.crossMajorMigration)
+        reasons.push("cross-major version migration needed");
+    if (reasons.length === 0)
+        reasons.push("project changes pending");
+    return `This project needs an Agentera upgrade (${reasons.join(", ")}). Preview the upgrade command.`;
+}
+export function integrationPhase(facts, statusOverride) {
+    const status = statusOverride ?? (facts.blocked > 0 ? "blocked" : facts.pending > 0 ? "pending" : "stay");
+    return {
+        status,
+        counts: { total: facts.total, pending: facts.pending, blocked: facts.blocked },
+        blockers: facts.blockers,
+    };
+}
+export function integrationExit(hasPendingWork, appBlocked) {
+    if (!hasPendingWork && !appBlocked) {
+        return { code: 0, meaning: "no_changes_needed" };
+    }
+    if (hasPendingWork && appBlocked) {
+        return { code: 1, meaning: "preview_and_blockers" };
+    }
+    if (hasPendingWork)
+        return { code: 1, meaning: "preview_required" };
+    return { code: 1, meaning: "manual_review_required" };
+}