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

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

@@ -1,25 +1,31 @@
 import path from 'node:path';
 import fs from 'fs-extra';
 import { probeAgentVersion } from '../utils/agent-version.js';
+import { previewCodexManager, resolveCodexManager, } from '../utils/codex-manager.js';
 import { createNoopDebugLogger } from '../output/debug-log.js';
 import { createNoopReporter } from '../output/reporter.js';
 import { getDefaultNativeCliRunner } from '../utils/native-cli.js';
-import { readPluginManifest, resolvePluginsFromCatalog } from '../utils/manifest.js';
+import { readPluginManifest } from '../utils/manifest.js';
 import { resolveAwHome } from '../utils/paths.js';
 import { resolveCliPackageRoot } from '../utils/paths.js';
 import { supportsPlatform } from '../utils/platform-support.js';
 import { hasCodexProjectManagedArtifacts } from '../utils/codex-project-surface.js';
-import { createRebuildActiveStore, executeRebuildOperation, releaseRebuildOperationLease, } from './rebuild-operations.js';
-import { assertNoClaudeUnboundNativeNameCollision, createRebuildIntegration, discoverRebuildTargetNames, inspectNativeMarketplaceRegistrations, } from './rebuild-integration.js';
+import { createRebuildActiveStore, executeRebuildOperation, } from './rebuild-operations.js';
+import { assertNoClaudeUnboundNativeNameCollision, codexNativeRemovalRequired, createRebuildIntegration, discoverRebuildTargetNames, inspectNativeMarketplaceRegistrations, } from './rebuild-integration.js';
 import { getNamespacedMarketplaceName } from '../utils/local-marketplace.js';
 import { formatPluginId, parsePluginId, planPluginSelectorSourceIds, preflightDesiredArtifactCollisions, withResolvedMultiSourceCatalog, } from '../utils/multi-source-catalog.js';
+import { resolveCatalogOperationContext, } from '../utils/catalog-operation-context.js';
 import { assertStrictSemVer } from '../utils/manifest.js';
 import { assertCatalogSourceInventoryComplete, canonicalMarketplaceRegistrationNames, inventoryCatalogSourceReferences, } from '../utils/catalog-source-references.js';
 import { resolveEffectivePluginConfig } from '../utils/plugin-config.js';
 import { cleanupCorruptExclusivePluginDirectory, inspectOwnedComponents, } from '../utils/ownership.js';
 import { codexProjectConfigAliasesUserHome, getClaudeHome, getCodexHome, resolveCanonicalRepoProjectKey, resolveRepoRootSync, } from '../utils/state-paths.js';
 import { resolvePluginMetaDependencyClosure } from '../utils/plugin-dependencies.js';
+import { validateCatalogSnapshotPluginEntriesComplete } from '../utils/catalog-snapshot.js';
+import { AwCapabilityUnsupportedError, IMPLEMENTED_AW_CAPABILITIES, } from './aw-capabilities.js';
+import { checkAwCapabilitySupport } from '../utils/manifest.js';
 import { createDependencyOperationPlan, } from './dependency-operation-plan.js';
