agentera 3.0.0-dev.2 → 3.0.0-dev.21

package/dist/upgrade/nextMajorDoctor.js

@@ -0,0 +1,156 @@
+import { cliDistributionMajor } from "./compatibility.js";
+import { loadUpdateChannelsAuthority, resolveSelectedChannel, } from "./channels.js";
+import { resolveRunningVersion } from "./versionResolution.js";
+/**
+ * Head-of-output "next major" doctor section.
+ * Authority: references/cli/update-channels.yaml (channels.<channel>.next_major)
+ */
+export const NEXT_MAJOR_SECTION_HEADER = "Next major";
+export const NEXT_MAJOR_LINE_CAP = 6;
+/** v1 installs predate the channel authority; hardcoded stable-line successor mapping. */
+export const V1_NEXT_MAJOR_FALLBACK = {
+    concept: "forward_successor_line",
+    currentVersion: "1.x",
+    currentChannel: "stable",
+    channel: "stable",
+    version: "2.x",
+    announced: true,
+    npmOnlyAdvisory: "",
+    guideUrl: "https://github.com/jgabor/agentera/blob/main/UPGRADE.md#recommended-upgrade-v1--v2-stable-channel",
+    previewCommand: "npx -y agentera@latest upgrade --dry-run",
+    irreversibleAdvisory: "Forward migration upgrades artifact format from Markdown to YAML; review the preview before applying.",
+};
+function parseNextMajorBlock(raw) {
+    if (raw === null || raw === undefined) {
+        return null;
+    }
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        return null;
+    }
+    const block = raw;
+    const channel = String(block.channel ?? "").trim().toLowerCase();
+    if (channel !== "stable" && channel !== "development") {
+        return null;
+    }
+    const version = String(block.version ?? "").trim();
+    if (!version) {
+        return null;
+    }
+    const guideUrl = String(block.guide_url ?? "").trim();
+    const previewCommand = String(block.preview_command ?? "").trim();
+    const irreversibleAdvisory = String(block.irreversible_advisory ?? "").trim();
+    if (!guideUrl || !previewCommand || !irreversibleAdvisory) {
+        return null;
+    }
+    return {
+        concept: String(block.concept ?? "forward_successor_line").trim(),
+        channel: channel,
+        version,
+        announced: block.announced !== false,
+        npmOnlyAdvisory: String(block.npm_only_advisory ?? "").trim(),
+        guideUrl,
+        previewCommand,
+        irreversibleAdvisory,
+    };
+}
+let testSuccessorAnnouncedOverride = null;
+/** Reset injectable successor announcement gate (tests). */
+export function setSuccessorAnnouncedOverrideForTests(value) {
+    testSuccessorAnnouncedOverride = value;
+}
+/**
+ * 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, channel);
+    return block?.announced === true;
+}
+export function loadChannelNextMajor(sourceRoot, channel) {
+    const authority = loadUpdateChannelsAuthority(sourceRoot);
+    const channels = authority.channels;
+    const entry = channels?.[channel];
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+        return null;
+    }
+    return parseNextMajorBlock(entry.next_major);
+}
+export function formatNextMajorDoctorLines(args) {
+    const nextLine = args.block.npmOnlyAdvisory
+        ? `Next: ${args.block.version} (${args.block.channel} channel). ${args.block.npmOnlyAdvisory}`
+        : `Next: ${args.block.version} (${args.block.channel} channel)`;
+    return [
+        NEXT_MAJOR_SECTION_HEADER,
+        `Current: ${args.currentVersion} (${args.currentChannel} channel)`,
+        nextLine,
+        `Guide: ${args.block.guideUrl}`,
+        `Preview: ${args.block.previewCommand}`,
+        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,
+        home,
+        sourceRoot,
+    });
+    const currentChannel = selected.channel;
+    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({
+            currentVersion: block.currentVersion,
+            currentChannel: block.currentChannel,
+            block,
+        });
+    }
+    const authorityBlock = loadChannelNextMajor(sourceRoot, successorChannel);
+    if (!authorityBlock || !authorityBlock.announced) {
+        return null;
+    }
+    const runningVersion = ctx.runningVersion ??
+        (install
+            ? resolveRunningVersion({
+                appHome: install.appHome,
+                sourceRoot,
+                install,
+            })
+            : null) ??
+        `${runningDistributionMajor}.x`;
+    return formatNextMajorDoctorLines({
+        currentVersion: runningVersion,
+        currentChannel: displayChannel,
+        block: authorityBlock,
+    });
+}
+export function prependNextMajorDoctorSection(text, sectionLines) {
+    if (!sectionLines || sectionLines.length === 0) {
+        return text;
+    }
+    return `${sectionLines.join("\n")}\n\n${text}`;
+}
+//# sourceMappingURL=nextMajorDoctor.js.map

package/dist/upgrade/nextMajorDoctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nextMajorDoctor.js","sourceRoot":"","sources":["../../src/upgrade/nextMajorDoctor.ts"],"names":[],"mappings":"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"}

package/dist/upgrade/npxPlatformStatus.js

@@ -0,0 +1,23 @@
+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 };
+}
+//# sourceMappingURL=npxPlatformStatus.js.map

package/dist/upgrade/npxPlatformStatus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"npxPlatformStatus.js","sourceRoot":"","sources":["../../src/upgrade/npxPlatformStatus.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAiC,MAAM,aAAa,CAAC;AAiB/E,gFAAgF;AAChF,MAAM,UAAU,wBAAwB,CACtC,IAAqC;IAErC,MAAM,GAAG,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;IACjF,MAAM,YAAY,GAAG,sBAAsB,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC5D,MAAM,UAAU,GAA6B;QAC3C,UAAU,EAAE,SAAS;QACrB,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,gBAAgB,EAAE,IAAI,CAAC,gBAAgB,IAAI,CAAC,OAAO,CAAC;QACpD,yBAAyB,EAAE,IAAI;QAC/B,GAAG;KACJ,CAAC;IACF,IAAI,IAAI,CAAC,eAAe,KAAK,SAAS,EAAE,CAAC;QACvC,UAAU,CAAC,eAAe,GAAG,IAAI,CAAC,eAAe,CAAC;IACpD,CAAC;IACD,MAAM,cAAc,GAAG,iBAAiB,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;IACnE,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,CAAC;AAC1C,CAAC"}

package/dist/upgrade/projectIntegration.js

@@ -1,56 +1,126 @@
-import { expanduser, resolvePath } from "../core/paths.js";
-import { APP_MANUAL_REVIEW_NEEDED, APP_MIGRATION_NEEDED, APP_OUTDATED, APP_REPAIR_NEEDED, APP_UP_TO_DATE, } from "./doctor.js";
+import { expanduser, isFile, resolvePath } from "../core/paths.js";
+import { isNpxBundleRoot } from "../core/sourceRoot.js";
+import { APP_MIGRATION_NEEDED, APP_MANUAL_REVIEW_NEEDED, APP_OUTDATED, APP_REPAIR_NEEDED, APP_UP_TO_DATE, } from "./doctor.js";
+import { doctorRoots } from "./appModel.js";
+import { resolveNpxPlatformStatus } from "./npxPlatformStatus.js";
 import { classifyInstall, crossMajorBoundaryApplies } from "./compatibility.js";
-import { resolveUpdateChannel } from "./channels.js";
+import { resolveInvokedUpdateChannel } from "./channels.js";
 import fs from "node:fs";
-import { planRuntimeRewirePhase, } from "./migrateArtifactsV2ToV3.js";
-import { textUsesPythonManagedEntrypoint } from "./runtimeMigration.js";
+import path from "node:path";
+import { detectV1ArtifactPairs, planRuntimeRewirePhase, } from "./migrateArtifactsV2ToV3.js";
+import { projectHasProjectLevelRuntimeHooks, textUsesPythonManagedEntrypoint, } from "./runtimeMigration.js";
+import { isStableSuccessorAnnounced } from "./nextMajorDoctor.js";
 import { buildUpgradeCommands } from "./upgradeCommands.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 { classifyIntegrationScenario, integrationScenarioMessage, integrationExit, integrationGuidance, integrationPhase, lifecycleIntegrationPhase, } from "./projectIntegrationDecision.js";
+import { classifyUpgradeOutcome, parseSemverMajor, resolveRunningVersion, shouldIncludeCrossMajorPlanItems, } from "./versionResolution.js";
+import { lifecycleOwnershipJournalPath, readLifecycleOwnershipJournal, } from "../runtime/lifecycleOwnershipJournal.js";
+import { observeRuntimeLifecycle, } from "../runtime/lifecycleSnapshot.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_REWIRE_ACTIONS = new Set(["rewire-runtime", "retire-hooks"]);
-function isPythonManagedRewireItem(item) {
-    if (item.action === "retire-hooks") {
-        return item.status === "pending";
-    }
-    if (item.action !== "rewire-runtime" || item.status !== "pending" || !item.source) {
+function isPendingRuntimeMigrationItem(item) {
+    if (item.status !== "pending" || item.action === "configure") {
         return false;
     }
-    try {
-        return textUsesPythonManagedEntrypoint(fs.readFileSync(item.source, "utf8"));
+    if (item.action === "rewire-runtime") {
+        if (!item.source) {
+            return false;
+        }
+        try {
+            return textUsesPythonManagedEntrypoint(fs.readFileSync(item.source, "utf8"));
+        }
+        catch {
+            return false;
+        }
     }
-    catch {
+    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") {
+        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);
-    return phase.items.filter((item) => item.status === "pending" && RUNTIME_REWIRE_ACTIONS.has(item.action));
-}
-/** True when the project still has Python-managed runtime hooks/config to rewire. */
-export function projectHasPendingRuntimeRewire(ctx) {
-    const phase = planRuntimeRewirePhase(ctx);
-    return phase.items.some((item) => isPythonManagedRewireItem(item));
+    const projectRoot = resolvePath(ctx.project);
+    const hasProjectHooks = projectHasProjectLevelRuntimeHooks(ctx.project);
+    return phase.items.filter((item) => {
+        if (item.status !== "pending" || item.action === "configure") {
+            return false;
+        }
+        if (hasProjectHooks) {
+            return (item.source?.startsWith(projectRoot) ?? false) && isPendingRuntimeMigrationItem(item);
+        }
+        return isGlobalStaleRuntimeItem(item, ctx);
+    });
 }
 function appNeedsUpgrade(bundleStatus) {
     return (bundleStatus === APP_OUTDATED ||
         bundleStatus === APP_REPAIR_NEEDED ||
         bundleStatus === APP_MIGRATION_NEEDED);
 }
