@lesliechan721/aw 0.1.0-beta.8 → 0.1.0-beta.9

package/dist/src/commands/rebuild-integration.js

@@ -1,17 +1,18 @@
 import crypto from 'node:crypto';
+import os from 'node:os';
 import path from 'node:path';
 import fs from 'fs-extra';
 import { generateAgentArtifacts } from '../generators/agents.js';
-import { extractCodexHookGroups } from '../generators/hooks.js';
 import { generateInstructionArtifacts, renderCodexManagedInstructionBlock, } from '../generators/instructions.js';
 import { generateCodexPermissionArtifacts, mergeClaudePermissions, } from '../generators/permissions.js';
 import { buildGeneratedName } from '../generators/shared.js';
-import { applyConditionalCodexConfigTransactionFile, applyCodexConfigTransactionFile, composeManagedDeveloperInstructionsBlock, readCodexConfigFile, readRenderedCodexMcpServersFile, } from '../utils/codex-config.js';
+import { applyConditionalCodexConfigTransactionFile, applyCodexConfigTransactionFile, composeManagedDeveloperInstructionsBlock, readCodexConfigFile, } from '../utils/codex-config.js';
+import { canonicalizePathThroughExistingAncestor } from '../utils/state-paths.js';
 import { createCodexSkillExpectedTree, createCodexSkillStagingTreeContentDigest, } from '../utils/codex-skill-staging.js';
 import { createDynamicSkillExpectedTree, createDynamicSkillTreeContentDigest, skillDirectoryMatchesExpectedTree, validateSkillDirectory, writeDynamicSkillTree, } from '../utils/dynamic-skill-tree.js';
-import { parseCodexSharedHooksFile, renderTrackedHookGroupIdentity, resolvePlatformHookDefinitions, serializeTrackedHookGroupIdentity, } from '../utils/hooks-contract.js';
-import { buildCodexMarketplaceAddInvocation, buildCodexMarketplaceListInvocation, buildCodexMarketplaceRemoveInvocation, buildCodexPluginAddInvocation, buildCodexPluginListInvocation, buildCodexPluginRemoveInvocation, runNativeCliChecked, } from '../utils/native-cli.js';
-import { OWNED_TEXT_HEADER_PREFIX, createSharedOwnerToken, createSkillOwnerMarkerContent, parseSharedOwnerToken, parseOwnedTextHeader, readSkillOwnerMarker, inspectOwnedComponents, writeOwnedTextFile, } from '../utils/ownership.js';
+import { parseCodexSharedHooksFile, serializeTrackedHookGroupIdentity, } from '../utils/hooks-contract.js';
+import { buildCodexMarketplaceAddInvocation, buildCodexMarketplaceListInvocation, buildCodexMarketplaceRemoveInvocation, buildCodexPluginAddInvocation, buildCodexPluginListInvocation, buildCodexProjectPluginListInvocations, buildCodexPluginRemoveInvocation, postcheckCodexProjectPluginActivation, runNativeCliChecked, } from '../utils/native-cli.js';
+import { OWNED_TEXT_HEADER_PREFIX, createSharedOwnerToken, parseSharedOwnerToken, parseOwnedTextHeader, readSkillOwnerMarker, inspectOwnedComponents, writeOwnedTextFile, } from '../utils/ownership.js';
 import { resolveArtifactRenderConfig, runArtifactRenderer } from '../utils/artifact-renderer.js';
 import { validateArtifactPlan } from '../utils/artifact-plan.js';
 import { createAwPluginRequirementsReceipt, readPluginManifest, } from '../utils/manifest.js';
@@ -23,11 +24,13 @@ import { readCatalogSourcesConfigSnapshot } from '../utils/catalog-sources.js';
 import { getNamespacedMarketplaceName, projectMarketplaceManifestForPlatform, replayNamespacedCodexSkillOverlays, } from '../utils/local-marketplace.js';
 import { cleanupOrphanNamespacedMarketplaceRoot, commitMarketplaceGenerationBackup, } from '../utils/orphan-marketplace-cleanup.js';
 import { readClaudeSettings, writeClaudeSettings } from '../adapters/helpers.js';
-import { requiresCodexNativePlugin } from '../utils/codex-project-surface.js';
+import { analyzeCodexSurface } from '../utils/codex-surface-analysis.js';
+import { inspectCodexSharedNative, } from '../utils/codex-shared-native.js';
+import { calculateCodexSharedNativePayloadDigest } from '../utils/catalog-digests.js';
 import { assertCanonicalProjectManagedRoots } from '../utils/project-boundary.js';
 import { findCodexRoleNameConflict, resolveCodexRoleNamespace, } from '../utils/codex-roles.js';
 const MARKETPLACE_NAME = 'aw';
-const MCP_OWNER_ENV = 'AW_AGENT_WORKFLOWS_OWNER';
+const LEGACY_MCP_OWNER_ENV = 'AW_AGENT_WORKFLOWS_OWNER';
 function requirementsReceipt(plugin) {
     const receipt = createAwPluginRequirementsReceipt({ name: plugin.manifest.name, version: plugin.manifest.version }, plugin.manifest.requires?.aw.capabilities ?? []);
     return Buffer.from(`${JSON.stringify(receipt, null, 2)}\n`, 'utf8');
@@ -38,6 +41,112 @@ function requireCodexManager(manager) {
     }
     return manager;
 }
+export async function executeCodexReconcileActivations(options) {
+    const byScope = {
+        user: { upserts: {}, removals: new Set() },
+        project: { upserts: {}, removals: new Set() },
+    };
+    for (const plan of options.plans) {
+        for (const scope of ['user', 'project']) {
+            for (const action of plan.activationActions[scope]) {
+                if (action.action === 'enable' || action.action === 'disable') {
+                    byScope[scope].upserts[action.codexPluginId] = action.desired;
+                    byScope[scope].removals.delete(action.codexPluginId);
+                }
+                else if (action.action === 'remove') {
+                    byScope[scope].removals.add(action.codexPluginId);
+                }
+            }
+        }
+        for (const removal of plan.staleActivationRemovals) {
+            if (!Object.hasOwn(byScope[removal.scope].upserts, removal.codexPluginId)) {
+                byScope[removal.scope].removals.add(removal.codexPluginId);
+            }
+        }
+    }
+    for (const scope of ['user', 'project']) {
+        const enables = Object.fromEntries(Object.entries(byScope[scope].upserts)
+            .filter(([, desired]) => desired));
+        if (Object.keys(enables).length === 0)
+            continue;
+        const configPath = resolveCodexPaths(options.cwd, scope, options.env).configTomlPath;
+        await applyCodexConfigTransactionFile(configPath, { upsertPluginActivations: enables });
+        const enabledConfig = await readCodexConfigFile(configPath);
+        for (const pluginId of Object.keys(enables)) {
+            if (enabledConfig.snapshot.plugins[pluginId]?.enabled !== true) {
+                throw new Error(`codexActivationPostcheckFailed: ${pluginId} ${scope} activation was not enabled before obsolete activation removal.`);
+            }
+        }
+    }
+    for (const scope of ['user', 'project']) {
+        const transaction = byScope[scope];
+        const disables = Object.fromEntries(Object.entries(transaction.upserts)
+            .filter(([, desired]) => !desired));
+        if (Object.keys(disables).length === 0 && transaction.removals.size === 0)
+            continue;
+        await applyCodexConfigTransactionFile(resolveCodexPaths(options.cwd, scope, options.env).configTomlPath, {
+            ...(transaction.removals.size > 0
+                ? { removePluginActivations: [...transaction.removals].sort() }
+                : {}),
+            ...(Object.keys(disables).length > 0
+                ? { upsertPluginActivations: disables }
+                : {}),
+        });
+    }
+    const [userConfig, projectConfig] = await Promise.all([
+        readCodexConfigFile(resolveCodexPaths(options.cwd, 'user', options.env).configTomlPath),
+        readCodexConfigFile(resolveCodexPaths(options.cwd, 'project', options.env).configTomlPath),
+    ]);
+    for (const plan of options.plans) {
+        for (const scope of ['user', 'project']) {
+            const snapshot = scope === 'user' ? userConfig.snapshot : projectConfig.snapshot;
+            for (const action of plan.activationActions[scope]) {
+                const actual = snapshot.plugins[action.codexPluginId]?.enabled;
+                const expected = action.desired
+                    ? true
+                    : action.action === 'disable' || actual === false ? false : undefined;
+                if (actual !== expected) {
+                    throw new Error(`codexActivationPostcheckFailed: ${action.codexPluginId} ${scope} activation is ${String(actual)}; expected ${String(expected)}.`);
+                }
+            }
+            for (const removal of plan.staleActivationRemovals.filter((entry) => entry.scope === scope)) {
+                if (snapshot.plugins[removal.codexPluginId]?.enabled !== undefined) {
+                    throw new Error(`codexActivationPostcheckFailed: stale ${removal.codexPluginId} ${scope} activation remains.`);
+                }
+            }
+        }
+    }
+    const observedProjectChecks = options.plans.flatMap((plan) => plan.postcheck.support === 'observed'
+        ? plan.postcheck.plugins.filter((plugin) => plugin.neutralCwdRequired)
+        : []);
+    if (observedProjectChecks.length === 0)
+        return;
+    const manager = requireCodexManager(options.manager);
+    const neutralCwd = await fs.mkdtemp(path.join(os.tmpdir(), 'aw-codex-postcheck-'));
+    try {
+        const invocations = buildCodexProjectPluginListInvocations(manager, {
+            exactCwd: options.cwd,
+            neutralCwd,
+            env: options.env,
+        });
+        const [exactResult, neutralResult] = await Promise.all([
+            runNativeCliChecked(invocations.exact, options.runner),
+            runNativeCliChecked(invocations.neutral, options.runner),
+        ]);
+        for (const plugin of observedProjectChecks) {
+            postcheckCodexProjectPluginActivation({
+                pluginId: plugin.codexPluginId,
+                userEnabled: plugin.expectedUserEnabled,
+                projectEnabled: plugin.expectedProjectEnabled,
+                exactResult,
+                neutralResult,
+            });
+        }
+    }
+    finally {
+        await fs.remove(neutralCwd);
+    }
+}
 const CODEX_REMOVE_RECOVERY = 'Codex residue was retained. Retry cleanup or uninstall, upgrade AW, or install a compatible official Codex CLI.';
 function ownerIdentity(plugin, artifactKey, platform, scope) {
     return { owner: 'agent-workflows', plugin, artifactKey, platform, scope };
@@ -202,84 +311,85 @@ function createCodexInstructionComponent(options) {
         },
     };
 }
