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

package/dist/upgrade/upgradeCommands.js

@@ -7,6 +7,16 @@ function shellQuote(value) {
 export function commandText(parts) {
     return parts.map(shellQuote).join(" ");
 }
+export function fullEntityUpgradeCommand(project) {
+    return commandText([
+        "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);
@@ -32,9 +42,12 @@ export function buildUpgradeCommands(args) {
             applyParts.push("--only", phase);
         }
     }
+    if (args.legacyCleanup) {
+        previewParts.push("--legacy-cleanup", args.legacyCleanup);
+        applyParts.push("--legacy-cleanup", args.legacyCleanup);
+    }
     return {
         dryRunCommand: commandText(previewParts),
         applyCommand: commandText(applyParts),
     };
 }
-//# sourceMappingURL=upgradeCommands.js.map

package/dist/upgrade/upgradeLock.js

@@ -0,0 +1,85 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+const MAX_LOCK_BYTES = 4 * 1024;
+export class UpgradeLockError extends Error {
+    constructor(lockPath) {
+        super(`upgrade mutation is locked; inspect ${lockPath}, remove that file only if no upgrade owns it, then rerun`);
+        this.name = "UpgradeLockError";
+    }
+}
+export function upgradeLockPath(root, domain) {
+    return path.join(root, ".agentera", `upgrade-${domain}.lock`);
+}
+function manualRecovery(lockPath) {
+    return new UpgradeLockError(lockPath);
+}
+function removeCreatedParent(parent, created) {
+    if (!created)
+        return;
+    try {
+        fs.rmdirSync(parent);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== "ENOENT" && code !== "ENOTEMPTY" && code !== "EEXIST")
+            throw error;
+    }
+}
+function lockRecord(lockPath) {
+    try {
+        const stat = fs.lstatSync(lockPath);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MAX_LOCK_BYTES)
+            return null;
+        const value = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+        if (value === null
+            || typeof value !== "object"
+            || Object.keys(value).length !== 1
+            || typeof value.token !== "string"
+            || value.token.length === 0)
+            return null;
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+export function acquireUpgradeLock(root, domain) {
+    const lockPath = upgradeLockPath(root, domain);
+    const parent = path.dirname(lockPath);
+    let createdParent = false;
+    try {
+        fs.mkdirSync(parent);
+        createdParent = true;
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+    }
+    const token = randomUUID();
+    let fd;
+    try {
+        fd = fs.openSync(lockPath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, 0o600);
+    }
+    catch (error) {
+        removeCreatedParent(parent, createdParent);
+        if (error.code === "EEXIST")
+            throw manualRecovery(lockPath);
+        throw error;
+    }
+    try {
+        fs.writeFileSync(fd, `${JSON.stringify({ token })}\n`);
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    return { domain, path: lockPath, token, createdParent };
+}
+export function releaseUpgradeLock(lock) {
+    const record = lockRecord(lock.path);
+    if (!record || record.token !== lock.token)
+        throw manualRecovery(lock.path);
+    fs.unlinkSync(lock.path);
+    removeCreatedParent(path.dirname(lock.path), lock.createdParent);
+}

package/dist/upgrade/upgradeOrchestrator.js

@@ -1,16 +1,22 @@
 import os from "node:os";
+import path from "node:path";
 import { expanduser, resolvePath } from "../core/paths.js";
 import { resolveDoctorInstallRoot, resolveSourceRootStrict } from "./appModel.js";
-import { MAJOR_BOUNDARY_ITEM_TAG, STATUS_APPLIED, STATUS_MANUAL_REVIEW_NEEDED, STATUS_NO_CHANGES_NEEDED, STATUS_READY_TO_APPLY, UPGRADE_PREVIEW_SCHEMA, classifyInstall, crossMajorBoundaryApplies, previewCrossMajorGuard, } from "./compatibility.js";
+import { MAJOR_BOUNDARY_ITEM_TAG, STATUS_APPLIED, STATUS_MANUAL_REVIEW_NEEDED, STATUS_NO_CHANGES_NEEDED, STATUS_READY_TO_APPLY, UPGRADE_PREVIEW_SCHEMA, classifyInstall, crossMajorBoundaryApplies, } from "./compatibility.js";
 import { classifyUpgradeOutcome, isBlockedUpgradeOutcome, shouldIncludeCrossMajorPlanItems, } from "./versionResolution.js";
-import { resolveUpdateChannel } from "./channels.js";
+import { resolveInvokedUpdateChannel } from "./channels.js";
 import { buildUpgradeCommands } from "./upgradeCommands.js";
-import { projectHasPendingRuntimeRewire } from "./projectIntegration.js";
-import { MIGRATION_STATUSES, applyMigrationPhases, detectV1ArtifactPairs, dryRunMigration, } from "./migrateArtifactsV2ToV3.js";
+import { pendingRuntimeMigrationItems } from "./projectIntegration.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";
+import { applyPreparedEntityCutover, inspectEntityCutoverForUpgrade, prepareEntityCutoverForUpgrade, } from "../state/entityCutover.js";
+import { detectStateMode } from "../state/stateMode.js";
 const DEFAULT_PHASES = ["detect", "artifacts", "runtime", "cleanup"];
 const MIGRATION_ONLY_PHASES = ["artifacts", "runtime", "cleanup"];
 function emptySummary() {
-    return { pending: 0, applied: 0, noop: 0, blocked: 0, failed: 0, skipped: 0 };
+    return { pending: 0, applied: 0, noop: 0, blocked: 0, failed: 0 };
 }
 function aggregateSummary(phases) {
     const summary = emptySummary();
@@ -30,8 +36,6 @@ function workflowStatus(summary) {
         return "pending";
     if (summary.applied > 0)
         return "applied";
-    if (summary.skipped > 0 && summary.noop === 0 && summary.applied === 0)
-        return "skipped";
     return "noop";
 }
 function lifecycleStatusFromWorkflow(workflow, mode) {
@@ -41,7 +45,6 @@ function lifecycleStatusFromWorkflow(workflow, mode) {
         case "applied":
             return STATUS_APPLIED;
         case "noop":
-        case "skipped":
             return STATUS_NO_CHANGES_NEEDED;
         case "blocked":
         case "failed":
@@ -76,8 +79,6 @@ function summarizeOrchestratorPhase(name, items, message = "") {
         status = "pending";
     else if (summary.applied > 0)
         status = "applied";
-    else if (summary.skipped > 0 && summary.noop === 0 && summary.applied === 0)
-        status = "skipped";
     else
         status = "noop";
     return { name, status, summary, items, message };
@@ -123,13 +124,127 @@ function migrationPhaseToOrchestrator(phase) {
         message: phase.message,
     };
 }
+function entityReadinessPhase(project, sourceRoot, pendingV1Artifacts, selected, apply, activeUpgradeLockPaths) {
+    try {
+        const cutover = inspectEntityCutoverForUpgrade(project, sourceRoot, apply && selected, activeUpgradeLockPaths);
+        if (cutover.phase === "active") {
+            return summarizeOrchestratorPhase("entities", [{
+                    status: "noop",
+                    action: "entity-state-active",
+                    message: "validated entity authority is already active",
+                }]);
+        }
+        if (cutover.phase !== "ready") {
+            if (!selected) {
+                return summarizeOrchestratorPhase("entities", [{
+                        status: "blocked",
+                        action: "entity-cutover-required",
+                        message: "a forward entity cutover must complete inside one full upgrade before any filtered effects",
+                    }]);
+            }
+            return summarizeOrchestratorPhase("entities", [{
+                    status: "pending",
+                    action: "entity-cutover",
+                    message: "validated forward entity publication is ready to complete without deleting canonical entities",
+                }]);
+        }
+        if (!selected) {
+            return summarizeOrchestratorPhase("entities", [{
+                    status: "blocked",
+                    action: "entity-cutover-required",
+                    message: "marker-absent projects require one full cross-major upgrade; filtered apply is unavailable",
+                }]);
+        }
+        if (pendingV1Artifacts) {
+            return summarizeOrchestratorPhase("entities", [{
+                    status: "blocked",
+                    action: "resolve-v1-state",
+                    message: "pending v1 Markdown state is not a supported automatic source; preserve it and follow the manual v1 recovery instructions in UPGRADE.md",
+                }]);
+        }
+        const empty = cutover.entityCount === 0;
+        return summarizeOrchestratorPhase("entities", [{
+                status: empty ? "blocked" : "pending",
+                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.todoReconciliation ? "; apply also journals TODO visible IDs, Markdown-owned public baselines, activation, canonical Markdown, and the authority marker" : ""}`,
+            }]);
+    }
+    catch (error) {
+        return summarizeOrchestratorPhase("entities", [{
+                status: "blocked",
+                action: "validate-entity-state",
+                message: error.message,
+            }]);
+    }
+}
+function lifecyclePhase(result) {
+    const cleanup = result.cleanupSummary;
+    const summary = {
+        pending: cleanup.pending,
+        applied: cleanup.applied,
+        noop: cleanup.noop,
+        failed: cleanup.failed,
+        blocked: cleanup.blocked_unowned + cleanup.skipped_dependency + cleanup.action_required,
+    };
+    return {
+        name: "lifecycle",
+        status: workflowStatus(summary),
+        summary,
+        items: [],
+        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) {
-    const sourceRoot = resolveSourceRootStrict();
+    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`);
+    }
     const home = resolvePath(expanduser(args.home ?? os.homedir()));
-    const env = { ...process.env, HOME: home };
     const project = resolvePath(expanduser(args.project ?? process.cwd()));
+    if (!args.yes)
+        return buildUpgradePlanUnlocked(args, home, project, []);
+    const projectLock = acquireUpgradeLock(project, "project");
+    try {
+        const runtimeLock = acquireUpgradeLock(home, "runtime");
+        try {
+            return buildUpgradePlanUnlocked(args, home, project, [projectLock.path, runtimeLock.path]);
+        }
+        finally {
+            releaseUpgradeLock(runtimeLock);
+        }
+    }
+    finally {
+        releaseUpgradeLock(projectLock);
+    }
+}
+function buildUpgradePlanUnlocked(args, home, project, activeUpgradeLockPaths) {
+    const sourceRoot = resolveSourceRootStrict();
+    const homeScopedPath = (value) => {
+        if (!value)
+            return null;
+        // Relative overrides retain their normal process-cwd meaning before the
+        // resolved path is checked. The home itself and its descendants are valid.
+        const resolved = resolvePath(value);
+        const relative = path.relative(home, resolved);
+        const withinHome = relative === ""
+            || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+        return withinHome ? resolved : null;
+    };
+    const xdgConfigHome = homeScopedPath(process.env.XDG_CONFIG_HOME) ?? path.join(home, ".config");
+    const env = {
+        ...process.env,
+        HOME: home,
+        XDG_CONFIG_HOME: xdgConfigHome,
+    };
+    if (!homeScopedPath(process.env.OPENCODE_CONFIG_DIR)) {
+        delete env.OPENCODE_CONFIG_DIR;
+    }
     const [installRoot] = resolveDoctorInstallRoot(args.installRoot ?? null, { home, sourceRoot });
-    const channel = resolveUpdateChannel({
+    const channel = resolveInvokedUpdateChannel({
         channel: args.channel ?? null,
         env,
         home,
@@ -143,6 +258,42 @@ export function buildUpgradePlan(args) {
         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,
@@ -152,32 +303,77 @@ export function buildUpgradePlan(args) {
         sourceRoot,
         channel: args.channel ?? null,
         env,
+        installAppContentIfMissing: false,
     };
-    const pendingRuntimeRewire = projectHasPendingRuntimeRewire(migrationCtx);
+    const pendingRuntimeSync = pendingRuntimeMigrationItems(migrationCtx).length > 0;
     const pendingV1Artifacts = detectV1ArtifactPairs(project).length > 0;
+    const pendingPlanLifecycleMigration = hasPendingPlanLifecycleMigration(project);
     const crossMajorMigration = crossMajorBoundary && shouldIncludeCrossMajorPlanItems(channel, upgradeOutcome);
-    const artifactsOnlyMigration = pendingV1Artifacts && !crossMajorMigration;
-    const runtimeOnlyMigration = pendingRuntimeRewire && !crossMajorMigration && !artifactsOnlyMigration;
-    const runMigration = crossMajorMigration || pendingRuntimeRewire || pendingV1Artifacts;
-    const effectiveOnly = args.only && args.only.length > 0
-        ? args.only
-        : artifactsOnlyMigration
-            ? ["artifacts"]
-            : runtimeOnlyMigration
-                ? ["runtime"]
-                : MIGRATION_ONLY_PHASES;
+    const entityAuthorityActive = detectStateMode(project, sourceRoot) === "entities";
+    const projectEntityCutover = !entityAuthorityActive
+        && channel.distributionMajor >= 3
+        && !args.only
+        && !args.legacyCleanup;
+    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")) {
         phases.push(buildDetectPhase(install, crossMajorBoundary, upgradeOutcome, channel));
     }
     let migrationPreview = runMigration ? dryRunMigration(migrationCtx) : null;
-    if (args.yes && migrationPreview) {
-        migrationPreview = applyMigrationPhases(migrationCtx, migrationPreview, effectiveOnly);
+    const entityBoundary = projectEntityCutover || crossMajorMigration;
+    const filteredEntityBoundary = entityBoundary && Boolean(args.only && args.only.length > 0);
+    const entitySelected = entityBoundary && (!filteredEntityBoundary || (!args.yes && Boolean(args.only?.includes("artifacts"))));
+    const partialStateApply = filteredEntityBoundary && !entitySelected;
+    let entityPhase = entitySelected || partialStateApply || (entityAuthorityActive && crossMajorMigration)
+        ? entityReadinessPhase(project, sourceRoot, pendingV1Artifacts, entitySelected, Boolean(args.yes), activeUpgradeLockPaths)
+        : null;
+    const entityCutoverPending = entityPhase?.items.some(({ action }) => action === "entity-cutover") ?? false;
+    if (migrationPreview && (entityAuthorityActive || (args.yes && entityCutoverPending))) {
+        delegatePlanLifecycleToEntityCutover(migrationPreview.artifacts);
+    }
+    const lifecycleArgs = args.legacyCleanup ? {
+        home,
+        appHome: installRoot,
+        apply: false,
+        resourceCleanup: args.legacyCleanup,
+    } : null;
+    let lifecycle = lifecycleArgs ? runLifecycleUpgrade(lifecycleArgs) : null;
+    const plannedPhases = [
+        ...phases,
+        ...(migrationPreview && phaseFilter.has("artifacts") ? [migrationPhaseToOrchestrator(migrationPreview.artifacts)] : []),
+        ...(entityPhase ? [entityPhase] : []),
+        ...(migrationPreview && phaseFilter.has("runtime") ? [migrationPhaseToOrchestrator(migrationPreview.runtime)] : []),
+        ...(migrationPreview && phaseFilter.has("cleanup") ? [migrationPhaseToOrchestrator(migrationPreview.cleanup)] : []),
+        ...(lifecycle ? [lifecyclePhase(lifecycle)] : []),
+    ];
+    const entityPreflight = aggregateSummary(plannedPhases.filter((phase) => ["detect", "artifacts", "entities"].includes(phase.name)));
+    const entityPreflightBlocked = entityPreflight.blocked > 0 || entityPreflight.failed > 0;
+    let preparedEntityMigration = null;
+    if (args.yes && entitySelected && entityPhase?.status === "pending" && !entityPreflightBlocked) {
+        preparedEntityMigration = prepareEntityCutoverForUpgrade(project, sourceRoot, activeUpgradeLockPaths);
+    }
+    if (preparedEntityMigration) {
+        const result = applyPreparedEntityCutover(preparedEntityMigration, activeUpgradeLockPaths);
+        entityPhase = summarizeOrchestratorPhase("entities", [{
+                status: "applied",
+                action: "entity-cutover",
+                message: `${result.entity_count} entity record(s) published and validated; authority marker written last`,
+            }]);
+    }
+    if (args.yes && migrationPreview && !entityPreflightBlocked) {
+        const applyPhases = args.only ?? MIGRATION_ONLY_PHASES;
+        migrationPreview = applyMigrationPhases(migrationCtx, migrationPreview, applyPhases);
     }
     if (migrationPreview) {
         if (phaseFilter.has("artifacts")) {
             phases.push(migrationPhaseToOrchestrator(migrationPreview.artifacts));
         }
+        if (entityPhase)
+            phases.push(entityPhase);
         if (phaseFilter.has("runtime")) {
             phases.push(migrationPhaseToOrchestrator(migrationPreview.runtime));
         }
@@ -185,43 +381,27 @@ export function buildUpgradePlan(args) {
             phases.push(migrationPhaseToOrchestrator(migrationPreview.cleanup));
         }
     }
-    else if (crossMajorBoundary) {
-        const guard = previewCrossMajorGuard({
-            appHome: installRoot,
-            sourceRoot,
-            channel: args.channel ?? null,
-            env,
-            home,
-            catalog: null,
-        });
-        for (const guardPhase of guard.phases) {
-            if (guardPhase.name === "detect" || !phaseFilter.has(guardPhase.name)) {
-                continue;
-            }
-            const items = guardPhase.items.map((item) => ({
-                status: "blocked",
-                action: item.verb,
-                message: `${item.name} requires semver forward-major confirmation on the selected channel`,
-            }));
-            phases.push({
-                name: guardPhase.name,
-                status: items.length > 0 ? "blocked" : "noop",
-                summary: { ...emptySummary(), blocked: items.length },
-                items,
-                message: "",
-            });
-        }
+    if (!migrationPreview && entityPhase)
+        phases.push(entityPhase);
+    if (lifecycleArgs && args.yes && !entityPreflightBlocked) {
+        lifecycle = runLifecycleUpgrade({ ...lifecycleArgs, apply: true });
+    }
+    if (lifecycle) {
+        phases.push(lifecyclePhase(lifecycle));
     }
     const summary = aggregateSummary(phases);
     const status = workflowStatus(summary);
+    const appSummary = aggregateSummary(phases.filter((phase) => phase.name !== "lifecycle"));
+    const appApplyBlocked = appSummary.blocked > 0 || appSummary.failed > 0;
     const mode = args.yes ? "apply" : "plan";
     const lifecycleStatus = lifecycleStatusFromWorkflow(status, mode);
-    const blocked = status === "blocked" || status === "failed";
+    const hasPending = summary.pending > 0;
     const commands = buildUpgradeCommands({
         project,
         installRoot: crossMajorMigration || crossMajorBoundary ? installRoot : null,
         channel,
-        only: args.only ?? (artifactsOnlyMigration ? ["artifacts"] : runtimeOnlyMigration ? ["runtime"] : undefined),
+        only: args.only,
+        legacyCleanup: args.legacyCleanup,
         cwdDefault: true,
     });
     return {
@@ -237,9 +417,10 @@ export function buildUpgradePlan(args) {
         appHome: installRoot,
         home,
         phases,
+        lifecycle,
         summary,
-        dryRunCommand: blocked || lifecycleStatus === STATUS_NO_CHANGES_NEEDED ? null : commands.dryRunCommand,
-        applyCommand: blocked || lifecycleStatus === STATUS_NO_CHANGES_NEEDED ? null : commands.applyCommand,
+        dryRunCommand: appApplyBlocked || !hasPending ? null : commands.dryRunCommand,
+        applyCommand: appApplyBlocked || !hasPending ? null : commands.applyCommand,
     };
 }
 export function validateUpgradeApply(args, plan) {
@@ -249,10 +430,25 @@ export function validateUpgradeApply(args, plan) {
     if (!args.yes) {
         return null;
     }
-    if (isBlockedUpgradeOutcome(plan.upgradeOutcome)) {
+    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 (!args.legacyCleanup && isBlockedUpgradeOutcome(plan.upgradeOutcome)) {
         return plan.upgradeOutcome.message ?? "upgrade blocked";
     }
-    if (plan.crossMajorBoundary &&
+    const appPhases = plan.phases.filter((phase) => phase.name !== "lifecycle");
+    const entityImportPending = appPhases.some((phase) => phase.name === "entities" && phase.items.some((item) => item.action === "entity-cutover" && item.status === "pending"));
+    const applyBlockingPhases = entityImportPending
+        ? appPhases.filter((phase) => ["detect", "artifacts", "entities"].includes(phase.name))
+        : appPhases;
+    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 (!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");
@@ -288,6 +484,15 @@ export function renderUpgradePlan(plan) {
             }
         }
     }
+    if (plan.lifecycle) {
+        lines.push("");
+        lines.push("native Agentera resource cleanup:");
+        lines.push(`  ownership journal: ${plan.lifecycle.ownershipJournal.state} at ${plan.lifecycle.ownershipJournal.path}`);
+        lines.push(`  secure publication: ${plan.lifecycle.platform.securePublication ? "available" : "unavailable"} (${plan.lifecycle.platform.requirement})`);
+        lines.push(`  scope: ownership-proven native Agentera resource ${plan.lifecycle.nativeResourceCleanup.resourceId}; unrelated user-owned data excluded`);
+        const cleanup = plan.lifecycle.cleanupSummary;
+        lines.push(`  counts: pending=${cleanup.pending}, applied=${cleanup.applied}, noop=${cleanup.noop}, blocked=${cleanup.blocked_unowned + cleanup.action_required}`);
+    }
     if (plan.mode === "plan" && plan.summary.pending > 0 && plan.applyCommand) {
         lines.push("");
         lines.push(`Next: if this preview looks right, apply with: ${plan.applyCommand}`);
@@ -317,4 +522,3 @@ export function sortKeysDeep(value) {
     return value;
 }
 export { MAJOR_BOUNDARY_ITEM_TAG };
-//# sourceMappingURL=upgradeOrchestrator.js.map

package/dist/upgrade/v3CapabilitySurface.js

@@ -0,0 +1,14 @@
+import path from "node:path";
+import { CAPABILITY_INSTRUCTIONS } from "../capabilities/index.js";
+import { isFile } from "../core/paths.js";
+const INSTRUCTION_MODULE_ROOT = path.join("packages", "cli", "src", "capabilities");
+/**
+ * v3 repo signal (D65): all twelve capability instruction modules live under
+ * packages/cli/src/capabilities/<name>/instructions.ts. When present, in-tree
+ * .cursor/agents/ uses prime --context and must not be overwritten from a v2
+ * app-home bundle during runtime rewiring.
+ */
+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")));
+}

package/dist/upgrade/versionResolution.js

@@ -4,6 +4,7 @@ import { isNpxBundleRoot } from "../core/sourceRoot.js";
 import { classifyResolvedRoot } from "../state/installRoot.js";
 import { doctorRoots, loadSuiteVersion } from "./appModel.js";
 import { loadUpdateChannelsAuthority } from "./channels.js";
+import { isStableSuccessorAnnounced } from "./nextMajorDoctor.js";
 export const IRREVERSIBLE_V2_RETURN = "return to the v2 Python line is permanently unsupported after migrating to v3+";
 let testVersionCatalog = null;
 /** Reset injectable catalog (tests). */
@@ -132,6 +133,13 @@ export function classifyUpgradeOutcome(args) {
                 message: "stable channel tracks the 2.x support line; switch to the development channel to preview v2→v3 migration",
             };
         }
+        if (!isStableSuccessorAnnounced(args.sourceRoot, "stable")) {
+            return {
+                ...base,
+                kind: "up_to_date",
+                message: `v3 successor line is not announced yet; v2 managed app files remain current on the ${args.channel.channel} channel`,
+            };
+        }
         return {
             ...base,
             kind: "migration_to_latest_on_channel",
@@ -176,4 +184,3 @@ export function isBlockedUpgradeOutcome(outcome) {
     return (outcome.kind === "blocked_downgrade_to_v2" ||
         outcome.kind === "blocked_downgrade_not_implemented");
 }
-//# sourceMappingURL=versionResolution.js.map