+function resolveIntegrationTargets(args) {
+    if (!isNpxBundleRoot(args.sourceRoot)) {
+        return {
+            installRoot: args.installRoot,
+            bundleStatus: args.bundleStatus,
+            crossMajorBoundary: args.crossMajorBoundary ?? false,
+            crossMajorBoundaryDetected: args.crossMajorBoundaryDetected ?? false,
+        };
+    }
+    const { platformRoot, platformStatus } = resolveNpxPlatformStatus({
+        home: args.home,
+        sourceRoot: args.sourceRoot,
+        project: args.project,
+        env: args.env,
+    });
+    return {
+        installRoot: platformRoot,
+        bundleStatus: args.bundleStatus,
+        platformBundleStatus: platformStatus.status,
+        crossMajorBoundary: Boolean(platformStatus.crossMajorBoundary),
+        crossMajorBoundaryDetected: Boolean(platformStatus.crossMajorBoundaryDetected),
+    };
+}
+/** Observe the canonical lifecycle projection used by project integration. */
+export function observeProjectIntegrationLifecycle(args, installRoot) {
+    const lifecycleInstallRoot = isNpxBundleRoot(args.sourceRoot)
+        ? resolveIntegrationTargets(args).installRoot
+        : installRoot ?? resolveIntegrationTargets(args).installRoot;
+    const ownership = readLifecycleOwnershipJournal(lifecycleOwnershipJournalPath(lifecycleInstallRoot));
+    const canonicalSkillTarget = path.join(isNpxBundleRoot(args.sourceRoot)
+        ? args.sourceRoot
+        : doctorRoots(lifecycleInstallRoot).activeBundleRoot, "skills", "agentera");
+    return observeRuntimeLifecycle({
+        home: resolvePath(expanduser(args.home)),
+        project: resolvePath(args.project),
+        sourceRoot: args.sourceRoot,
+        env: { ...(args.env ?? process.env), HOME: resolvePath(expanduser(args.home)) },
+        ledger: ownership.ledger,
+        canonicalSkillTarget,
+    });
+}
 function commandChannel(args, channel, crossMajor, upgradeOutcome) {
     if (crossMajor && !shouldIncludeCrossMajorPlanItems(channel, upgradeOutcome)) {
-        return resolveUpdateChannel({
+        return resolveInvokedUpdateChannel({
             channel: "development",
             env: args.env,
             home: args.home,
@@ -59,99 +129,184 @@ function commandChannel(args, channel, crossMajor, upgradeOutcome) {
     }
     return channel;
 }
+function lifecycleIntegrationFacts(snapshot) {
+    const actions = snapshot.actions;
+    const isHostAction = (action) => action.actionClass === "manual_verification" &&
+        action.ownership === "user_owned" &&
+        action.manual?.command !== null &&
+        action.manual?.command !== undefined;
+    const isManualReview = (action) => action.actionClass === "manual_verification" && !isHostAction(action);
+    const runtimesFor = (predicate) => [...new Set(actions.filter(predicate).flatMap((action) => action.runtimeIds))].sort();
+    const pendingOwnedRuntimes = runtimesFor((action) => action.actionClass === "repairable_owned");
+    const hostActionRuntimes = runtimesFor(isHostAction);
+    const manualReviewRuntimes = runtimesFor(isManualReview);
+    const doctorRuntimes = runtimesFor((action) => action.actionClass === "unobservable_gap");
+    const blockers = [
+        ...new Set([
+            ...snapshot.runtimes.flatMap((runtime) => runtime.blockers.map((blocker) => `${blocker.code}: ${blocker.detail}`)),
+            ...actions
+                .filter((action) => action.actionClass !== "repairable_owned")
+                .map((action) => `${action.actionClass}: ${action.reason}`),
+        ]),
+    ];
+    return {
+        pendingOwnedCount: actions.filter((action) => action.actionClass === "repairable_owned").length,
+        pendingOwnedRuntimes,
+        manualReviewCount: actions.filter(isManualReview).length,
+        manualReviewRuntimes,
+        hostActionCount: actions.filter(isHostAction).length,
+        hostActionRuntimes,
+        doctorCount: actions.filter((action) => action.actionClass === "unobservable_gap").length,
+        doctorRuntimes,
+        blockers,
+    };
+}
+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 "host_action_required":
+            return "Run the user-owned host action, then retry Agentera to re-observe the runtime.";
+        case "doctor_diagnostics_required":
+            return "Run Agentera doctor diagnostics, then retry Agentera after the gap is observable.";
+        case "manual_review_required":
+            return "Complete the manual review, then retry Agentera to re-observe project integration.";
+    }
+}
 export function summarizeProjectIntegration(args) {
-    const channel = resolveUpdateChannel({
+    const channel = resolveInvokedUpdateChannel({
         channel: args.channel ?? null,
         env: args.env,
         home: args.home,
         sourceRoot: args.sourceRoot,
     });
-    const install = classifyInstall({ appHome: args.installRoot, sourceRoot: args.sourceRoot });
-    const crossMajor = args.crossMajorBoundary ?? crossMajorBoundaryApplies(install, args.sourceRoot);
+    const integrationTargets = resolveIntegrationTargets(args);
+    const install = classifyInstall({ appHome: integrationTargets.installRoot, sourceRoot: args.sourceRoot });
+    const crossMajorDetected = args.crossMajorBoundaryDetected ??
+        crossMajorBoundaryApplies(install, args.sourceRoot);
+    const successorAnnounced = isStableSuccessorAnnounced(args.sourceRoot, "stable");
+    const crossMajor = crossMajorDetected && successorAnnounced;
+    const runningMajor = parseSemverMajor(resolveRunningVersion({
+        appHome: integrationTargets.installRoot,
+        sourceRoot: args.sourceRoot,
+        install,
+    })) ?? 0;
+    const majorBoundaryBlock = crossMajorDetected && !successorAnnounced && runningMajor > 0 && runningMajor < 3
+        ? majorBoundaryBlockMessage(channel.channel)
+        : null;
     const upgradeOutcome = classifyUpgradeOutcome({
-        appHome: args.installRoot,
+        appHome: integrationTargets.installRoot,
         sourceRoot: args.sourceRoot,
         install,
         channel,
     });
-    const ctx = migrationContext(args, channel);
-    const pending = pendingRuntimeMigrationItems(ctx);
-    const pendingRuntimes = [
-        ...new Set(pending.map((item) => item.runtime).filter((runtime) => Boolean(runtime))),
-    ];
+    const v1Artifacts = detectV1ArtifactPairs(args.project);
+    const lifecycleSnapshot = args.lifecycleSnapshot ?? observeProjectIntegrationLifecycle(args, integrationTargets.installRoot);
+    const lifecycle = lifecycleIntegrationFacts(lifecycleSnapshot);
     const crossMajorMigration = crossMajor && shouldIncludeCrossMajorPlanItems(channel, upgradeOutcome);
-    const crossMajorNeedsPreview = crossMajor && !crossMajorMigration;
-    const needsAppUpgrade = appNeedsUpgrade(args.bundleStatus);
-    const runtimeOnly = pending.length > 0 && !crossMajorMigration && !crossMajorNeedsPreview && !needsAppUpgrade;
-    if (args.bundleStatus === APP_MANUAL_REVIEW_NEEDED &&
-        pending.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: [],
-            dry_run_command: null,
-            apply_command: null,
-            update_channel: channel.channel,
-        };
-    }
-    if (args.bundleStatus === APP_UP_TO_DATE &&
-        pending.length === 0 &&
-        !crossMajorMigration &&
-        !crossMajorNeedsPreview) {
-        return {
-            recommendation: "stay",
-            message: "This project matches your current Agentera install; no upgrade is needed.",
-            pending_runtime: 0,
-            pending_runtimes: [],
-            dry_run_command: null,
-            apply_command: null,
-            update_channel: channel.channel,
-        };
-    }
-    const cmdsChannel = commandChannel(args, channel, crossMajor, upgradeOutcome);
-    const onlyPhases = runtimeOnly ? ["runtime"] : undefined;
-    const installRootForCommands = crossMajorMigration || crossMajorNeedsPreview || needsAppUpgrade ? args.installRoot : null;
-    const cmds = buildUpgradeCommands({
-        project: args.project,
-        installRoot: installRootForCommands,
-        channel: cmdsChannel,
-        only: onlyPhases,
-        cwdDefault: true,
+    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 +
+        (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,
     });
-    let message;
-    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 = `This project still uses older Agentera runtime wiring (${runtimes}); preview rewiring hooks to the current npm entrypoint.`;
-    }
-    else {
-        message = "Preview Agentera upgrade changes for this project before applying.";
+    const lifecyclePhase = lifecycleIntegrationPhase(lifecycle);
+    const hasUpgradeWork = appPending > 0 || lifecycle.pendingOwnedCount > 0;
+    const hasBlockers = appBlockers.length > 0 || lifecyclePhase.counts.blocked > 0;
+    const aggregateStatus = hasUpgradeWork
+        ? "upgrade"
+        : hasBlockers
+            ? "blocked"
+            : "stay";
+    const scenarioFacts = {
+        bundleStatus: classificationBundleStatus,
+        pendingRuntimeCount: lifecycle.pendingOwnedCount,
+        pendingArtifactCount: v1Artifacts.length,
+        crossMajor,
+        crossMajorMigration,
+        crossMajorNeedsPreview: Boolean(majorBoundaryBlock) || (crossMajor && !crossMajorMigration),
+        needsAppUpgrade,
+    };
+    const scenario = classifyIntegrationScenario(scenarioFacts);
+    const pendingRuntimes = lifecycle.pendingOwnedRuntimes;
+    const runtimeSelector = pendingRuntimes.length === 1 ? pendingRuntimes[0] : pendingRuntimes.length > 1 ? "all" : null;
+    const guidance = integrationGuidance(lifecycle, hasUpgradeWork);
+    if (!hasUpgradeWork && appBlockers.length > 0 && guidance.runtimes.length === 0) {
+        guidance.route = "manual_review";
+        guidance.message = appBlockers.join("; ");
     }
+    const exit = integrationExit(hasUpgradeWork, lifecycle, appBlockers.length > 0);
+    const cmdsChannel = commandChannel(args, channel, crossMajor, upgradeOutcome);
+    const cmds = hasUpgradeWork
+        ? buildUpgradeCommands({
+            project: args.project,
+            installRoot: null,
+            channel: cmdsChannel,
+            only: null,
+            runtime: runtimeSelector,
+            cwdDefault: true,
+        })
+        : null;
+    const message = hasUpgradeWork
+        ? `${integrationScenarioMessage(scenario, scenarioFacts)} ${guidance.message}`
+        : guidance.message;
     return {
-        recommendation: "upgrade",
+        recommendation: aggregateStatus === "upgrade" ? "upgrade" : "stay",
         message,
-        pending_runtime: pending.length,
+        pending_runtime: pendingRuntimes.length,
         pending_runtimes: pendingRuntimes,
-        dry_run_command: cmds.dryRunCommand,
-        apply_command: cmds.applyCommand,
-        update_channel: cmdsChannel.channel,
-        upgrade_only: onlyPhases,
+        pending_artifacts: v1Artifacts.length,
+        dry_run_command: cmds?.dryRunCommand ?? null,
+        apply_command: cmds?.applyCommand ?? null,
+        update_channel: hasUpgradeWork ? cmdsChannel.channel : channel.channel,
+        upgrade_only: undefined,
+        major_boundary_block: majorBoundaryBlock,
+        phases: {
+            app: appPhase,
+            lifecycle: lifecyclePhase,
+        },
+        aggregate_status: aggregateStatus,
+        guidance,
+        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_runtime > 0 && summary.upgrade_only?.includes("runtime") ? "normal" : "degraded";
-    return `${prefix}: ${summary.message} Preview ${preview}.`;
+    const prefix = summary.pending_artifacts > 0 || summary.pending_runtime > 0
+        ? "normal"
+        : "degraded";
+    const previewText = summary.dry_run_command ? ` Preview ${preview}.` : "";
+    return `${prefix}: ${summary.message}${previewText}`;
 }
 //# sourceMappingURL=projectIntegration.js.map