agentera 3.0.0-dev.8 → 3.0.0-dev.81

package/dist/upgrade/productV1ResetAuthority.js

@@ -0,0 +1,139 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolveSourceRoot } from "../core/sourceRoot.js";
+import { loadYamlMapping } from "../core/yaml.js";
+import { loadRegistry } from "../registries/packageRegistry.js";
+import { NATIVE_RESOURCE_CLEANUP_CONTRACT_RELATIVE_PATH } from "../runtime/lifecycleAuthority.js";
+export const PRODUCT_V1_RESET_AUTHORITY_RELATIVE_PATH = "references/adapters/product-v1-reset.yaml";
+const PACKAGE_REGISTRY_RELATIVE_PATH = "references/adapters/package-registry.yaml";
+const RUNTIME_LIFECYCLE_RELATIVE_PATH = "references/adapters/runtime-lifecycle-authority.yaml";
+const ALLOWED_ROOTS = new Set(["project", "profile_root", "install_root", "runtime_declared_roots"]);
+function mapping(value, field) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${field} must be a mapping`);
+    }
+    return value;
+}
+function text(value, field) {
+    if (typeof value !== "string" || value.length === 0)
+        throw new Error(`${field} must be a non-empty string`);
+    return value;
+}
+function textList(value, field) {
+    if (!Array.isArray(value) || value.length === 0)
+        throw new Error(`${field} must be a non-empty string list`);
+    return value.map((item, index) => text(item, `${field}[${index}]`));
+}
+function relativePath(value, field) {
+    const result = text(value, field);
+    if (path.isAbsolute(result) || result.split("/").includes("..")) {
+        throw new Error(`${field} must stay within its declared root`);
+    }
+    return result;
+}
+export function loadProductV1ResetAuthority(authorityPath = path.join(resolveSourceRoot(), PRODUCT_V1_RESET_AUTHORITY_RELATIVE_PATH), sourceRoot = resolveSourceRoot()) {
+    const data = loadYamlMapping(fs.readFileSync(authorityPath, "utf8"));
+    if (data.schema_version !== "agentera.productV1ResetInventory.v1") {
+        throw new Error("product v1 reset authority has unsupported schema_version");
+    }
+    const policy = mapping(data.policy, "policy");
+    if (policy.trigger !== "any_declared_product_v1_generation_evidence"
+        || policy.schema_identifier_suffix_is_evidence !== false
+        || policy.discovery !== "declared_roots_only"
+        || policy.preserve_unlisted_state !== true) {
+        throw new Error("product v1 reset authority policy must require bounded product-generation evidence");
+    }
+    const sources = mapping(data.source_authorities, "source_authorities");
+    if (sources.retired_resources !== NATIVE_RESOURCE_CLEANUP_CONTRACT_RELATIVE_PATH
+        || sources.package_inventory !== PACKAGE_REGISTRY_RELATIVE_PATH
+        || sources.runtime_lifecycle !== RUNTIME_LIFECYCLE_RELATIVE_PATH) {
+        throw new Error("product v1 reset authority must reference the existing runtime and package authorities");
+    }
+    for (const authority of Object.values(sources)) {
+        if (typeof authority !== "string" || !fs.existsSync(path.join(sourceRoot, authority))) {
+            throw new Error(`product v1 reset source authority does not exist: ${String(authority)}`);
+        }
+    }
+    const triggers = mapping(data.trigger_evidence, "trigger_evidence");
+    if (!Array.isArray(triggers.project_artifacts) || triggers.project_artifacts.length === 0) {
+        throw new Error("trigger_evidence.project_artifacts must be non-empty");
+    }
+    const projectArtifacts = triggers.project_artifacts.map((value, index) => {
+        const item = mapping(value, `trigger_evidence.project_artifacts[${index}]`);
+        if (item.generation !== "product_v1") {
+            throw new Error(`trigger_evidence.project_artifacts[${index}].generation must be product_v1`);
+        }
+        if (typeof item.triggers_reset !== "boolean") {
+            throw new Error(`trigger_evidence.project_artifacts[${index}].triggers_reset must be boolean`);
+        }
+        return {
+            id: text(item.id, `trigger_evidence.project_artifacts[${index}].id`),
+            generation: "product_v1",
+            triggersReset: item.triggers_reset === true,
+            path: relativePath(item.path, `trigger_evidence.project_artifacts[${index}].path`),
+            currentPath: relativePath(item.current_path, `trigger_evidence.project_artifacts[${index}].current_path`),
+        };
+    });
+    const packageTrigger = mapping(triggers.installation_package, "trigger_evidence.installation_package");
+    const packageRecord = loadRegistry(path.join(sourceRoot, PACKAGE_REGISTRY_RELATIVE_PATH), sourceRoot).get("agentera");
+    if (packageTrigger.generation !== "product_v1"
+        || packageTrigger.triggers_reset !== true
+        || packageTrigger.authority !== PACKAGE_REGISTRY_RELATIVE_PATH
+        || packageTrigger.manifest !== packageRecord.version_authority.persisted_authority
+        || packageTrigger.selector !== packageRecord.version_authority.selector
+        || packageTrigger.predicate !== "semver_major_equals_1") {
+        throw new Error("installation package trigger must use the package inventory's version authority and product-v1 major");
+    }
+    const runtimeTrigger = mapping(triggers.runtime_resources, "trigger_evidence.runtime_resources");
+    if (runtimeTrigger.authority !== NATIVE_RESOURCE_CLEANUP_CONTRACT_RELATIVE_PATH
+        || runtimeTrigger.role !== "reset_scope_only") {
+        throw new Error("retired runtime identities must remain reset scope, not product-v1 trigger evidence");
+    }
+    if (!Array.isArray(data.scope_inventory) || data.scope_inventory.length === 0) {
+        throw new Error("scope_inventory must be non-empty");
+    }
+    const ids = new Set();
+    const scope = data.scope_inventory.map((value, index) => {
+        const item = mapping(value, `scope_inventory[${index}]`);
+        const id = text(item.id, `scope_inventory[${index}].id`);
+        const owner = text(item.owner, `scope_inventory[${index}].owner`);
+        const action = item.action;
+        const boundedRoot = item.bounded_root;
+        if (ids.has(id))
+            throw new Error(`scope_inventory has duplicate id: ${id}`);
+        if (action !== "delete" && action !== "recreate")
+            throw new Error(`scope_inventory[${index}].action is invalid`);
+        if (typeof boundedRoot !== "string" || !ALLOWED_ROOTS.has(boundedRoot)) {
+            throw new Error(`scope_inventory[${index}].bounded_root is invalid`);
+        }
+        ids.add(id);
+        return {
+            id,
+            action: action,
+            owner,
+            boundedRoot: boundedRoot,
+            targets: textList(item.targets, `scope_inventory[${index}].targets`).map((target, targetIndex) => relativePath(target, `scope_inventory[${index}].targets[${targetIndex}]`)),
+        };
+    });
+    return {
+        sourcePath: authorityPath,
+        projectArtifacts,
+        installationPackage: {
+            manifest: packageTrigger.manifest,
+            selector: packageTrigger.selector,
+            predicate: "semver_major_equals_1",
+        },
+        scope,
+    };
+}
+export function productV1ArtifactPairs() {
+    return loadProductV1ResetAuthority().projectArtifacts.map(({ path: legacyPath, currentPath }) => [legacyPath, currentPath]);
+}
+export function productV1ProjectTriggerPaths() {
+    return loadProductV1ResetAuthority().projectArtifacts
+        .filter(({ triggersReset }) => triggersReset)
+        .map(({ path: legacyPath }) => legacyPath);
+}
+export function isProductV1PackageVersion(version) {
+    return /^1\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(version);
+}

package/dist/upgrade/projectIntegration.js

@@ -1,84 +1,38 @@
-import { expanduser, isFile, resolvePath } from "../core/paths.js";
+import { resolvePath } from "../core/paths.js";
 import { isNpxBundleRoot } from "../core/sourceRoot.js";
-import { APP_MIGRATION_NEEDED, APP_OUTDATED, APP_REPAIR_NEEDED, APP_UP_TO_DATE, } 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 { planRuntimeRetirementPhase, } from "./migrateArtifactsV2ToV3.js";
+import { projectHasProjectLevelRuntimeHooks, } from "./runtimeMigration.js";
 import { isStableSuccessorAnnounced } from "./nextMajorDoctor.js";
 import { buildUpgradeCommands } from "./upgradeCommands.js";
-import { classifyIntegrationScenario, integrationScenarioMessage, integrationScenarioRecommendation, } from "./projectIntegrationDecision.js";
+import { classifyIntegrationScenario, integrationScenarioMessage, integrationExit, integrationPhase, } from "./projectIntegrationDecision.js";
 import { classifyUpgradeOutcome, parseSemverMajor, resolveRunningVersion, shouldIncludeCrossMajorPlanItems, } from "./versionResolution.js";
 const MAJOR_BOUNDARY_BLOCK_MESSAGE_PREFIX = "v3 successor line is not announced yet; v2 managed app files remain current on the";
 function majorBoundaryBlockMessage(channelName) {
     const label = channelName.trim() || "current";
     return `${MAJOR_BOUNDARY_BLOCK_MESSAGE_PREFIX} ${label} channel`;
 }
-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,
-    };
-}
-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);
+    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) => {
@@ -111,16 +65,22 @@ function resolveIntegrationTargets(args) {
         project: args.project,
         env: args.env,
     });
+    // The executing npm bundle is already a complete app. A missing optional
+    // platform install therefore needs no integration work, while an existing
+    // stale or damaged platform install still retains its observed status.
+    const platformBundleStatus = platformStatus.rootStatus === "missing"
+        ? APP_UP_TO_DATE
+        : platformStatus.status;
     return {
         installRoot: platformRoot,
         bundleStatus: args.bundleStatus,
-        platformBundleStatus: platformStatus.status,
+        platformBundleStatus,
         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,
@@ -130,115 +90,147 @@ 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 install = args.installClassification ?? classifyInstall({ appHome: integrationTargets.installRoot, sourceRoot: args.sourceRoot });
     const crossMajorDetected = args.crossMajorBoundaryDetected ??
         crossMajorBoundaryApplies(install, args.sourceRoot);
-    const successorAnnounced = isStableSuccessorAnnounced(args.sourceRoot, "stable");
+    const successorAnnounced = args.successorAnnounced ?? isStableSuccessorAnnounced(args.sourceRoot, "stable");
     const crossMajor = crossMajorDetected && successorAnnounced;
-    const runningMajor = parseSemverMajor(resolveRunningVersion({
-        appHome: integrationTargets.installRoot,
-        sourceRoot: args.sourceRoot,
-        install,
-    })) ?? 0;
-    if (crossMajorDetected && !successorAnnounced && runningMajor > 0 && runningMajor < 3) {
-        const blockMessage = majorBoundaryBlockMessage(channel.channel);
-        return {
-            recommendation: "stay",
-            message: blockMessage,
-            pending_runtime: 0,
-            pending_runtimes: [],
-            pending_artifacts: 0,
-            dry_run_command: null,
-            apply_command: null,
-            update_channel: channel.channel,
-            major_boundary_block: blockMessage,
-        };
-    }
-    const upgradeOutcome = classifyUpgradeOutcome({
+    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 pendingProjectMigration = pendingRuntimeMigrationItems({
         appHome: integrationTargets.installRoot,
+        project: args.project,
+        home: args.home,
+        force: false,
         sourceRoot: args.sourceRoot,
-        install,
-        channel,
-    });
-    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;
+        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) &&
-            pending.length === 0 &&
-            v1Artifacts.length === 0
+        ? appNeedsUpgrade(integrationTargets.platformBundleStatus ?? APP_UP_TO_DATE)
         : appNeedsUpgrade(classificationBundleStatus);
-    const facts = {
+    const appPending = 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 hasUpgradeWork = appPending > 0;
+    const hasBlockers = appBlockers.length > 0;
+    const aggregateStatus = hasUpgradeWork
+        ? "upgrade"
+        : hasBlockers
+            ? "blocked"
+            : "stay";
+    const scenarioFacts = {
         bundleStatus: classificationBundleStatus,
-        pendingRuntimeCount: pending.length,
-        pendingArtifactCount: v1Artifacts.length,
+        pendingArtifactCount: pendingProjectMigration.length,
         crossMajor,
         crossMajorMigration,
-        crossMajorNeedsPreview,
+        crossMajorNeedsPreview: Boolean(majorBoundaryBlock) || (crossMajor && !crossMajorMigration),
         needsAppUpgrade,
     };
-    const scenario = classifyIntegrationScenario(facts);
-    const recommendation = integrationScenarioRecommendation(scenario);
-    const message = integrationScenarioMessage(scenario, facts);
-    if (recommendation === "stay") {
-        return {
-            recommendation: "stay",
-            message,
-            pending_runtime: 0,
-            pending_runtimes: [],
-            pending_artifacts: 0,
-            dry_run_command: null,
-            apply_command: null,
-            update_channel: channel.channel,
-            major_boundary_block: null,
-        };
-    }
+    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 cmds = buildUpgradeCommands({
-        project: args.project,
-        installRoot: null,
-        channel: cmdsChannel,
-        only: null,
-        cwdDefault: true,
-    });
+    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: pendingRuntimes.length,
-        pending_runtimes: pendingRuntimes,
-        pending_artifacts: v1Artifacts.length,
-        dry_run_command: cmds.dryRunCommand,
-        apply_command: cmds.applyCommand,
-        update_channel: cmdsChannel.channel,
-        upgrade_only: undefined,
-        major_boundary_block: null,
+        pending_artifacts: 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
+    const prefix = summary.pending_artifacts > 0
         ? "normal"
         : "degraded";
-    return `${prefix}: ${summary.message} Preview ${preview}.`;
+    const previewText = summary.dry_run_command ? ` Preview ${preview}.` : "";
+    return `${prefix}: ${summary.message}${previewText}`;
 }
-//# sourceMappingURL=projectIntegration.js.map

package/dist/upgrade/projectIntegrationDecision.js

@@ -1,7 +1,6 @@
 import { APP_MANUAL_REVIEW_NEEDED, APP_UP_TO_DATE } from "./doctor.js";
 export function classifyIntegrationScenario(facts) {
-    if (facts.pendingRuntimeCount === 0 &&
-        facts.pendingArtifactCount === 0 &&
+    if (facts.pendingArtifactCount === 0 &&
         !facts.crossMajor &&
         !facts.crossMajorMigration &&
         !facts.crossMajorNeedsPreview &&
@@ -13,13 +12,6 @@ export function classifyIntegrationScenario(facts) {
     }
     return "upgrade";
 }
-export function integrationScenarioRecommendation(scenario) {
-    if (scenario === "stay")
-        return "stay";
-    if (scenario === "blocked")
-        return "stay";
-    return "upgrade";
-}
 export function integrationScenarioMessage(scenario, facts) {
     if (scenario === "stay")
         return "Your Agentera install is up to date.";
@@ -27,10 +19,8 @@ export function integrationScenarioMessage(scenario, facts) {
         return "Cross-major version boundary detected; v3 successor not yet announced. Stay on the current channel.";
     }
     const reasons = [];
-    if (facts.pendingRuntimeCount > 0)
-        reasons.push("runtime wiring needs sync");
     if (facts.pendingArtifactCount > 0)
-        reasons.push("v1 artifacts need migration");
+        reasons.push("project state needs migration");
     if (facts.needsAppUpgrade)
         reasons.push("app bundle needs update");
     if (facts.crossMajorMigration)
@@ -39,4 +29,22 @@ export function integrationScenarioMessage(scenario, facts) {
         reasons.push("project changes pending");
     return `This project needs an Agentera upgrade (${reasons.join(", ")}). Preview the upgrade command.`;
 }
-//# sourceMappingURL=projectIntegrationDecision.js.map
+export function integrationPhase(facts, statusOverride) {
+    const status = statusOverride ?? (facts.blocked > 0 ? "blocked" : facts.pending > 0 ? "pending" : "stay");
+    return {
+        status,
+        counts: { total: facts.total, pending: facts.pending, blocked: facts.blocked },
+        blockers: facts.blockers,
+    };
+}
+export function integrationExit(hasPendingWork, appBlocked) {
+    if (!hasPendingWork && !appBlocked) {
+        return { code: 0, meaning: "no_changes_needed" };
+    }
+    if (hasPendingWork && appBlocked) {
+        return { code: 1, meaning: "preview_and_blockers" };
+    }
+    if (hasPendingWork)
+        return { code: 1, meaning: "preview_required" };
+    return { code: 1, meaning: "manual_review_required" };
+}

package/dist/upgrade/retiredResourceDiagnostics.js

@@ -0,0 +1,117 @@
+import fs from "node:fs";
+import path from "node:path";
+import { loadNativeResourceCleanupContract, retiredResourceDiagnosticIds, } from "../runtime/nativeResourceCleanup.js";
+function templateRoot(template, roots) {
+    const match = /^\{(home|project|install_root)\}\//.exec(template);
+    if (!match)
+        throw new Error(`unsafe retired-resource diagnostic path template: ${template}`);
+    return roots[match[1]];
+}
+function expandTemplate(template, roots, name) {
+    const root = templateRoot(template, roots);
+    const expanded = template
+        .replace("{home}", roots.home)
+        .replace("{project}", roots.project)
+        .replace("{install_root}", roots.install_root)
+        .replace("{name}", name ?? "");
+    if (expanded.includes("{") || expanded.includes("..")) {
+        throw new Error(`unsafe retired-resource diagnostic path template: ${template}`);
+    }
+    const resolved = path.resolve(expanded);
+    const relative = path.relative(root, resolved);
+    if (relative === "" || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new Error(`retired-resource diagnostic path escapes its root: ${template}`);
+    }
+    return resolved;
+}
+function fileContains(pathname, marker, maximumFileBytes) {
+    let stat;
+    try {
+        stat = fs.lstatSync(pathname);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        return "uninspectable";
+    }
+    if (!stat.isFile() || stat.size > maximumFileBytes)
+        return "uninspectable";
+    const fd = fs.openSync(pathname, "r");
+    try {
+        const content = Buffer.alloc(stat.size);
+        fs.readSync(fd, content, 0, content.length, 0);
+        return content.toString("utf8").includes(marker) ? "path_present" : null;
+    }
+    catch {
+        return "uninspectable";
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function observeDestination(pathname, definition, maximumFileBytes) {
+    if (definition.contains) {
+        const observation = fileContains(pathname, definition.contains, maximumFileBytes);
+        return observation ? { path: pathname, observation } : null;
+    }
+    try {
+        fs.lstatSync(pathname);
+        return { path: pathname, observation: "path_present" };
+    }
+    catch (error) {
+        return error.code === "ENOENT"
+            ? null
+            : { path: pathname, observation: "uninspectable" };
+    }
+}
+function namesFor(definition) {
+    return definition.id.includes("{name}") || definition.destinations.some((item) => item.includes("{name}"))
+        ? definition.names
+        : [""];
+}
+export function diagnoseRetiredResources(opts) {
+    const contract = opts.contract ?? loadNativeResourceCleanupContract();
+    if (opts.resourceId && !retiredResourceDiagnosticIds(contract).includes(opts.resourceId)) {
+        throw new Error(`unknown retired Agentera resource ID: ${opts.resourceId}`);
+    }
+    const roots = {
+        home: path.resolve(opts.home),
+        project: path.resolve(opts.project),
+        install_root: path.resolve(opts.installRoot),
+    };
+    const observed = new Map();
+    for (const definition of contract.diagnosticResources) {
+        for (const name of namesFor(definition)) {
+            const id = definition.id.replace("{name}", name);
+            if (opts.resourceId && id !== opts.resourceId)
+                continue;
+            for (const destination of definition.destinations) {
+                const pathname = expandTemplate(destination, roots, name || null);
+                const observation = observeDestination(pathname, definition, contract.diagnosticMaximumFileBytes);
+                if (!observation)
+                    continue;
+                const current = observed.get(id) ?? [];
+                current.push(observation);
+                observed.set(id, current);
+            }
+        }
+    }
+    const entries = [...observed.entries()].sort(([left], [right]) => left.localeCompare(right));
+    const retained = entries.slice(0, contract.diagnosticMaximumResources).map(([id, observations]) => ({
+        id,
+        status: "action_required",
+        evidence: {
+            paths: [...new Set(observations.map((observation) => observation.path))].sort(),
+            observation: observations.some((observation) => observation.observation === "uninspectable")
+                ? "uninspectable"
+                : "path_present",
+        },
+    }));
+    return {
+        schemaVersion: "agentera.retiredResourceDiagnosis.v1",
+        status: retained.length > 0 || entries.length > contract.diagnosticMaximumResources ? "action_required" : "clean",
+        selectedResourceId: opts.resourceId ?? null,
+        resources: retained,
+        omittedResourceCount: Math.max(0, entries.length - retained.length),
+    };
+}