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

package/dist/upgrade/channels.js

@@ -2,7 +2,7 @@ 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";
@@ -205,16 +205,14 @@ export function resolveUpdateChannel(args = {}) {
 export function resolveInvokedUpdateChannel(args = {}) {
     const env = args.env ?? process.env;
     const sourceRoot = args.sourceRoot ?? resolveSourceRoot(env);
-    if (isNpxBundleRoot(sourceRoot)) {
-        return resolveUpdateChannel({ ...args, channel: "development", sourceRoot });
+    const selected = resolveSelectedChannel({ ...args, sourceRoot });
+    if (selected.source !== "default") {
+        return resolveUpdateChannel({ ...args, sourceRoot });
     }
     if (cliDistributionMajor(sourceRoot) >= 3) {
-        const selected = resolveSelectedChannel({ ...args, sourceRoot });
-        if (selected.source === "default") {
-            return resolveUpdateChannel({ ...args, channel: "development", sourceRoot });
-        }
+        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) {
@@ -227,4 +225,3 @@ export function parseConfigUpdateChannel(text) {
     }
     return parseChannelValue(raw, "config_file");
 }
-//# sourceMappingURL=channels.js.map

package/dist/upgrade/compatibility.js

@@ -36,7 +36,7 @@ const CROSS_MAJOR_ITEMS = [
     { phase: "runtime", verb: "migrate", name: "v2_to_v3_runtime_rewire" },
     { phase: "cleanup", verb: "migrate", name: "v2_to_v3_app_home_cleanup" },
 ];
-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")) &&
@@ -59,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);
@@ -73,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,
@@ -91,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,
@@ -151,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 });
@@ -207,4 +234,3 @@ export function foreignLayoutHasUnexpectedEntries(root) {
         return false;
     }
 }
-//# sourceMappingURL=compatibility.js.map

package/dist/upgrade/doctor.js

@@ -1,11 +1,12 @@
 import fs from "node:fs";
 import path from "node:path";
+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 { resolveInvokedUpdateChannel } from "./channels.js";
-import { classifyInstall, cliDistributionMajor, crossMajorBoundaryApplies, projectInstallTrack, } from "./compatibility.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";
@@ -36,14 +37,7 @@ function buildInvokingCliRetryCommand(sourceRoot, channel, env, expectedCommand)
     if (runtime !== "js") {
         return null;
     }
