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

package/dist/upgrade/appContentRefresh.js

@@ -0,0 +1,383 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { CAPABILITY_INSTRUCTIONS } from "../capabilities/index.js";
+import { isFile, pathExists, resolvePath } from "../core/paths.js";
+import { doctorRoots } from "./appModel.js";
+import { hasBundleRootEvidence } from "./bundleEvidence.js";
+import { INSTALLED_HOOKS_SURFACE_LABEL, applyInstalledHooksRetirementItems, detectStaleInstalledHooksSurface, planInstalledHooksRetirementItems, } from "./installedHooksRetirement.js";
+import { bindMigrationResource, withBoundMigrationDirectory } from "./migrationPublication.js";
+export const APP_CONTENT_REFRESH_ACTION = "refresh-app-content";
+/**
+ * Top-level app-home entry names written and refreshed by {@link applyAppContentRefresh}.
+ * The cleanup gate treats these as refreshable managed app content (not user state,
+ * not genuinely unrecognized) so v3's own content surface is never flagged as a
+ * false-positive "unrecognized entries" block. Sourced here as the single authority;
+ * do not mirror this list in the gate or doctor.
+ */
+export const MANAGED_APP_CONTENT_ROOT_ENTRIES = new Set([
+    "skills",
+    "references",
+    "registry.json",
+    "dist",
+]);
+/** Stale-surface labels surfaced in upgrade dry-run (B6 / defect #11). */
+export const APP_CONTENT_SURFACE_LABELS = [
+    "SKILL.md",
+    "protocol.yaml",
+    "capability_schema_contract.yaml",
+    "capabilities/*/schemas/*",
+    "references/",
+    "registry.json",
+    "dist/capabilities",
+    INSTALLED_HOOKS_SURFACE_LABEL,
+];
+const V2_CAPABILITY_VERBS = [
+    "hej",
+    "visionera",
+    "resonera",
+    "inspirera",
+    "planera",
+    "realisera",
+    "optimera",
+    "inspektera",
+    "dokumentera",
+    "profilera",
+    "visualisera",
+    "orkestrera",
+];
+const SKIP_COPY_PARTS = new Set(["__pycache__", ".pytest_cache", "node_modules"]);
+const SKIP_COPY_SUFFIXES = [".pyc", ".pyo"];
+function shouldSkipCopyEntry(name) {
+    if (SKIP_COPY_PARTS.has(name)) {
+        return true;
+    }
+    return SKIP_COPY_SUFFIXES.some((suffix) => name.endsWith(suffix));
+}
+function shouldSkipCapabilityFile(relFromSkills) {
+    return /capabilities\/[^/]+\/instructions\.md$/i.test(relFromSkills.replace(/\\/g, "/"));
+}
+function runtimeCompiledRoot() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+}
+export function resolveAppContentSources(sourceRoot, compiledRoot = runtimeCompiledRoot()) {
+    const root = resolvePath(sourceRoot);
+    const candidate = path.join(resolvePath(compiledRoot), "capabilities");
+    const distCapabilities = pathExists(candidate) && fs.statSync(candidate).isDirectory() ? candidate : null;
+    return {
+        skillsDir: path.join(root, "skills"),
+        referencesDir: path.join(root, "references"),
+        registryJson: path.join(root, "registry.json"),
+        distCapabilities,
+    };
+}
+function readInstalledText(installedRoot, rel) {
+    const filePath = path.join(installedRoot, rel);
+    if (!isFile(filePath)) {
+        return null;
+    }
+    return fs.readFileSync(filePath, "utf8");
+}
+function filesEqual(left, right) {
+    if (!isFile(left) || !isFile(right)) {
+        return false;
+    }
+    return fs.readFileSync(left).equals(fs.readFileSync(right));
+}
+export function skillMdLooksV2(text) {
+    if (text.includes("packages/cli/src/capabilities") || text.includes("instructions.ts")) {
+        return false;
+    }
+    return V2_CAPABILITY_VERBS.some((verb) => new RegExp(`\\b${verb}\\b`).test(text));
+}
+export function contractLooksV2(text) {
+    return /\binstructions\.md\b/.test(text) && !/\binstructions\.ts\b/.test(text);
+}
+function installedRootForDetection(appHome) {
+    const roots = doctorRoots(appHome);
+    if (hasBundleRootEvidence(roots.activeBundleRoot)) {
+        return roots.activeBundleRoot;
+    }
+    if (isFile(path.join(roots.activeBundleRoot, "skills", "agentera", "SKILL.md"))) {
+        return roots.activeBundleRoot;
+    }
+    if (isFile(path.join(appHome, "skills", "agentera", "SKILL.md"))) {
+        return appHome;
+    }
+    return null;
+}
+function walkYamlFiles(dir) {
+    if (!pathExists(dir)) {
+        return [];
+    }
+    const out = [];
+    const walk = (current) => {
+        for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+            const full = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+            }
+            else if (entry.isFile() && entry.name.endsWith(".yaml")) {
+                out.push(full);
+            }
+        }
+    };
+    walk(dir);
+    return out;
+}
+function capabilitySchemasStale(installedRoot, sources) {
+    const sourceSchemasRoot = path.join(sources.skillsDir, "agentera", "capabilities");
+    const installedSchemasRoot = path.join(installedRoot, "skills", "agentera", "capabilities");
+    if (!pathExists(sourceSchemasRoot)) {
+        return false;
+    }
+    for (const sourceFile of walkYamlFiles(sourceSchemasRoot)) {
+        const rel = path.relative(sourceSchemasRoot, sourceFile);
+        const installedFile = path.join(installedSchemasRoot, rel);
+        if (!filesEqual(sourceFile, installedFile)) {
+            return true;
+        }
+    }
+    return false;
+}
+function referencesStale(installedRoot, sources) {
+    if (!pathExists(sources.referencesDir)) {
+        return false;
+    }
+    const installedReferences = path.join(installedRoot, "references");
+    if (!pathExists(installedReferences)) {
+        return true;
+    }
+    const walk = (sourceDir, installedDir) => {
+        for (const entry of fs.readdirSync(sourceDir, { withFileTypes: true })) {
+            if (shouldSkipCopyEntry(entry.name)) {
+                continue;
+            }
+            const sourcePath = path.join(sourceDir, entry.name);
+            const installedPath = path.join(installedDir, entry.name);
+            if (entry.isDirectory()) {
+                if (!pathExists(installedPath) || !fs.statSync(installedPath).isDirectory()) {
+                    return true;
+                }
+                if (walk(sourcePath, installedPath)) {
+                    return true;
+                }
+                continue;
+            }
+            if (!filesEqual(sourcePath, installedPath)) {
+                return true;
+            }
+        }
+        return false;
+    };
+    return walk(sources.referencesDir, installedReferences);
+}
+function distCapabilitiesStale(installedRoot, sources) {
+    if (!sources.distCapabilities) {
+        return false;
+    }
+    const installedDist = path.join(installedRoot, "dist", "capabilities");
+    for (const capability of Object.keys(CAPABILITY_INSTRUCTIONS)) {
+        const sourceModule = path.join(sources.distCapabilities, capability, "instructions.js");
+        const installedModule = path.join(installedDist, capability, "instructions.js");
+        if (!filesEqual(sourceModule, installedModule)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Returns stale v2 app-content surface labels for gap detection during upgrade dry-run.
+ */
+export function detectStaleAppContentSurfaces(appHome, sourceRoot, compiledRoot) {
+    const installedRoot = installedRootForDetection(appHome);
+    if (!installedRoot) {
+        return [];
+    }
+    const sources = resolveAppContentSources(sourceRoot, compiledRoot);
+    const stale = [];
+    const skillRel = path.join("skills", "agentera", "SKILL.md");
+    const skillSource = path.join(sources.skillsDir, "agentera", "SKILL.md");
+    const skillInstalled = path.join(installedRoot, skillRel);
+    const skillText = readInstalledText(installedRoot, skillRel);
+    if (!filesEqual(skillSource, skillInstalled) || (skillText !== null && skillMdLooksV2(skillText))) {
+        stale.push("SKILL.md");
+    }
+    const protocolRel = path.join("skills", "agentera", "protocol.yaml");
+    if (!filesEqual(path.join(sources.skillsDir, "agentera", "protocol.yaml"), path.join(installedRoot, protocolRel))) {
+        stale.push("protocol.yaml");
+    }
+    const contractRel = path.join("skills", "agentera", "capability_schema_contract.yaml");
+    const contractText = readInstalledText(installedRoot, contractRel);
+    if (!filesEqual(path.join(sources.skillsDir, "agentera", "capability_schema_contract.yaml"), path.join(installedRoot, contractRel)) ||
+        (contractText !== null && contractLooksV2(contractText))) {
+        stale.push("capability_schema_contract.yaml");
+    }
+    if (capabilitySchemasStale(installedRoot, sources)) {
+        stale.push("capabilities/*/schemas/*");
+    }
+    if (referencesStale(installedRoot, sources)) {
+        stale.push("references/");
+    }
+    if (!filesEqual(sources.registryJson, path.join(installedRoot, "registry.json"))) {
+        stale.push("registry.json");
+    }
+    if (distCapabilitiesStale(installedRoot, sources)) {
+        stale.push("dist/capabilities");
+    }
+    if (detectStaleInstalledHooksSurface(appHome)) {
+        stale.push(INSTALLED_HOOKS_SURFACE_LABEL);
+    }
+    return stale;
+}
+function copyFileEnsuringDir(source, target) {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.copyFileSync(source, target);
+}
+function copyTree(sourceDir, targetDir, relPrefix = "") {
+    fs.mkdirSync(targetDir, { recursive: true });
+    for (const entry of fs.readdirSync(sourceDir, { withFileTypes: true })) {
+        if (shouldSkipCopyEntry(entry.name)) {
+            continue;
+        }
+        const rel = relPrefix ? `${relPrefix}/${entry.name}` : entry.name;
+        if (shouldSkipCapabilityFile(rel)) {
+            continue;
+        }
+        const from = path.join(sourceDir, entry.name);
+        const to = path.join(targetDir, entry.name);
+        if (entry.isDirectory()) {
+            copyTree(from, to, rel);
+        }
+        else if (entry.isFile()) {
+            copyFileEnsuringDir(from, to);
+        }
+    }
+}
+export function refreshAppContentTargetRoot(appHome) {
+    return resolvePath(appHome);
+}
+function applyAppContentRefreshToTarget(targetRoot, sourceRoot, compiledRoot) {
+    const sources = resolveAppContentSources(sourceRoot, compiledRoot);
+    if (!pathExists(sources.skillsDir)) {
+        throw new Error(`app content refresh: missing source skills directory at ${sources.skillsDir}`);
+    }
+    if (!pathExists(sources.referencesDir)) {
+        throw new Error(`app content refresh: missing source references directory at ${sources.referencesDir}`);
+    }
+    if (!isFile(sources.registryJson)) {
+        throw new Error(`app content refresh: missing source registry.json at ${sources.registryJson}`);
+    }
+    copyTree(sources.skillsDir, path.join(targetRoot, "skills"), "skills");
+    copyTree(sources.referencesDir, path.join(targetRoot, "references"), "references");
+    copyFileEnsuringDir(sources.registryJson, path.join(targetRoot, "registry.json"));
+    if (sources.distCapabilities) {
+        copyTree(sources.distCapabilities, path.join(targetRoot, "dist", "capabilities"), "dist/capabilities");
+    }
+}
+export function applyAppContentRefresh(appHome, sourceRoot, compiledRoot) {
+    applyAppContentRefreshToTarget(refreshAppContentTargetRoot(appHome), sourceRoot, compiledRoot);
+}
+function refreshItemStatus(staleSurfaces) {
+    return staleSurfaces.length > 0 ? "pending" : "noop";
+}
+export function planAppContentRefreshItems(ctx) {
+    const sourceRoot = ctx.sourceRoot;
+    if (!sourceRoot) {
+        return [];
+    }
+    const appHome = resolvePath(ctx.appHome);
+    const resolvedSourceRoot = resolvePath(sourceRoot);
+    const installedRoot = installedRootForDetection(appHome);
+    if (!installedRoot) {
+        if (!pathExists(appHome)) {
+            return ctx.installAppContentIfMissing ? [{
+                    status: "pending",
+                    action: APP_CONTENT_REFRESH_ACTION,
+                    runtime: "installed-app",
+                    source: resolvedSourceRoot,
+                    target: refreshAppContentTargetRoot(appHome),
+                    message: "will install stable app content required by selected lifecycle repair",
+                }] : [];
+        }
+        const target = refreshAppContentTargetRoot(appHome);
+        const item = {
+            status: "pending",
+            action: APP_CONTENT_REFRESH_ACTION,
+            runtime: "installed-app",
+            source: resolvedSourceRoot,
+            target,
+            message: "install root has user data only; will install v3 app content (skills, references, registry, dist/capabilities)",
+        };
+        const evidenceError = bindMigrationResource(item, "target", target, [path.dirname(target)], "directory");
+        if (evidenceError) {
+            item.status = "blocked";
+            item.message = `app content refresh preserved the target: ${evidenceError}; review the unsafe path manually`;
+        }
+        return [item];
+    }
+    const staleSurfaces = detectStaleAppContentSurfaces(appHome, resolvedSourceRoot, ctx.compiledRoot);
+    const hookItems = planInstalledHooksRetirementItems(ctx);
+    if (staleSurfaces.length === 0 && hookItems.every((item) => item.status === "noop")) {
+        return [
+            {
+                status: "noop",
+                action: APP_CONTENT_REFRESH_ACTION,
+                source: installedRoot,
+                target: refreshAppContentTargetRoot(appHome),
+                message: "installed app content already matches v3 source surfaces",
+            },
+        ];
+    }
+    const targetRoot = refreshAppContentTargetRoot(appHome);
+    const refreshItems = staleSurfaces.map((surface) => {
+        const item = {
+            status: refreshItemStatus([surface]),
+            action: APP_CONTENT_REFRESH_ACTION,
+            runtime: "installed-app",
+            source: resolvedSourceRoot,
+            target: targetRoot,
+            message: `will refresh stale v2 surface ${surface} from sourceRoot into managed app home`,
+            preserved: [...APP_CONTENT_SURFACE_LABELS],
+            removedPreview: staleSurfaces,
+        };
+        const evidenceError = bindMigrationResource(item, "target", targetRoot, [path.dirname(targetRoot)], "directory");
+        if (evidenceError) {
+            item.status = "blocked";
+            item.message = `app content refresh preserved the target: ${evidenceError}; review the unsafe path manually`;
+        }
+        return item;
+    });
+    return [...refreshItems, ...hookItems.filter((item) => item.status !== "noop")];
+}
+export function applyAppContentRefreshItem(item, ctx, beforePublication) {
+    if (item.status !== "pending" || item.action !== APP_CONTENT_REFRESH_ACTION) {
+        return;
+    }
+    try {
+        const sourceRoot = resolvePath(ctx.sourceRoot ?? item.source ?? "");
+        withBoundMigrationDirectory(item, "target", (targetRoot) => applyAppContentRefreshToTarget(targetRoot, sourceRoot, ctx.compiledRoot), beforePublication);
+        item.status = "applied";
+        item.message = "refreshed installed app content from v3 sourceRoot";
+    }
+    catch (exc) {
+        item.status = "blocked";
+        item.message = `refresh-app-content preserved the target: ${exc.message}; rerun and review it manually`;
+    }
+}
+export function applyAppContentRefreshItems(items, ctx) {
+    applyInstalledHooksRetirementItems(items, ctx);
+    const pending = items.filter((item) => item.action === APP_CONTENT_REFRESH_ACTION && item.status === "pending");
+    if (pending.length === 0) {
+        return;
+    }
+    applyAppContentRefreshItem(pending[0], ctx);
+    if (pending[0]?.status === "applied") {
+        for (const item of pending.slice(1)) {
+            if (item.action === APP_CONTENT_REFRESH_ACTION) {
+                item.status = "applied";
+                item.message = "refreshed installed app content from v3 sourceRoot";
+            }
+        }
+    }
+}

package/dist/upgrade/appModel.js

@@ -2,9 +2,11 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { expanduser, isFile, pathExists, resolvePath } from "../core/paths.js";
+import { resolveProfileDirOverride } from "../core/envPaths.js";
 import { resolveSourceRoot } from "../core/sourceRoot.js";
 import { SOURCE_LABELS, classifyResolvedRoot, isForeignPlatformDefaultAppHome, resolveCandidate, } from "../state/installRoot.js";
 import { loadRegistry } from "../registries/packageRegistry.js";
+import { hasBundleRootEvidence } from "./bundleEvidence.js";
 /**
  * App-home / app-model resolution used by doctor and upgrade. Faithful TS port
  * of the resolution layer in scripts/agentera_upgrade.py.
@@ -32,8 +34,8 @@ function sourceRootMissing(root) {
 }
 export function loadSuiteVersion(sourceRoot) {
     const record = loadRegistry().get("agentera");
-    const authority = record.version_authority;
-    const authorityPath = path.join(sourceRoot, authority.persisted_authority);
+    const authority = record.version_authority; // cast: parsed registry IO boundary
+    const authorityPath = path.join(sourceRoot, authority.persisted_authority); // cast: parsed registry IO boundary
     if (!isFile(authorityPath)) {
         return null;
     }
@@ -55,10 +57,6 @@ export function loadSuiteVersion(sourceRoot) {
     const version = first && typeof first === "object" ? first.version : null;
     return typeof version === "string" && version ? version : null;
 }
-function hasBundleRootEvidence(root) {
-    return (isFile(path.join(root, "scripts", "agentera")) &&
-        isFile(path.join(root, "skills", "agentera", "SKILL.md")));
-}
 export function doctorRoots(appHome) {
     const managedAppRoot = path.join(appHome, "app");
     let activeBundleRoot;
@@ -138,6 +136,10 @@ export function resolveInstallRoot(value, sourceRoot, home, env = process.env) {
         }
         return candidate;
     }
+    const profileDir = resolveProfileDirOverride(env);
+    if (profileDir) {
+        return resolvePath(profileDir);
+    }
     const def = env[DEFAULT_INSTALL_ROOT_ENV];
     if (def) {
         const candidate = resolvePath(def);
@@ -189,4 +191,3 @@ export function resolveActiveAppModel(value = null, opts = {}) {
         runtimeRoot: roots.runtimeRoot,
     };
 }
-//# sourceMappingURL=appModel.js.map

package/dist/upgrade/atomicWriter.js

@@ -0,0 +1 @@
+export { writeFileAtomic } from "../core/atomicWriter.js";

package/dist/upgrade/bundleEvidence.js

@@ -0,0 +1,33 @@
+import fs from "node:fs";
+import path from "node:path";
+import { isFile } from "../core/paths.js";
+const HEAD_READ_BYTES = 2048;
+export function readScriptHead(filePath) {
+    let fd;
+    try {
+        fd = fs.openSync(filePath, "r");
+        const buf = Buffer.alloc(HEAD_READ_BYTES);
+        const bytes = fs.readSync(fd, buf, 0, HEAD_READ_BYTES, 0);
+        return buf.slice(0, bytes).toString("utf8");
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch { }
+        }
+    }
+}
+export function hasBundleRootEvidence(root) {
+    if (!isFile(path.join(root, "scripts", "agentera"))) {
+        return false;
+    }
+    if (!isFile(path.join(root, "skills", "agentera", "SKILL.md"))) {
+        return false;
+    }
+    return readScriptHead(path.join(root, "scripts", "agentera")) !== null;
+}

package/dist/upgrade/channels.js

@@ -2,9 +2,10 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { expanduser } from "../core/paths.js";
-import { isNpxBundleRoot, resolveSourceRoot } from "../core/sourceRoot.js";
+import { resolveSourceRoot } from "../core/sourceRoot.js";
 import { loadTomlFile, parseToml } from "../core/toml.js";
 import { loadYamlMappingFile } from "../core/yaml.js";
+import { cliDistributionMajor } from "./compatibility.js";
 /**
  * Update channel resolution for upgrade, doctor, and prime.
  * Authority: references/cli/update-channels.yaml
@@ -57,7 +58,7 @@ function readConfigChannel(home) {
     }
     let mapping;
     try {
-        mapping = loadTomlFile(configPath);
+        mapping = loadTomlFile(configPath); // cast: TOML parse IO boundary
     }
     catch {
         return null;
@@ -73,7 +74,7 @@ function readConfigChannel(home) {
 }
 export function loadUpdateChannelsAuthority(sourceRoot) {
     const authorityPath = path.join(authorityRootFor(sourceRoot), UPDATE_CHANNELS_AUTHORITY);
-    return loadYamlMappingFile(authorityPath);
+    return loadYamlMappingFile(authorityPath); // cast: YAML parse IO boundary
 }
 function authorityForSourceRoot(authorityRoot) {
     if (cachedAuthority && cachedAuthorityRoot === authorityRoot) {
@@ -124,7 +125,7 @@ export function assertStableNpmUpdateCommand(channel, updateCommand, distTag) {
     if (distTag !== "latest") {
         throw new Error(`stable channel dist tag must be latest, got ${JSON.stringify(distTag)}`);
     }
-    const forbidden = [/@next\b/i, /@3\.\d/i, /@3\.0\.0-dev/i, /-alpha/i, /-rc/i, /-beta/i];
+    const forbidden = [/@next\b/i, /@3\.\d/i, /@3\.0\.0-next/i, /-alpha/i, /-rc/i, /-beta/i];
     for (const pattern of forbidden) {
         if (pattern.test(updateCommand)) {
             throw new Error(`stable channel update command must not target 3.x pre-releases: ${updateCommand}`);
@@ -204,14 +205,18 @@ export function resolveUpdateChannel(args = {}) {
 export function resolveInvokedUpdateChannel(args = {}) {
     const env = args.env ?? process.env;
     const sourceRoot = args.sourceRoot ?? resolveSourceRoot(env);
-    if (isNpxBundleRoot(sourceRoot)) {
+    const selected = resolveSelectedChannel({ ...args, sourceRoot });
+    if (selected.source !== "default") {
+        return resolveUpdateChannel({ ...args, sourceRoot });
+    }
+    if (cliDistributionMajor(sourceRoot) >= 3) {
         return resolveUpdateChannel({ ...args, channel: "development", sourceRoot });
     }
-    return resolveUpdateChannel(args);
+    return resolveUpdateChannel({ ...args, channel: "stable", sourceRoot });
 }
 /** Parse `update.channel` from TOML text (tests). */
 export function parseConfigUpdateChannel(text) {
-    const raw = readNestedKey(parseToml(text), CONFIG_CHANNEL_KEY);
+    const raw = readNestedKey(parseToml(text), CONFIG_CHANNEL_KEY); // cast: TOML parse IO boundary
     if (raw === undefined || raw === null) {
         return null;
     }
@@ -220,4 +225,3 @@ export function parseConfigUpdateChannel(text) {
     }
     return parseChannelValue(raw, "config_file");
 }
-//# sourceMappingURL=channels.js.map

package/dist/upgrade/compatibility.js

@@ -6,6 +6,7 @@ import { BUNDLE_MARKER } from "../state/installRoot.js";
 import { doctorRoots, loadSuiteVersion } from "./appModel.js";
 import { resolveUpdateChannel } from "./channels.js";
 import { classifyUpgradeOutcome, shouldIncludeCrossMajorPlanItems, } from "./versionResolution.js";
+import { hasBundleRootEvidence } from "./bundleEvidence.js";
 export { shouldIncludeCrossMajorPlanItems } from "./versionResolution.js";
 /**
  * v2/v3 install layout detection and cross-major upgrade guard rails.
@@ -18,16 +19,24 @@ export const STATUS_READY_TO_APPLY = "ready_to_apply";
 export const STATUS_APPLIED = "applied";
 export const UPGRADE_PREVIEW_SCHEMA = "agentera.upgrade.v2";
 export const STATUS_CONCEPT_MAJOR_BOUNDARY = "major_boundary_crossing";
+export function projectInstallTrack(kind) {
+    switch (kind) {
+        case "v2_managed_app_home":
+            return "v2";
+        case "v3_self_contained_npm":
+            return "v3";
+        case "source_checkout":
+            return "source";
+        case "unknown_foreign":
+            return "unknown";
+    }
+}
 const CROSS_MAJOR_ITEMS = [
     { phase: "artifacts", verb: "migrate", name: "v2_to_v3_artifacts" },
     { phase: "runtime", verb: "migrate", name: "v2_to_v3_runtime_rewire" },
     { phase: "cleanup", verb: "migrate", name: "v2_to_v3_app_home_cleanup" },
 ];
-function hasBundleRootEvidence(root) {
-    return (isFile(path.join(root, "scripts", "agentera")) &&
-        isFile(path.join(root, "skills", "agentera", "SKILL.md")));
-}
-function isSourceCheckoutRoot(sourceRoot) {
+export function isSourceCheckoutRoot(sourceRoot) {
     return (pathExists(path.join(sourceRoot, ".git")) &&
         isFile(path.join(sourceRoot, "skills", "agentera", "SKILL.md")) &&
         isFile(path.join(sourceRoot, "registry.json")) &&
@@ -50,11 +59,38 @@ function hasV2ManagedEvidence(signals, activeBundleRoot) {
         hasBundleRootEvidence(activeBundleRoot) &&
         !signals.npxBundleSentinelAtActiveRoot);
 }
+let distributionMajorWarned = false;
+function readPackageJsonMajor(sourceRoot) {
+    const pkgPath = path.join(sourceRoot, "package.json");
+    if (!isFile(pkgPath)) {
+        return null;
+    }
+    try {
+        const data = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+        const version = data?.version;
+        if (typeof version !== "string" || !version) {
+            return null;
+        }
+        const major = Number.parseInt(version.split(".")[0] ?? "", 10);
+        if (Number.isFinite(major) && major > 0) {
+            return major;
+        }
+    }
+    catch {
+        // Malformed package.json — fall through to diagnostic
+    }
+    return null;
+}
 export function cliDistributionMajor(sourceRoot) {
     if (isSourceCheckoutRoot(sourceRoot)) {
         return 3;
     }
     if (isNpxBundleRoot(sourceRoot)) {
+        const version = loadSuiteVersion(sourceRoot);
+        const major = version ? Number.parseInt(version.split(".")[0] ?? "", 10) : Number.NaN;
+        if (Number.isFinite(major) && major > 0) {
+            return major;
+        }
         return 3;
     }
     const version = loadSuiteVersion(sourceRoot);
@@ -64,17 +100,28 @@ export function cliDistributionMajor(sourceRoot) {
             return major;
         }
     }
+    const pkgMajor = readPackageJsonMajor(sourceRoot);
+    if (pkgMajor !== null) {
+        return pkgMajor;
+    }
+    if (!distributionMajorWarned) {
+        distributionMajorWarned = true;
+        process.stderr.write(`agentera: could not determine distribution major version from registry.json or package.json at ${sourceRoot}; defaulting to 2\n`);
+    }
     return 2;
 }
+export function __resetDistributionMajorWarnedForTests() {
+    distributionMajorWarned = false;
+}
 export function classifyInstall(args) {
     const appHome = args.appHome;
     const sourceRoot = args.sourceRoot;
     const roots = doctorRoots(appHome);
     const activeBundleRoot = roots.activeBundleRoot;
     const signals = readSignals(appHome, sourceRoot, activeBundleRoot);
-    if (isNpxBundleRoot(sourceRoot) || isNpxBundleRoot(activeBundleRoot) || isNpxBundleRoot(appHome)) {
+    if (hasV2ManagedEvidence(signals, activeBundleRoot)) {
         return {
-            kind: "v3_self_contained_npm",
+            kind: "v2_managed_app_home",
             appHome,
             activeBundleRoot,
             managedAppRoot: roots.managedAppRoot,
@@ -82,9 +129,9 @@ export function classifyInstall(args) {
             signals,
         };
     }
-    if (hasV2ManagedEvidence(signals, activeBundleRoot)) {
+    if (isNpxBundleRoot(sourceRoot) || isNpxBundleRoot(activeBundleRoot) || isNpxBundleRoot(appHome)) {
         return {
-            kind: "v2_managed_app_home",
+            kind: "v3_self_contained_npm",
             appHome,
             activeBundleRoot,
             managedAppRoot: roots.managedAppRoot,
@@ -142,17 +189,6 @@ function groupItemsByPhase(items) {
     }
     return phases;
 }
-export function collectV3MigrationOperations(preview) {
-    const out = [];
-    for (const phase of preview.phases) {
-        for (const item of phase.items) {
-            if (item.verb === "migrate" && item.tag === MAJOR_BOUNDARY_ITEM_TAG) {
-                out.push(item);
-            }
-        }
-    }
-    return out;
-}
 export function previewCrossMajorGuard(args) {
     const channel = resolveUpdateChannel(args);
     const install = classifyInstall({ appHome: args.appHome, sourceRoot: args.sourceRoot });
@@ -198,4 +234,3 @@ export function foreignLayoutHasUnexpectedEntries(root) {
         return false;
     }
 }
-//# sourceMappingURL=compatibility.js.map