agentera 3.0.0-dev.7 → 3.0.0-dev.72

package/dist/upgrade/projectIntegration.js

@@ -1,98 +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 { detectV1ArtifactPairs, planRuntimeRetirementPhase, } from "./migrateArtifactsV2ToV3.js";
+import { projectHasProjectLevelRuntimeHooks, } from "./runtimeMigration.js";
 import { isStableSuccessorAnnounced } from "./nextMajorDoctor.js";
 import { buildUpgradeCommands } from "./upgradeCommands.js";
-import { classifyIntegrationScenario, integrationScenarioMessage, integrationScenarioNeedsInstallRoot, integrationScenarioOnlyPhases, 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);
-}
-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) => {
@@ -105,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 ||
@@ -139,7 +74,7 @@ function resolveIntegrationTargets(args) {
     };
 }
 function commandChannel(args, channel, crossMajor, upgradeOutcome) {
-    if (crossMajor && !shouldIncludeCrossMajorPlanItems(channel, upgradeOutcome)) {
+    if (crossMajor && upgradeOutcome && !shouldIncludeCrossMajorPlanItems(channel, upgradeOutcome)) {
         return resolveInvokedUpdateChannel({
             channel: "development",
             env: args.env,
@@ -149,122 +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 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 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,
-    });
-    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 scenario = classifyIntegrationScenario({
+    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 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: v1Artifacts.length + pendingProjectMigration.length,
         crossMajor,
         crossMajorMigration,
-        crossMajorNeedsPreview,
+        crossMajorNeedsPreview: Boolean(majorBoundaryBlock) || (crossMajor && !crossMajorMigration),
         needsAppUpgrade,
-    });
-    const recommendation = integrationScenarioRecommendation(scenario);
-    const message = integrationScenarioMessage(scenario, {
-        projectLevelRuntimeHooks: projectHasProjectLevelRuntimeHooks(args.project),
-        pendingRuntimes,
-    });
-    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 onlyPhases = integrationScenarioOnlyPhases(scenario);
-    const installRootForCommands = integrationScenarioNeedsInstallRoot(scenario)
-        ? integrationTargets.installRoot
+    const cmds = hasUpgradeWork
+        ? buildUpgradeCommands({
+            project: args.project,
+            installRoot: null,
+            channel: cmdsChannel,
+            only: null,
+            cwdDefault: true,
+        })
         : null;
-    const cmds = buildUpgradeCommands({
-        project: args.project,
-        installRoot: installRootForCommands,
-        channel: cmdsChannel,
-        only: onlyPhases,
-        cwdDefault: true,
-    });
+    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: onlyPhases,
-        major_boundary_block: null,
+        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

package/dist/upgrade/projectIntegrationDecision.js

@@ -1,93 +1,50 @@
-import { APP_MANUAL_REVIEW_NEEDED, APP_MIGRATION_NEEDED, APP_OUTDATED, APP_REPAIR_NEEDED, APP_UP_TO_DATE } from "./doctor.js";
+import { APP_MANUAL_REVIEW_NEEDED, APP_UP_TO_DATE } from "./doctor.js";
 export function classifyIntegrationScenario(facts) {
-    const { bundleStatus, pendingRuntimeCount, pendingArtifactCount, crossMajor, crossMajorMigration, crossMajorNeedsPreview, needsAppUpgrade, } = facts;
-    if (bundleStatus === APP_MANUAL_REVIEW_NEEDED &&
-        pendingRuntimeCount === 0 &&
-        pendingArtifactCount === 0 &&
-        !crossMajor) {
-        return "stay_manual_review";
+    if (facts.pendingArtifactCount === 0 &&
+        !facts.crossMajor &&
+        !facts.crossMajorMigration &&
+        !facts.crossMajorNeedsPreview &&
+        (facts.bundleStatus === APP_UP_TO_DATE || facts.bundleStatus === APP_MANUAL_REVIEW_NEEDED)) {
+        return "stay";
     }
-    const artifactsOnly = pendingArtifactCount > 0 && !crossMajorMigration && !crossMajorNeedsPreview && !needsAppUpgrade;
-    const runtimeOnly = pendingRuntimeCount > 0 &&
-        !artifactsOnly &&
-        !crossMajorMigration &&
-        !crossMajorNeedsPreview &&
-        !needsAppUpgrade;
-    if (!artifactsOnly &&
-        !runtimeOnly &&
-        !crossMajorMigration &&
-        !crossMajorNeedsPreview &&
-        !needsAppUpgrade &&
-        bundleStatus === APP_UP_TO_DATE &&
-        pendingRuntimeCount === 0 &&
-        pendingArtifactCount === 0) {
-        return "stay_up_to_date";
+    if (facts.crossMajorNeedsPreview) {
+        return "blocked";
     }
-    if (crossMajorMigration || crossMajorNeedsPreview) {
-        return crossMajorMigration ? "upgrade_cross_major" : "upgrade_cross_major_preview";
-    }
-    if (needsAppUpgrade) {
-        if (bundleStatus === APP_OUTDATED) {
-            return "upgrade_app_outdated";
-        }
-        if (bundleStatus === APP_REPAIR_NEEDED) {
-            return "upgrade_app_repair";
-        }
-        if (bundleStatus === APP_MIGRATION_NEEDED) {
-            return "upgrade_app_migration";
-        }
-        return "upgrade_app_outdated";
-    }
-    if (artifactsOnly) {
-        return "upgrade_artifacts_only";
-    }
-    if (runtimeOnly) {
-        return "upgrade_runtime_only";
-    }
-    if (pendingRuntimeCount > 0) {
-        return "upgrade_runtime_mixed";
-    }
-    return "upgrade_generic";
+    return "upgrade";
 }
-export function integrationScenarioRecommendation(scenario) {
-    return scenario === "stay_manual_review" || scenario === "stay_up_to_date" ? "stay" : "upgrade";
+export function integrationScenarioMessage(scenario, facts) {
+    if (scenario === "stay")
+        return "Your Agentera install is up to date.";
+    if (scenario === "blocked") {
+        return "Cross-major version boundary detected; v3 successor not yet announced. Stay on the current channel.";
+    }
+    const reasons = [];
+    if (facts.pendingArtifactCount > 0)
+        reasons.push("project state needs migration");
+    if (facts.needsAppUpgrade)
+        reasons.push("app bundle needs update");
+    if (facts.crossMajorMigration)
+        reasons.push("cross-major version migration needed");
+    if (reasons.length === 0)
+        reasons.push("project changes pending");
+    return `This project needs an Agentera upgrade (${reasons.join(", ")}). Preview the upgrade command.`;
 }
-export function integrationScenarioOnlyPhases(scenario) {
-    if (scenario === "upgrade_artifacts_only") {
-        return ["artifacts"];
-    }
-    if (scenario === "upgrade_runtime_only") {
-        return ["runtime"];
-    }
-    return undefined;
+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 integrationScenarioNeedsInstallRoot(scenario) {
-    return (scenario === "upgrade_cross_major" ||
-        scenario === "upgrade_cross_major_preview" ||
-        scenario === "upgrade_app_outdated" ||
-        scenario === "upgrade_app_repair" ||
-        scenario === "upgrade_app_migration");
-}
-const SCENARIO_MESSAGES = {
-    stay_manual_review: "Agentera needs manual review for your app directory before this project can be upgraded safely.",
-    stay_up_to_date: "This project matches your current Agentera install; no upgrade is needed.",
-    upgrade_artifacts_only: "This project still uses v1 Markdown artifacts; preview migrating them to v2 YAML before continuing.",
-    upgrade_cross_major: "Your Agentera app copy is still on v2 while the CLI is on v3; preview the one-way v2→v3 migration before applying.",
-    upgrade_cross_major_preview: "Your Agentera app copy is still on v2 while the CLI is on v3; preview the one-way v2→v3 migration before applying.",
-    upgrade_app_outdated: "Your Agentera app copy is out of date; preview the update with agentera upgrade before applying.",
-    upgrade_app_repair: "Your Agentera app copy needs repair; preview the repair with agentera upgrade before applying.",
-    upgrade_app_migration: "Your Agentera app copy needs migration; preview the migration with agentera upgrade before applying.",
-    upgrade_runtime_only: "",
-    upgrade_runtime_mixed: "",
-    upgrade_generic: "Preview Agentera upgrade changes for this project before applying.",
-};
-export function integrationScenarioMessage(scenario, opts) {
-    if (scenario === "upgrade_runtime_only" || scenario === "upgrade_runtime_mixed") {
-        const runtimes = opts.pendingRuntimes.length > 0 ? opts.pendingRuntimes.join(", ") : "runtime configs";
-        return opts.projectLevelRuntimeHooks
-            ? `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.`;
+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" };
     }
-    return SCENARIO_MESSAGES[scenario];
+    if (hasPendingWork)
+        return { code: 1, meaning: "preview_required" };
+    return { code: 1, meaning: "manual_review_required" };
 }
-//# sourceMappingURL=projectIntegrationDecision.js.map

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),
+    };
+}