-    if (isNpxBundleRoot(sourceRoot)) {
-        return commandText(["npx", "-y", "agentera", expectedCommand]);
-    }
-    const packageSpec = channel.channel === "development" ? "agentera@next" : "agentera@latest";
-    return commandText(["npx", "-y", packageSpec, expectedCommand]);
-}
-function crossMajorPendingApprovalPhrase() {
-    return "no upgrade offered: v3 successor line is not announced yet";
+    return commandText([...channel.updateCommand.trim().split(/\s+/).slice(0, 3), expectedCommand]);
 }
 /**
  * Doctor status build. Faithful TS port of build_doctor_status /
@@ -69,12 +63,6 @@ export function appLifecycleActionNoun(status) {
     }
     return "repair";
 }
-export function appLifecycleApprovalPhrase(status, installRoot) {
-    if (status === APP_UP_TO_DATE) {
-        return "no action needed: Agentera app files are up to date";
-    }
-    return `approve app files ${appLifecycleActionNoun(status)} for ${installRoot}`;
-}
 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([
@@ -91,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",
@@ -123,6 +112,9 @@ function agenteraUserStateDirIsRecognized(p) {
             // recognized so v2->v3 migration preserves legacy objective state.
             continue;
         }
+        if (entry === "runtime-lifecycle" && isLifecycleOwnershipStateDirectory(full)) {
+            continue;
+        }
         return false;
     }
     return true;
@@ -171,6 +163,13 @@ export function buildDoctorStatus(installRoot, opts) {
     const home = opts.home;
     const project = opts.project;
     const expectedCommands = opts.expectedCommands ?? EXPECTED_STATE_COMMANDS;
+    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
@@ -192,16 +191,49 @@ export function buildDoctorStatus(installRoot, opts) {
             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";
@@ -233,16 +265,13 @@ export function buildDoctorStatus(installRoot, opts) {
     const rootStatus = classified.rootStatus;
     const signals = classified.signals;
     const blocked = classified.blocked;
-    const env = { ...(opts.env ?? process.env), HOME: home };
-    const channel = resolveInvokedUpdateChannel({
-        channel: opts.channel ?? null,
-        env,
-        home,
-        sourceRoot,
-    });
     const install = classifyInstall({ appHome: installRoot, sourceRoot });
     const crossMajorDetected = crossMajorBoundaryApplies(install, 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) {
@@ -297,8 +326,6 @@ export function buildDoctorStatus(installRoot, opts) {
         sourceRoot,
         installRoot,
         installRootSource: rootSource,
-        home,
-        project,
         rootStatus,
         installKind: install.kind,
         markerVersion,
@@ -313,9 +340,6 @@ export function buildDoctorStatus(installRoot, opts) {
         crossMajorBoundaryDetected: crossMajorDetected,
         crossMajorBoundary,
         retryCommand: buildInvokingCliRetryCommand(sourceRoot, channel, env, expectedCommands[0] ?? "prime"),
-        approval: crossMajorPending
-            ? crossMajorPendingApprovalPhrase()
-            : appLifecycleApprovalPhrase(status, installRoot),
     };
 }
 export function publicDoctorStatus(status) {
@@ -353,4 +377,3 @@ export function doctorParityJsonEnvelope(status) {
     }
     return out;
 }
-//# sourceMappingURL=doctor.js.map

package/dist/upgrade/doctorClassifier.js

@@ -129,6 +129,17 @@ function appendManagedStaleSignals(ctx, signals) {
             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));
@@ -174,4 +185,3 @@ export function classifyInstallRootStatus(ctx) {
     const classifier = ROOT_CLASSIFIERS[kind] ?? classifyManaged;
     return classifier(ctx);
 }
-//# sourceMappingURL=doctorClassifier.js.map

package/dist/upgrade/installedHooksRetirement.js

@@ -2,6 +2,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { isFile, pathExists, resolvePath } from "../core/paths.js";
 import { doctorRoots } from "./appModel.js";
+import { hasBundleRootEvidence } from "./bundleEvidence.js";
+import { bindMigrationResource, removeBoundMigrationResource, verifyBoundMigrationResource, } from "./migrationPublication.js";
 export const INSTALLED_HOOKS_SURFACE_LABEL = "hooks/";
 export const RETIRE_INSTALLED_HOOKS_ACTION = "retire-installed-hooks";
 const V2_HOOK_INVOCATION_PATTERNS = [
@@ -11,6 +13,15 @@ const V2_HOOK_INVOCATION_PATTERNS = [
     /\$\{PLUGIN_ROOT\}\/hooks\/[^"'\n]*\.py/,
 ];
 const SKIP_HOOK_SCAN_PARTS = new Set([".agentera", "sessions", "benchmarks", "intermediate", "backup"]);
+const V2_INSTALLED_HOOK_FILES = new Set([
+    "validate_artifact.py",
+    "cursor_session_start.py",
+    "cursor_pre_tool_use.py",
+    "cursor_session_stop.py",
+    "session_start.py",
+    "session_stop.py",
+    "codex-hooks.json",
+]);
 function hooksDirHasPythonFiles(hooksDir) {
     if (!pathExists(hooksDir) || !fs.statSync(hooksDir).isDirectory()) {
         return false;
@@ -81,22 +92,20 @@ export function detectStaleInstalledHooksSurface(appHome) {
     return (installedBundleUsesV2PythonHooks(appHome) ||
         scanInstalledBundleForV2HookInvocations(appHome).length > 0);
 }
-export function retireInstalledV2Hooks(appHome) {
-    const removed = [];
-    for (const hooksDir of listInstalledHookDirs(appHome)) {
-        fs.rmSync(hooksDir, { recursive: true, force: true });
-        removed.push(path.relative(resolvePath(appHome), hooksDir) || "hooks");
-    }
-    return removed;
-}
-function retireItemStatus(stale) {
-    return stale ? "pending" : "noop";
-}
 export function planInstalledHooksRetirementItems(ctx) {
     const appHome = resolvePath(ctx.appHome);
+    const roots = doctorRoots(appHome);
+    if (!hasBundleRootEvidence(roots.activeBundleRoot)) {
+        return [{
+                status: "noop",
+                action: RETIRE_INSTALLED_HOOKS_ACTION,
+                runtime: "installed-app",
+                source: appHome,
+                message: "installed hooks preserved because managed bundle ownership is unproven",
+            }];
+    }
     const hookDirs = listInstalledHookDirs(appHome);
-    const invocationHits = scanInstalledBundleForV2HookInvocations(appHome);
-    const stale = hookDirs.length > 0 || invocationHits.length > 0;
+    const stale = hookDirs.length > 0 || scanInstalledBundleForV2HookInvocations(appHome).length > 0;
     if (!stale) {
         return [
             {
@@ -110,25 +119,24 @@ export function planInstalledHooksRetirementItems(ctx) {
     }
     const items = [];
     for (const hooksDir of hookDirs) {
-        items.push({
-            status: "pending",
-            action: RETIRE_INSTALLED_HOOKS_ACTION,
-            runtime: "installed-app",
-            source: hooksDir,
-            target: appHome,
-            message: `will retire v2 Python hooks at ${path.relative(appHome, hooksDir) || "hooks"}`,
-            removedPreview: fs.readdirSync(hooksDir).filter((name) => name.endsWith(".py")),
-        });
-    }
-    if (invocationHits.length > 0) {
-        items.push({
-            status: retireItemStatus(true),
-            action: RETIRE_INSTALLED_HOOKS_ACTION,
-            runtime: "installed-app",
-            source: appHome,
-            message: `will remove installed bundle files still invoking uv run hooks/*.py (${invocationHits.join(", ")})`,
-            removedPreview: invocationHits,
-        });
+        for (const name of fs.readdirSync(hooksDir).filter((entry) => V2_INSTALLED_HOOK_FILES.has(entry))) {
+            const source = path.join(hooksDir, name);
+            const item = {
+                status: "pending",
+                action: RETIRE_INSTALLED_HOOKS_ACTION,
+                runtime: "installed-app",
+                source,
+                target: appHome,
+                message: `will retire marker-owned v2 installed hook ${path.relative(appHome, source)}`,
+                removedPreview: [path.relative(appHome, source)],
+            };
+            const evidenceError = bindMigrationResource(item, "source", source, [appHome], "file");
+            if (evidenceError) {
+                item.status = "blocked";
+                item.message = `installed hook preserved: ${evidenceError}; review the unsafe path manually`;
+            }
+            items.push(item);
+        }
     }
     return items;
 }
@@ -138,19 +146,18 @@ export function applyInstalledHooksRetirementItems(items, ctx) {
         return;
     }
     try {
-        const removed = retireInstalledV2Hooks(ctx.appHome);
+        for (const item of pending)
+            verifyBoundMigrationResource(item, "source");
         for (const item of pending) {
+            removeBoundMigrationResource(item, "source");
             item.status = "applied";
-            item.message =
-                removed.length > 0
-                    ? `retired v2 Python hooks (${removed.join(", ")})`
-                    : "retired v2 Python hook invocations from installed bundle";
+            item.message = `retired v2 installed hook ${path.relative(resolvePath(ctx.appHome), item.source)}`;
         }
     }
     catch (exc) {
         for (const item of pending) {
-            item.status = "failed";
-            item.message = `${RETIRE_INSTALLED_HOOKS_ACTION} failed: ${exc.message}`;
+            item.status = "blocked";
+            item.message = `installed hook preserved: ${exc.message}; rerun migration and review it manually`;
         }
     }
 }
@@ -187,4 +194,3 @@ export function installedBundleHasV2HookInvocationText(appHome) {
 export function isV2HookScript(filePath) {
     return isFile(filePath) && filePath.endsWith(".py") && filePath.includes(`${path.sep}hooks${path.sep}`);
 }
-//# sourceMappingURL=installedHooksRetirement.js.map