-function codexMcpOwner(actual) {
-    const envValue = actual?.value?.env;
-    return envValue
-        && typeof envValue === 'object'
-        && !Array.isArray(envValue)
-        && typeof envValue[MCP_OWNER_ENV] === 'string'
-        ? envValue[MCP_OWNER_ENV]
-        : null;
+function createCodexActivationComponent(options) {
+    return {
+        kind: 'shared-config',
+        identity: options.identity,
+        label: `${options.configPath}#plugins.${options.codexPluginId}.enabled`,
+        inspect: async () => {
+            const plugin = (await readCodexConfigFile(options.configPath))
+                .snapshot.plugins[options.codexPluginId];
+            return plugin?.enabled === options.desired ? 'present' : 'absent';
+        },
+        remove: async () => {
+            await applyCodexConfigTransactionFile(options.configPath, {
+                removePluginActivations: [options.codexPluginId],
+            });
+        },
+    };
 }
-function createCodexMcpComponent(options) {
-    const ownerKey = createSharedOwnerToken(options.identity);
+function createCodexActivationCleanupComponent(options) {
     return {
         kind: 'shared-config',
         identity: options.identity,
-        label: `${options.configPath}#mcp_servers.${options.serverKey}`,
+        label: `${options.configPath}#plugins.${options.codexPluginId}.enabled`,
         inspect: async () => {
-            const config = await readCodexConfigFile(options.configPath);
-            const actual = config.snapshot.mcpServers[options.serverKey];
-            if (!actual)
-                return 'absent';
-            return codexMcpOwner(actual) === ownerKey ? 'present' : 'foreign';
+            const actual = (await readCodexConfigFile(options.configPath))
+                .snapshot.plugins[options.codexPluginId]?.enabled;
+            return options.disposition === 'remove'
+                ? actual === undefined ? 'absent' : 'present'
+                : actual === true ? 'present' : 'absent';
         },
         remove: async () => {
             await applyConditionalCodexConfigTransactionFile(options.configPath, (snapshot) => {
-                const actual = snapshot.mcpServers[options.serverKey];
-                return codexMcpOwner(actual) === ownerKey
-                    ? { removeMcpServers: [options.serverKey] }
+                const actual = snapshot.plugins[options.codexPluginId]?.enabled;
+                if (options.disposition === 'remove') {
+                    return actual === undefined
+                        ? null
+                        : { removePluginActivations: [options.codexPluginId] };
+                }
+                return actual === true
+                    ? { upsertPluginActivations: { [options.codexPluginId]: false } }
                     : null;
             });
         },
     };
 }
-async function codexRoleRegistrationOwned(options) {
-    if (!options.registration?.configFile)
-        return false;
-    const expected = path.normalize(path.relative(path.dirname(options.configPath), options.rolePath));
-    const actual = path.normalize(path.relative(path.dirname(options.configPath), path.resolve(path.dirname(options.configPath), options.registration.configFile)));
-    if (actual !== expected)
-        return false;
-    const raw = await fs.readFile(options.rolePath, 'utf8').catch(() => '');
-    try {
-        return Boolean(parseOwnedTextHeader(raw, options.fileIdentity));
-    }
-    catch {
-        return false;
-    }
+function legacyCodexMcpOwner(actual) {
+    const envValue = actual?.value?.env;
+    return envValue
+        && typeof envValue === 'object'
+        && !Array.isArray(envValue)
+        && typeof envValue[LEGACY_MCP_OWNER_ENV] === 'string'
+        ? envValue[LEGACY_MCP_OWNER_ENV]
+        : null;
 }
-function createCodexRoleRegistrationComponent(options) {
-    const inspect = async () => {
-        const config = await readCodexConfigFile(options.configPath);
-        const registration = config.snapshot.agents[options.roleKey];
-        if (!registration)
-            return 'absent';
-        return await codexRoleRegistrationOwned({ ...options, registration })
-            ? 'present'
-            : 'foreign';
-    };
+function createLegacyCodexMcpCleanupComponent(options) {
+    const ownerKey = createSharedOwnerToken(options.identity);
     return {
         kind: 'shared-config',
         identity: options.identity,
-        label: `${options.configPath}#agents.${options.roleKey}`,
-        inspect,
+        label: `${options.configPath}#mcp_servers.${options.serverKey}`,
+        inspect: async () => {
+            const actual = (await readCodexConfigFile(options.configPath))
+                .snapshot.mcpServers[options.serverKey];
+            if (!actual)
+                return 'absent';
+            return legacyCodexMcpOwner(actual) === ownerKey ? 'present' : 'foreign';
+        },
         remove: async () => {
-            await applyConditionalCodexConfigTransactionFile(options.configPath, async (snapshot) => {
-                const registration = snapshot.agents[options.roleKey];
-                return await codexRoleRegistrationOwned({ ...options, registration })
-                    ? { removeAgentRegistrations: [options.roleKey] }
-                    : null;
-            });
+            await applyConditionalCodexConfigTransactionFile(options.configPath, (snapshot) => legacyCodexMcpOwner(snapshot.mcpServers[options.serverKey]) === ownerKey
+                ? { removeMcpServers: [options.serverKey] }
+                : null);
         },
     };
 }
-async function readCodexHooks(hooksPath) {
+async function readLegacyCodexHooks(hooksPath) {
     if (!await fs.pathExists(hooksPath))
         return parseCodexSharedHooksFile({ hooks: {} });
     return parseCodexSharedHooksFile(await fs.readJson(hooksPath));
 }
-function renderCodexHookGroups(groups) {
+function renderLegacyCodexHookGroups(groups) {
     const hooks = {};
     for (const group of groups) {
         hooks[group.event] ??= [];
@@ -287,16 +397,15 @@ function renderCodexHookGroups(groups) {
     }
     return `${JSON.stringify({ hooks }, null, 2)}\n`;
 }
-export async function applyCodexHookGroupsTransactionFile(hooksPath, update, testHooks) {
+async function applyLegacyCodexHookCleanupTransactionFile(hooksPath, update) {
     return withConfigFileMutation({
         filePath: hooksPath,
         allowedRoot: path.dirname(hooksPath),
         action: async () => {
-            const parsed = await readCodexHooks(hooksPath);
+            const parsed = await readLegacyCodexHooks(hooksPath);
             const groups = update(parsed);
             if (!groups)
                 return false;
-            await testHooks?.beforeCommit?.();
             if (groups.length === 0) {
                 await atomicRemoveConfigFile({
                     filePath: hooksPath,
@@ -307,40 +416,27 @@ export async function applyCodexHookGroupsTransactionFile(hooksPath, update, tes
                 await atomicReplaceConfigFile({
                     filePath: hooksPath,
                     allowedRoot: path.dirname(hooksPath),
-                    content: renderCodexHookGroups(groups),
+                    content: renderLegacyCodexHookGroups(groups),
                 });
             }
             return true;
         },
     });
 }
-function renderCodexSharedHookGroup(identity) {
-    const rendered = renderTrackedHookGroupIdentity(identity);
-    const rawGroup = {
-        ...(rendered.matcher === undefined ? {} : { matcher: rendered.matcher }),
-        hooks: rendered.hooks,
-    };
-    return {
-        event: rendered.event,
-        matcher: rendered.matcher,
-        hooks: rendered.hooks,
-        rawGroup,
-    };
-}
-function createCodexHookComponent(options) {
+function createLegacyCodexHookCleanupComponent(options) {
     const serialized = serializeTrackedHookGroupIdentity(options.identity);
     return {
         kind: 'shared-config',
         identity: ownerIdentity(options.pluginName, internalArtifactKey('hook', serialized), 'codex', options.scope),
         label: `${options.hooksPath}#${serialized}`,
         inspect: async () => {
-            const parsed = await readCodexHooks(options.hooksPath);
+            const parsed = await readLegacyCodexHooks(options.hooksPath);
             return parsed.managedIdentities.some((entry) => serializeTrackedHookGroupIdentity(entry) === serialized)
                 ? 'present'
                 : 'absent';
         },
         remove: async () => {
-            await applyCodexHookGroupsTransactionFile(options.hooksPath, (parsed) => {
+            await applyLegacyCodexHookCleanupTransactionFile(options.hooksPath, (parsed) => {
                 let removed = false;
                 const remaining = parsed.groups.flatMap((entry) => {
                     if (!removed
@@ -356,19 +452,44 @@ function createCodexHookComponent(options) {
         },
     };
 }
-function ownedCodexHookIdentity(options) {
-    const artifactKey = internalArtifactKey('hook', serializeTrackedHookGroupIdentity(options.identity));
-    const identity = {
-        ...ownerIdentity(options.pluginName, artifactKey, 'codex', options.scope),
-        ...(options.sourceId ? {
-            sourceId: options.sourceId,
-            sourceIdentity: options.sourceIdentity,
-            pluginId: options.pluginId,
-        } : {}),
+async function codexRoleRegistrationOwned(options) {
+    if (!options.registration?.configFile)
+        return false;
+    const expected = path.normalize(path.relative(path.dirname(options.configPath), options.rolePath));
+    const actual = path.normalize(path.relative(path.dirname(options.configPath), path.resolve(path.dirname(options.configPath), options.registration.configFile)));
+    if (actual !== expected)
+        return false;
+    const raw = await fs.readFile(options.rolePath, 'utf8').catch(() => '');
+    try {
+        return Boolean(parseOwnedTextHeader(raw, options.fileIdentity));
+    }
+    catch {
+        return false;
+    }
+}
+function createCodexRoleRegistrationComponent(options) {
+    const inspect = async () => {
+        const config = await readCodexConfigFile(options.configPath);
+        const registration = config.snapshot.agents[options.roleKey];
+        if (!registration)
+            return 'absent';
+        return await codexRoleRegistrationOwned({ ...options, registration })
+            ? 'present'
+            : 'foreign';
     };
     return {
-        ...options.identity,
-        command: `${OWNED_TEXT_HEADER_PREFIX}${JSON.stringify(JSON.parse(createSkillOwnerMarkerContent(identity)))}\n${options.identity.command}`,
+        kind: 'shared-config',
+        identity: options.identity,
+        label: `${options.configPath}#agents.${options.roleKey}`,
+        inspect,
+        remove: async () => {
+            await applyConditionalCodexConfigTransactionFile(options.configPath, async (snapshot) => {
+                const registration = snapshot.agents[options.roleKey];
+                return await codexRoleRegistrationOwned({ ...options, registration })
+                    ? { removeAgentRegistrations: [options.roleKey] }
+                    : null;
+            });
+        },
     };
 }
 function sameOwnerIdentity(left, right) {
@@ -381,17 +502,6 @@ function sameOwnerIdentity(left, right) {
         && left.platform === right.platform
         && left.scope === right.scope;
 }
-function readOwnedHookIdentity(identity, scope) {
-    try {
-        const parsed = parseOwnedTextHeader(identity.command);
-        return parsed?.identity.platform === 'codex' && parsed.identity.scope === scope
-            ? parsed.identity
-            : null;
-    }
-    catch {
-        return null;
-    }
-}
 function sharedOwnerPluginName(value) {
     return parseSharedOwnerToken(value)?.plugin ?? value;
 }
@@ -415,7 +525,6 @@ async function scanCodexSharedComponents(options) {
         remove: async () => undefined,
     });
     const containsOwnedEvidence = (raw) => raw.includes(options.pluginName) && (raw.includes('[[aw-managed:start plugin=')
-        || raw.includes(MCP_OWNER_ENV)
         || raw.includes(OWNED_TEXT_HEADER_PREFIX)
         || raw.includes('agent-workflows'));
     if (options.scanConfig) {
@@ -437,24 +546,6 @@ async function scanCodexSharedComponents(options) {
                 configPath: options.paths.configTomlPath,
             }));
         }
-        for (const [serverKey, server] of Object.entries(config?.snapshot.mcpServers ?? {})) {
-            const envValue = server.value?.env;
-            if (envValue
-                && typeof envValue === 'object'
-                && !Array.isArray(envValue)
-                && parseSharedOwnerToken(String(envValue[MCP_OWNER_ENV]))?.pluginId === options.pluginId) {
-                const identity = expectedIdentity(internalArtifactKey('mcp', serverKey));
-                if (createSharedOwnerToken(identity) !== envValue[MCP_OWNER_ENV])
-                    continue;
-                output.push(createCodexMcpComponent({
-                    identity,
-                    scope: options.scope,
-                    configPath: options.paths.configTomlPath,
-                    serverKey,
-                    owned: true,
-                }));
-            }
-        }
         for (const [roleKey, registration] of Object.entries(config?.snapshot.agents ?? {})) {
             if (!registration.configFile)
                 continue;
@@ -479,28 +570,6 @@ async function scanCodexSharedComponents(options) {
             }));
         }
     }
-    if (options.scope === 'project' && options.scanHooks) {
-        const hooks = await readCodexHooks(options.paths.hooksPath).catch(async (error) => {
-            if (!options.ignoreReadErrors)
-                throw error;
-            const raw = await fs.readFile(options.paths.hooksPath, 'utf8').catch(() => '');
-            if (containsOwnedEvidence(raw)) {
-                output.push(corruptedComponent(options.paths.hooksPath, error));
-            }
-            return null;
-        });
-        for (const identity of hooks?.managedIdentities ?? []) {
-            const parsedIdentity = readOwnedHookIdentity(identity, options.scope);
-            if (!parsedIdentity || !sameOwnerIdentity(parsedIdentity, expectedIdentity(parsedIdentity.artifactKey)))
-                continue;
-            output.push(createCodexHookComponent({
-                pluginName: options.pluginName,
-                scope: options.scope,
-                hooksPath: options.paths.hooksPath,
-                identity,
-            }));
-        }
-    }
     return output;
 }
 async function scanClaudeSharedComponents(options) {
@@ -615,14 +684,19 @@ async function preflightCodexWriteSafety(options) {
     const pluginName = options.plugin.manifest.name;
     const userConfigPath = resolveCodexPaths(options.cwd, 'user', options.env).configTomlPath;
     const projectConfigPath = resolveCodexPaths(options.cwd, 'project', options.env).configTomlPath;
+    const nativeSurface = analyzeCodexSurface(options.plugin.manifest).nativeKinds.length > 0;
+    const needsUserConfig = options.scope === 'user'
+        || nativeSurface;
     let userConfig;
-    try {
-        userConfig = await readCodexConfigFile(userConfigPath);
-    }
-    catch (error) {
-        throw new Error(`codexProjectUserConfigUnreadable: 无法解析用户级 Codex 配置 ${userConfigPath}：${error instanceof Error ? error.message : String(error)}`);
+    if (needsUserConfig) {
+        try {
+            userConfig = await readCodexConfigFile(userConfigPath);
+        }
+        catch (error) {
+            throw new Error(`codexProjectUserConfigUnreadable: 无法解析用户级 Codex 配置 ${userConfigPath}：${error instanceof Error ? error.message : String(error)}`);
+        }
     }
-    if (options.scope === 'project') {
+    if (options.scope === 'project' && userConfig) {
         const expectedPluginId = `${pluginName}@${options.plugin.marketplaceName ?? MARKETPLACE_NAME}`;
         for (const [key, plugin] of Object.entries(userConfig.snapshot.plugins)) {
             if (key !== expectedPluginId
@@ -637,7 +711,7 @@ async function preflightCodexWriteSafety(options) {
         && target.target === 'codex.agentRole'
         && target.roleKey)
         .map((target) => target.roleKey));
-    const needsProjectConfig = options.scope === 'project' && Boolean(options.plugin.manifest.mcpServers
+    const needsProjectConfig = options.scope === 'project' && Boolean(nativeSurface
         || resolvePlatformEntries(options.plugin.manifest.extensions?.instructions, 'codex').length > 0
         || (options.plugin.manifest.artifacts?.targets ?? []).some((target) => target.platform === 'codex'
             && target.scopes.includes('project')
@@ -654,7 +728,7 @@ async function preflightCodexWriteSafety(options) {
     if (roleKeys.size === 0)
         return;
     for (const configPath of options.scope === 'project'
-        ? [userConfigPath, projectConfigPath]
+        ? [projectConfigPath]
         : [userConfigPath]) {
         const configScope = configPath === userConfigPath ? 'user' : 'project';
         const ownedRolePaths = [];
@@ -705,33 +779,6 @@ function renderCodexRole(options) {
         '',
     ].join('\n');
 }
-async function resolveCodexMcpServers(plugin, scope) {
-    if (!plugin.manifest.mcpServers)
-        return {};
-    const relative = plugin.manifest.mcpServers.replace(/^\.\//u, '');
-    const direct = path.resolve(plugin.rootDir, relative);
-    const mcpPath = await fs.pathExists(direct)
-        ? direct
-        : path.resolve(plugin.rootDir, 'codex', relative);
-    const servers = await readRenderedCodexMcpServersFile(mcpPath);
-    return Object.fromEntries(Object.entries(servers).map(([key, server]) => {
-        const existingEnv = server.env;
-        if (existingEnv !== undefined && (typeof existingEnv !== 'object' || Array.isArray(existingEnv))) {
-            throw new Error(`MCP server ${key} 的 env 必须是 object。`);
-        }
-        const env = (existingEnv ?? {});
-        const ownerKey = createSharedOwnerToken(pluginOwnerIdentity(plugin, internalArtifactKey('mcp', key), 'codex', scope));
-        if (env[MCP_OWNER_ENV] !== undefined
-            && env[MCP_OWNER_ENV] !== plugin.manifest.name
-            && env[MCP_OWNER_ENV] !== ownerKey) {
-            throw new Error(`MCP server ${key} 不能覆盖保留的 ${MCP_OWNER_ENV} owner marker。`);
-        }
-        return [key, {
-                ...server,
-                env: { ...env, [MCP_OWNER_ENV]: ownerKey },
-            }];
-    }));
-}
 async function resolveDynamicArtifacts(options) {
     const declarations = (options.plugin.manifest.artifacts?.targets ?? []).filter((target) => target.platform === options.platform && target.scopes.includes(options.scope));
     if (declarations.length === 0)
@@ -845,9 +892,7 @@ async function buildBundledCodexSkillWrites(options) {
     const dynamicKeys = new Set((options.plugin.manifest.artifacts?.targets ?? [])
         .filter((target) => target.target === 'codex.skill' && target.skillKey)
         .map((target) => target.skillKey));
-    const targetRoot = options.scope === 'project'
-        ? path.join(options.repoRoot, '.agents', 'skills')
-        : path.join(options.marketplaceRoot ?? resolveAwHome(options.env), 'plugins', options.plugin.manifest.name, ...relativeRoot.split('/'));
+    const targetRoot = await canonicalizePathThroughExistingAncestor(path.join(options.marketplaceRoot ?? resolveAwHome(options.env), 'plugins', options.plugin.manifest.name, ...relativeRoot.split('/')));
     const writes = [];
     for (const entry of await fs.readdir(sourceRoot, { withFileTypes: true })) {
         if (entry.isSymbolicLink()) {
@@ -869,9 +914,9 @@ async function buildBundledCodexSkillWrites(options) {
             sourceRequirementsReceiptPolicy: 'allow',
         });
         const skillPath = path.join(targetRoot, entry.name);
-        const canRecoverPristine = options.scope === 'user'
-            && path.resolve(skillSource) !== path.resolve(skillPath);
-        const identity = ownerIdentity(options.plugin.manifest.name, entry.name, 'codex', options.scope);
+        const canRecoverPristine = await canonicalizePathThroughExistingAncestor(skillSource)
+            !== path.resolve(skillPath);
+        const identity = ownerIdentity(options.plugin.manifest.name, entry.name, 'codex', 'user');
         const component = pathComponent({
             kind: 'skill-directory',
             path: skillPath,
@@ -971,16 +1016,15 @@ async function buildCodexWrites(options) {
     const dynamicRoles = dynamic.artifacts.filter((entry) => entry.target === 'codex.agentRole');
     const dynamicSkills = dynamic.artifacts.filter((entry) => entry.target === 'codex.skill');
     const repoRoot = await resolveRepoRoot(options.cwd);
-    writes.push(...await buildBundledCodexSkillWrites({
-        plugin: options.plugin,
-        scope: options.scope,
-        repoRoot,
-        env: options.env,
-        marketplaceRoot: options.marketplaceRoot,
-    }));
-    const relativeSkillsRoot = await resolveCodexSkillsRelativeRoot(options.plugin);
+    if (options.scope === 'user') {
+        writes.push(...await buildBundledCodexSkillWrites({
+            plugin: options.plugin,
+            env: options.env,
+            marketplaceRoot: options.marketplaceRoot,
+        }));
+    }
     const skillRoot = options.scope === 'user'
-        ? path.join(options.marketplaceRoot ?? resolveAwHome(options.env), 'plugins', options.plugin.manifest.name, ...relativeSkillsRoot.split('/'))
+        ? path.join(getCodexHome(options.env), 'skills')
         : path.join(repoRoot, '.agents', 'skills');
     for (const artifact of dynamicSkills) {
         const tree = await createCodexSkillExpectedTree({
@@ -1002,7 +1046,6 @@ async function buildCodexWrites(options) {
     const staticInstructions = dynamicInstructions.length > 0
         ? []
         : resolvePlatformEntries(options.plugin.manifest.extensions?.instructions, 'codex');
-    const mcpServers = await resolveCodexMcpServers(options.plugin, options.scope);
     const hasInstructionOutput = dynamicInstructions.length > 0 || staticInstructions.length > 0;
     if (hasInstructionOutput) {
         const component = createCodexInstructionComponent({
@@ -1052,34 +1095,6 @@ async function buildCodexWrites(options) {
             });
         }
     }
-    for (const [serverKey, server] of Object.entries(mcpServers)) {
-        const component = createCodexMcpComponent({
-            identity: pluginOwnerIdentity(options.plugin, internalArtifactKey('mcp', serverKey), 'codex', options.scope),
-            scope: options.scope,
-            configPath: paths.configTomlPath,
-            serverKey,
-            owned: false,
-        });
-        writes.push({
-            artifact: {
-                path: paths.configTomlPath,
-                kind: 'mcpServer',
-                platform: 'codex',
-                artifactKey: serverKey,
-            },
-            component,
-            write: async () => {
-                await applyConditionalCodexConfigTransactionFile(paths.configTomlPath, (snapshot) => {
-                    const actual = snapshot.mcpServers[serverKey];
-                    const actualOwner = codexMcpOwner(actual);
-                    if (actual && actualOwner !== createSharedOwnerToken(component.identity)) {
-                        throw new Error(`Codex MCP server "${serverKey}" is foreign and cannot be overwritten by plugin "${options.plugin.manifest.name}".`);
-                    }
-                    return { upsertMcpServers: { [serverKey]: server } };
-                });
-            },
-        });
-    }
     for (const artifact of dynamicRoles) {
         const roleKey = artifact.roleKey;
         const rolePath = path.join(paths.configDir, 'agents', `${buildGeneratedName(options.plugin.manifest.name, roleKey)}.toml`);
@@ -1179,42 +1194,40 @@ async function buildCodexWrites(options) {
             kind: 'agent',
         }));
     }
-    if (options.scope === 'project') {
-        const hooks = resolvePlatformHookDefinitions(options.plugin.manifest, 'codex');
-        for (const rawIdentity of extractCodexHookGroups(hooks)) {
-            const identity = ownedCodexHookIdentity({
-                pluginName: options.plugin.manifest.name,
-                sourceId: options.plugin.sourceId,
-                sourceIdentity: options.plugin.sourceIdentity,
-                pluginId: options.plugin.pluginId,
-                scope: options.scope,
-                identity: rawIdentity,
-            });
-            const component = createCodexHookComponent({
-                pluginName: options.plugin.manifest.name,
-                scope: options.scope,
-                hooksPath: paths.hooksPath,
-                identity,
-            });
-            writes.push({
-                artifact: {
-                    path: paths.hooksPath,
-                    kind: 'hook',
-                    platform: 'codex',
-                    hookGroups: [identity],
-                },
-                component,
-                write: async () => {
-                    await applyCodexHookGroupsTransactionFile(paths.hooksPath, (parsed) => {
-                        const serialized = serializeTrackedHookGroupIdentity(identity);
-                        const exists = parsed.managedIdentities.some((entry) => serializeTrackedHookGroupIdentity(entry) === serialized);
-                        return exists
-                            ? null
-                            : [...parsed.rawGroups, renderCodexSharedHookGroup(identity)];
-                    });
-                },
-            });
-        }
+    const codexPluginId = `${options.plugin.manifest.name}@${options.marketplaceName ?? options.plugin.marketplaceName ?? MARKETPLACE_NAME}`;
+    const nativeSurface = analyzeCodexSurface(options.plugin.manifest).nativeKinds.length > 0;
+    const userActivationDesired = options.scope === 'user'
+        || options.userActivationDesired?.has(codexPluginId) === true;
+    for (const activation of !nativeSurface ? [] : options.scope === 'project'
+        ? [
+            {
+                scope: 'user',
+                desired: userActivationDesired,
+                configPath: resolveCodexPaths(options.cwd, 'user', options.env).configTomlPath,
+            },
+            { scope: 'project', desired: true, configPath: paths.configTomlPath },
+        ]
+        : [{ scope: 'user', desired: true, configPath: paths.configTomlPath }]) {
+        const component = createCodexActivationComponent({
+            identity: pluginOwnerIdentity(options.plugin, internalArtifactKey('activation', activation.scope), 'codex', options.scope),
+            configPath: activation.configPath,
+            codexPluginId,
+            desired: activation.desired,
+        });
+        writes.push({
+            artifact: {
+                path: activation.configPath,
+                kind: 'instruction',
+                platform: 'codex',
+                artifactKey: internalArtifactKey('activation', activation.scope),
+            },
+            component,
+            write: async () => {
+                await applyCodexConfigTransactionFile(activation.configPath, {
+                    upsertPluginActivations: { [codexPluginId]: activation.desired },
+                });
+            },
+        });
     }
     return writes;
 }
@@ -1278,13 +1291,13 @@ async function buildInspectionWrites(options) {
     }
     const paths = resolveCodexPaths(options.cwd, options.scope, options.env);
     const repoRoot = await resolveRepoRoot(options.cwd);
-    writes.push(...await buildBundledCodexSkillWrites({
-        plugin: options.plugin,
-        scope: options.scope,
-        repoRoot,
-        env: options.env,
-        marketplaceRoot: options.marketplaceRoot,
-    }));
+    if (options.scope === 'user') {
+        writes.push(...await buildBundledCodexSkillWrites({
+            plugin: options.plugin,
+            env: options.env,
+            marketplaceRoot: options.marketplaceRoot,
+        }));
+    }
     const instructions = resolvePlatformEntries(options.plugin.manifest.extensions?.instructions, 'codex');
     const targets = (options.plugin.manifest.artifacts?.targets ?? []).filter((target) => target.platform === 'codex' && target.scopes.includes(options.scope));
     const instructionTargets = targets.filter((target) => target.target === 'codex.developerInstructionsBlock');
@@ -1304,28 +1317,8 @@ async function buildInspectionWrites(options) {
             write: async () => undefined,
         });
     }
-    const mcpServers = await resolveCodexMcpServers(options.plugin, options.scope);
-    for (const serverKey of Object.keys(mcpServers)) {
-        writes.push({
-            artifact: {
-                path: paths.configTomlPath,
-                kind: 'mcpServer',
-                platform: 'codex',
-                artifactKey: serverKey,
-            },
-            component: createCodexMcpComponent({
-                identity: pluginOwnerIdentity(options.plugin, internalArtifactKey('mcp', serverKey), 'codex', options.scope),
-                scope: options.scope,
-                configPath: paths.configTomlPath,
-                serverKey,
-                owned: false,
-            }),
-            write: async () => undefined,
-        });
-    }
-    const relativeSkillsRoot = await resolveCodexSkillsRelativeRoot(options.plugin);
     const dynamicSkillRoot = options.scope === 'user'
-        ? path.join(options.marketplaceRoot ?? resolveAwHome(options.env), 'plugins', options.plugin.manifest.name, ...relativeSkillsRoot.split('/'))
+        ? path.join(getCodexHome(options.env), 'skills')
         : path.join(repoRoot, '.agents', 'skills');
     for (const target of targets) {
         const state = target.states.includes('present') ? 'present' : 'disabled';
@@ -1410,32 +1403,35 @@ async function buildInspectionWrites(options) {
             kind: 'agent',
         }));
     }
-    if (options.scope === 'project') {
-        for (const rawIdentity of extractCodexHookGroups(resolvePlatformHookDefinitions(options.plugin.manifest, 'codex'))) {
-            const identity = ownedCodexHookIdentity({
-                pluginName: options.plugin.manifest.name,
-                sourceId: options.plugin.sourceId,
-                sourceIdentity: options.plugin.sourceIdentity,
-                pluginId: options.plugin.pluginId,
-                scope: options.scope,
-                identity: rawIdentity,
-            });
-            writes.push({
-                artifact: {
-                    path: paths.hooksPath,
-                    kind: 'hook',
-                    platform: 'codex',
-                    hookGroups: [identity],
-                },
-                component: createCodexHookComponent({
-                    pluginName: options.plugin.manifest.name,
-                    scope: options.scope,
-                    hooksPath: paths.hooksPath,
-                    identity,
-                }),
-                write: async () => undefined,
-            });
-        }
+    const nativeSurface = analyzeCodexSurface(options.plugin.manifest).nativeKinds.length > 0;
+    const codexPluginId = `${options.plugin.manifest.name}@${options.marketplaceName ?? options.plugin.marketplaceName ?? MARKETPLACE_NAME}`;
+    const userActivationDesired = options.scope === 'user'
+        || options.userActivationDesired?.has(codexPluginId) === true;
+    for (const activation of !nativeSurface ? [] : options.scope === 'project'
+        ? [
+            {
+                scope: 'user',
+                desired: userActivationDesired,
+                configPath: resolveCodexPaths(options.cwd, 'user', options.env).configTomlPath,
+            },
+            { scope: 'project', desired: true, configPath: paths.configTomlPath },
+        ]
+        : [{ scope: 'user', desired: true, configPath: paths.configTomlPath }]) {
+        writes.push({
+            artifact: {
+                path: activation.configPath,
+                kind: 'instruction',
+                platform: 'codex',
+                artifactKey: internalArtifactKey('activation', activation.scope),
+            },
+            component: createCodexActivationComponent({
+                identity: pluginOwnerIdentity(options.plugin, internalArtifactKey('activation', activation.scope), 'codex', options.scope),
+                configPath: activation.configPath,
+                codexPluginId,
+                desired: activation.desired,
+            }),
+            write: async () => undefined,
+        });
     }
     return writes;
 }
@@ -1457,24 +1453,35 @@ async function buildHistoricalComponents(options) {
             continue;
         if (artifact.state === 'disabled')
             continue;
-        if (artifact.kind === 'hook' && options.platform === 'codex') {
+        if (options.platform === 'codex'
+            && artifact.artifactKey !== undefined
+            && new Set([
+                internalArtifactKey('activation', 'user'),
+                internalArtifactKey('activation', 'project'),
+            ]).has(artifact.artifactKey)) {
+            continue;
+        }
+        if (options.command === 'cleanup'
+            && artifact.kind === 'hook'
+            && options.platform === 'codex') {
             for (const identity of artifact.hookGroups ?? []) {
-                components.push(createCodexHookComponent({
+                components.push(createLegacyCodexHookCleanupComponent({
                     pluginName: options.pluginName,
                     scope: options.scope,
-                    hooksPath: resolveCodexPaths(options.cwd, options.scope, options.env).hooksPath,
+                    hooksPath: path.join(resolveCodexPaths(options.cwd, options.scope, options.env).configDir, 'hooks.json'),
                     identity,
                 }));
             }
             continue;
         }
-        if (artifact.kind === 'mcpServer' && options.platform === 'codex' && artifact.artifactKey) {
-            components.push(createCodexMcpComponent({
+        if (options.command === 'cleanup'
+            && artifact.kind === 'mcpServer'
+            && options.platform === 'codex'
+            && artifact.artifactKey) {
+            components.push(createLegacyCodexMcpCleanupComponent({
                 identity: historicalIdentity(internalArtifactKey('mcp', artifact.artifactKey)),
-                scope: options.scope,
                 configPath: resolveCodexPaths(options.cwd, options.scope, options.env).configTomlPath,
                 serverKey: artifact.artifactKey,
-                owned: false,
             }));
             continue;
         }
@@ -1538,7 +1545,7 @@ async function readdirCodexResidueIfPresent(directory) {
     }
     return fs.readdir(directory, { withFileTypes: true });
 }
-async function inspectCodexNativeResidue(options) {
+export async function inspectCodexNativeResidue(options) {
     const marketplaceName = options.marketplaceName ?? MARKETPLACE_NAME;
     const marketplaceRoot = options.marketplaceRoot ?? resolveAwHome(options.env);
     const pluginId = `${options.pluginName}@${marketplaceName}`;
@@ -1626,6 +1633,186 @@ async function inspectCodexNativeResidue(options) {
                 installedVersions: [], cacheVersions: [], enabled: false,
             };
 }
+function isPathWithin(root, candidate) {
+    const relative = path.relative(path.resolve(root), path.resolve(candidate));
+    return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+async function codexPayloadPathSafe(payloadRoot) {
+    const rootStats = await lstatCodexResidueIfPresent(payloadRoot);
+    if (!rootStats?.isDirectory() || rootStats.isSymbolicLink())
+        return false;
+    const pending = [payloadRoot];
+    while (pending.length > 0) {
+        const current = pending.pop();
+        for (const entry of await fs.readdir(current, { withFileTypes: true })) {
+            const entryPath = path.join(current, entry.name);
+            if (entry.isSymbolicLink()) {
+                const target = path.resolve(path.dirname(entryPath), await fs.readlink(entryPath));
+                if (!isPathWithin(payloadRoot, target))
+                    return false;
+            }
+            else if (entry.isDirectory()) {
+                pending.push(entryPath);
+            }
+            else if (!entry.isFile()) {
+                return false;
+            }
+        }
+    }
+    return true;
+}
+/**
+ * Read-only filesystem projection for the payload-aware shared-native classifier.
+ * It does not invoke Codex or create native/config state.
+ */
+export async function inspectCodexSharedNativeLive(options) {
+    const marketplaceName = options.marketplaceName ?? MARKETPLACE_NAME;
+    const marketplaceRoot = options.marketplaceRoot ?? resolveAwHome(options.env);
+    const pluginId = `${options.pluginName}@${marketplaceName}`;
+    const config = await readCodexConfigFile(resolveCodexPaths(options.cwd, 'user', options.env).configTomlPath);
+    const cacheRoot = path.join(getCodexHome(options.env), 'plugins', 'cache', marketplaceName, options.pluginName);
+    const installedManifestPath = path.join(getCodexHome(options.env), 'plugins', pluginId, 'manifest.json');
+    const cacheRootStats = await lstatCodexResidueIfPresent(cacheRoot);
+    let unsafeCachePath = Boolean(cacheRootStats
+        && (!cacheRootStats.isDirectory() || cacheRootStats.isSymbolicLink()));
+    const candidates = [];
+    if (cacheRootStats?.isDirectory() && !cacheRootStats.isSymbolicLink()) {
+        for (const entry of await fs.readdir(cacheRoot, { withFileTypes: true })) {
+            const payloadPath = path.join(cacheRoot, entry.name);
+            if (!entry.isDirectory() || entry.isSymbolicLink()) {
+                unsafeCachePath = true;
+                continue;
+            }
+            const manifestPaths = [
+                path.join(payloadPath, 'plugin.json'),
+                path.join(payloadPath, '.codex-plugin', 'plugin.json'),
+            ];
+            const existingManifestPaths = [];
+            for (const manifestPath of manifestPaths) {
+                const stats = await lstatCodexResidueIfPresent(manifestPath);
+                if (stats)
+                    existingManifestPaths.push(manifestPath);
+            }
+            if (existingManifestPaths.length !== 1) {
+                candidates.push({
+                    version: entry.name,
+                    manifest: existingManifestPaths.length === 0 ? { state: 'absent' } : { state: 'unreadable' },
+                    payloadPath,
+                });
+                continue;
+            }
+            const manifestPath = existingManifestPaths[0];
+            const manifestStats = await lstatCodexResidueIfPresent(manifestPath);
+            if (!manifestStats?.isFile() || manifestStats.isSymbolicLink()) {
+                candidates.push({ version: entry.name, manifest: { state: 'unreadable' }, payloadPath });
+                continue;
+            }
+            let manifest;
+            try {
+                const value = await fs.readJson(manifestPath);
+                if (!value || typeof value !== 'object' || Array.isArray(value))
+                    throw new Error('invalid manifest');
+                manifest = value;
+            }
+            catch {
+                candidates.push({ version: entry.name, manifest: { state: 'unreadable' }, payloadPath });
+                continue;
+            }
+            const pathSafe = await codexPayloadPathSafe(payloadPath);
+            let payloadDigest = options.expectedPayloadDigest;
+            if (pathSafe) {
+                try {
+                    payloadDigest = await calculateCodexSharedNativePayloadDigest(payloadPath);
+                }
+                catch {
+                    candidates.push({ version: entry.name, manifest: { state: 'unreadable' }, payloadPath });
+                    continue;
+                }
+            }
+            candidates.push({
+                version: typeof manifest.version === 'string' ? manifest.version : entry.name,
+                payloadPath,
+                manifest: {
+                    state: 'present',
+                    identity: typeof manifest.id === 'string'
+                        ? manifest.id
+                        : typeof manifest.name === 'string' ? manifest.name : '',
+                    version: typeof manifest.version === 'string' ? manifest.version : '',
+                    payloadDigest,
+                    payloadPath,
+                    pathSafe,
+                },
+            });
+        }
+    }
+    let installedVersion;
+    const installedStats = await lstatCodexResidueIfPresent(installedManifestPath);
+    if (installedStats?.isFile() && !installedStats.isSymbolicLink()) {
+        try {
+            const installed = await fs.readJson(installedManifestPath);
+            if (typeof installed.version === 'string')
+                installedVersion = installed.version;
+        }
+        catch {
+            installedVersion = undefined;
+        }
+    }
+    const selected = candidates.find((candidate) => candidate.version === installedVersion)
+        ?? candidates.find((candidate) => candidate.version === options.desiredVersion)
+        ?? (candidates.length === 1 ? candidates[0] : undefined);
+    const pluginListEntries = candidates.map((candidate) => ({
+        pluginId,
+        enabled: config.snapshot.plugins[pluginId]?.enabled === true,
+        ...(candidate.version ? { version: candidate.version } : {}),
+        path: candidate.payloadPath,
+    }));
+    if (installedStats && pluginListEntries.length === 0) {
+        pluginListEntries.push({
+            pluginId,
+            enabled: config.snapshot.plugins[pluginId]?.enabled === true,
+            ...(installedVersion ? { version: installedVersion } : {}),
+            path: path.dirname(installedManifestPath),
+        });
+    }
+    if (unsafeCachePath && pluginListEntries.length === 0) {
+        pluginListEntries.push({
+            pluginId,
+            enabled: config.snapshot.plugins[pluginId]?.enabled === true,
+            version: options.desiredVersion,
+            path: cacheRoot,
+        });
+    }
+    const manifest = unsafeCachePath
+        ? {
+            state: 'present',
+            identity: pluginId,
+            version: options.desiredVersion,
+            payloadDigest: options.expectedPayloadDigest,
+            payloadPath: cacheRoot,
+            pathSafe: false,
+        }
+        : selected?.manifest ?? { state: 'absent' };
+    const sharedNative = inspectCodexSharedNative({
+        pluginName: options.pluginName,
+        pluginId,
+        marketplaceName,
+        canonicalMarketplaceRoot: marketplaceRoot,
+        desiredVersion: options.desiredVersion,
+        expectedPayloadDigest: options.expectedPayloadDigest,
+        marketplaceRegistration: config.snapshot.marketplaces[marketplaceName],
+        marketplacePathSafe: true,
+        pluginListEntries,
+        manifest,
+        managedByCurrentIntent: options.managedByCurrentIntent && manifest.state === 'present',
+    });
+    return {
+        sharedNative,
+        ...(manifest.state === 'present' ? {
+            actualPayloadDigest: manifest.payloadDigest,
+            payloadPath: manifest.payloadPath,
+        } : {}),
+    };
+}
 export async function codexNativeRemovalRequired(options) {
     const residue = await inspectCodexNativeResidue(options);
     if (residue.state === 'present')
@@ -2457,6 +2644,8 @@ function createNativeDriver(options) {
     const codexManager = options.context.codexManager;
     const mirrorTransactions = new WeakMap();
     const finalizeNamespacedCleanup = async (target) => {
+        if (target.identity.platform === 'codex')
+            return;
         const { sourceId, sourceIdentity, marketplaceRoot, marketplaceName } = target.identity;
         if (!sourceId || !sourceIdentity || !marketplaceRoot)
             return;
@@ -2530,7 +2719,7 @@ function createNativeDriver(options) {
                 });
                 return state.pluginState;
             }
-            if (target.identity.platform === 'codex' && target.identity.scope === 'user') {
+            if (target.identity.platform === 'codex') {
                 const residue = await inspectCodexNativeResidue({
                     pluginName: target.identity.pluginName,
                     cwd: target.identity.cwd,
@@ -2562,7 +2751,7 @@ function createNativeDriver(options) {
                     return state.pluginState;
                 return state.pluginEnabled ? 'present' : 'partial';
             }
-            if (target.identity.platform === 'codex' && target.identity.scope === 'user') {
+            if (target.identity.platform === 'codex') {
                 const residue = await inspectCodexNativeResidue({
                     pluginName: target.identity.pluginName,
                     cwd: target.identity.cwd,
@@ -2572,7 +2761,34 @@ function createNativeDriver(options) {
                 });
                 if (residue.state !== 'present')
                     return residue.state;
-                return residue.enabled ? 'present' : 'partial';
+                if (target.identity.scope !== 'project' || !codexManager)
+                    return 'present';
+                const userConfig = await readCodexConfigFile(resolveCodexPaths(target.identity.cwd, 'user', options.context.env).configTomlPath);
+                const projectConfig = await readCodexConfigFile(resolveCodexPaths(target.identity.cwd, 'project', options.context.env).configTomlPath);
+                const pluginId = `${target.identity.pluginName}@${target.identity.marketplaceName ?? MARKETPLACE_NAME}`;
+                const neutralCwd = await fs.mkdtemp(path.join(os.tmpdir(), 'aw-codex-postcheck-'));
+                try {
+                    const invocations = buildCodexProjectPluginListInvocations(codexManager, {
+                        exactCwd: target.identity.cwd,
+                        neutralCwd,
+                        env: options.context.env,
+                    });
+                    const [exactResult, neutralResult] = await Promise.all([
+                        runNativeCliChecked(invocations.exact, runner),
+                        runNativeCliChecked(invocations.neutral, runner),
+                    ]);
+                    postcheckCodexProjectPluginActivation({
+                        pluginId,
+                        userEnabled: userConfig.snapshot.plugins[pluginId]?.enabled === true,
+                        projectEnabled: projectConfig.snapshot.plugins[pluginId]?.enabled === true,
+                        exactResult,
+                        neutralResult,
+                    });
+                }
+                finally {
+                    await fs.remove(neutralCwd);
+                }
+                return 'present';
             }
             return 'absent';
         },
@@ -2645,6 +2861,21 @@ function createNativeDriver(options) {
                 throw new Error('Missing rebuild integration plan.');
             const marketplaceName = target.identity.marketplaceName ?? MARKETPLACE_NAME;
             const expectedMarketplaceRoot = target.identity.marketplaceRoot ?? resolveAwHome(options.context.env);
+            if (target.identity.platform === 'codex') {
+                const before = await inspectCodexNativeResidue({
+                    pluginName: target.identity.pluginName,
+                    cwd: target.identity.cwd,
+                    env: options.context.env,
+                    marketplaceName,
+                    marketplaceRoot: expectedMarketplaceRoot,
+                });
+                if (before.state === 'foreign') {
+                    throw new Error(`codexSharedNativeForeign: ${before.labels.join(', ')}`);
+                }
+                if (before.state === 'present') {
+                    await runNativeCliChecked(buildCodexPluginRemoveInvocation(requireCodexManager(codexManager), `${target.identity.pluginName}@${marketplaceName}`, target.identity.cwd, options.context.env), runner);
+                }
+            }
             const writeGeneration = async () => {
                 if (mirrorTransactions.has(target)) {
                     throw new Error('Marketplace mirror transaction is already active for this target.');
@@ -2677,18 +2908,22 @@ function createNativeDriver(options) {
                     const marketplaceRoot = mirrored.rootDir;
                     const pluginId = `${target.identity.pluginName}@${marketplaceName}`;
                     if (target.identity.platform === 'codex') {
+                        const nativePluginRoot = await canonicalizePathThroughExistingAncestor(path.join(marketplaceRoot, 'plugins', target.identity.pluginName));
                         const requiredSkillWrites = plan.writes.filter((entry) => !entry.optional
                             && entry.component?.kind === 'skill-directory'
                             && entry.artifact.kind === 'skill'
                             && entry.artifact.state !== 'disabled'
-                            && target.identity.scope === 'user');
+                            && target.identity.scope === 'user'
+                            && !path.relative(nativePluginRoot, entry.component.path).startsWith('..'));
                         for (const write of requiredSkillWrites) {
                             await write.write();
                         }
                         const skillsRelativeRoot = await ensureCodexActiveSkillsManifest({
                             plugin: target.plugin,
                             marketplaceRoot,
-                            hasRequiredSkills: requiredSkillWrites.length > 0,
+                            hasRequiredSkills: target.identity.scope === 'project'
+                                ? target.plugin.manifest.skills !== undefined
+                                : requiredSkillWrites.length > 0,
                         });
                         const config = await readCodexConfigFile(resolveCodexPaths(target.identity.cwd, 'user', options.context.env).configTomlPath);
                         const marketplace = config.snapshot.marketplaces[marketplaceName];
@@ -2796,13 +3031,10 @@ export function createRebuildIntegration(options) {
                     cwd: input.cwd,
                     rootNames: input.platform === 'codex' ? ['.agents', '.codex'] : ['.claude'],
                     managedPaths: input.platform === 'codex'
-                        ? ['.codex/config.toml', '.codex/hooks.json']
+                        ? ['.codex/config.toml']
                         : ['.claude/settings.json'],
                 });
                 input = { ...input, cwd: canonicalRepoRoot };
-                if (materializing && input.platform === 'codex' && input.plugin.manifest.apps) {
-                    throw new Error(`Codex project scope 不支持 apps：${input.plugin.manifest.name}`);
-                }
             }
             if (materializing && input.platform === 'codex') {
                 await preflightCodexWriteSafety({
@@ -2829,9 +3061,15 @@ export function createRebuildIntegration(options) {
                     env: options.context.env,
                     loadPlugin,
                 });
+                if (input.expectedLifecycleMetadataIntegrityDigest !== undefined
+                    && active?.metadata.metadataIntegrityDigest
+                        !== input.expectedLifecycleMetadataIntegrityDigest) {
+                    throw new Error('stateInventoryFailed: lifecycle active generation changed after verified inventory.');
+                }
                 historicalArtifacts = active?.artifacts ?? [];
             }
             let writes = [];
+            let currentRemovalComponents = [];
             if (input.command !== 'cleanup' && input.command !== 'uninstall') {
                 if (input.readOnlyInspectionPlan) {
                     writes = await buildInspectionWrites({
@@ -2841,6 +3079,8 @@ export function createRebuildIntegration(options) {
                         cwd: input.cwd,
                         env: options.context.env,
                         marketplaceRoot: input.marketplaceRoot,
+                        marketplaceName: input.marketplaceName,
+                        userActivationDesired: options.context.codexUserActivationDesired,
                     });
                 }
                 else if (input.platform === 'codex') {
@@ -2850,6 +3090,8 @@ export function createRebuildIntegration(options) {
                         event,
                         historicalArtifacts,
                         scriptTimeoutMs: options.scriptTimeoutMs,
+                        marketplaceName: input.marketplaceName,
+                        userActivationDesired: options.context.codexUserActivationDesired,
                     });
                 }
                 else {
@@ -2862,6 +3104,22 @@ export function createRebuildIntegration(options) {
                     });
                 }
             }
+            else if (input.platform === 'codex' && input.scope === 'project') {
+                const currentRemovalWrites = await buildInspectionWrites({
+                    plugin: input.plugin,
+                    platform: input.platform,
+                    scope: input.scope,
+                    cwd: input.cwd,
+                    env: options.context.env,
+                    marketplaceRoot: input.marketplaceRoot,
+                    marketplaceName: input.marketplaceName,
+                    userActivationDesired: options.context.codexUserActivationDesired,
+                });
+                currentRemovalComponents = currentRemovalWrites.flatMap((write) => [
+                    ...(write.additionalComponents ?? []),
+                    ...(write.component ? [write.component] : []),
+                ]);
+            }
             const desiredComponents = writes.filter((write) => !write.optional).flatMap((write) => [
                 ...(write.additionalComponents ?? []),
                 ...(write.component ? [write.component] : []),
@@ -2889,8 +3147,13 @@ export function createRebuildIntegration(options) {
             })))).flat();
             const skillRoots = input.platform === 'codex'
                 ? input.scope === 'project'
-                    ? [path.join(await resolveRepoRoot(input.cwd), '.agents', 'skills')]
-                    : [path.join(input.marketplaceRoot ?? resolveAwHome(options.context.env), 'plugins', input.plugin.manifest.name)]
+                    ? []
+                    : [
+                        path.join(getCodexHome(options.context.env), 'skills'),
+                        ...(input.preserveCodexSharedNativePayload
+                            ? []
+                            : [await canonicalizePathThroughExistingAncestor(path.join(input.marketplaceRoot ?? resolveAwHome(options.context.env), 'plugins', input.plugin.manifest.name))]),
+                    ]
                 : [path.join(configDir, 'skills')];
             const scanSkills = () => Promise.all(skillRoots.map((root) => scanOwnedSkills({
                 sourceId: input.sourceId,
@@ -2901,7 +3164,7 @@ export function createRebuildIntegration(options) {
                 scope: input.scope,
             })));
             const scannedSkills = (await scanSkills()).flat();
-            const historicalComponents = await buildHistoricalComponents({
+            let historicalComponents = await buildHistoricalComponents({
                 sourceId: input.sourceId,
                 sourceIdentity: input.sourceIdentity,
                 pluginId: input.pluginId,
@@ -2911,7 +3174,24 @@ export function createRebuildIntegration(options) {
                 cwd: input.cwd,
                 env: options.context.env,
                 artifacts: historicalArtifacts,
+                command: input.command,
             });
+            if (input.preserveCodexSharedNativePayload) {
+                const nativePluginRoots = await Promise.all([
+                    path.join(input.marketplaceRoot ?? resolveAwHome(options.context.env), 'plugins', input.plugin.manifest.name),
+                    path.join(getCodexHome(options.context.env), 'plugins', 'cache', input.marketplaceName ?? MARKETPLACE_NAME, input.plugin.manifest.name),
+                ].map((root) => canonicalizePathThroughExistingAncestor(root)));
+                historicalComponents = historicalComponents.filter((component) => {
+                    if (!('path' in component))
+                        return true;
+                    return nativePluginRoots.every((nativePluginRoot) => {
+                        const relative = path.relative(nativePluginRoot, path.resolve(component.path));
+                        return relative === '..'
+                            || relative.startsWith(`..${path.sep}`)
+                            || path.isAbsolute(relative);
+                    });
+                });
+            }
             const sharedComponents = input.platform === 'codex'
                 ? await scanCodexSharedComponents({
                     sourceId: input.sourceId,
@@ -2921,7 +3201,6 @@ export function createRebuildIntegration(options) {
                     scope: input.scope,
                     paths: resolveCodexPaths(input.cwd, input.scope, options.context.env),
                     scanConfig: true,
-                    scanHooks: true,
                     ignoreReadErrors: true,
                 })
                 : await scanClaudeSharedComponents({
@@ -2933,10 +3212,28 @@ export function createRebuildIntegration(options) {
                     settingsPath: resolveClaudePaths(input.cwd, input.scope, options.context.env).settingsPath,
                 });
             const nativeRequired = input.platform === 'claude'
-                || (input.scope === 'user' && requiresCodexNativePlugin(input.plugin, input.scope));
-            const nativeCleanupCandidate = (input.platform === 'claude' || input.scope === 'user')
+                || analyzeCodexSurface(input.plugin.manifest).nativeKinds.length > 0;
+            const nativeDesired = nativeRequired
+                && input.command !== 'cleanup'
+                && input.command !== 'uninstall';
+            const codexNative = input.platform === 'codex' && nativeRequired
+                ? await inspectCodexNativeResidue({
+                    pluginName: input.plugin.manifest.name,
+                    cwd: input.cwd,
+                    env: options.context.env,
+                    marketplaceName: input.marketplaceName,
+                    marketplaceRoot: input.marketplaceRoot,
+                })
+                : undefined;
+            const codexNativeExact = codexNative?.state === 'present'
+                && codexNative.versions.length > 0
+                && codexNative.versions.every((version) => version === input.plugin.manifest.version);
+            const materializeNativeRequired = nativeDesired && (input.platform === 'claude'
+                || input.command === 'reinstall'
+                || !codexNativeExact);
+            const nativeCleanupCandidate = input.platform === 'claude'
                 && input.includeNativeCleanupCandidate !== false;
-            const nativePlugin = (nativeRequired || nativeCleanupCandidate)
+            const nativePlugin = (nativeDesired || nativeCleanupCandidate)
                 ? [{
                         kind: 'native-plugin',
                         identity: ownerIdentity(input.plugin.manifest.name, 'native', input.platform, input.scope),
@@ -2946,7 +3243,7 @@ export function createRebuildIntegration(options) {
             const marketplaceDesired = nativeRequired
                 && input.command !== 'cleanup'
                 && input.command !== 'uninstall';
-            const marketplace = input.platform === 'codex' && input.scope === 'user'
+            const marketplace = input.platform === 'codex' && input.scope === 'user' && nativeDesired
                 ? [createCodexMarketplaceComponent({
                         pluginName: input.plugin.manifest.name,
                         codexManager: options.context.codexManager,
@@ -2969,20 +3266,48 @@ export function createRebuildIntegration(options) {
                             desired: marketplaceDesired,
                         })]
                     : [];
-            if (nativeRequired
-                && input.command !== 'cleanup'
-                && input.command !== 'uninstall')
+            if (nativeDesired)
                 desiredComponents.push(...nativePlugin, ...marketplace);
+            const activationCleanup = input.platform === 'codex'
+                && nativeRequired
+                && (input.command === 'cleanup' || input.command === 'uninstall')
+                ? (input.scope === 'project'
+                    ? [
+                        createCodexActivationComponent({
+                            identity: ownerIdentity(input.plugin.manifest.name, internalArtifactKey('activation', 'project'), 'codex', input.scope),
+                            configPath: resolveCodexPaths(input.cwd, 'project', options.context.env).configTomlPath,
+                            codexPluginId: `${input.plugin.manifest.name}@${input.marketplaceName ?? MARKETPLACE_NAME}`,
+                            desired: true,
+                        }),
+                    ]
+                    : [createCodexActivationComponent({
+                            identity: ownerIdentity(input.plugin.manifest.name, internalArtifactKey('activation', 'user'), 'codex', input.scope),
+                            configPath: resolveCodexPaths(input.cwd, 'user', options.context.env).configTomlPath,
+                            codexPluginId: `${input.plugin.manifest.name}@${input.marketplaceName ?? MARKETPLACE_NAME}`,
+                            desired: true,
+                        })])
+                : [];
+            const explicitActivationCleanup = input.platform === 'codex'
+                ? (input.codexActivationCleanup ?? []).map((activation) => createCodexActivationCleanupComponent({
+                    identity: ownerIdentity(input.plugin.manifest.name, internalArtifactKey('activation', activation.scope), 'codex', input.scope),
+                    configPath: resolveCodexPaths(input.cwd, activation.scope, options.context.env).configTomlPath,
+                    codexPluginId: activation.codexPluginId,
+                    disposition: activation.disposition,
+                }))
+                : [];
             const allComponents = dedupeComponents([
                 ...desiredComponents,
                 ...optionalComponents,
                 ...(input.platform === 'codex' ? sharedComponents : []),
                 ...scannedText,
                 ...scannedSkills,
+                ...currentRemovalComponents,
                 ...historicalComponents,
                 ...(input.platform === 'claude' ? sharedComponents : []),
                 ...nativePlugin,
                 ...marketplace,
+                ...activationCleanup,
+                ...explicitActivationCleanup,
             ]);
             bindNamespacedOwnerIdentity(allComponents, input);
             const desiredKeys = new Set(desiredComponents.map(componentIdentityKey));
@@ -3005,11 +3330,15 @@ export function createRebuildIntegration(options) {
                 ownedComponents: allComponents,
                 desiredOwnedComponents: allComponents.filter((component) => desiredKeys.has(componentIdentityKey(component))),
                 optionalOwnedComponents: allComponents.filter((component) => optionalComponentKeys.has(componentIdentityKey(component))),
-                requiresNative: nativeRequired
-                    && input.command !== 'cleanup'
-                    && input.command !== 'uninstall',
+                requiresNative: nativeDesired,
+                writeNativeRequired: materializeNativeRequired,
                 artifacts: writes.map((write) => write.artifact),
                 lifecycleSource: input.plugin,
+                ...(input.expectedLifecycleMetadataIntegrityDigest
+                    ? {
+                        historicalLifecycleMetadataIntegrityDigest: input.expectedLifecycleMetadataIntegrityDigest,
+                    }
+                    : {}),
             };
             plans.set(target, {
                 catalog: input.catalog,
@@ -3022,7 +3351,13 @@ export function createRebuildIntegration(options) {
     };
 }
 export async function inspectRebuildTarget(options) {
-    const integration = createRebuildIntegration({ context: options.context });
+    const integration = createRebuildIntegration({
+        context: {
+            ...options.context,
+            codexUserActivationDesired: options.userActivationDesired
+                ?? options.context.codexUserActivationDesired,
+        },
+    });
     const target = await integration.buildTarget({
         ...(options.sourceId ? {
             sourceId: options.sourceId,
@@ -3042,7 +3377,9 @@ export async function inspectRebuildTarget(options) {
     });
     const inspection = await inspectOwnedComponents({
         components: target.ownedComponents,
-        nativeProbe: integration.driver.probeNativeHealth ?? integration.driver.probeNative,
+        nativeProbe: options.nativeProbe
+            ?? integration.driver.probeNativeHealth
+            ?? integration.driver.probeNative,
         verifyHealth: true,
     });
     if (!target.requiresNative)
@@ -3141,7 +3478,7 @@ export async function discoverRebuildTargetNames(options) {
             cwd: options.cwd,
             rootNames: options.platform === 'codex' ? ['.agents', '.codex'] : ['.claude'],
             managedPaths: options.platform === 'codex'
-                ? ['.codex/config.toml', '.codex/hooks.json']
+                ? ['.codex/config.toml']
                 : ['.claude/settings.json'],
         });
         options = { ...options, cwd: canonicalRepoRoot };
@@ -3155,7 +3492,7 @@ export async function discoverRebuildTargetNames(options) {
         names.add(name);
     const skillRoots = options.platform === 'codex'
         ? options.scope === 'project'
-            ? [path.join(await resolveRepoRoot(options.cwd), '.agents', 'skills')]
+            ? []
             : [path.join(resolveAwHome(options.env), 'plugins')]
         : [path.join(paths.configDir, 'skills')];
     if (options.platform === 'codex' && options.scope === 'user') {
@@ -3190,24 +3527,14 @@ export async function discoverRebuildTargetNames(options) {
         for (const name of Object.keys(config.snapshot.developerInstructions.managedBlocks)) {
             names.add(sharedOwnerPluginName(name));
         }
-        for (const server of Object.values(config.snapshot.mcpServers)) {
-            const envValue = server.value?.env;
-            const owner = envValue
-                && typeof envValue === 'object'
-                && !Array.isArray(envValue)
-                && typeof envValue[MCP_OWNER_ENV] === 'string'
-                ? envValue[MCP_OWNER_ENV]
-                : null;
-            if (owner)
-                names.add(sharedOwnerPluginName(owner));
-        }
         if (options.scope === 'project') {
-            const hooksPath = resolveCodexPaths(options.cwd, options.scope, options.env).hooksPath;
-            const hooks = await readCodexHooks(hooksPath).catch(() => null);
-            for (const identity of hooks?.managedIdentities ?? []) {
-                const owner = readOwnedHookIdentity(identity, options.scope);
-                if (owner)
-                    names.add(owner.plugin);
+            const suffix = `@${options.marketplaceName ?? MARKETPLACE_NAME}`;
+            for (const pluginId of Object.keys(config.snapshot.plugins)) {
+                if (!pluginId.endsWith(suffix))
+                    continue;
+                const name = pluginId.slice(0, -suffix.length);
+                if (/^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(name))
+                    names.add(name);
             }
         }
         else {