agentera 3.0.0-dev.6 → 3.0.0-dev.69

package/dist/upgrade/doctor.js

@@ -1,20 +1,68 @@
 import fs from "node:fs";
 import path from "node:path";
-import { expanduser, isFile, pathExists, resolvePath } from "../core/paths.js";
+import { isLifecycleOwnershipStateDirectory } from "../runtime/lifecycleOwnershipJournal.js";
+import { expanduser, pathExists, resolvePath } from "../core/paths.js";
 import { SOURCE_LABELS, classifyResolvedRoot } from "../state/installRoot.js";
 import { doctorRoots, loadSuiteVersion } from "./appModel.js";
 import { isNpxBundleRoot } from "../core/sourceRoot.js";
-import { resolveUpdateChannel } from "./channels.js";
-import { classifyInstall, crossMajorBoundaryApplies } from "./compatibility.js";
+import { resolveInvokedUpdateChannel } from "./channels.js";
+import { classifyInstall, cliDistributionMajor, crossMajorBoundaryApplies, isSourceCheckoutRoot, projectInstallTrack, } from "./compatibility.js";
 import { isStableSuccessorAnnounced } from "./nextMajorDoctor.js";
 import { buildUpgradeCommands, commandText } from "./upgradeCommands.js";
 import { parseSemverMajor } from "./versionResolution.js";
+import { classifyInstallRootStatus } from "./doctorClassifier.js";
+import { hasBundleRootEvidence } from "./bundleEvidence.js";
+function inferInvokingCliRuntime(sourceRoot, env) {
+    const explicit = (env.AGENTERA_CLI_RUNTIME ?? "").trim().toLowerCase();
+    if (explicit === "js" || explicit === "node") {
+        return "js";
+    }
+    if (explicit === "python" || explicit === "uv") {
+        return "python";
+    }
+    const argv0 = process.argv0 ?? "";
+    if (/\bnode\b/i.test(argv0)) {
+        return "js";
+    }
+    if (/\bpython\d*\b/i.test(argv0) || /\buv\b/i.test(argv0)) {
+        return "python";
+    }
+    if (cliDistributionMajor(sourceRoot) >= 3) {
+        return "js";
+    }
+    return "unknown";
+}
+function buildInvokingCliRetryCommand(sourceRoot, channel, env, expectedCommand) {
+    const runtime = inferInvokingCliRuntime(sourceRoot, env);
+    if (runtime !== "js") {
+        return null;
+    }
+    return commandText([...channel.updateCommand.trim().split(/\s+/).slice(0, 3), expectedCommand]);
+}
+/**
+ * Doctor status build. Faithful TS port of build_doctor_status /
+ * public_doctor_status from scripts/agentera_upgrade.py.
+ *
+ * The classification -> root_status/signals/status logic matches Python exactly.
+ * The emitted command strings use the TS-CLI invocation form (npx/node) rather
+ * than the Python uvx/uv form; the final wording is settled in Phase 8 packaging.
+ */
 export const APP_UP_TO_DATE = "up_to_date";
 export const APP_OUTDATED = "outdated";
 export const APP_REPAIR_NEEDED = "repair_needed";
 export const APP_MIGRATION_NEEDED = "migration_needed";
 export const APP_MANUAL_REVIEW_NEEDED = "manual_review_needed";
 export const EXPECTED_STATE_COMMANDS = ["prime"];
