agentera 3.0.0-dev.7 → 3.0.0-dev.74

package/dist/upgrade/runtimeMigration.js

@@ -1,16 +1,11 @@
 import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
+import { createHash } from "node:crypto";
 import { isFile, pathExists, resolvePath } from "../core/paths.js";
-import { AGENTERA_PROFILE_DIR_ENV, PROFILERA_PROFILE_DIR_ENV } from "../core/envPaths.js";
-import { resolveSourceRoot } from "../core/sourceRoot.js";
-import { registryModelPath } from "../registries/artifactRegistry.js";
-import { loadRegistry } from "../registries/runtimeAdapterRegistry.js";
-import { codexCopiedHooksAreAgenteraOnly, codexPluginHooksEnabled, retireCodexCopiedHookTrust, } from "../setup/codex.js";
-import { hasManagedMarker, opencodeCommandTemplate, opencodeConfigDir, } from "../setup/opencode.js";
-import { resolveUpdateChannel } from "./channels.js";
-import { applyInstalledHooksRetirementItems, planInstalledHooksRetirementItems, textReferencesV2InstalledHooks, } from "./installedHooksRetirement.js";
-import { projectUsesV3CapabilityInstructionModules } from "./v3CapabilitySurface.js";
+import { hasManagedMarker, opencodeConfigDir, } from "../setup/opencode.js";
+import { OPENCODE_SKILL_NAMES } from "../setup/opencodeConstants.js";
+import { doctorRoots } from "./appModel.js";
+import { bindMigrationResource, removeBoundMigrationResource, verifyBoundMigrationResource, } from "./migrationPublication.js";
 const PYTHON_MANAGED_PATTERNS = [
     /hooks\/validate_artifact\.py/,
     /hooks\/cursor_session_start\.py/,
@@ -26,15 +21,6 @@ const PYTHON_MANAGED_PATTERNS = [
     /cursor_pre_tool_use\.py/,
     /cursor_session_stop\.py/,
 ];
-const RUNTIME_MIGRATION_ACTIONS = new Set([
-    "rewire-runtime",
-    "rewire-env-var",
-    "retire-hooks",
-    "copy-plugin",
-    "copy-agent",
-    "copy-command",
-    "link-skill",
-]);
 export function projectHasProjectLevelRuntimeHooks(project) {
     const root = resolvePath(project);
     const candidates = [
@@ -46,382 +32,234 @@ export function projectHasProjectLevelRuntimeHooks(project) {
     return candidates.some((candidate) => isFile(candidate) || pathExists(candidate));
 }
 const OPENCODE_COMMAND_NAMES = ["agentera"];
-const OPENCODE_SKILL_NAMES = ["agentera", "status"];
-const CURSOR_AGENT_MARKER = "<!-- agentera: managed -->";
-export function resolveNpxHookCommands(ctx) {
-    const env = ctx.env ?? process.env;
-    const home = ctx.home ?? env.HOME ?? os.homedir();
-    const sourceRoot = ctx.sourceRoot ?? resolveSourceRoot(env);
-    const channel = resolveUpdateChannel({
-        channel: ctx.channel ?? null,
-        env,
-        home,
-        sourceRoot,
-    });
-    const cliEntrypoint = channel.updateCommand.trim();
-    return {
-        cliEntrypoint,
-        validate: `${cliEntrypoint} hook validate-artifact`,
-        cursorSessionStart: `${cliEntrypoint} hook cursor-session-start`,
-        cursorSessionStop: `${cliEntrypoint} hook session-stop`,
-        cursorPreTool: `${cliEntrypoint} hook cursor-pre-tool-use`,
-    };
-}
 export function textUsesPythonManagedEntrypoint(text) {
     if (/AGENTERA_HOME\s*=/.test(text)) {
         return true;
     }
     return PYTHON_MANAGED_PATTERNS.some((pattern) => pattern.test(text));
 }
-const V3_NPX_ENTRYPOINT = /\bnpx\s+-y\s+agentera\b/;
-export function textUsesV3NpmEntrypoint(text) {
-    return V3_NPX_ENTRYPOINT.test(text);
-}
-export function textUsesProfileraProfileDir(text) {
-    return text.includes(PROFILERA_PROFILE_DIR_ENV);
-}
-export function rewireRuntimeText(text, runtime, commands) {
-    let next = text;
-    next = next.replace(/uv run\s+\\?"?\$\{AGENTERA_HOME\}\/hooks\/validate_artifact\.py\\?"?/g, commands.validate);
-    next = next.replace(/uv run\s+\\?"?\$\{AGENTERA_HOME\}\/app\/hooks\/validate_artifact\.py\\?"?/g, commands.validate);
-    next = next.replace(/uv run\s+\\?"?\$\{PLUGIN_ROOT\}\/hooks\/validate_artifact\.py\\?"?/g, commands.validate);
-    next = next.replace(/uv run\s+hooks\/validate_artifact\.py/g, commands.validate);
-    if (next.includes("validate_artifact.py")) {
-        next = next.replace(/["']?[^"'\n]*hooks\/validate_artifact\.py[^"'\n]*["']?/g, `"${commands.validate}"`);
+const RETIRED_NPX_HOOK = /\bnpx\s+-y\s+agentera(?:@(?:next|latest))?\s+hook\s+/;
+const V2_AGENTERA_HOOK = /(?:\buv(?:x|\s+run)\b[^"'\n]*(?:\$\{(?:AGENTERA_HOME|PLUGIN_ROOT)\}|hooks\/)\/[^"'\n]*\.py|\$\{AGENTERA_HOME\}\/(?:app\/scripts|(?:app\/)?hooks)\/[^"'\n]*\.py)/;
+function retiredHookCommands(value, commands = []) {
+    if (Array.isArray(value)) {
+        for (const entry of value)
+            retiredHookCommands(entry, commands);
     }
-    next = next.replace(/["']?[^"'\n]*cursor_session_start\.py[^"'\n]*["']?/g, `"${commands.cursorSessionStart}"`);
-    next = next.replace(/["']?[^"'\n]*cursor_pre_tool_use\.py[^"'\n]*["']?/g, `"${commands.cursorPreTool}"`);
-    next = next.replace(/["']?[^"'\n]*cursor_session_stop\.py[^"'\n]*["']?/g, `"${commands.cursorSessionStop}"`);
-    next = next.replace(/["']?[^"'\n]*\/app\/scripts\/agentera[^"'\n]*["']?/g, `"${commands.cliEntrypoint}"`);
-    next = next.replace(/["']?[^"'\n]*scripts\/agentera[^"'\n]*["']?/g, `"${commands.cliEntrypoint}"`);
-    next = next.replace(/npx -y agentera hook /g, `${commands.cliEntrypoint} hook `);
-    next = next.replace(/npx -y agentera@latest hook /g, `${commands.cliEntrypoint} hook `);
-    if (runtime === "codex") {
-        next = next.replace(/AGENTERA_HOME\s*=\s*"[^"]*"/g, "");
-        next = next.replace(/AGENTERA_HOME\s*=\s*'[^']*'/g, "");
-        next = next.replace(/set\s*=\s*\{\s*,/g, "set = {");
-        next = next.replace(/,\s*,/g, ",");
-        next = next.replace(/,\s*\}/g, " }");
-        next = next.replace(/set\s*=\s*\{\s*\}/g, "set = { }");
+    else if (value !== null && typeof value === "object") {
+        for (const [key, entry] of Object.entries(value)) {
+            if (key === "command" && typeof entry === "string")
+                commands.push(entry);
+            else
+                retiredHookCommands(entry, commands);
+        }
     }
-    return next;
+    return commands;
 }
-export function rewireProfileraEnvVar(text) {
-    return text.replaceAll(PROFILERA_PROFILE_DIR_ENV, AGENTERA_PROFILE_DIR_ENV);
+function isRetiredAgenteraHookCommand(command) {
+    return V2_AGENTERA_HOOK.test(command) || RETIRED_NPX_HOOK.test(command);
 }
-function needsChannelNpxRewire(text, cliEntrypoint) {
-    if (/npx -y agentera hook /.test(text) && !text.includes(cliEntrypoint)) {
-        return true;
+/**
+ * Native hook files have no durable per-entry ownership record. Remove only a
+ * file whose every command is a retired Agentera invocation; mixed files are
+ * preserved for the owner to review rather than surgically rewritten.
+ */
+export function wholeResourceProvesV2HookOwnership(text) {
+    let document;
+    try {
+        document = JSON.parse(text);
     }
-    if (/npx -y agentera@latest hook /.test(text) && !text.includes(cliEntrypoint)) {
-        return true;
+    catch {
+        return false;
     }
-    return false;
+    const commands = retiredHookCommands(document);
+    return commands.length > 0 && commands.every(isRetiredAgenteraHookCommand);
 }
-function pushRewireItem(items, runtime, filePath, commands) {
-    const text = fs.readFileSync(filePath, "utf8");
-    const needsBare = needsChannelNpxRewire(text, commands.cliEntrypoint);
-    if (!textUsesPythonManagedEntrypoint(text) && !textReferencesV2InstalledHooks(text) && !needsBare) {
-        if (textUsesV3NpmEntrypoint(text)) {
-            items.push({
-                status: "noop",
-                action: "rewire-runtime",
-                runtime,
-                source: filePath,
-                message: "runtime config already references npm self-contained entrypoint",
-            });
-        }
-        else {
-            items.push({
-                status: "blocked",
-                action: "rewire-runtime",
-                runtime,
-                source: filePath,
-                message: "runtime config has neither v2 Python patterns nor v3 npm entrypoint; manual review needed",
-            });
-        }
-        return;
-    }
-    const newText = rewireRuntimeText(text, runtime, commands);
-    const status = newText === text ? "blocked" : "pending";
-    items.push({
-        status,
-        action: "rewire-runtime",
-        runtime,
-        source: filePath,
-        target: filePath,
-        newText,
-        message: status === "pending"
-            ? "will rewire runtime config from Python managed app-home to npm self-contained entrypoint"
-            : "runtime config uses Python managed paths but could not be rewritten safely",
-    });
+function textContainsRetiredAgenteraHook(text) {
+    return textUsesPythonManagedEntrypoint(text) || RETIRED_NPX_HOOK.test(text);
 }
-function pushEnvVarRewireItem(items, runtime, filePath) {
+function pushRetireHookItem(items, runtime, filePath, allowedRoot) {
     const text = fs.readFileSync(filePath, "utf8");
-    if (!textUsesProfileraProfileDir(text)) {
+    if (!textContainsRetiredAgenteraHook(text)) {
         return;
     }
-    const newText = rewireProfileraEnvVar(text);
-    const status = newText === text ? "noop" : "pending";
-    items.push({
-        status,
-        action: "rewire-env-var",
+    const item = {
+        status: wholeResourceProvesV2HookOwnership(text) ? "pending" : "blocked",
+        action: "retire-hooks",
         runtime,
         source: filePath,
-        target: filePath,
-        newText,
-        message: status === "pending"
-            ? "will rewire PROFILERA_PROFILE_DIR to AGENTERA_PROFILE_DIR"
-            : "PROFILERA_PROFILE_DIR reference already migrated",
-    });
-}
-function hasCursorManagedAgentMarker(text) {
-    return text.includes(CURSOR_AGENT_MARKER);
-}
-function copyIfChanged(source, target) {
-    if (!isFile(source)) {
-        return false;
+        message: wholeResourceProvesV2HookOwnership(text)
+            ? "will remove whole-resource-proven retired Agentera hook"
+            : "retired Agentera hook preserved: complete resource ownership is unproven; review and remove it manually",
+    };
+    if (item.status === "blocked") {
+        items.push(item);
+        return;
     }
-    if (isFile(target)) {
-        const before = fs.readFileSync(source);
-        const after = fs.readFileSync(target);
-        if (before.equals(after)) {
-            return false;
-        }
+    const evidenceError = bindMigrationResource(item, "source", filePath, [allowedRoot], "file");
+    if (evidenceError) {
+        item.status = "blocked";
+        item.message = `retired Agentera hook preserved: ${evidenceError}; review the unsafe path manually`;
     }
-    fs.mkdirSync(path.dirname(target), { recursive: true });
-    fs.copyFileSync(source, target);
-    return true;
+    items.push(item);
 }
-function planCodexItems(items, home, project, commands, force) {
+function planCodexItems(items, home, project) {
     for (const root of [project, home]) {
         const hooksPath = path.join(root, ".codex", "hooks", "codex-hooks.json");
-        const configPath = path.join(root, ".codex", "config.toml");
         if (isFile(hooksPath)) {
-            pushRewireItem(items, "codex", hooksPath, commands);
-        }
-        if (isFile(configPath)) {
-            pushRewireItem(items, "codex", configPath, commands);
-            const configText = fs.readFileSync(configPath, "utf8");
-            const pluginHooks = codexPluginHooksEnabled(configText);
-            if (pluginHooks && isFile(hooksPath)) {
-                let hooksText;
-                try {
-                    hooksText = fs.readFileSync(hooksPath, "utf8");
-                }
-                catch {
-                    hooksText = "";
-                }
-                if (codexCopiedHooksAreAgenteraOnly(hooksText)) {
-                    items.push({
-                        status: "pending",
-                        action: "retire-hooks",
-                        runtime: "codex",
-                        source: hooksPath,
-                        target: configPath,
-                        message: "will remove Agentera-owned copied Codex hooks because plugin hooks are enabled",
-                    });
-                }
-                else if (hooksText.includes("validate_artifact") || hooksText.includes("hook validate-artifact")) {
-                    items.push({
-                        status: force ? "pending" : "blocked",
-                        action: "retire-hooks",
-                        runtime: "codex",
-                        source: hooksPath,
-                        target: configPath,
-                        message: "plugin hooks are enabled, but copied hook target needs manual review before retirement",
-                    });
-                }
-            }
+            pushRetireHookItem(items, "codex", hooksPath, root);
         }
     }
 }
-function planCursorItems(items, home, project, sourceRoot, commands) {
-    for (const hooksPath of [
-        path.join(project, ".cursor", "hooks.json"),
-        path.join(home, ".cursor", "hooks.json"),
+function planCursorItems(items, home, project) {
+    for (const [root, hooksPath] of [
+        [project, path.join(project, ".cursor", "hooks.json")],
+        [home, path.join(home, ".cursor", "hooks.json")],
     ]) {
         if (isFile(hooksPath)) {
-            pushRewireItem(items, "cursor", hooksPath, commands);
+            pushRetireHookItem(items, "cursor", hooksPath, root);
         }
     }
-    const agentsSource = path.join(sourceRoot, ".cursor", "agents");
-    const pluginSource = path.join(sourceRoot, ".cursor-plugin", "plugin.json");
-    for (const root of [project]) {
-        const agentsDir = path.join(root, ".cursor", "agents");
-        if (isFile(pluginSource) && root === project) {
-            const pluginTarget = path.join(root, ".cursor-plugin", "plugin.json");
-            if (!isFile(pluginTarget)) {
-                items.push({
-                    status: "pending",
-                    action: "copy-plugin",
-                    runtime: "cursor",
-                    source: pluginSource,
-                    target: pluginTarget,
-                    message: "will copy managed Cursor plugin manifest",
-                });
-            }
-            else if (!fs.readFileSync(pluginSource).equals(fs.readFileSync(pluginTarget))) {
-                items.push({
-                    status: "pending",
-                    action: "copy-plugin",
-                    runtime: "cursor",
-                    source: pluginSource,
-                    target: pluginTarget,
-                    message: "will refresh managed Cursor plugin manifest",
-                });
-            }
+}
+function symlinkOwnership(linkPath, managedSkillsRoot) {
+    let stat;
+    let target;
+    try {
+        stat = fs.lstatSync(linkPath);
+        if (!stat.isSymbolicLink())
+            return null;
+        target = fs.readlinkSync(linkPath);
+    }
+    catch {
+        return null;
+    }
+    const resolvedTarget = path.resolve(path.dirname(linkPath), target);
+    const relative = path.relative(managedSkillsRoot, resolvedTarget);
+    if (relative === "" || relative.startsWith("..") || path.isAbsolute(relative))
+        return null;
+    return {
+        kind: "managed-app-symlink",
+        identity: `${stat.dev}:${stat.ino}`,
+        fingerprint: `sha256:${createHash("sha256").update(target).digest("hex")}`,
+        root: managedSkillsRoot,
+    };
+}
+export function planStaleCommandCleanupItems(ctx, items) {
+    const env = ctx.env ?? process.env;
+    const home = resolvePath(ctx.home);
+    const commandsDir = path.join(opencodeConfigDir(home, env), "commands");
+    if (!pathExists(commandsDir) || !fs.statSync(commandsDir).isDirectory()) {
+        return;
+    }
+    const currentNames = new Set(OPENCODE_COMMAND_NAMES);
+    for (const entry of fs.readdirSync(commandsDir)) {
+        if (!entry.endsWith(".md")) {
+            continue;
         }
-        const skipInTreeCursorAgents = root === project && projectUsesV3CapabilityInstructionModules(project);
-        if (skipInTreeCursorAgents) {
-            items.push({
-                status: "skipped",
-                action: "copy-agent",
-                runtime: "cursor",
-                target: agentsDir,
-                message: "v3 capability instruction modules present; in-tree .cursor/agents/ uses prime --context and is not overwritten",
-            });
+        const filePath = path.join(commandsDir, entry);
+        if (!isFile(filePath)) {
+            continue;
         }
-        else if (pathExists(agentsSource)) {
-            const CURSOR_MANAGED_AGENT = "agentera.md";
-            const src = path.join(agentsSource, CURSOR_MANAGED_AGENT);
-            if (isFile(src)) {
-                const dst = path.join(agentsDir, CURSOR_MANAGED_AGENT);
-                if (!isFile(dst)) {
-                    items.push({
-                        status: "pending",
-                        action: "copy-agent",
-                        runtime: "cursor",
-                        source: src,
-                        target: dst,
-                        message: "will copy managed Cursor Agentera agent",
-                    });
-                }
-                else {
-                    const dstText = fs.readFileSync(dst, "utf8");
-                    const srcText = fs.readFileSync(src, "utf8");
-                    if (hasCursorManagedAgentMarker(dstText) && dstText !== srcText) {
-                        items.push({
-                            status: "pending",
-                            action: "copy-agent",
-                            runtime: "cursor",
-                            source: src,
-                            target: dst,
-                            message: "will refresh stale managed Cursor Agentera agent",
-                        });
-                    }
-                }
-            }
+        const body = fs.readFileSync(filePath, "utf8");
+        if (!hasManagedMarker(body)) {
+            continue;
+        }
+        const name = entry.slice(0, -3);
+        if (currentNames.has(name)) {
+            continue;
+        }
+        const item = {
+            status: "pending",
+            action: "remove-stale-command",
+            runtime: "opencode",
+            source: filePath,
+            message: `will remove stale managed command ${path.basename(filePath)}`,
+        };
+        const evidenceError = bindMigrationResource(item, "source", filePath, [home], "file");
+        if (evidenceError) {
+            item.status = "blocked";
+            item.message = `stale command preserved: ${evidenceError}; review the unsafe path manually`;
         }
+        items.push(item);
     }
 }
-function planOpencodeItems(items, home, sourceRoot, env, commands) {
-    const configDir = opencodeConfigDir(home, env);
-    const pluginSource = path.join(sourceRoot, ".opencode", "plugins", "agentera.js");
-    const pluginTarget = path.join(configDir, "plugins", "agentera.js");
-    if (isFile(pluginSource)) {
-        const needsCopy = !isFile(pluginTarget) ||
-            textUsesPythonManagedEntrypoint(fs.readFileSync(pluginTarget, "utf8")) ||
-            needsChannelNpxRewire(fs.readFileSync(pluginTarget, "utf8"), commands.cliEntrypoint);
+export function planStaleSkillCleanupItems(ctx, items) {
+    const env = ctx.env ?? process.env;
+    const home = resolvePath(ctx.home);
+    const skillsDir = path.join(opencodeConfigDir(home, env), "skills");
+    let skillsDirectory;
+    try {
+        skillsDirectory = fs.lstatSync(skillsDir);
+    }
+    catch {
+        return;
+    }
+    if (!skillsDirectory.isDirectory()) {
         items.push({
-            status: needsCopy ? "pending" : "noop",
-            action: "copy-plugin",
+            status: "blocked",
+            action: "remove-stale-skill",
             runtime: "opencode",
-            source: pluginSource,
-            target: pluginTarget,
-            message: needsCopy
-                ? "will copy current Agentera OpenCode plugin to native plugin path"
-                : "OpenCode plugin already current at native plugin path",
+            source: skillsDir,
+            message: `preserved ${skillsDir}: the legacy skills path is not a real directory; replace the unsafe path or review it manually`,
         });
+        return;
     }
-    const commandsSourceDir = path.join(sourceRoot, ".opencode", "commands");
-    const commandsTargetDir = path.join(configDir, "commands");
-    for (const name of OPENCODE_COMMAND_NAMES) {
-        const src = path.join(commandsSourceDir, `${name}.md`);
-        const expected = opencodeCommandTemplate(name);
-        const dst = path.join(commandsTargetDir, `${name}.md`);
-        if (isFile(src)) {
-            const needsCopy = !isFile(dst) || (hasManagedMarker(fs.readFileSync(dst, "utf8")) && fs.readFileSync(dst, "utf8") !== expected);
-            items.push({
-                status: needsCopy ? "pending" : "noop",
-                action: "copy-command",
-                runtime: "opencode",
-                source: src,
-                target: dst,
-                message: needsCopy ? "will sync managed OpenCode command" : "OpenCode managed command already current",
-            });
-        }
-    }
-    const agentsSourceDir = path.join(sourceRoot, ".opencode", "agents");
-    const agentsTargetDir = path.join(configDir, "agents");
-    const OPENCODE_MANAGED_AGENT = "agentera.md";
-    if (pathExists(agentsSourceDir)) {
-        const src = path.join(agentsSourceDir, OPENCODE_MANAGED_AGENT);
-        if (isFile(src)) {
-            const dst = path.join(agentsTargetDir, OPENCODE_MANAGED_AGENT);
-            const needsCopy = !isFile(dst) || !fs.readFileSync(src).equals(fs.readFileSync(dst));
-            items.push({
-                status: needsCopy ? "pending" : "noop",
-                action: "copy-agent",
-                runtime: "opencode",
-                source: src,
-                target: dst,
-                message: needsCopy ? "will copy managed OpenCode Agentera agent" : "OpenCode Agentera agent already current",
-            });
-        }
-    }
-    const skillsSourceRoot = path.join(sourceRoot, "skills");
-    const skillsTargetDir = path.join(configDir, "skills");
-    for (const name of OPENCODE_SKILL_NAMES) {
-        const src = path.join(skillsSourceRoot, name);
-        const dst = path.join(skillsTargetDir, name);
-        if (!isFile(path.join(src, "SKILL.md"))) {
+    const requiredNames = new Set(OPENCODE_SKILL_NAMES);
+    const managedSkillsRoot = path.join(doctorRoots(resolvePath(ctx.appHome)).activeBundleRoot, "skills");
+    for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+        const linkPath = path.join(skillsDir, entry.name);
+        if (!entry.isSymbolicLink()) {
+            if (requiredNames.has(entry.name)) {
+                items.push({
+                    status: "blocked",
+                    action: "remove-stale-skill",
+                    runtime: "opencode",
+                    source: linkPath,
+                    message: `preserved ${linkPath}: name and directory shape do not prove Agentera ownership; review and remove it manually if appropriate`,
+                });
+            }
             continue;
         }
-        if (!pathExists(dst)) {
+        let linkTarget;
+        try {
+            linkTarget = fs.readlinkSync(linkPath);
+        }
+        catch {
             items.push({
-                status: "pending",
-                action: "link-skill",
+                status: "blocked",
+                action: "remove-stale-skill",
                 runtime: "opencode",
-                source: src,
-                target: dst,
-                message: "will create OpenCode skill link",
+                source: linkPath,
+                message: `preserved ${linkPath}: the symlink target could not be inspected; review the unsafe resource manually`,
             });
             continue;
         }
-        try {
-            const linkTarget = fs.readlinkSync(dst);
-            if (!linkTarget.includes("agentera") && path.basename(linkTarget) !== name) {
+        const ownership = symlinkOwnership(linkPath, managedSkillsRoot);
+        if (!ownership) {
+            if (requiredNames.has(entry.name) || linkTarget.toLowerCase().includes("agentera")) {
                 items.push({
                     status: "blocked",
-                    action: "link-skill",
-                    runtime: "opencode",
-                    source: src,
-                    target: dst,
-                    message: "OpenCode skill path is user-owned; manual review required",
-                });
-            }
-            else if (path.resolve(path.dirname(dst), linkTarget) !== path.resolve(src)) {
-                items.push({
-                    status: "pending",
-                    action: "link-skill",
+                    action: "remove-stale-skill",
                     runtime: "opencode",
-                    source: src,
-                    target: dst,
-                    message: "will update stale Agentera-managed OpenCode skill link",
+                    source: linkPath,
+                    message: `preserved ${linkPath}: skill name or target text does not prove Agentera ownership; confirm ownership and remove it manually if appropriate`,
                 });
             }
+            continue;
         }
-        catch {
-            items.push({
-                status: "pending",
-                action: "link-skill",
-                runtime: "opencode",
-                source: src,
-                target: dst,
-                message: "will replace non-symlink OpenCode skill path with managed link",
-            });
+        const item = {
+            status: "pending",
+            action: "remove-stale-skill",
+            runtime: "opencode",
+            source: linkPath,
+            ownership,
+            message: `will remove v2 app-owned OpenCode skill symlink ${entry.name}`,
+        };
+        const evidenceError = bindMigrationResource(item, "source", linkPath, [home], "symlink");
+        if (evidenceError) {
+            item.status = "blocked";
+            item.message = `legacy skill preserved: ${evidenceError}; review the unsafe path manually`;
         }
+        items.push(item);
     }
 }
 function walkJsonHookFiles(dir) {
@@ -444,10 +282,10 @@ function walkJsonHookFiles(dir) {
     walk(dir);
     return out;
 }
-function planCopilotItems(items, project, commands) {
+function planCopilotItems(items, project) {
     const hooksDir = path.join(project, ".github", "hooks");
     for (const hookFile of walkJsonHookFiles(hooksDir)) {
-        pushRewireItem(items, "copilot", hookFile, commands);
+        pushRetireHookItem(items, "copilot", hookFile, project);
     }
     if (!items.some((item) => item.runtime === "copilot")) {
         items.push({
@@ -458,37 +296,6 @@ function planCopilotItems(items, project, commands) {
         });
     }
 }
-function planEnvRuntimeNoops(items, runtime, message) {
-    if (!items.some((item) => item.runtime === runtime)) {
-        items.push({ status: "noop", action: "configure", runtime, message });
-    }
-}
-function planEnvVarRewireItems(ctx, items) {
-    const home = resolvePath(ctx.home);
-    const project = resolvePath(ctx.project);
-    const env = ctx.env;
-    const configDir = opencodeConfigDir(home, env);
-    const candidates = [
-        { runtime: "opencode", filePath: path.join(configDir, "plugins", "agentera.js") },
-        { runtime: "cursor", filePath: path.join(project, ".cursor", "hooks.json") },
-        { runtime: "cursor", filePath: path.join(home, ".cursor", "hooks.json") },
-        { runtime: "codex", filePath: path.join(home, ".codex", "config.toml") },
-        { runtime: "codex", filePath: path.join(home, ".codex", "hooks", "codex-hooks.json") },
-        { runtime: "installed-app", filePath: path.join(project, ".agentera", "docs.yaml") },
-        { runtime: "installed-app", filePath: path.join(ctx.appHome, ".agentera", "docs.yaml") },
-        { runtime: "installed-app", filePath: registryModelPath(ctx.appHome) },
-        { runtime: "installed-app", filePath: registryModelPath(path.join(ctx.appHome, "app")) },
-    ];
-    const hooksDir = path.join(project, ".github", "hooks");
-    for (const hookFile of walkJsonHookFiles(hooksDir)) {
-        candidates.push({ runtime: "copilot", filePath: hookFile });
-    }
-    for (const { runtime, filePath } of candidates) {
-        if (!isFile(filePath))
-            continue;
-        pushEnvVarRewireItem(items, runtime, filePath);
-    }
-}
 export function planRuntimeMigrationItems(ctx) {
     if (!ctx.env) {
         throw new Error("MigrationContext.env is required for runtime migration planning; pass sandboxMigrationEnv(home, sourceRoot) in tests or an explicit env in callers.");
@@ -496,124 +303,126 @@ export function planRuntimeMigrationItems(ctx) {
     const home = resolvePath(ctx.home);
     const project = resolvePath(ctx.project);
     const env = ctx.env;
-    const sourceRoot = resolvePath(ctx.sourceRoot ?? resolveSourceRoot(env));
-    const commands = resolveNpxHookCommands({ ...ctx, home, env, sourceRoot });
     const items = [];
-    planCodexItems(items, home, project, commands, ctx.force);
-    planCursorItems(items, home, project, sourceRoot, commands);
-    planOpencodeItems(items, home, sourceRoot, env, commands);
-    planCopilotItems(items, project, commands);
-    planEnvVarRewireItems(ctx, items);
-    const hookRetirement = planInstalledHooksRetirementItems(ctx).filter((item) => item.status === "pending");
-    if (hookRetirement.length > 0 && items.some((item) => item.action === "rewire-runtime" && item.status === "pending")) {
-        items.push(...hookRetirement);
-    }
-    planEnvRuntimeNoops(items, "claude", "Claude Code plugin installs expose the app home without local config writes; use --update-packages to refresh marketplace surfaces");
-    planEnvRuntimeNoops(items, "cursor-agent", "Cursor Agent CLI inherits workspace Cursor hooks; no separate managed install surface");
-    void loadRegistry();
+    planCodexItems(items, home, project);
+    planCursorItems(items, home, project);
+    planStaleCommandCleanupItems(ctx, items);
+    planStaleSkillCleanupItems(ctx, items);
+    planCopilotItems(items, project);
     return items;
 }
-export function applyRuntimeMigrationItem(item, commands) {
+const RUNTIME_MIGRATION_ACTIONS = new Set([
+    "retire-hooks",
+    "remove-stale-command",
+    "remove-stale-skill",
+]);
+function isRuntimeMigrationAction(action) {
+    return RUNTIME_MIGRATION_ACTIONS.has(action);
+}
+export function applyRuntimeMigrationItem(item) {
     if (item.status !== "pending") {
         return;
     }
     try {
         switch (item.action) {
-            case "rewire-runtime": {
-                if (!item.target || item.newText === undefined) {
+            case "retire-hooks": {
+                if (!item.source) {
                     item.status = "failed";
-                    item.message = "rewire-runtime missing target or newText";
+                    item.message = "retire-hooks missing source";
                     return;
                 }
-                fs.writeFileSync(item.target, item.newText, "utf8");
+                verifyBoundMigrationResource(item, "source");
+                removeBoundMigrationResource(item, "source");
                 item.status = "applied";
-                item.message = "runtime config rewired to npm self-contained entrypoint";
+                item.message = "retired whole-resource-proven Agentera hook";
                 break;
             }
-            case "rewire-env-var": {
-                if (!item.target || item.newText === undefined) {
+            case "remove-stale-command": {
+                if (!item.source) {
                     item.status = "failed";
-                    item.message = "rewire-env-var missing target or newText";
+                    item.message = "remove-stale-command missing source";
                     return;
                 }
-                fs.writeFileSync(item.target, item.newText, "utf8");
-                item.status = "applied";
-                item.message = "rewired PROFILERA_PROFILE_DIR to AGENTERA_PROFILE_DIR";
-                break;
-            }
-            case "copy-plugin":
-            case "copy-agent":
-            case "copy-command": {
-                if (!item.source || !item.target) {
-                    item.status = "failed";
-                    item.message = `${item.action} missing source or target`;
-                    return;
+                if (!pathExists(item.source)) {
+                    item.status = "noop";
+                    item.message = `stale command already absent at ${item.source}`;
+                }
+                else {
+                    removeBoundMigrationResource(item, "source");
+                    item.status = "applied";
+                    item.message = `removed stale managed command ${path.basename(item.source)}`;
                 }
-                copyIfChanged(item.source, item.target);
-                item.status = "applied";
-                item.message = `applied ${item.action}`;
                 break;
             }
-            case "link-skill": {
-                if (!item.source || !item.target) {
+            case "remove-stale-skill": {
+                if (!item.source) {
                     item.status = "failed";
-                    item.message = "link-skill missing source or target";
+                    item.message = "remove-stale-skill missing source";
                     return;
                 }
-                fs.mkdirSync(path.dirname(item.target), { recursive: true });
-                // lstat (not stat): stat follows symlinks and ENOENTs on dangling links; rmSync then fails.
-                let targetStat = null;
                 try {
-                    targetStat = fs.lstatSync(item.target);
-                }
-                catch {
-                    /* target absent */
-                }
-                if (targetStat) {
-                    if (targetStat.isSymbolicLink()) {
-                        fs.unlinkSync(item.target);
+                    const stat = fs.lstatSync(item.source);
+                    if (stat.isSymbolicLink()) {
+                        const target = fs.readlinkSync(item.source);
+                        const identity = `${stat.dev}:${stat.ino}`;
+                        const fingerprint = `sha256:${createHash("sha256").update(target).digest("hex")}`;
+                        const resolvedTarget = path.resolve(path.dirname(item.source), target);
+                        const relative = item.ownership?.root
+                            ? path.relative(item.ownership.root, resolvedTarget)
+                            : "..";
+                        if (item.ownership?.kind !== "managed-app-symlink"
+                            || item.ownership.identity !== identity
+                            || item.ownership.fingerprint !== fingerprint
+                            || relative === ""
+                            || relative.startsWith("..")
+                            || path.isAbsolute(relative)) {
+                            item.status = "blocked";
+                            item.message = `preserved ${item.source}: authoritative symlink ownership changed or is missing; rerun migration and review the resource`;
+                            break;
+                        }
+                        removeBoundMigrationResource(item, "source");
+                        item.status = "applied";
+                        item.message = `removed stale skill symlink ${path.basename(item.source)}`;
                     }
                     else {
-                        fs.rmSync(item.target, { recursive: true, force: true });
+                        item.status = "blocked";
+                        item.message = `preserved ${item.source}: only a fingerprinted v2 app-owned symlink is eligible; review it manually`;
                     }
                 }
-                fs.symlinkSync(item.source, item.target);
-                item.status = "applied";
-                item.message = "OpenCode skill link created";
-                break;
-            }
-            case "retire-hooks": {
-                if (!item.source) {
-                    item.status = "failed";
-                    item.message = "retire-hooks missing source";
-                    return;
-                }
-                if (isFile(item.source)) {
-                    fs.rmSync(item.source, { force: true });
-                }
-                if (item.target && isFile(item.target)) {
-                    const configText = fs.readFileSync(item.target, "utf8");
-                    const next = retireCodexCopiedHookTrust(configText, item.source);
-                    fs.writeFileSync(item.target, next, "utf8");
+                catch (error) {
+                    if (error.code === "ENOENT") {
+                        item.status = "noop";
+                        item.message = "stale skill already absent";
+                    }
+                    else {
+                        item.status = "failed";
+                        item.message = `remove-stale-skill failed: ${error.message}`;
+                    }
                 }
-                item.status = "applied";
-                item.message = "retired Agentera-owned copied Codex hooks";
                 break;
             }
             default:
+                item.status = "failed";
+                item.message = `unsupported runtime migration action: ${item.action}`;
                 break;
         }
     }
     catch (exc) {
-        item.status = "failed";
-        item.message = `${item.action} failed: ${exc.message}`;
+        item.status = "blocked";
+        item.message = `${item.action} preserved the resource: ${exc.message}; rerun migration and review it manually`;
     }
 }
-export function applyRuntimeMigrationItems(items, ctx) {
-    const commands = resolveNpxHookCommands(ctx);
+export function applyRuntimeMigrationItems(items, _ctx) {
     for (const item of items) {
-        applyRuntimeMigrationItem(item, commands);
+        if (item.status !== "pending") {
+            continue;
+        }
+        if (isRuntimeMigrationAction(item.action)) {
+            applyRuntimeMigrationItem(item);
+        }
+        else {
+            item.status = "failed";
+            item.message = `unsupported runtime migration action: ${item.action}`;
+        }
     }
-    applyInstalledHooksRetirementItems(items, ctx);
 }
-//# sourceMappingURL=runtimeMigration.js.map