agentera 3.0.0-dev.5 → 3.0.0-dev.51

package/dist/upgrade/migrationPublication.js

@@ -0,0 +1,122 @@
+import fs from "node:fs";
+import path from "node:path";
+import { observeLifecyclePath, publishLifecycleResource, removeLifecycleResource, verifyLifecycleResourceAtPublication, withPinnedLifecycleDirectory, } from "../runtime/lifecyclePublication.js";
+const evidenceByItem = new WeakMap();
+const MIGRATION_EVIDENCE = Symbol.for("agentera.migrationMutationEvidence");
+function evidenceFor(item) {
+    const existing = evidenceByItem.get(item) ?? item[MIGRATION_EVIDENCE];
+    if (existing)
+        return existing;
+    const created = { resources: {} };
+    evidenceByItem.set(item, created);
+    item[MIGRATION_EVIDENCE] = created;
+    return created;
+}
+function readEvidence(item) {
+    return evidenceByItem.get(item) ?? item[MIGRATION_EVIDENCE];
+}
+export function cloneMigrationItem(item) {
+    const clone = { ...item };
+    const evidence = readEvidence(item);
+    if (evidence) {
+        evidenceByItem.set(clone, evidence);
+        clone[MIGRATION_EVIDENCE] = evidence;
+    }
+    return clone;
+}
+function observationError(destination, observation, expectedKind) {
+    if (observation.unsafeReason)
+        return observation.unsafeReason;
+    if (!observation.parentComplete)
+        return `parent chain is incomplete for ${destination}`;
+    if (observation.kind !== expectedKind || !observation.identity || !observation.fingerprint) {
+        return `${destination} is not an observable ${expectedKind}`;
+    }
+    return null;
+}
+export function bindMigrationResource(item, role, destination, allowedRoots, kind) {
+    const observation = observeLifecyclePath(destination, allowedRoots);
+    const error = observationError(destination, observation, kind);
+    if (error)
+        return error;
+    evidenceFor(item).resources[role] = { destination, kind, observation };
+    return null;
+}
+function boundResource(item, role) {
+    const resource = readEvidence(item)?.resources[role];
+    if (!resource)
+        throw new Error(`migration ${role} publication evidence is missing`);
+    return resource;
+}
+export function verifyBoundMigrationResource(item, role) {
+    const resource = boundResource(item, role);
+    verifyLifecycleResourceAtPublication({ id: `${item.action}.${role}`, destination: resource.destination, kind: resource.kind }, resource.observation);
+}
+export function withBoundMigrationDirectory(item, role, callback, hook) {
+    const resource = boundResource(item, role);
+    if (resource.kind !== "directory")
+        throw new Error(`migration ${role} is not a directory`);
+    return withPinnedLifecycleDirectory({ id: `${item.action}.${role}`, destination: resource.destination, kind: "directory" }, resource.observation, callback, hook);
+}
+export function updateBoundMigrationFile(item, role, content) {
+    const resource = boundResource(item, role);
+    if (resource.kind !== "file")
+        throw new Error(`migration ${role} is not a file`);
+    publishLifecycleResource({ id: `${item.action}.${role}`, destination: resource.destination, kind: "file", content }, "update", resource.observation);
+}
+export function removeBoundMigrationResource(item, role) {
+    const resource = boundResource(item, role);
+    removeLifecycleResource({ id: `${item.action}.${role}`, destination: resource.destination, kind: resource.kind }, resource.observation);
+}
+function walkTree(root) {
+    const entries = [];
+    const walk = (destination) => {
+        const stat = fs.lstatSync(destination);
+        const kind = stat.isSymbolicLink()
+            ? "symlink"
+            : stat.isFile()
+                ? "file"
+                : stat.isDirectory()
+                    ? "directory"
+                    : (() => { throw new Error(`unsupported bundle entry type at ${destination}`); })();
+        entries.push({ destination, kind });
+        if (kind === "directory") {
+            for (const name of fs.readdirSync(destination).sort())
+                walk(path.join(destination, name));
+        }
+    };
+    walk(root);
+    return entries;
+}
+export function bindMigrationTree(item, root, allowedRoots) {
+    try {
+        const tree = walkTree(root).map(({ destination, kind }) => {
+            const observation = observeLifecyclePath(destination, allowedRoots);
+            const error = observationError(destination, observation, kind);
+            if (error)
+                throw new Error(error);
+            return { destination, kind, observation };
+        });
+        evidenceFor(item).tree = tree;
+        return null;
+    }
+    catch (error) {
+        return error.message;
+    }
+}
+export function removeBoundMigrationTree(item) {
+    const tree = readEvidence(item)?.tree;
+    if (!tree)
+        throw new Error("migration cleanup tree evidence is missing");
+    const current = walkTree(tree[0].destination);
+    if (current.length !== tree.length
+        || current.some((entry, index) => entry.destination !== tree[index]?.destination || entry.kind !== tree[index]?.kind)) {
+        throw new Error("managed app cleanup set changed after preview");
+    }
+    for (const entry of tree) {
+        verifyLifecycleResourceAtPublication({ id: `${item.action}.verify`, destination: entry.destination, kind: entry.kind }, entry.observation);
+    }
+    for (const entry of [...tree].reverse()) {
+        removeLifecycleResource({ id: `${item.action}.remove`, destination: entry.destination, kind: entry.kind }, entry.observation);
+    }
+}

package/dist/upgrade/nextMajorDoctor.js

@@ -14,6 +14,7 @@ export const V1_NEXT_MAJOR_FALLBACK = {
     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",
@@ -45,12 +46,30 @@ function parseNextMajorBlock(raw) {
         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;
@@ -73,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,
@@ -84,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({
@@ -93,22 +128,22 @@ export function resolveNextMajorDoctorLines(ctx) {
             block,
         });
     }
-    const authorityBlock = loadChannelNextMajor(sourceRoot, currentChannel);
-    if (!authorityBlock) {
+    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,
     });
 }
@@ -118,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,91 +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 { detectV1ArtifactPairs, planRuntimeRetirementPhase, } from "./migrateArtifactsV2ToV3.js";
+import { projectHasProjectLevelRuntimeHooks, } 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, 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) => {
@@ -98,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 ||
@@ -114,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,
@@ -144,131 +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 crossMajor = args.crossMajorBoundary ??
-        integrationTargets.crossMajorBoundary ??
+    const install = args.installClassification ?? classifyInstall({ appHome: integrationTargets.installRoot, sourceRoot: args.sourceRoot });
+    const crossMajorDetected = args.crossMajorBoundaryDetected ??
         crossMajorBoundaryApplies(install, 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