+/** Operation noun for doctor/prime copy derived from aggregate lifecycle status. */
+export function appLifecycleActionNoun(status) {
+    if (status === APP_OUTDATED) {
+        return "update";
+    }
+    if (status === APP_MIGRATION_NEEDED) {
+        return "migration";
+    }
+    return "repair";
+}
 export const BUNDLE_MARKER = ".agentera-bundle.json";
 /** Agentera user state preserved during v2→v3 managed app-home cleanup. */
 export const AGENTERA_USER_STATE_NAMES = new Set([
@@ -31,6 +79,7 @@ export const ROOT_USER_STATE_FILE_NAMES = new Set([
     "TODO.md",
     "CHANGELOG.md",
     "DESIGN.md",
+    "v3-handoff.json",
 ]);
 export const ROOT_USER_STATE_DIR_NAMES = new Set([
     "history",
@@ -39,10 +88,6 @@ export const ROOT_USER_STATE_DIR_NAMES = new Set([
     "intermediate",
     "sessions",
 ]);
-function hasBundleRootEvidence(root) {
-    return (isFile(path.join(root, "scripts", "agentera")) &&
-        isFile(path.join(root, "skills", "agentera", "SKILL.md")));
-}
 function legacyDefaultAppHome(home) {
     return resolvePath(path.join(expanduser(home), ".agents", "agentera"));
 }
@@ -62,7 +107,12 @@ function agenteraUserStateDirIsRecognized(p) {
         if (AGENTERA_USER_STATE_NAMES.has(entry) && st.isFile()) {
             continue;
         }
-        if (entry === "optimera" && st.isDirectory()) {
+        if ((entry === "optimize" || entry === "optimera") && st.isDirectory()) {
+            // "optimera" is the v2 stable legacy objective dir name; keep it
+            // recognized so v2->v3 migration preserves legacy objective state.
+            continue;
+        }
+        if (entry === "runtime-lifecycle" && isLifecycleOwnershipStateDirectory(full)) {
             continue;
         }
         return false;
@@ -107,34 +157,19 @@ function sourceKey(rootSource) {
     }
     return "explicit";
 }
-function recoverableStaleDefaultSignal(appHome, roots) {
-    return {
-        status: APP_REPAIR_NEEDED,
-        kind: "recoverable_stale_default",
-        message: "Agentera found an old app directory and can repair it without asking you to edit shell settings",
-        deprecatedDefaultAppHome: appHome,
-        managedAppRoot: roots.managedAppRoot,
-    };
-}
-function userDataOnlySignal(appHome, roots) {
-    return {
-        status: APP_REPAIR_NEEDED,
-        kind: "user_data_only_app_home",
-        message: "This Agentera directory only has your Agentera data, so Agentera can safely add fresh app files under app/",
-        appHome,
-        managedAppRoot: roots.managedAppRoot,
-    };
-}
-function blockedRootRecoveryMessage(_rootSource) {
-    return "choose a different Agentera directory, or use --force only if you checked this directory and want Agentera to replace files there";
-}
 export function buildDoctorStatus(installRoot, opts) {
     const rootSource = opts.rootSource;
     const sourceRoot = opts.sourceRoot;
     const home = opts.home;
     const project = opts.project;
     const expectedCommands = opts.expectedCommands ?? EXPECTED_STATE_COMMANDS;
-    const probeCli = opts.probeCli ?? true;
+    const env = { ...(opts.env ?? process.env), HOME: home };
+    const channel = opts.resolvedChannel ?? resolveInvokedUpdateChannel({
+        channel: opts.channel ?? null,
+        env,
+        home,
+        sourceRoot,
+    });
     // Fully self-contained npx bundle: the bundle IS the app and is always current
     // (its version is the package version), so there is no install/upgrade step.
     // Report it as the authoritative, up-to-date app home. (Sentinel-gated; never
@@ -149,22 +184,56 @@ export function buildDoctorStatus(installRoot, opts) {
             appHomeSource: "bundled app",
             managedAppRoot: sourceRoot,
             userDataRoot: sourceRoot,
-            activeBundleRoot: sourceRoot,
+            activeAppRoot: sourceRoot,
             authoritativeRoot: sourceRoot,
             skillRoot: path.join(sourceRoot, "skills", "agentera"),
             runtimeRoot: sourceRoot,
             sourceRoot,
             installRoot: sourceRoot,
             installRootSource: "bundled app",
-            home,
-            project,
             rootStatus: "bundled",
+            installKind: "v3_self_contained_npm",
             markerVersion: bundleExpected,
             signals: [],
             dryRunCommand: null,
             applyCommand: null,
-            retryCommand: commandText(["npx", "-y", "agentera", expectedCommands[0] ?? "prime"]),
-            approval: "no action needed: self-contained app bundle is current",
+            retryCommand: commandText([
+                ...channel.updateCommand.trim().split(/\s+/).slice(0, 3),
+                expectedCommands[0] ?? "prime",
+            ]),
+            updateChannel: channel.channel,
+        };
+    }
+    // Source checkout: the CLI invocation IS the app, so the install root is
+    // user state only and never needs upgrade gating. Narrowed to the default
+    // app home AND an existing install root so an explicit --install-root, a
+    // missing default app home (still a real diagnostic), and AGENTERA_HOME
+    // overrides all keep their existing inspection behavior.
+    if (isSourceCheckoutRoot(sourceRoot) && rootSource === SOURCE_LABELS.default && pathExists(installRoot)) {
+        const checkoutExpected = opts.expectedVersion || loadSuiteVersion(sourceRoot) || "unknown";
+        return {
+            schemaVersion: "agentera.bundleStatus.v1",
+            status: APP_UP_TO_DATE,
+            expectedVersion: checkoutExpected,
+            appHome: installRoot,
+            appHomeSource: rootSource,
+            managedAppRoot: installRoot,
+            userDataRoot: installRoot,
+            activeAppRoot: installRoot,
+            authoritativeRoot: installRoot,
+            skillRoot: path.join(sourceRoot, "skills", "agentera"),
+            runtimeRoot: sourceRoot,
+            sourceRoot,
+            installRoot,
+            installRootSource: rootSource,
+            rootStatus: "source",
+            installKind: "source_checkout",
+            markerVersion: null,
+            signals: [],
+            dryRunCommand: null,
+            applyCommand: null,
+            retryCommand: null,
+            updateChannel: channel.channel,
         };
     }
     const expected = opts.expectedVersion || loadSuiteVersion(sourceRoot) || "unknown";
@@ -175,153 +244,53 @@ export function buildDoctorStatus(installRoot, opts) {
         expectedVersion: expected,
     });
     const markerVersion = classification.current_version;
-    const signals = [];
-    let blocked = false;
     const recoverableStaleDefault = isRecoverableStaleDefaultAppHome(installRoot, rootSource, home);
     const legacyBundleRoot = activeBundleRoot === installRoot &&
         hasBundleRootEvidence(installRoot) &&
         !pathExists(path.join(installRoot, ".git"));
-    let rootStatus;
-    if (classification.kind === "missing_default") {
-        rootStatus = "missing";
-        signals.push({
-            status: APP_REPAIR_NEEDED,
-            kind: "missing_bundle",
-            message: "Agentera is not installed in the normal directory yet",
-        });
-    }
-    else if (classification.kind === "missing_explicit_or_environment" && recoverableStaleDefault) {
-        rootStatus = "missing";
-        signals.push(recoverableStaleDefaultSignal(installRoot, roots));
-    }
-    else if (classification.kind === "missing_explicit_or_environment") {
-        rootStatus = "missing";
-        blocked = true;
-        signals.push({
-            status: APP_MANUAL_REVIEW_NEEDED,
-            kind: "invalid_install_root",
-            message: "Agentera was told to use a directory that does not exist. " +
-                "Choose an existing Agentera directory, or install into the normal Agentera directory.",
-        });
-    }
-    else if (classification.kind === "file_valued_root") {
-        rootStatus = "invalid";
-        blocked = true;
-        signals.push({
-            status: APP_MANUAL_REVIEW_NEEDED,
-            kind: "invalid_install_root",
-            message: `Agentera was told to use a file instead of a directory; ${blockedRootRecoveryMessage(rootSource)}`,
-        });
-    }
-    else if ((classification.kind === "invalid_bundle" || classification.kind === "unmanaged_directory") &&
-        recoverableStaleDefault) {
-        rootStatus = "stale_default";
-        signals.push(recoverableStaleDefaultSignal(installRoot, roots));
-    }
-    else if (classification.kind === "unmanaged_directory" && appHomeIsUserDataOnly(installRoot)) {
-        rootStatus = "user_data_only";
-        signals.push(userDataOnlySignal(installRoot, roots));
-    }
-    else if (classification.kind === "unmanaged_directory") {
-        rootStatus = "unmanaged";
-        blocked = true;
-        signals.push({
-            status: APP_MANUAL_REVIEW_NEEDED,
-            kind: "unmanaged_install_root",
-            message: `This directory already has files Agentera does not recognize, so Agentera will not change it automatically; ${blockedRootRecoveryMessage(rootSource)}`,
-        });
-    }
-    else if (classification.kind === "invalid_bundle") {
-        rootStatus = "invalid";
-        blocked = true;
-        signals.push({
-            status: APP_MANUAL_REVIEW_NEEDED,
-            kind: "invalid_bundle",
-            message: `This directory looks like a broken Agentera install; ${blockedRootRecoveryMessage(rootSource)}`,
-        });
-    }
-    else {
-        rootStatus = "managed";
-        if (legacyBundleRoot) {
-            signals.push({
-                status: APP_MIGRATION_NEEDED,
-                kind: APP_MIGRATION_NEEDED,
-                message: "Agentera app files are in the old place and can be moved into app/",
-                legacyBundleRoot: installRoot,
-                managedAppRoot: roots.managedAppRoot,
-            });
-        }
-        const reason = classification.diagnostic.evidence.reason;
-        if (classification.kind === "managed_stale" && reason === "missing_marker") {
-            if (recoverableStaleDefault) {
-                signals.push(recoverableStaleDefaultSignal(installRoot, roots));
-            }
-            signals.push({
-                status: APP_REPAIR_NEEDED,
-                kind: "missing_marker",
-                message: "Agentera app files need repair",
-            });
-        }
-        else if (classification.kind === "managed_stale" && reason === "version_mismatch") {
-            if (recoverableStaleDefault) {
-                signals.push(recoverableStaleDefaultSignal(installRoot, roots));
-            }
-            signals.push({
-                status: APP_OUTDATED,
-                kind: "version_mismatch",
-                expected,
-                actual: markerVersion,
-                message: "Agentera app files are valid but need an update to the expected version",
-            });
-        }
-        const probe = probeCli
-            ? (opts.probeRunner ?? defaultProbe)({
-                bundleRoot: activeBundleRoot,
-                appHome: installRoot,
-                project,
-                expectedCommands,
-            })
-            : { ok: true };
-        if (!probe.ok) {
-            let kind = "cli_probe_unavailable";
-            if (probe.returnCode !== null && probe.returnCode !== undefined && probe.returnCode !== 0) {
-                kind = "cli_probe_failed";
-            }
-            else if (probe.missingCommands && probe.missingCommands.length > 0) {
-                kind = "missing_command";
-            }
-            signals.push({
-                status: APP_REPAIR_NEEDED,
-                kind,
-                message: probe.message,
-                returnCode: probe.returnCode ?? null,
-                missingCommands: probe.missingCommands ?? [],
-                stdoutTail: probe.stdoutTail ?? [],
-                stderrTail: probe.stderrTail ?? [],
-            });
-        }
-    }
-    const env = { ...(opts.env ?? process.env), HOME: home };
-    const channel = resolveUpdateChannel({
-        channel: opts.channel ?? null,
-        env,
-        home,
-        sourceRoot,
+    const userDataOnly = classification.kind === "unmanaged_directory" && appHomeIsUserDataOnly(installRoot);
+    const classified = classifyInstallRootStatus({
+        installRoot,
+        rootSource,
+        roots,
+        classification,
+        expected,
+        markerVersion,
+        recoverableStaleDefault,
+        legacyBundleRoot,
+        userDataOnly,
+        project,
+        expectedCommands,
     });
+    const rootStatus = classified.rootStatus;
+    const signals = classified.signals;
+    const blocked = classified.blocked;
     const install = classifyInstall({ appHome: installRoot, sourceRoot });
     const crossMajorDetected = crossMajorBoundaryApplies(install, sourceRoot);
-    const successorAnnounced = isStableSuccessorAnnounced(sourceRoot);
+    const successorAnnounced = isStableSuccessorAnnounced(sourceRoot, "stable");
+    if (opts.observation) {
+        opts.observation.install = install;
+        opts.observation.successorAnnounced = successorAnnounced;
+    }
     const crossMajorBoundary = crossMajorDetected && successorAnnounced;
+    let crossMajorPending = false;
     if (crossMajorDetected && !successorAnnounced) {
-        for (let i = signals.length - 1; i >= 0; i--) {
-            const signal = signals[i];
+        for (const signal of signals) {
             if (signal.kind !== "version_mismatch") {
                 continue;
             }
             const actualMajor = parseSemverMajor(String(signal.actual ?? markerVersion ?? "")) ?? 0;
             const expectedMajor = parseSemverMajor(String(signal.expected ?? expected)) ?? 0;
             if (actualMajor > 0 && actualMajor < 3 && expectedMajor >= 3) {
-                signals.splice(i, 1);
+                crossMajorPending = true;
+                signals.push({
+                    status: APP_MANUAL_REVIEW_NEEDED,
+                    kind: "cross_major_pending",
+                    expected: signal.expected,
+                    actual: signal.actual,
+                    message: `Agentera app files are on v${actualMajor}.x while the CLI is on v${expectedMajor}.x; the v${expectedMajor} successor line is not announced yet, so no upgrade is offered`,
+                });
+                break;
             }
         }
     }
@@ -335,11 +304,13 @@ export function buildDoctorStatus(installRoot, opts) {
         ? APP_MANUAL_REVIEW_NEEDED
         : signals.some((s) => s.kind === APP_MIGRATION_NEEDED)
             ? APP_MIGRATION_NEEDED
-            : signals.some((s) => s.status === APP_REPAIR_NEEDED)
-                ? APP_REPAIR_NEEDED
-                : signals.some((s) => s.status === APP_OUTDATED)
-                    ? APP_OUTDATED
-                    : APP_UP_TO_DATE;
+            : crossMajorPending
+                ? APP_MANUAL_REVIEW_NEEDED
+                : signals.some((s) => s.status === APP_REPAIR_NEEDED)
+                    ? APP_REPAIR_NEEDED
+                    : signals.some((s) => s.status === APP_OUTDATED)
+                        ? APP_OUTDATED
+                        : APP_UP_TO_DATE;
     return {
         schemaVersion: "agentera.bundleStatus.v1",
         status,
@@ -348,45 +319,41 @@ export function buildDoctorStatus(installRoot, opts) {
         appHomeSource: rootSource,
         managedAppRoot: roots.managedAppRoot,
         userDataRoot: installRoot,
-        activeBundleRoot,
+        activeAppRoot: activeBundleRoot,
         authoritativeRoot: roots.managedAppRoot,
         skillRoot: roots.skillRoot,
         runtimeRoot: roots.runtimeRoot,
         sourceRoot,
         installRoot,
         installRootSource: rootSource,
-        home,
-        project,
         rootStatus,
+        installKind: install.kind,
         markerVersion,
         signals,
-        dryRunCommand: blocked || status === APP_UP_TO_DATE ? null : upgradeCommands.dryRunCommand,
-        applyCommand: blocked || status === APP_UP_TO_DATE ? null : upgradeCommands.applyCommand,
+        dryRunCommand: blocked || crossMajorPending || status === APP_UP_TO_DATE
+            ? null
+            : upgradeCommands.dryRunCommand,
+        applyCommand: blocked || crossMajorPending || status === APP_UP_TO_DATE
+            ? null
+            : upgradeCommands.applyCommand,
         updateChannel: channel.channel,
+        crossMajorBoundaryDetected: crossMajorDetected,
         crossMajorBoundary,
-        retryCommand: commandText([
-            "node",
-            path.join(activeBundleRoot, "scripts", "agentera"),
-            expectedCommands[0] ?? "prime",
-        ]),
-        approval: `approve app files repair for ${installRoot}`,
+        retryCommand: buildInvokingCliRetryCommand(sourceRoot, channel, env, expectedCommands[0] ?? "prime"),
     };
 }
-/** Default CLI probe placeholder (wired to the bundled TS CLI in Phase 8). */
-const defaultProbe = ({ expectedCommands }) => ({
-    ok: false,
-    command: null,
-    returnCode: null,
-    stdoutTail: [],
-    stderrTail: [],
-    missingCommands: [...expectedCommands],
-    message: "CLI probe not yet wired to the bundled TS CLI",
-});
 export function publicDoctorStatus(status) {
-    const pub = JSON.parse(JSON.stringify(status));
-    delete pub.installRoot;
-    delete pub.installRootSource;
-    return pub;
+    const { installRoot: _installRoot, installRootSource: _installRootSource, installKind: _installKind, rootStatus: _rootStatus, platformAppHome, cliApp, ...rest } = status;
+    const result = { ...rest };
+    if (platformAppHome) {
+        const { rootStatus: _prs, ...platform } = platformAppHome;
+        result.platformAppHome = platform;
+    }
+    if (cliApp) {
+        const { rootStatus: _crs, ...cli } = cliApp;
+        result.cliApp = cli;
+    }
+    return result;
 }
 /** Oracle-pinned keys for `agentera doctor --format json` (parity-remaining-families.json). */
 export const DOCTOR_PARITY_JSON_KEYS = [
@@ -403,11 +370,10 @@ export const DOCTOR_PARITY_JSON_KEYS = [
 /** Public doctor JSON envelope: command label plus oracle structural keys only. */
 export function doctorParityJsonEnvelope(status) {
     const pub = publicDoctorStatus(status);
-    const out = { command: "doctor" };
+    const out = { command: "doctor", install_track: projectInstallTrack(status.installKind) };
     for (const key of DOCTOR_PARITY_JSON_KEYS) {
         if (key in pub)
             out[key] = pub[key];
     }
     return out;
 }
-//# sourceMappingURL=doctor.js.map

package/dist/upgrade/doctorClassifier.js

@@ -0,0 +1,187 @@
+import { APP_MANUAL_REVIEW_NEEDED, APP_MIGRATION_NEEDED, APP_OUTDATED, APP_REPAIR_NEEDED, } from "./doctor.js";
+function blockedRootRecoveryMessage(_rootSource) {
+    return "choose a different Agentera directory, or use --force only if you checked this directory and want Agentera to replace files there";
+}
+function recoverableStaleDefaultSignal(appHome, roots) {
+    return {
+        status: APP_REPAIR_NEEDED,
+        kind: "recoverable_stale_default",
+        message: "Agentera found an old app directory and can repair it without asking you to edit shell settings",
+        deprecatedDefaultAppHome: appHome,
+        managedAppRoot: roots.managedAppRoot,
+    };
+}
+function userDataOnlySignal(appHome, roots) {
+    return {
+        status: APP_REPAIR_NEEDED,
+        kind: "user_data_only_app_home",
+        message: "This Agentera directory only has your Agentera data, so Agentera can safely add fresh app files under app/",
+        appHome,
+        managedAppRoot: roots.managedAppRoot,
+    };
+}
+function classifyMissingDefault(_ctx) {
+    return {
+        rootStatus: "missing",
+        blocked: false,
+        signals: [
+            {
+                status: APP_REPAIR_NEEDED,
+                kind: "missing_bundle",
+                message: "Agentera is not installed in the normal directory yet",
+            },
+        ],
+    };
+}
+function classifyMissingExplicitOrEnvironment(ctx) {
+    if (ctx.recoverableStaleDefault) {
+        return {
+            rootStatus: "missing",
+            blocked: false,
+            signals: [recoverableStaleDefaultSignal(ctx.installRoot, ctx.roots)],
+        };
+    }
+    return {
+        rootStatus: "missing",
+        blocked: true,
+        signals: [
+            {
+                status: APP_MANUAL_REVIEW_NEEDED,
+                kind: "invalid_install_root",
+                message: "Agentera was told to use a directory that does not exist. " +
+                    "Choose an existing Agentera directory, or install into the normal Agentera directory.",
+            },
+        ],
+    };
+}
+function classifyFileValuedRoot(ctx) {
+    return {
+        rootStatus: "invalid",
+        blocked: true,
+        signals: [
+            {
+                status: APP_MANUAL_REVIEW_NEEDED,
+                kind: "invalid_install_root",
+                message: `Agentera was told to use a file instead of a directory; ${blockedRootRecoveryMessage(ctx.rootSource)}`,
+            },
+        ],
+    };
+}
+function classifyInvalidBundle(ctx) {
+    if (ctx.recoverableStaleDefault) {
+        return {
+            rootStatus: "stale_default",
+            blocked: false,
+            signals: [recoverableStaleDefaultSignal(ctx.installRoot, ctx.roots)],
+        };
+    }
+    return {
+        rootStatus: "invalid",
+        blocked: true,
+        signals: [
+            {
+                status: APP_MANUAL_REVIEW_NEEDED,
+                kind: "invalid_bundle",
+                message: `This directory looks like a broken Agentera install; ${blockedRootRecoveryMessage(ctx.rootSource)}`,
+            },
+        ],
+    };
+}
+function classifyUnmanagedDirectory(ctx) {
+    if (ctx.recoverableStaleDefault) {
+        return {
+            rootStatus: "stale_default",
+            blocked: false,
+            signals: [recoverableStaleDefaultSignal(ctx.installRoot, ctx.roots)],
+        };
+    }
+    if (ctx.userDataOnly) {
+        return {
+            rootStatus: "user_data_only",
+            blocked: false,
+            signals: [userDataOnlySignal(ctx.installRoot, ctx.roots)],
+        };
+    }
+    return {
+        rootStatus: "unmanaged",
+        blocked: true,
+        signals: [
+            {
+                status: APP_MANUAL_REVIEW_NEEDED,
+                kind: "unmanaged_install_root",
+                message: `This directory already has files Agentera does not recognize, so Agentera will not change it automatically; ${blockedRootRecoveryMessage(ctx.rootSource)}`,
+            },
+        ],
+    };
+}
+function appendManagedStaleSignals(ctx, signals) {
+    const reason = ctx.classification.diagnostic.evidence.reason;
+    if (ctx.classification.kind !== "managed_stale") {
+        return;
+    }
+    if (reason === "missing_marker") {
+        if (ctx.recoverableStaleDefault) {
+            signals.push(recoverableStaleDefaultSignal(ctx.installRoot, ctx.roots));
+        }
+        signals.push({
+            status: APP_REPAIR_NEEDED,
+            kind: "missing_marker",
+            message: "Agentera app files need repair",
+        });
+    }
+    else if (reason === "corrupt_marker") {
+        if (ctx.recoverableStaleDefault) {
+            signals.push(recoverableStaleDefaultSignal(ctx.installRoot, ctx.roots));
+        }
+        const markerPath = String(ctx.classification.diagnostic.evidence.markerPath);
+        signals.push({
+            status: APP_REPAIR_NEEDED,
+            kind: "corrupt_bundle_marker",
+            message: `bundle marker file is corrupt: ${markerPath}`,
+        });
+    }
+    else if (reason === "version_mismatch") {
+        if (ctx.recoverableStaleDefault) {
+            signals.push(recoverableStaleDefaultSignal(ctx.installRoot, ctx.roots));
+        }
+        signals.push({
+            status: APP_OUTDATED,
+            kind: "version_mismatch",
+            expected: ctx.expected,
+            actual: ctx.markerVersion,
+            message: "Agentera app files are valid but need an update to the expected version",
+        });
+    }
+}
+function classifyManaged(ctx) {
+    const signals = [];
+    if (ctx.legacyBundleRoot) {
+        signals.push({
+            status: APP_MIGRATION_NEEDED,
+            kind: APP_MIGRATION_NEEDED,
+            message: "Agentera app files are in the old place and can be moved into app/",
+            legacyAppRoot: ctx.installRoot,
+            managedAppRoot: ctx.roots.managedAppRoot,
+        });
+    }
+    appendManagedStaleSignals(ctx, signals);
+    return {
+        rootStatus: "managed",
+        blocked: false,
+        signals,
+    };
+}
+const ROOT_CLASSIFIERS = {
+    missing_default: classifyMissingDefault,
+    missing_explicit_or_environment: classifyMissingExplicitOrEnvironment,
+    file_valued_root: classifyFileValuedRoot,
+    invalid_bundle: classifyInvalidBundle,
+    unmanaged_directory: classifyUnmanagedDirectory,
+    managed_fresh: classifyManaged,
+    managed_stale: classifyManaged,
+};
+export function classifyInstallRootStatus(ctx) {
+    const kind = ctx.classification.kind;
+    const classifier = ROOT_CLASSIFIERS[kind] ?? classifyManaged;
+    return classifier(ctx);
+}