+import { offlineCleanupEvidenceFromInventory, offlineCleanupEvidenceMatches, } from './offline-cleanup-evidence.js';
 let rebuildCommandTestHooks;
 async function emitRebuildActionEvent(runtime, event) {
     await Promise.allSettled([
@@ -27,49 +33,6 @@ async function emitRebuildActionEvent(runtime, event) {
         Promise.resolve().then(() => runtime.debugLogger.log(event)),
     ]);
 }
-async function withRebuildActionEvent(options) {
-    const source = {
-        plugin: options.identity.pluginName,
-        platform: options.identity.platform,
-        scope: options.identity.scope,
-        action: options.command,
-    };
-    const startedAt = Date.now();
-    await emitRebuildActionEvent(options.runtime, {
-        type: 'rebuild:action',
-        source,
-        data: { name: options.name, phase: 'start' },
-    });
-    let result;
-    try {
-        result = await options.operation();
-    }
-    catch (error) {
-        await emitRebuildActionEvent(options.runtime, {
-            type: 'rebuild:action',
-            source,
-            data: {
-                name: options.name,
-                phase: 'failure',
-                durationMs: Math.max(0, Date.now() - startedAt),
-                message: options.name === 'operation.lock'
-                    ? '获取操作锁失败。'
-                    : '释放操作锁失败。',
-            },
-        });
-        throw error;
-    }
-    await emitRebuildActionEvent(options.runtime, {
-        type: 'rebuild:action',
-        source,
-        data: {
-            name: options.name,
-            phase: 'success',
-            durationMs: Math.max(0, Date.now() - startedAt),
-        },
-    });
-    return result;
-}
 export function setRebuildCommandTestHooksForTests(hooks) {
     rebuildCommandTestHooks = hooks;
 }
@@ -82,11 +45,10 @@ function createSyntheticPlugin(pluginName, env) {
         rootDir,
         manifestPath: path.join(rootDir, '.agents-plugin', 'plugin.json'),
         manifest: {
-            schemaVersion: 1,
+            schemaVersion: 2,
             name: pluginName,
             version: '0.0.0',
             description: 'Cleanup-only target for a plugin missing from the current catalog.',
-            compatibility: { aw: { minVersion: '0.0.0' } },
             marketplace: {
                 category: 'cleanup',
                 strict: true,
@@ -110,17 +72,6 @@ function failedResult(command, identity, message, phase = 'preflight') {
         error: { phase, message },
     };
 }
-function appendOperationReleaseFailure(result, message) {
-    result.actions.push({ name: 'operation.release', status: 'failed' });
-    result.failures.push({ phase: 'operation.release', message });
-    if (result.status === 'failed')
-        return result;
-    return {
-        ...result,
-        status: 'failed',
-        error: { phase: 'operation.release', message },
-    };
-}
 function toTargetResult(result) {
     return {
         target: {
@@ -138,17 +89,17 @@ function toTargetResult(result) {
         ...(result.status === 'failed' ? { message: result.error.message } : {}),
     };
 }
-async function assertAgentVersions(options) {
+async function assertClaudeVersion(options) {
+    if (!options.platforms.includes('claude'))
+        return;
     const failures = [];
-    for (const platform of options.platforms) {
-        const result = await probeAgentVersion(platform, {
-            cwd: options.cwd,
-            env: options.env,
-            runner: options.runtime.nativeCliRunner,
-        });
-        if (result.status !== 'supported')
-            failures.push(result);
-    }
+    const result = await probeAgentVersion('claude', {
+        cwd: options.cwd,
+        env: options.env,
+        runner: options.runtime.nativeCliRunner,
+    });
+    if (result.status !== 'supported')
+        failures.push(result);
     if (failures.length > 0) {
         throw new Error(failures.map((failure) => `${failure.command} 版本检查失败：${failure.details ?? failure.status}；最低版本 ${failure.requiredMinVersion}。`)
             .join('；'));
@@ -177,8 +128,7 @@ async function runSingleSourceRebuildCommand(options) {
         nativeCliRunner: options.runtime?.nativeCliRunner ?? getDefaultNativeCliRunner(),
         reporter: options.runtime?.reporter ?? createNoopReporter(),
         debugLogger: options.runtime?.debugLogger ?? createNoopDebugLogger(),
-        runtimeLeaseHeld: options.runtime?.runtimeLeaseHeld,
-        lifecycleLeaseHeld: options.runtime?.lifecycleLeaseHeld,
+        ...(options.runtime?.codexManager ? { codexManager: options.runtime.codexManager } : {}),
         expectedCatalogConfigDigest: options.runtime?.expectedCatalogConfigDigest,
     };
     const env = runtime.env;
@@ -186,7 +136,23 @@ async function runSingleSourceRebuildCommand(options) {
     const catalog = options.runtime?.catalogResolution;
     if (!catalog)
         throw new Error('Internal error: a resolved catalog source is required.');
-    const catalogPlugins = await resolvePluginsFromCatalog(catalog.rootDir, undefined);
+    const requestedByPlatform = await resolveRequestedNames({
+        command: options.command,
+        pluginNames: options.pluginNames,
+        all: options.all,
+        platforms: selected,
+        scope: options.commandOptions.scope,
+        cwd: options.commandOptions.cwd,
+        env,
+        nativeCliRunner: runtime.nativeCliRunner,
+    });
+    const exactPluginNames = [...new Set([...requestedByPlatform.values()].flat())];
+    const catalogPlugins = options.runtime?.resolvedCatalogPlugins ?? (await Promise.all(exactPluginNames.map(async (pluginName) => {
+        const pluginRoot = path.join(catalog.rootDir, 'plugins', pluginName);
+        return await fs.pathExists(pluginRoot)
+            ? readPluginManifest(pluginRoot, { mode: 'bundle' })
+            : null;
+    }))).filter((plugin) => plugin !== null);
     if (options.runtime?.namespacedSource) {
         for (const plugin of catalogPlugins) {
             plugin.sourceId = options.runtime.namespacedSource.sourceId;
@@ -199,16 +165,6 @@ async function runSingleSourceRebuildCommand(options) {
         }
     }
     const catalogByName = new Map(catalogPlugins.map((plugin) => [plugin.manifest.name, plugin]));
-    const requestedByPlatform = await resolveRequestedNames({
-        command: options.command,
-        pluginNames: options.pluginNames,
-        all: options.all,
-        platforms: selected,
-        scope: options.commandOptions.scope,
-        cwd: options.commandOptions.cwd,
-        env,
-        nativeCliRunner: runtime.nativeCliRunner,
-    });
     if (options.commandOptions.platform === 'both'
         && options.command !== 'cleanup'
         && options.command !== 'uninstall') {
@@ -220,12 +176,14 @@ async function runSingleSourceRebuildCommand(options) {
         }
     }
     const platforms = selected.filter((platform) => (requestedByPlatform.get(platform)?.length ?? 0) > 0);
-    await assertAgentVersions({
-        platforms,
-        cwd: options.commandOptions.cwd,
-        env,
-        runtime,
-    });
+    if (options.runtime?.bypassDependencyPlan) {
+        await assertClaudeVersion({
+            platforms,
+            cwd: options.commandOptions.cwd,
+            env,
+            runtime,
+        });
+    }
     const integration = options.runtime?.preparedTarget
         ? {
             driver: options.runtime.preparedTarget.driver,
@@ -238,7 +196,6 @@ async function runSingleSourceRebuildCommand(options) {
     const activeStore = createRebuildActiveStore({
         env,
         loadPlugin: (bundleRoot) => readPluginManifest(bundleRoot, { mode: 'bundle' }),
-        isLifecycleLeaseHeld: () => runtime.lifecycleLeaseHeld === true,
     });
     const targets = [];
     const results = [];
@@ -304,26 +261,6 @@ async function runSingleSourceRebuildCommand(options) {
                 results.push(failedResult(options.command, identity, `${pluginName} 没有 Codex project scope 可生成的 Skills、instructions、roles、MCP、hooks 或 permissions。`));
                 continue;
             }
-            let operationLock;
-            if (!options.runtime?.operationLeaseHeld) {
-                try {
-                    await rebuildCommandTestHooks?.beforeOperationLockAcquire?.({
-                        command: options.command,
-                        identity,
-                    });
-                    operationLock = await withRebuildActionEvent({
-                        runtime,
-                        command: options.command,
-                        identity,
-                        name: 'operation.lock',
-                        operation: () => activeStore.acquireOperation(identity),
-                    });
-                }
-                catch (error) {
-                    results.push(failedResult(options.command, identity, error instanceof Error ? error.message : String(error), 'operation.lock'));
-                    continue;
-                }
-            }
             let result;
             try {
                 if (options.runtime?.preparedTargetError)
@@ -358,34 +295,17 @@ async function runSingleSourceRebuildCommand(options) {
                         ...options.runtime.resolvedReviewEvidenceByPlugin?.[pluginName],
                     });
                 }
-                const { acquireOperation: _acquireOperation, ...operationHeldStore } = activeStore;
                 result = await executeRebuildOperation({
                     command: options.command,
                     target,
                     driver: integration.driver,
-                    activeStore: operationHeldStore,
+                    activeStore,
                     onActionEvent: (event) => emitRebuildActionEvent(runtime, event),
                 });
             }
             catch (error) {
                 result = error.result ?? failedResult(options.command, identity, error instanceof Error ? error.message : String(error), 'preflight');
             }
-            result.actions.unshift({ name: 'operation.lock', status: 'succeeded' });
-            if (operationLock) {
-                try {
-                    await withRebuildActionEvent({
-                        runtime,
-                        command: options.command,
-                        identity,
-                        name: 'operation.release',
-                        operation: () => releaseRebuildOperationLease(operationLock),
-                    });
-                    result.actions.push({ name: 'operation.release', status: 'succeeded' });
-                }
-                catch (error) {
-                    result = appendOperationReleaseFailure(result, error instanceof Error ? error.message : String(error));
-                }
-            }
             results.push(result);
         }
     }
@@ -431,7 +351,6 @@ function toCatalogResolution(source) {
         source: 'local',
         catalogVersion: source.manifest.catalogVersion,
         channel: source.manifest.channel,
-        minAwVersion: source.manifest.compatibility.aw.minVersion,
     };
 }
 function mergeRebuildCommandResults(results) {
@@ -460,6 +379,9 @@ function mergeRebuildCommandResults(results) {
         ...(results.find((result) => result.dependencyPlan)?.dependencyPlan
             ? { dependencyPlan: results.find((result) => result.dependencyPlan).dependencyPlan }
             : {}),
+        ...(results.find((result) => result.codexManagerPreview)?.codexManagerPreview
+            ? { codexManagerPreview: results.find((result) => result.codexManagerPreview).codexManagerPreview }
+            : {}),
     };
 }
 function leaseSafeRebuildResult(result) {
@@ -553,6 +475,10 @@ function resolveLiveCleanupTargets(options) {
                 platform: reference.platform,
                 scope: reference.scope,
                 ...(marketplaceName ? { marketplaceName } : {}),
+                ...((liveNames.size === 1
+                    || (marketplaceName !== undefined && unboundNativeNames.has(marketplaceName)))
+                    ? { nativeRegistration: true }
+                    : {}),
                 ...(marketplaceIdentityUnresolved ? { marketplaceIdentityUnresolved: true } : {}),
             };
             const key = [target.pluginId, target.sourceIdentity, target.platform, target.scope].join('\0');
@@ -625,9 +551,40 @@ async function cleanupOfflineOwnedComponents(options) {
     }
     const results = [];
     const warnings = [];
+    const nativeCliRunner = options.nativeCliRunner ?? getDefaultNativeCliRunner();
+    let codexManager = options.codexManager;
+    const codexManagerNeedFailures = new Map();
+    if (!codexManager) {
+        const codexManagerRequired = (await Promise.all(options.targets.map(async (target) => {
+            if (target.platform !== 'codex' || target.scope !== 'user')
+                return false;
+            try {
+                return await codexNativeRemovalRequired({
+                    pluginName: target.pluginName,
+                    cwd: options.cwd,
+                    env: options.env,
+                    marketplaceName: target.marketplaceName,
+                    marketplaceRoot: path.join(resolveAwHome(options.env), 'marketplaces', target.sourceId),
+                });
+            }
+            catch (error) {
+                codexManagerNeedFailures.set(target, new Error('codexNativeResidueProbeFailed: Codex native residue was retained because its config or cache evidence could not be read. Repair the damaged Codex weak state, then retry cleanup; you can also upgrade AW or install a compatible official Codex CLI.', { cause: error }));
+                return false;
+            }
+        }))).some(Boolean);
+        if (codexManagerRequired) {
+            codexManager = await (options.codexManagerResolver ?? resolveCodexManager)({
+                cwd: options.cwd,
+                env: options.env,
+                runner: nativeCliRunner,
+                authorizer: options.managedCodexAuthorizer,
+            });
+        }
+    }
     const context = {
         env: options.env,
-        nativeCliRunner: options.nativeCliRunner ?? getDefaultNativeCliRunner(),
+        nativeCliRunner,
+        ...(codexManager ? { codexManager } : {}),
         reporter: createNoopReporter(),
         debugLogger: createNoopDebugLogger(),
     };
@@ -635,7 +592,6 @@ async function cleanupOfflineOwnedComponents(options) {
     const activeStore = createRebuildActiveStore({
         env: options.env,
         loadPlugin: (bundleRoot) => readPluginManifest(bundleRoot, { mode: 'bundle' }),
-        isLifecycleLeaseHeld: () => context.lifecycleLeaseHeld === true,
     });
     for (const target of options.targets) {
         const exclusiveRecovery = {
@@ -690,6 +646,7 @@ async function cleanupOfflineOwnedComponents(options) {
         plugin.pluginId = target.pluginId;
         const marketplaceName = target.marketplaceName ?? 'aw';
         plugin.marketplaceName = marketplaceName;
+        const codexManagerNeedFailure = codexManagerNeedFailures.get(target);
         const desired = await integration.buildTarget({
             sourceId: target.sourceId,
             sourceIdentity: target.sourceIdentity,
@@ -706,23 +663,38 @@ async function cleanupOfflineOwnedComponents(options) {
                 source: 'local',
                 catalogVersion: '0.0.0',
                 channel: 'beta',
-                minAwVersion: '0.0.0',
             },
             includeHistoricalLifecycleArtifacts: false,
+            includeNativeCleanupCandidate: target.nativeRegistration === true && !codexManagerNeedFailure,
         });
-        let result;
-        const operationLock = await activeStore.acquireOperation(desired.identity);
-        try {
-            const { acquireOperation: _acquireOperation, ...operationHeldStore } = activeStore;
-            result = await executeRebuildOperation({
-                command: 'cleanup',
-                target: desired,
-                driver: integration.driver,
-                activeStore: operationHeldStore,
-            });
-        }
-        finally {
-            await releaseRebuildOperationLease(operationLock);
+        const driver = codexManagerNeedFailure && integration.driver.probeNative
+            ? {
+                ...integration.driver,
+                probeNative: async () => {
+                    throw codexManagerNeedFailure;
+                },
+            }
+            : integration.driver;
+        let result = await executeRebuildOperation({
+            command: 'cleanup',
+            target: desired,
+            driver,
+            activeStore,
+        });
+        if (codexManagerNeedFailure) {
+            const residual = `${target.pluginName}@${marketplaceName}`;
+            result = {
+                ...result,
+                status: 'failed',
+                actions: [...result.actions, { name: 'cleanup.owned', status: 'failed' }],
+                residual: [...new Set([...result.residual, residual])],
+                failures: [...result.failures, {
+                        phase: 'cleanup.owned',
+                        label: residual,
+                        message: codexManagerNeedFailure.message,
+                    }],
+                error: { phase: 'cleanup.owned', message: codexManagerNeedFailure.message },
+            };
         }
         const exclusiveResidual = (await Promise.all(exclusiveRecovery.residual.map(async (entry) => await fs.pathExists(entry) ? entry : null))).filter((entry) => entry !== null);
         const exclusiveQuarantined = (await Promise.all(exclusiveRecovery.quarantined.map(async (entry) => await fs.pathExists(entry) ? entry : null))).filter((entry) => entry !== null);
@@ -781,8 +753,33 @@ async function cleanupOfflineOwnedComponents(options) {
         })),
     });
 }
+async function previewOfflineOwnedComponents(options) {
+    if (options.targets.some((target) => target.marketplaceIdentityUnresolved)) {
+        throw namespacedPreflightError('marketplaceIdentityUnavailable: Cannot uniquely recover the native marketplace name from live inventory or a canonical native registration path.', options.targets);
+    }
+    await options.onPreviewStage?.('inventory');
+    const preview = mergeRebuildCommandResults([]);
+    const codexManagerRequired = (await Promise.all(options.targets.flatMap((target) => target.platform === 'codex' && target.scope === 'user'
+        ? [codexNativeRemovalRequired({
+                pluginName: target.pluginName,
+                cwd: options.cwd,
+                env: options.env,
+                marketplaceName: target.marketplaceName,
+                marketplaceRoot: path.join(resolveAwHome(options.env), 'marketplaces', target.sourceId),
+            })]
+        : []))).some(Boolean);
+    await options.onPreviewStage?.('dependencyPlan');
+    if (codexManagerRequired) {
+        preview.codexManagerPreview = await (options.codexManagerPreviewer ?? previewCodexManager)({
+            cwd: options.cwd,
+            env: options.env,
+            runner: options.nativeCliRunner,
+        });
+    }
+    return preview;
+}
 async function assertOfflineCleanupDependents(options) {
-    const inventory = await inventoryCatalogSourceReferences({
+    const inventory = await options.readInventory({
         cwd: options.cwd,
         env: options.env,
         includeHistoricalProjects: true,
@@ -817,19 +814,27 @@ export async function runRebuildCommand(options) {
         return runSingleSourceRebuildCommand(options);
     }
     const runtimeEnv = options.runtime?.env ?? process.env;
+    const readInventory = options.runtime?.inventoryCatalogSourceReferences
+        ?? inventoryCatalogSourceReferences;
+    let ordinaryInventory;
+    const readOrdinaryInventory = async () => {
+        ordinaryInventory ??= await readInventory({
+            cwd: options.commandOptions.cwd,
+            env: runtimeEnv,
+        });
+        return ordinaryInventory;
+    };
     let requestedPluginNames = options.pluginNames;
     const cleanupForce = options.command === 'cleanup'
         && options.commandOptions.force === true;
+    const expectedOfflineCleanup = options.runtime?.expectedOfflineCleanupEvidence;
     let cleanupInventory;
     let cleanupLiveTargets = [];
     let cleanupHasDamagedExclusiveTarget = false;
     let liveTargets = [];
     let legacyLiveTargets = [];
     if (options.command === 'cleanup' && !options.all) {
-        cleanupInventory = await inventoryCatalogSourceReferences({
-            cwd: options.commandOptions.cwd,
-            env: runtimeEnv,
-        });
+        cleanupInventory = await readOrdinaryInventory();
         const live = resolveLiveCleanupTargets({
             selectors: requestedPluginNames,
             platforms: selectedPlatforms(options.commandOptions.platform),
@@ -838,7 +843,27 @@ export async function runRebuildCommand(options) {
         });
         requestedPluginNames = live.selectors;
         cleanupLiveTargets = live.targets;
-        if (cleanupForce) {
+        if (expectedOfflineCleanup) {
+            const liveTarget = cleanupLiveTargets.find((target) => target.pluginId === expectedOfflineCleanup.pluginId
+                && target.pluginName === expectedOfflineCleanup.pluginName
+                && target.sourceId === expectedOfflineCleanup.sourceId
+                && target.sourceIdentity === expectedOfflineCleanup.sourceIdentity
+                && target.platform === expectedOfflineCleanup.platform
+                && target.scope === expectedOfflineCleanup.scope);
+            const actualOfflineCleanup = liveTarget
+                ? offlineCleanupEvidenceFromInventory({
+                    ...expectedOfflineCleanup,
+                    inventory: cleanupInventory,
+                })
+                : null;
+            if (!liveTarget
+                || !actualOfflineCleanup
+                || !offlineCleanupEvidenceMatches(expectedOfflineCleanup, actualOfflineCleanup)) {
+                throw namespacedPreflightError('operationReviewStale: offline cleanup ownership evidence changed before mutation.', cleanupLiveTargets);
+            }
+            cleanupLiveTargets = [liveTarget];
+        }
+        if (cleanupForce && !expectedOfflineCleanup) {
             const damagedTargets = (await Promise.all(requestedPluginNames.map(async (selector) => parsePluginId(selector).sourceId
                 ? discoverDamagedExclusiveCleanupTargets({
                     selector,
@@ -857,6 +882,16 @@ export async function runRebuildCommand(options) {
         liveTargets = cleanupLiveTargets;
     }
     if (cleanupHasDamagedExclusiveTarget) {
+        if (options.runtime?.previewDependencyPlanOnly) {
+            return previewOfflineOwnedComponents({
+                targets: cleanupLiveTargets,
+                cwd: options.commandOptions.cwd,
+                env: runtimeEnv,
+                nativeCliRunner: options.runtime.nativeCliRunner,
+                codexManagerPreviewer: options.runtime.codexManagerPreviewer,
+                onPreviewStage: options.runtime.onPreviewStage,
+            });
+        }
         return cleanupOfflineOwnedComponents({
             targets: cleanupLiveTargets,
             cwd: options.commandOptions.cwd,
@@ -864,14 +899,14 @@ export async function runRebuildCommand(options) {
             force: true,
             removeObsoleteInstallationContracts: options.runtime?.removeObsoleteInstallationContracts,
             nativeCliRunner: options.runtime?.nativeCliRunner,
+            codexManager: options.runtime?.codexManager,
+            codexManagerResolver: options.runtime?.codexManagerResolver,
+            managedCodexAuthorizer: options.runtime?.managedCodexAuthorizer,
             corruptExclusiveDirectoryOperations: options.runtime?.corruptExclusiveDirectoryOperations,
         });
     }
     if (options.all) {
-        const inventory = await inventoryCatalogSourceReferences({
-            cwd: options.commandOptions.cwd,
-            env: runtimeEnv,
-        });
+        const inventory = await readOrdinaryInventory();
         if (options.command !== 'cleanup')
             assertCatalogSourceInventoryComplete(inventory);
         const requestedPlatforms = new Set(selectedPlatforms(options.commandOptions.platform));
@@ -928,34 +963,52 @@ export async function runRebuildCommand(options) {
         if (options.runtime?.previewDependencyPlanOnly) {
             await options.runtime.onPreviewStage?.('catalog');
         }
+        if (options.runtime?.catalogBootstrapError !== undefined) {
+            throw options.runtime.catalogBootstrapError;
+        }
+        const catalogOperation = options.runtime?.catalogOperationContext
+            ?? (options.command === 'cleanup'
+                ? undefined
+                : await resolveCatalogOperationContext({
+                    cliVersion: resolveRuntimeCliVersion(),
+                    ...(sourceIds ? { sourceIds } : {}),
+                    env: runtimeEnv,
+                    ...(options.runtime?.catalogGenerationRuntime
+                        ? { runtime: options.runtime.catalogGenerationRuntime }
+                        : {}),
+                    ...(options.runtime?.awHomeMutationToken
+                        ? { bootstrapMissingActive: false }
+                        : {}),
+                }));
+        if (options.runtime?.expectedGenerationSetDigest
+            && catalogOperation?.generationSetDigest !== options.runtime.expectedGenerationSetDigest) {
+            throw new Error('operationReviewStale: Active Catalog generation changed before mutation.');
+        }
         const resolvedResult = await withResolvedMultiSourceCatalog({
             cliVersion: resolveRuntimeCliVersion(),
-            freshnessPolicy: options.command === 'cleanup'
-                ? 'cacheFirst'
-                : options.runtime?.previewDependencyPlanOnly
-                    ? options.runtime.previewCatalogFreshnessPolicy ?? 'requireRemote'
-                    : 'requireRemote',
+            freshnessPolicy: 'cacheFirst',
             ...(sourceIds ? { sourceIds } : {}),
+            ...(catalogOperation ? { operationContext: catalogOperation } : {}),
+            ...(options.command === 'cleanup' || options.runtime?.awHomeMutationToken
+                ? { bootstrapMissingActive: false }
+                : {}),
             env: runtimeEnv,
             consume: async (catalog) => {
                 const failedSources = catalog.sources.filter((source) => source.error);
                 if (failedSources.length > 0) {
                     throw namespacedPreflightError(`Cannot resolve required catalog sources: ${failedSources.map((source) => source.sourceId).join(', ')}.`, liveTargets, legacyLiveTargets);
                 }
-                const available = (await Promise.all(catalog.sources.map(async (item) => {
+                const availableEntries = catalog.sources.flatMap((item) => {
                     const source = item.resolution;
-                    const plugins = await resolvePluginsFromCatalog(source.rootDir, undefined);
-                    return plugins.map((plugin) => {
-                        const pluginId = formatPluginId({ sourceId: source.sourceId, pluginName: plugin.manifest.name });
-                        plugin.sourceId = source.sourceId;
-                        plugin.sourceIdentity = source.sourceIdentity;
-                        plugin.pluginId = pluginId;
-                        return { source, plugin, pluginId };
-                    });
-                }))).flat();
-                const selected = selectors.map((selector, index) => {
-                    const matches = available.filter((entry) => entry.plugin.manifest.name === selector.pluginName
-                        && (selector.sourceId === undefined || entry.source.sourceId === selector.sourceId));
+                    return source.manifest.entries.map((entry) => ({
+                        source,
+                        entry,
+                        pluginId: formatPluginId({ sourceId: source.sourceId, pluginName: entry.name }),
+                    }));
+                });
+                const selectedEntries = selectors.map((selector, index) => {
+                    const matches = availableEntries.filter((candidate) => candidate.entry.name === selector.pluginName
+                        && (selector.sourceId === undefined || candidate.source.sourceId === selector.sourceId));
                     if (matches.length === 0) {
                         throw new Error(`Plugin "${requestedPluginNames[index]}" does not exist in the required catalog source set.`);
                     }
@@ -967,6 +1020,65 @@ export async function runRebuildCommand(options) {
                 const dependencyEnabled = options.command === 'install'
                     || options.command === 'upgrade'
                     || options.command === 'reinstall';
+                const entryClosure = (roots) => {
+                    const result = [];
+                    const seen = new Set();
+                    const visiting = new Set();
+                    const byId = new Map(availableEntries.map((candidate) => [candidate.pluginId, candidate]));
+                    const visit = (candidate) => {
+                        if (seen.has(candidate.pluginId))
+                            return;
+                        if (visiting.has(candidate.pluginId))
+                            throw new Error(`Catalog dependency cycle includes "${candidate.pluginId}".`);
+                        visiting.add(candidate.pluginId);
+                        for (const dependency of candidate.entry.dependencies) {
+                            const dependencyId = formatPluginId({ sourceId: candidate.source.sourceId, pluginName: dependency });
+                            const resolved = byId.get(dependencyId);
+                            if (!resolved)
+                                throw new Error(`Catalog plugin "${candidate.pluginId}" depends on missing plugin "${dependency}".`);
+                            visit(resolved);
+                        }
+                        visiting.delete(candidate.pluginId);
+                        seen.add(candidate.pluginId);
+                        result.push(candidate);
+                    };
+                    for (const root of roots)
+                        visit(root);
+                    return result;
+                };
+                const removalConsumerEntries = options.command === 'cleanup' || options.command === 'uninstall'
+                    ? availableEntries.filter((candidate) => selectedEntries.some((selectedEntry) => candidate.source.sourceId === selectedEntry.source.sourceId
+                        && candidate.entry.dependencies.includes(selectedEntry.entry.name)))
+                    : [];
+                const requiredEntryClosure = dependencyEnabled
+                    ? entryClosure(selectedEntries)
+                    : [...new Map([...selectedEntries, ...removalConsumerEntries].map((candidate) => [candidate.pluginId, candidate])).values()];
+                if (dependencyEnabled) {
+                    for (const candidate of requiredEntryClosure) {
+                        const requiredCapabilities = candidate.entry.requires.aw.capabilities ?? [];
+                        const support = checkAwCapabilitySupport(requiredCapabilities, IMPLEMENTED_AW_CAPABILITIES);
+                        if (!support.supported) {
+                            throw new AwCapabilityUnsupportedError(candidate.pluginId, support.missing);
+                        }
+                    }
+                    for (const item of catalog.sources) {
+                        const source = item.resolution;
+                        const names = requiredEntryClosure
+                            .filter((candidate) => candidate.source.sourceId === source.sourceId)
+                            .map((candidate) => candidate.entry.name);
+                        if (names.length > 0) {
+                            await validateCatalogSnapshotPluginEntriesComplete(source.rootDir, names);
+                        }
+                    }
+                }
+                const available = await Promise.all(requiredEntryClosure.map(async (candidate) => {
+                    const plugin = await readPluginManifest(path.join(candidate.source.rootDir, 'plugins', candidate.entry.name), { mode: 'bundle' });
+                    plugin.sourceId = candidate.source.sourceId;
+                    plugin.sourceIdentity = candidate.source.sourceIdentity;
+                    plugin.pluginId = candidate.pluginId;
+                    return { source: candidate.source, plugin, pluginId: candidate.pluginId };
+                }));
+                const selected = selectedEntries.map((entry) => available.find((candidate) => candidate.pluginId === entry.pluginId));
                 const selectedIds = new Set(selected.map((entry) => entry.pluginId));
                 const resolveClosureEntries = (rootsBySource) => catalog.sources.flatMap((item) => {
                     const source = item.resolution;
@@ -1034,10 +1146,7 @@ export async function runRebuildCommand(options) {
                 if (options.runtime?.previewDependencyPlanOnly) {
                     await options.runtime.onPreviewStage?.('inventory');
                 }
-                const stateInventory = await inventoryCatalogSourceReferences({
-                    cwd: options.commandOptions.cwd,
-                    env: runtimeEnv,
-                });
+                const stateInventory = await readOrdinaryInventory();
                 if (options.command !== 'cleanup')
                     assertCatalogSourceInventoryComplete(stateInventory);
                 const commandProjectKey = await resolveCanonicalRepoProjectKey(options.commandOptions.cwd);
@@ -1121,19 +1230,13 @@ export async function runRebuildCommand(options) {
                     nativeCliRunner: options.runtime?.nativeCliRunner ?? getDefaultNativeCliRunner(),
                     reporter: options.runtime?.reporter ?? createNoopReporter(),
                     debugLogger: options.runtime?.debugLogger ?? createNoopDebugLogger(),
-                    runtimeLeaseHeld: options.runtime?.runtimeLeaseHeld,
-                    lifecycleLeaseHeld: options.runtime?.lifecycleLeaseHeld,
                     expectedCatalogConfigDigest: catalog.configDigest,
                 };
                 const inspection = createRebuildIntegration({
                     context: executionContext,
                     scriptTimeoutMs: options.commandOptions.scriptTimeoutMs,
                 });
-                const createPlan = async (preparedInventory) => {
-                    const inventory = preparedInventory ?? await inventoryCatalogSourceReferences({
-                        cwd: options.commandOptions.cwd,
-                        env: runtimeEnv,
-                    });
+                const createPlan = async (inventory) => {
                     if (options.command !== 'cleanup')
                         assertCatalogSourceInventoryComplete(inventory);
                     const targets = [];
@@ -1172,8 +1275,8 @@ export async function runRebuildCommand(options) {
                             const hasUnexpectedPresent = result.components.some((entry) => entry.state === 'present' && !required.has(entry.component) && !optional.has(entry.component));
                             const hasPartial = result.components.some((entry) => entry.state === 'partial');
                             const hasAnyPresent = result.components.some((entry) => entry.state === 'present');
-                            const state = !hasAnyPresent
-                                && result.components.every((entry) => entry.state === 'absent')
+                            const hasAnyOwned = hasAnyPresent || hasPartial;
+                            const state = !hasAnyOwned
                                 ? 'absent'
                                 : hasPartial || hasUnexpectedPresent || !presentRequired
                                     ? 'partial'
@@ -1195,7 +1298,7 @@ export async function runRebuildCommand(options) {
                             : options.command === 'reinstall' ? 'reinstall' : 'upgrade';
                         let errorCode;
                         const hasForeignCollision = [...requestedInspection.components, ...otherInspection.components]
-                            .some((component) => component.diagnostic?.includes('foreign collision'));
+                            .some((component) => component.collision !== undefined);
                         if (dependencyEnabled && hasForeignCollision) {
                             action = 'block';
                             errorCode = 'artifactCollision';
@@ -1305,11 +1408,77 @@ export async function runRebuildCommand(options) {
                         targets,
                     });
                 };
+                const operationNeedsNativeCli = async (platform, plan) => {
+                    for (const { entry, platform: selectedPlatform } of executionSelections) {
+                        if (selectedPlatform !== platform)
+                            continue;
+                        const planned = plan?.targets.find((target) => target.pluginId === entry.pluginId && target.platform === selectedPlatform);
+                        if (dependencyEnabled && (!planned
+                            || planned.action === 'keep'
+                            || planned.action === 'block'))
+                            continue;
+                        const scope = planned?.resolvedScope ?? options.commandOptions.scope;
+                        const marketplaceName = marketplaceNameFor(entry, selectedPlatform, scope);
+                        entry.plugin.marketplaceName = marketplaceName;
+                        const marketplaceRoot = path.join(resolveAwHome(runtimeEnv), 'marketplaces', entry.source.sourceId);
+                        if (!dependencyEnabled && selectedPlatform === 'codex') {
+                            if (scope === 'user' && await codexNativeRemovalRequired({
+                                pluginName: entry.plugin.manifest.name,
+                                cwd: options.commandOptions.cwd,
+                                env: runtimeEnv,
+                                marketplaceName,
+                                marketplaceRoot,
+                            }))
+                                return true;
+                            continue;
+                        }
+                        const target = await inspection.buildTarget({
+                            sourceId: entry.source.sourceId,
+                            sourceIdentity: entry.source.sourceIdentity,
+                            pluginId: entry.pluginId,
+                            marketplaceName,
+                            marketplaceRoot,
+                            plugin: entry.plugin,
+                            platform: selectedPlatform,
+                            scope,
+                            cwd: options.commandOptions.cwd,
+                            command: dependencyEnabled
+                                ? planned.action
+                                : options.command,
+                            catalog: toCatalogResolution(entry.source),
+                            includeHistoricalLifecycleArtifacts: false,
+                            readOnlyInspectionPlan: true,
+                        });
+                        if (dependencyEnabled && target.requiresNative)
+                            return true;
+                        const nativeComponents = target.ownedComponents.filter((component) => component.kind === 'native-plugin'
+                            || (component.kind === 'shared-config'
+                                && component.identity.artifactKey.startsWith('marketplace-')));
+                        if (nativeComponents.length === 0)
+                            continue;
+                        const nativeInspection = await inspectOwnedComponents({
+                            components: nativeComponents,
+                            nativeProbe: inspection.driver.probeNative,
+                        });
+                        if (nativeInspection.components.some((component) => component.state === 'present' || component.state === 'partial')) {
+                            return true;
+                        }
+                    }
+                    return false;
+                };
                 if (options.runtime?.previewDependencyPlanOnly) {
                     await options.runtime.onPreviewStage?.('dependencyPlan');
-                    const initialPlan = await createPlan(stateInventory);
+                    const initialPlan = dependencyEnabled ? await createPlan(stateInventory) : undefined;
                     const preview = mergeRebuildCommandResults([]);
-                    preview.dependencyPlan = initialPlan;
+                    if (initialPlan)
+                        preview.dependencyPlan = initialPlan;
+                    if (await operationNeedsNativeCli('codex', initialPlan)) {
+                        preview.codexManagerPreview = await (options.runtime.codexManagerPreviewer ?? previewCodexManager)({
+                            cwd: options.commandOptions.cwd,
+                            env: runtimeEnv,
+                            runner: options.runtime?.nativeCliRunner,
+                        });
+                    }
                     return preview;
                 }
                 for (const { entry, platform } of executionSelections.filter((selection) => selectedIds.has(selection.entry.pluginId))) {
@@ -1326,6 +1495,9 @@ export async function runRebuildCommand(options) {
                             cwd: options.commandOptions.cwd,
                         },
                         configDigest: catalog.configDigest,
+                        ...(catalogOperation
+                            ? { generationSetDigest: catalogOperation.generationSetDigest }
+                            : {}),
                         sourceId: entry.source.sourceId,
                         sourceIdentity: entry.source.sourceIdentity,
                         resolvedCommit: entry.source.resolvedCommit,
@@ -1334,7 +1506,11 @@ export async function runRebuildCommand(options) {
                         contentDigest: entry.source.manifest.entries.find((candidate) => candidate.name === entry.plugin.manifest.name)?.contentDigest,
                     });
                 }
-                const lockedPlan = await createPlan();
+                const lockedPlan = await createPlan(stateInventory);
+                if (options.runtime?.expectedOperationDependencyPlan
+                    && JSON.stringify(lockedPlan) !== JSON.stringify(options.runtime.expectedOperationDependencyPlan)) {
+                    throw namespacedPreflightError('operationReviewStale: dependency plan changed before mutation.', preflightTargets);
+                }
                 for (const pluginName of new Set(lockedPlan.targets.flatMap((target) => target.platform === 'claude'
                     && (target.action === 'install'
                         || target.action === 'upgrade'
@@ -1347,16 +1523,25 @@ export async function runRebuildCommand(options) {
                         env: runtimeEnv,
                     });
                 }
-                await assertAgentVersions({
-                    platforms: [...new Set(executionSelections.flatMap(({ entry, platform }) => supportsPlatform(entry.plugin.manifest, platform) ? [platform] : []))],
+                const codexManagerRequired = await operationNeedsNativeCli('codex', lockedPlan);
+                const claudeCliRequired = await operationNeedsNativeCli('claude', lockedPlan);
+                if (codexManagerRequired) {
+                    executionContext.codexManager = await (options.runtime?.codexManagerResolver ?? resolveCodexManager)({
+                        cwd: options.commandOptions.cwd,
+                        env: runtimeEnv,
+                        runner: executionContext.nativeCliRunner,
+                        authorizer: options.runtime?.managedCodexAuthorizer,
+                    });
+                }
+                await assertClaudeVersion({
+                    platforms: claudeCliRequired ? ['claude'] : [],
                     cwd: options.commandOptions.cwd,
                     env: runtimeEnv,
-                    runtime: {
-                        env: runtimeEnv,
-                        nativeCliRunner: options.runtime?.nativeCliRunner ?? getDefaultNativeCliRunner(),
-                        reporter: options.runtime?.reporter ?? createNoopReporter(),
-                        debugLogger: options.runtime?.debugLogger ?? createNoopDebugLogger(),
-                    },
+                    runtime: executionContext,
+                });
+                const executionIntegration = createRebuildIntegration({
+                    context: executionContext,
+                    scriptTimeoutMs: options.commandOptions.scriptTimeoutMs,
                 });
                 const preparedTargets = new Map();
                 const preparedTargetErrors = new Map();
@@ -1369,7 +1554,7 @@ export async function runRebuildCommand(options) {
                         continue;
                     const marketplaceName = marketplaceNameFor(entry, platform, planned.resolvedScope);
                     try {
-                        const target = await inspection.buildTarget({
+                        const target = await executionIntegration.buildTarget({
                             sourceId: entry.source.sourceId,
                             sourceIdentity: entry.source.sourceIdentity,
                             pluginId: entry.pluginId,
@@ -1385,7 +1570,7 @@ export async function runRebuildCommand(options) {
                         });
                         preparedTargets.set(`${entry.pluginId}\0${platform}`, {
                             target,
-                            driver: inspection.driver,
+                            driver: executionIntegration.driver,
                             context: executionContext,
                         });
                         if (selectedIds.has(entry.pluginId)) {
@@ -1417,7 +1602,7 @@ export async function runRebuildCommand(options) {
                 }
                 const removalRequiredConsumers = new Map();
                 if ((options.command === 'cleanup' && !cleanupForce) || options.command === 'uninstall') {
-                    const removalStateInventory = await inventoryCatalogSourceReferences({
+                    const removalStateInventory = await readInventory({
                         cwd: options.commandOptions.cwd,
                         env: runtimeEnv,
                         includeHistoricalProjects: true,
@@ -1628,9 +1813,14 @@ export async function runRebuildCommand(options) {
                         runtime: {
                             ...options.runtime,
                             env: runtimeEnv,
+                            ...(executionContext.codexManager
+                                ? { codexManager: executionContext.codexManager }
+                                : {}),
                             catalogResolution: toCatalogResolution(entry.source),
+                            resolvedCatalogPlugins: available
+                                .filter((candidate) => candidate.source.sourceId === entry.source.sourceId)
+                                .map((candidate) => candidate.plugin),
                             namespacedSource,
-                            operationLeaseHeld: true,
                             dependencyReviewPreflightHandled: true,
                             targetBuiltHookHandled: true,
                             preparedTarget: preparedTargets.get(`${entry.pluginId}\0${platform}`),
@@ -1639,6 +1829,9 @@ export async function runRebuildCommand(options) {
                             resolvedReviewEvidenceByPlugin: {
                                 [entry.plugin.manifest.name]: {
                                     configDigest: catalog.configDigest,
+                                    ...(catalogOperation
+                                        ? { generationSetDigest: catalogOperation.generationSetDigest }
+                                        : {}),
                                     sourceId: entry.source.sourceId,
                                     sourceIdentity: entry.source.sourceIdentity,
                                     resolvedCommit: entry.source.resolvedCommit,
@@ -1657,7 +1850,7 @@ export async function runRebuildCommand(options) {
                 return leaseSafeRebuildResult(merged);
             },
         });
-        if (cleanupForce) {
+        if (cleanupForce && !options.runtime?.previewDependencyPlanOnly) {
             try {
                 await (options.runtime?.removeObsoleteInstallationContracts ?? fs.remove)(path.join(resolveAwHome(runtimeEnv), 'installation-contracts'));
             }
@@ -1677,25 +1870,42 @@ export async function runRebuildCommand(options) {
         const message = error instanceof Error ? error.message : String(error);
         const catalogUnavailable = message.startsWith('Cannot resolve required catalog sources:')
             || message.includes('does not exist in the required catalog source set')
-            || (message.includes('Catalog source') && message.includes('does not exist'));
+            || (message.includes('Catalog source')
+                && (message.includes('does not exist')
+                    || message.includes('is not configured')
+                    || message.includes('has no Active generation')));
         if (options.command === 'cleanup'
             && (catalogUnavailable || message.includes('sourceChanged'))
             && cleanupInventory
             && cleanupLiveTargets.length > 0) {
-            if (!cleanupForce) {
+            if (!cleanupForce || expectedOfflineCleanup) {
                 await assertOfflineCleanupDependents({
                     targets: cleanupLiveTargets,
                     cwd: options.commandOptions.cwd,
                     env: runtimeEnv,
+                    readInventory,
+                });
+            }
+            if (options.runtime?.previewDependencyPlanOnly) {
+                return previewOfflineOwnedComponents({
+                    targets: cleanupLiveTargets,
+                    cwd: options.commandOptions.cwd,
+                    env: runtimeEnv,
+                    nativeCliRunner: options.runtime.nativeCliRunner,
+                    codexManagerPreviewer: options.runtime.codexManagerPreviewer,
+                    onPreviewStage: options.runtime.onPreviewStage,
                 });
             }
             return cleanupOfflineOwnedComponents({
                 targets: cleanupLiveTargets,
                 cwd: options.commandOptions.cwd,
                 env: runtimeEnv,
-                force: cleanupForce,
+                force: cleanupForce && !expectedOfflineCleanup,
                 removeObsoleteInstallationContracts: options.runtime?.removeObsoleteInstallationContracts,
                 nativeCliRunner: options.runtime?.nativeCliRunner,
+                codexManager: options.runtime?.codexManager,
+                codexManagerResolver: options.runtime?.codexManagerResolver,
+                managedCodexAuthorizer: options.runtime?.managedCodexAuthorizer,
                 corruptExclusiveDirectoryOperations: options.runtime?.corruptExclusiveDirectoryOperations,
             });
         }