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

package/dist/src/tui/controller.js

@@ -1,7 +1,10 @@
 import crypto from 'node:crypto';
+import { CatalogGenerationError } from '../utils/catalog-generation-error.js';
 import { buildTuiViewModel, hasInstalledPlacement, } from './model.js';
 import { safeDiagnosticCode } from './diagnostics.js';
+import { targetHasArtifactCollision } from '../utils/target-eligibility.js';
 import { TuiRouter, } from './router.js';
+import { CatalogRefreshCoordinator, } from './catalog-generation.js';
 function reviewPreparationStageLabel(stage) {
     return {
         validate: '验证当前状态',
@@ -42,7 +45,10 @@ function cloneFrozen(value) {
     return deepFreeze(structuredClone(value));
 }
 export function operationEvidenceFingerprint(evidence) {
-    return crypto.createHash('sha256').update(JSON.stringify(stableValue(evidence))).digest('hex');
+    const { codexManager: _runtimeSelection, ...staleEvidence } = evidence;
+    return crypto.createHash('sha256')
+        .update(JSON.stringify(stableValue(staleEvidence)))
+        .digest('hex');
 }
 function sourceIdFromPluginId(pluginId) {
     const separator = pluginId.indexOf('/');
@@ -69,6 +75,14 @@ function operationLabels(intent) {
             destructive: false,
         };
     }
+    if (intent.kind === 'catalogActivate') {
+        return {
+            title: '使用 Catalog 更新',
+            description: '切换当前 Catalog generation；不会自动升级已安装插件，也不会修改设置。',
+            primaryLabel: '使用已下载的更新',
+            destructive: false,
+        };
+    }
     if (intent.kind === 'pluginWrite') {
         if (intent.originIssue) {
             if (intent.action === 'cleanup') {
@@ -163,7 +177,41 @@ function reviewChanges(intent, evidence, dependencyOverview) {
                     description: review.collisions.map((collision) => collision.name).join('、') }] : []),
         ];
     }
+    if (intent.kind === 'catalogActivate') {
+        const candidate = evidence?.catalogCandidate;
+        if (!candidate) {
+            throw new TuiOperationBlockedError('catalogGenerationCandidateUnavailable', '缺少 Catalog Candidate Review 证据。');
+        }
+        return [
+            {
+                kind: 'change',
+                title: `Catalog ${candidate.activeVersion} → ${candidate.candidateVersion}`,
+                description: `${candidate.channel === 'beta' ? 'Beta' : 'Release'} · ${candidate.requestedRef}`,
+            },
+            {
+                kind: 'change',
+                title: `插件变化 +${candidate.pluginChanges.added}  ~${candidate.pluginChanges.updated}  −${candidate.pluginChanges.removed}`,
+            },
+            { kind: 'keep', title: '已安装插件不会自动升级' },
+            { kind: 'keep', title: '当前设置不会改变' },
+            { kind: 'change', title: '激活后重新加载插件列表和依赖关系' },
+        ];
+    }
     if (intent.kind === 'pluginWrite') {
+        const runtimeChanges = evidence?.codexManager
+            ? [{
+                    kind: evidence.codexManager.state === 'requires-install' ? 'add' : 'keep',
+                    group: 'runtime',
+                    title: evidence.codexManager.state === 'requires-install'
+                        ? '获取 Codex runtime'
+                        : 'Codex runtime',
+                    description: evidence.codexManager.state === 'requires-install'
+                        ? `${evidence.codexManager.packageName}@${evidence.codexManager.version} · AW-managed 缓存`
+                        : evidence.codexManager.state === 'cached'
+                            ? `${evidence.codexManager.packageName}@${evidence.codexManager.version} · 复用 AW-managed 缓存`
+                            : `使用兼容的 system Codex ${evidence.codexManager.version}`,
+                }]
+            : [];
         const plan = evidence?.dependencyPlan;
         if (plan && (intent.action === 'install' || intent.action === 'upgrade' || intent.action === 'reinstall')) {
             const changes = plan.targets.map((target) => {
@@ -188,7 +236,7 @@ function reviewChanges(intent, evidence, dependencyOverview) {
                 title: '插件设置和已有依赖保持不变',
                 description: '移除根插件时不会自动清理依赖。',
             });
-            return changes;
+            return [...changes, ...runtimeChanges];
         }
         const platforms = intent.platform === 'both'
             ? ['codex', 'claude']
@@ -220,17 +268,23 @@ function reviewChanges(intent, evidence, dependencyOverview) {
         if (intent.originIssue) {
             changes.push({ kind: 'keep', title: '插件设置保持不变' }, { kind: 'warning', title: '执行前重新检查完整目标和来源证据' });
         }
-        return changes;
+        return [...changes, ...runtimeChanges];
     }
     if (intent.kind === 'configReset') {
         const layerLabel = intent.scope === 'user'
             ? '个人默认'
             : intent.projectLayer === 'local' ? '当前项目（仅本机）' : '当前项目';
         return [
-            { kind: 'remove', title: `删除${layerLabel}中的已存值`, description: '有效值将恢复为继承值或默认值。' },
-            { kind: 'change', title: '重新计算有效设置' },
-            { kind: 'change', title: '重新应用当前可见安装位置' },
-            { kind: 'keep', title: intent.scope === 'user' ? '当前项目和本机设置层保持不变' : '其他设置层保持不变' },
+            ...(intent.changes?.map((change) => ({
+                kind: 'remove', group: 'configChanges', title: `${layerLabel} · ${change.title}`,
+                description: `${change.before} → ${change.after}`,
+            })) ?? [{ kind: 'remove', group: 'configChanges', title: `删除${layerLabel}中的已存值`, description: '有效值将恢复为继承值或默认值。' }]),
+            ...((evidence?.config?.affectedTargets.length ?? 0) > 0
+                ? evidence.config.affectedTargets.map((target) => ({
+                    kind: 'change', group: 'configImpact', title: `重新应用 ${target.platform === 'codex' ? 'Codex' : 'Claude Code'} · ${target.scope === 'user' ? '所有项目' : '当前项目'}`,
+                }))
+                : [{ kind: 'keep', group: 'configImpact', title: '当前没有可见安装；只保存设置' }]),
+            { kind: 'keep', group: 'preserved', title: intent.scope === 'user' ? '当前项目和本机设置层保持不变' : '其他设置层保持不变' },
         ];
     }
     if (intent.kind === 'sourceMutation') {
@@ -255,17 +309,24 @@ function reviewChanges(intent, evidence, dependencyOverview) {
         throw new TuiOperationBlockedError('operationNotImplemented', '这个写操作尚未接入新 Controller。');
     }
     const privateKeys = new Set([...(intent.sensitiveKeys ?? []), ...(intent.privateKeys ?? [])]);
+    const removeKeys = new Set(intent.removeKeys ?? []);
     if (intent.changes) {
         return [
             ...intent.changes.map((change) => ({
-                kind: 'change',
-                title: change.title,
-                description: privateKeys.has(change.key)
-                    ? change.after === '未设置' ? '已设置 → 未设置' : '已设置 → 将更新'
-                    : `${change.before} → ${change.after}`,
+                kind: removeKeys.has(change.key) ? 'remove' : 'change',
+                group: 'configChanges',
+                title: removeKeys.has(change.key) ? `删除 ${change.title} 中的值` : change.title,
+                description: removeKeys.has(change.key)
+                    ? privateKeys.has(change.key) ? `已设置 → ${change.after}` : `${change.before} → ${change.after}`
+                    : privateKeys.has(change.key) ? '已设置 → 将更新'
+                        : `${change.before} → ${change.after}`,
             })),
-            { kind: 'change', title: '重新应用插件内容', description: '只处理当前可见安装位置。' },
-            { kind: 'keep', title: '其他项目不会被自动扫描' },
+            ...((evidence?.config?.affectedTargets.length ?? 0) > 0
+                ? evidence.config.affectedTargets.map((target) => ({
+                    kind: 'change', group: 'configImpact', title: `重新应用 ${target.platform === 'codex' ? 'Codex' : 'Claude Code'} · ${target.scope === 'user' ? '所有项目' : '当前项目'}`,
+                }))
+                : [{ kind: 'keep', group: 'configImpact', title: '当前没有可见安装；只保存设置' }]),
+            { kind: 'keep', group: 'preserved', title: '其他项目不会被自动扫描' },
         ];
     }
     const updateKeys = Object.keys(intent.updates ?? {});
@@ -283,33 +344,45 @@ function reviewChanges(intent, evidence, dependencyOverview) {
     ];
 }
 function technicalDetails(evidence) {
+    const short = (value) => {
+        const normalized = value.startsWith('sha256:') ? value.slice(7) : value;
+        return normalized.slice(0, 8);
+    };
     const details = [
-        `Catalog 配置：${evidence.catalog.configDigest}`,
-        `Catalog 组合：${evidence.catalog.compositeDigest}`,
+        `Catalog 配置：${short(evidence.catalog.configDigest)}`,
+        `Catalog 组合：${short(evidence.catalog.compositeDigest)}`,
     ];
+    if (evidence.catalog.generationSetDigest) {
+        details.push(`Catalog generation：${short(evidence.catalog.generationSetDigest)}`);
+    }
     if (evidence.source) {
         details.push(`来源：${evidence.source.sourceId}`);
-        details.push(`来源身份：${evidence.source.sourceIdentity}`);
+        if (evidence.source.sourceIdentity)
+            details.push(`来源身份：${short(evidence.source.sourceIdentity)}`);
         if (evidence.source.resolvedCommit)
-            details.push(`Snapshot commit：${evidence.source.resolvedCommit}`);
+            details.push(`Snapshot commit：${short(evidence.source.resolvedCommit)}`);
         if (evidence.source.snapshotDigest)
-            details.push(`Snapshot digest：${evidence.source.snapshotDigest}`);
+            details.push(`Snapshot digest：${short(evidence.source.snapshotDigest)}`);
         if (evidence.source.contentDigest)
-            details.push(`Content digest：${evidence.source.contentDigest}`);
+            details.push(`Content digest：${short(evidence.source.contentDigest)}`);
     }
     if (evidence.targetFingerprint)
-        details.push(`目标状态：${evidence.targetFingerprint}`);
+        details.push(`目标状态：${short(evidence.targetFingerprint)}`);
+    if (evidence.offlineCleanup) {
+        details.push(`离线清理原因：${evidence.offlineCleanup.reason}`);
+        details.push(`离线清理目标：${short(evidence.offlineCleanup.targetFingerprint)}`);
+    }
     if (evidence.dependencyPlan)
         details.push(`安装计划：${evidence.dependencyPlan.resolvedPluginIds.length} 个插件`);
     if (evidence.config)
-        details.push(`设置层：${evidence.config.scope}/${evidence.config.projectLayer} · ${evidence.config.storeDigest}`);
+        details.push(`设置层：${evidence.config.scope}/${evidence.config.projectLayer} · ${short(evidence.config.storeDigest)}`);
     if (evidence.sourceWrite) {
-        details.push(`候选配置：${evidence.sourceWrite.candidateDigest}`);
-        details.push(`引用清单：${evidence.sourceWrite.inventoryDigest} · ${evidence.sourceWrite.referenceCount} 项`);
+        details.push(`候选配置：${short(evidence.sourceWrite.candidateDigest)}`);
+        details.push(`引用清单：${short(evidence.sourceWrite.inventoryDigest)} · ${evidence.sourceWrite.referenceCount} 项`);
     }
     if (evidence.portable) {
         details.push(`Portable 候选：${evidence.portable.selected.length} 个`);
-        details.push(`Materialization：${evidence.portable.materializationDigest}`);
+        details.push(`Materialization：${short(evidence.portable.materializationDigest)}`);
         details.push(`Skills CLI：${evidence.portable.skillsCliVersion}`);
     }
     return details;
@@ -317,6 +390,8 @@ function technicalDetails(evidence) {
 function issueCode(error) {
     if (error instanceof TuiOperationBlockedError)
         return error.code;
+    if (error instanceof CatalogGenerationError)
+        return error.code;
     if (error instanceof Error && error.name === 'CatalogSourcesConfigConflictError') {
         return 'operationReviewStale';
     }
@@ -353,10 +428,12 @@ export class TuiController {
     #tickets = new Map();
     #inflightOperations = new Map();
     #abort = new AbortController();
+    #catalogRefreshCoordinator;
     #progressUnsubscribe;
     #progressFeed;
     #phase = 'idle';
     #status;
+    #catalogGenerations = new Map();
     #viewModel;
     #progress = { messages: [] };
     #progressTargets = [];
@@ -376,6 +453,26 @@ export class TuiController {
     #disposed = false;
     constructor(dependencies, progressFeed) {
         this.dependencies = dependencies;
+        if (dependencies.refreshCatalogSource) {
+            this.#catalogRefreshCoordinator = new CatalogRefreshCoordinator({
+                maxConcurrency: 2,
+                execute: dependencies.refreshCatalogSource,
+                onUpdate: (sourceId, state, errorCode) => {
+                    const current = this.#catalogGenerations.get(sourceId);
+                    if (current) {
+                        this.#catalogGenerations.set(sourceId, {
+                            ...current,
+                            refreshState: state,
+                            ...(errorCode ? { lastCheckCode: errorCode } : {}),
+                        });
+                    }
+                    this.#publish();
+                },
+                onResult: (source) => {
+                    this.#catalogGenerations.set(source.sourceId, structuredClone(source));
+                },
+            });
+        }
         this.#progressFeed = progressFeed;
         if (progressFeed) {
             this.#progressUnsubscribe = progressFeed.subscribe((progress) => {
@@ -407,9 +504,12 @@ export class TuiController {
     get snapshot() {
         return cloneFrozen({
             phase: this.#phase,
+            ...(this.#status?.cliChannel ? { cliChannel: this.#status.cliChannel } : {}),
             router: this.#router.snapshot,
             ...(this.#viewModel ? { viewModel: this.#viewModel } : {}),
             sourceHealth: [...this.#health.values()],
+            catalogGenerations: [...this.#catalogGenerations.values()]
+                .sort((left, right) => left.sourceId.localeCompare(right.sourceId, 'en')),
             progress: this.#progress,
             progressTargets: this.#progressTargets,
             ...(this.#activeReview ? { activeReview: this.#activeReview } : {}),
@@ -495,6 +595,14 @@ export class TuiController {
             && !this.#viewModel?.sourceTabs.some((source) => source.id === route.sourceId)) {
             return { name: 'sourceList' };
         }
+        if ((route.name === 'catalogCandidate'
+            || route.name === 'catalogRefreshPolicy'
+            || route.name === 'catalogRefresh'
+            || route.name === 'catalogImmutableViolation'
+            || route.name === 'catalogActivationBlocked')
+            && !this.#catalogGenerations.has(route.sourceId)) {
+            return { name: 'sourceList' };
+        }
         return route;
     }
     #normalizeCurrentRoute() {
@@ -505,6 +613,12 @@ export class TuiController {
     }
     #applyStatus(status) {
         this.#status = structuredClone(status);
+        if (status.catalogGenerations) {
+            this.#catalogGenerations.clear();
+            for (const source of status.catalogGenerations) {
+                this.#catalogGenerations.set(source.sourceId, structuredClone(source));
+            }
+        }
         this.#health.clear();
         for (const source of status.payload.catalog.sources) {
             this.#health.set(source.id, {
@@ -566,6 +680,10 @@ export class TuiController {
         this.#sourceAborts.clear();
     }
     #startGitSourceRefreshes() {
+        if (this.#catalogRefreshCoordinator) {
+            this.#catalogRefreshCoordinator.start([...this.#catalogGenerations.values()]);
+            return;
+        }
         for (const source of this.#status?.payload.catalog.sources ?? []) {
             if (source.type === 'git')
                 void this.refreshSource(source.id).catch(() => undefined);
@@ -573,6 +691,7 @@ export class TuiController {
     }
     async load() {
         this.#cancelSourceRefreshes();
+        this.dependencies.beginCatalogSession?.();
         const generation = ++this.#generation;
         this.#phase = 'loading';
         this.#publish();
@@ -601,6 +720,10 @@ export class TuiController {
     async refreshSource(sourceId) {
         if (this.#disposed || !this.#status)
             return;
+        if (this.#catalogRefreshCoordinator) {
+            await this.#catalogRefreshCoordinator.refresh(sourceId, this.#catalogGenerations.get(sourceId)?.refreshState ?? 'idle');
+            return;
+        }
         this.#sourceAborts.get(sourceId)?.abort();
         const sourceAbort = new AbortController();
         this.#sourceAborts.set(sourceId, sourceAbort);
@@ -907,9 +1030,11 @@ export class TuiController {
         this.#publish();
     }
     back() {
-        this.#cancelReviewPreparation();
-        this.#cancelPortableRequest();
         const route = this.#router.snapshot.current.route;
+        if (route.name !== 'catalogActivationBlocked' || route.reason !== 'reviewPreparation') {
+            this.#cancelReviewPreparation();
+        }
+        this.#cancelPortableRequest();
         if (route.name === 'review' && this.#activeReview?.operationId === route.operationId) {
             this.#tickets.delete(this.#activeReview.reviewToken);
             this.#activeReview = undefined;
@@ -1067,6 +1192,10 @@ export class TuiController {
             }));
         }
         return plugin.supportedPlatforms.map((platform) => {
+            const statusTarget = this.#status?.payload.targets.find((target) => (target.pluginId === pluginId && target.platform === platform && target.scope === scope));
+            if (statusTarget && targetHasArtifactCollision(statusTarget)) {
+                return { platform, compatible: false, disabled: '存在输出冲突；请先移除或迁移占用内容' };
+            }
             const placement = plugin.installedPlacements.find((entry) => entry.platform === platform);
             if (!placement)
                 return { platform, compatible: false, disabled: '当前没有可信的平台能力信息' };
@@ -1085,6 +1214,16 @@ export class TuiController {
             }
             const overview = this.#viewModel?.dependencyOverviews.find((entry) => entry.pluginId === pluginId);
             for (const dependency of overview?.dependencies ?? []) {
+                const dependencyTarget = this.#status?.payload.targets.find((target) => (target.pluginId === dependency.pluginId
+                    && target.platform === platform
+                    && target.scope === scope));
+                if (dependencyTarget && targetHasArtifactCollision(dependencyTarget)) {
+                    return {
+                        platform,
+                        compatible: false,
+                        disabled: `${dependency.displayName} 存在输出冲突`,
+                    };
+                }
                 const dependentPlugin = this.#viewModel?.plugins.find((entry) => entry.pluginId === dependency.pluginId);
                 if (!dependentPlugin || !dependentPlugin.supportedPlatforms.includes(platform)) {
                     return {
@@ -1128,6 +1267,89 @@ export class TuiController {
             health: this.#health.get(sourceId),
         });
     }
+    listCatalogCandidates() {
+        return cloneFrozen([...this.#catalogGenerations.values()]
+            .filter((source) => source.candidate)
+            .sort((left, right) => left.sourceId.localeCompare(right.sourceId, 'en')));
+    }
+    getCatalogGeneration(sourceId) {
+        const source = this.#catalogGenerations.get(sourceId);
+        return source ? cloneFrozen(source) : undefined;
+    }
+    getSessionCatalogVersion(sourceId) {
+        return this.#status?.payload.catalog.sources.find((source) => source.id === sourceId)?.catalogVersion;
+    }
+    beginCatalogActivation(options) {
+        const source = this.#catalogGenerations.get(options.sourceId);
+        if (!source?.candidate) {
+            throw new TuiOperationBlockedError('catalogGenerationCandidateUnavailable', 'Catalog Candidate 不再可用。请重新检查来源。');
+        }
+        let reason;
+        let preservedLabel;
+        const refreshingSourceId = this.#catalogRefreshCoordinator?.refreshingSourceIds()[0];
+        if (refreshingSourceId) {
+            reason = 'refreshProgress';
+            preservedLabel = options.dirtyDraft
+                ? `${options.dirtyDraft.label}已保留；${refreshingSourceId} Catalog 来源正在刷新`
+                : `${refreshingSourceId} Catalog 来源刷新`;
+        }
+        else if (options.dirtyDraft) {
+            reason = options.dirtyDraft.kind === 'config' ? 'configDraft' : 'sourceDraft';
+            preservedLabel = options.dirtyDraft.label;
+        }
+        else if (this.#portableDraft) {
+            reason = 'portableDraft';
+            preservedLabel = 'Portable Skills 当前选择';
+        }
+        else if (this.#reviewPreparation)
+            reason = 'reviewPreparation';
+        else if (this.#router.snapshot.current.route.name === 'progress') {
+            reason = this.#activeReview?.operationKind === 'sourceMutation'
+                ? 'sourceMutationProgress' : 'writeProgress';
+        }
+        else if (this.#activeReview)
+            reason = 'activeReview';
+        else {
+            const refreshing = [...this.#catalogGenerations.values()].find((candidate) => candidate.refreshState === 'checking'
+                || candidate.refreshState === 'downloading'
+                || candidate.refreshState === 'validating');
+            if (refreshing) {
+                reason = 'refreshProgress';
+                preservedLabel = `${refreshing.sourceId} Catalog 来源刷新`;
+            }
+        }
+        if (reason) {
+            this.#router.push({
+                name: 'catalogActivationBlocked',
+                sourceId: options.sourceId,
+                reason,
+                ...(preservedLabel ? { preservedLabel } : {}),
+            });
+            this.#publish();
+            return undefined;
+        }
+        return this.startReviewPreparation({
+            kind: 'catalogActivate',
+            sourceId: options.sourceId,
+            candidateGenerationKey: source.candidate.generationKey,
+        }, { name: 'catalogCandidate', sourceId: options.sourceId });
+    }
+    cancelCatalogRefresh(sourceId) {
+        this.#catalogRefreshCoordinator?.cancel(sourceId);
+    }
+    async setCatalogRefreshPolicy(sourceId, refreshPolicy) {
+        if (!this.dependencies.setCatalogRefreshPolicy) {
+            throw new TuiOperationBlockedError('catalogGenerationRefreshPolicyUnavailable', 'Catalog 自动刷新设置不可用。');
+        }
+        const source = await this.dependencies.setCatalogRefreshPolicy(sourceId, refreshPolicy);
+        if (this.#disposed)
+            return;
+        const current = this.#catalogGenerations.get(sourceId);
+        this.#catalogGenerations.set(sourceId, current
+            ? { ...current, refreshPolicy: source.refreshPolicy }
+            : structuredClone(source));
+        this.#publish();
+    }
     async inspectSourceRemoval(sourceId) {
         if (!this.dependencies.inspectSourceRemoval) {
             throw new TuiOperationBlockedError('stateInventoryFailed', '来源引用清单不可用。');
@@ -1167,7 +1389,9 @@ export class TuiController {
         catch (error) {
             const code = issueCode(error);
             await this.#logOperationError(error, code, intent);
-            throw new TuiOperationBlockedError(code, '操作未建立。请检查当前设置后重试。');
+            throw new TuiOperationBlockedError(code, code === 'catalogGenerationUnavailable'
+                ? '本次加载时 Catalog 来源不可用。请刷新来源并重新加载后重试。'
+                : '操作未建立。请检查当前设置后重试。');
         }
     }
     startReviewPreparation(intent, returnRoute) {
@@ -1239,11 +1463,12 @@ export class TuiController {
     }
     #reviewPreparationIsCurrent(token) {
         const preparation = this.#reviewPreparation;
+        const route = this.#router.snapshot.current.route;
         return Boolean(preparation && preparation.token === token
             && !preparation.abort.signal.aborted
             && !this.#disposed
-            && this.#router.snapshot.current.route.name === 'reviewPreparing'
-            && this.#router.snapshot.current.route.preparationId === preparation.snapshot.id);
+            && (route.name === 'reviewPreparing' && route.preparationId === preparation.snapshot.id
+                || route.name === 'catalogActivationBlocked' && route.reason === 'reviewPreparation'));
     }
     async #runReviewPreparation(token) {
         const preparation = this.#reviewPreparation;
@@ -1281,13 +1506,16 @@ export class TuiController {
         catch (error) {
             if (!this.#reviewPreparationIsCurrent(token))
                 return;
+            const code = issueCode(error);
             const active = this.#reviewPreparation;
             active.snapshot.state = 'failed';
             active.snapshot.stages = active.snapshot.stages.map((stage) => stage.state === 'running' ? { ...stage, state: 'failed' } : stage);
             active.snapshot.code = 'reviewPreparationFailed';
-            active.snapshot.message = '无法准备确认信息。请返回检查选择，或重试。';
+            active.snapshot.message = code === 'catalogGenerationUnavailable'
+                ? '本次加载时 Catalog 来源不可用。请刷新来源并重新加载后重试。'
+                : '无法准备确认信息。请返回检查选择，或重试。';
             this.#publish();
-            await this.#logOperationError(error, issueCode(error), intent);
+            await this.#logOperationError(error, code, intent);
         }
     }
     async #prepareReviewEvidence(intent, signal, onStage = () => undefined) {
@@ -1361,10 +1589,19 @@ export class TuiController {
                     ? { version: this.#viewModel.plugins.find((plugin) => plugin.pluginId === intent.pluginId).version }
                     : {}),
             },
+            ...(evidence.source && 'catalogVersion' in evidence.source
+                && typeof evidence.source.catalogVersion === 'string'
+                && evidence.source.snapshotDigest
+                ? { catalogBinding: {
+                        sourceId: evidence.source.sourceId,
+                        catalogVersion: evidence.source.catalogVersion,
+                        generationDigestShort: evidence.source.snapshotDigest.replace(/^sha256:/u, '').slice(0, 8),
+                    } }
+                : {}),
             changes: reviewChanges(intent, evidence, 'pluginId' in intent ? this.getPluginDependencyOverview(intent.pluginId) : undefined),
             technicalDetails: technicalDetails(evidence),
-            ...(intent.kind === 'pluginWrite' && intent.action === 'cleanup'
-                ? { equivalentCommand: `aw cleanup ${intent.pluginId} --platform ${intent.platform} --scope ${intent.scope}${intent.force === true ? ' --force' : ''}` }
+            ...(intent.kind === 'pluginWrite'
+                ? { equivalentCommand: `aw ${intent.action} ${intent.pluginId} --platform ${intent.platform} --scope ${intent.scope}${intent.action === 'cleanup' && intent.force === true ? ' --force' : ''}${evidence.codexManager?.state === 'requires-install' ? ' --allow-managed-codex-install' : ''}` }
                 : {}),
             primaryLabel: intent.kind === 'pluginWrite' && evidence.dependencyPlan
                 ? `${labels.primaryLabel} ${evidence.dependencyPlan.resolvedPluginIds.length} 个插件`
@@ -1435,7 +1672,9 @@ export class TuiController {
         this.#publish();
         try {
             this.#assertIssueOrigin(ticket.intent);
-            await this.dependencies.validateIntent?.(structuredClone(ticket.intent), this.#abort.signal);
+            if (ticket.intent.kind !== 'pluginWrite') {
+                await this.dependencies.validateIntent?.(structuredClone(ticket.intent), this.#abort.signal);
+            }
         }
         catch (error) {
             if (!this.#operationIsCurrent(generation))
@@ -1444,6 +1683,9 @@ export class TuiController {
             await this.#logOperationError(error, code, ticket.intent);
             if (!this.#operationIsCurrent(generation))
                 return this.#detachedBlocked(operationId, ticket.intent);
+            if (code === 'operationReviewStale' && ticket.intent.kind === 'catalogActivate') {
+                return this.#rebuildStaleReview(ticket, operationId, undefined, generation);
+            }
             this.#cancelSourceRefreshes();
             generation = ++this.#generation;
             try {
@@ -1465,23 +1707,28 @@ export class TuiController {
         }
         if (!this.#operationIsCurrent(generation))
             return this.#detachedBlocked(operationId, ticket.intent);
-        let current;
-        try {
-            current = await this.dependencies.captureEvidence(structuredClone(ticket.intent), this.#abort.signal);
-        }
-        catch (error) {
-            if (!this.#operationIsCurrent(generation))
-                return this.#detachedBlocked(operationId, ticket.intent);
-            const code = issueCode(error);
-            await this.#logOperationError(error, code, ticket.intent);
+        if (ticket.intent.kind !== 'pluginWrite') {
+            let current;
+            try {
+                current = await this.dependencies.captureEvidence(structuredClone(ticket.intent), this.#abort.signal);
+            }
+            catch (error) {
+                if (!this.#operationIsCurrent(generation))
+                    return this.#detachedBlocked(operationId, ticket.intent);
+                const code = issueCode(error);
+                await this.#logOperationError(error, code, ticket.intent);
+                if (!this.#operationIsCurrent(generation))
+                    return this.#detachedBlocked(operationId, ticket.intent);
+                if (code === 'operationReviewStale' && ticket.intent.kind === 'catalogActivate') {
+                    return this.#rebuildStaleReview(ticket, operationId, undefined, generation);
+                }
+                return this.#setBlocked(operationId, code, { intent: ticket.intent, returnRoute: ticket.returnRoute });
+            }
             if (!this.#operationIsCurrent(generation))
                 return this.#detachedBlocked(operationId, ticket.intent);
-            return this.#setBlocked(operationId, code, { intent: ticket.intent, returnRoute: ticket.returnRoute });
-        }
-        if (!this.#operationIsCurrent(generation))
-            return this.#detachedBlocked(operationId, ticket.intent);
-        if (operationEvidenceFingerprint(current) !== operationEvidenceFingerprint(ticket.evidence)) {
-            return this.#rebuildStaleReview(ticket, operationId, current, generation);
+            if (operationEvidenceFingerprint(current) !== operationEvidenceFingerprint(ticket.evidence)) {
+                return this.#rebuildStaleReview(ticket, operationId, current, generation);
+            }
         }
         if (ticket.intent.kind === 'sourceMutation') {
             this.#cancelSourceRefreshes();
@@ -1499,9 +1746,14 @@ export class TuiController {
                 return this.#detachedBlocked(operationId, ticket.intent);
             this.#cancelSourceRefreshes();
             generation = ++this.#generation;
-            if (ticket.intent.kind === 'sourceMutation') {
+            if (ticket.intent.kind === 'sourceMutation' || ticket.intent.kind === 'catalogActivate') {
+                this.dependencies.beginCatalogSession?.(ticket.intent.kind === 'catalogActivate'
+                    ? { bootstrapMissingActive: false }
+                    : undefined);
                 try {
-                    this.#progressFeed?.setCurrent({ target: 'Catalog 来源配置', phase: '读取最终状态' }, '来源操作：读取最终状态');
+                    this.#progressFeed?.setCurrent({ target: ticket.intent.kind === 'catalogActivate' ? 'Catalog generation' : 'Catalog 来源配置', phase: '读取最终状态' }, ticket.intent.kind === 'catalogActivate'
+                        ? 'Catalog 激活：重新加载当前会话'
+                        : '来源操作：读取最终状态');
                 }
                 catch {
                     // Progress diagnostics must not replace the completed source write.
@@ -1545,6 +1797,17 @@ export class TuiController {
                 && Boolean(hasFailedDependencyTarget);
             if (pluginSummary?.code === 'operationFailed') {
                 const unsuccessfulTargets = pluginSummary.targets?.filter((target) => target.state === 'failed' || target.state === 'skipped') ?? [];
+                const managerFailureCode = unsuccessfulTargets.map((target) => target.errorCode).find((code) => code === 'codexSystemCliUnsupported'
+                    || code === 'managedCodexAuthorizationRequired'
+                    || code === 'managedCodexUnavailable');
+                if (managerFailureCode) {
+                    return this.#setBlocked(operationId, managerFailureCode, {
+                        intent: ticket.intent,
+                        navigation: 'result',
+                        returnRoute: ticket.returnRoute,
+                        summary: pluginSummary,
+                    });
+                }
                 const dependencyStillRequired = unsuccessfulTargets.length > 0
                     && unsuccessfulTargets.every((target) => target.errorCode === 'dependencyStillRequired');
                 return this.#setBlocked(operationId, dependencyStillRequired ? 'dependencyStillRequired' : 'operationFailed', {
@@ -1637,7 +1900,8 @@ export class TuiController {
             this.#activeReview = undefined;
             this.#router.replace({ name: 'result', operationId });
             this.#publish();
-            this.#startGitSourceRefreshes();
+            if (ticket.intent.kind !== 'catalogActivate')
+                this.#startGitSourceRefreshes();
             return cloneFrozen(result);
         }
         catch (error) {
@@ -1689,6 +1953,7 @@ export class TuiController {
     }
     async #rebuildStaleReview(ticket, operationId, currentEvidence, generation = this.#generation) {
         this.#cancelSourceRefreshes();
+        this.dependencies.beginCatalogSession?.({ bootstrapMissingActive: false });
         generation = ++this.#generation;
         try {
             const refreshed = await this.dependencies.loadStatus(this.#abort.signal);
@@ -1706,15 +1971,23 @@ export class TuiController {
                 returnRoute: ticket.returnRoute,
             });
         }
+        const intent = ticket.intent.kind === 'catalogActivate'
+            ? (() => {
+                const candidate = this.#catalogGenerations.get(ticket.intent.sourceId)?.candidate;
+                return candidate
+                    ? { ...ticket.intent, candidateGenerationKey: candidate.generationKey }
+                    : ticket.intent;
+            })()
+            : ticket.intent;
         try {
-            this.#assertIssueOrigin(ticket.intent);
-            await this.dependencies.validateIntent?.(structuredClone(ticket.intent), this.#abort.signal);
+            this.#assertIssueOrigin(intent);
+            await this.dependencies.validateIntent?.(structuredClone(intent), this.#abort.signal);
         }
         catch (error) {
             if (!this.#operationIsCurrent(generation))
                 return this.#detachedBlocked(operationId, ticket.intent);
             const code = issueCode(error);
-            await this.#logOperationError(error, code, ticket.intent);
+            await this.#logOperationError(error, code, intent);
             if (!this.#operationIsCurrent(generation))
                 return this.#detachedBlocked(operationId, ticket.intent);
             const result = {
@@ -1722,7 +1995,7 @@ export class TuiController {
                 operationId,
                 code,
                 message: '状态已变化，原操作不再安全。请修改选择后重试。',
-                ...this.#operationIdentity(ticket.intent),
+                ...this.#operationIdentity(intent),
                 returnRoute: structuredClone(this.#normalizeRoute(ticket.returnRoute)),
             };
             this.#result = structuredClone(result);
@@ -1736,50 +2009,56 @@ export class TuiController {
         let evidence = currentEvidence;
         if (!evidence) {
             try {
-                evidence = await this.dependencies.captureEvidence(structuredClone(ticket.intent), this.#abort.signal);
+                evidence = await this.dependencies.captureEvidence(structuredClone(intent), this.#abort.signal);
             }
             catch (error) {
                 if (!this.#operationIsCurrent(generation))
                     return this.#detachedBlocked(operationId, ticket.intent);
                 const code = issueCode(error);
-                await this.#logOperationError(error, code, ticket.intent);
+                await this.#logOperationError(error, code, intent);
                 if (!this.#operationIsCurrent(generation))
                     return this.#detachedBlocked(operationId, ticket.intent);
-                return this.#setBlocked(operationId, code, { intent: ticket.intent, returnRoute: ticket.returnRoute });
+                return this.#setBlocked(operationId, code, { intent, returnRoute: ticket.returnRoute });
             }
         }
         if (!this.#operationIsCurrent(generation))
             return this.#detachedBlocked(operationId, ticket.intent);
-        if (ticket.intent.kind === 'portableInstall') {
+        if (intent.kind === 'portableInstall') {
             try {
-                await this.refreshPortableInstallDraft(ticket.intent.pluginId);
+                await this.refreshPortableInstallDraft(intent.pluginId);
             }
             catch (error) {
                 if (!this.#operationIsCurrent(generation))
                     return this.#detachedBlocked(operationId, ticket.intent);
                 const code = issueCode(error);
-                await this.#logOperationError(error, code, ticket.intent);
-                return this.#setBlocked(operationId, code, { intent: ticket.intent, returnRoute: ticket.returnRoute });
+                await this.#logOperationError(error, code, intent);
+                return this.#setBlocked(operationId, code, { intent, returnRoute: ticket.returnRoute });
             }
         }
         if (!this.#operationIsCurrent(generation))
             return this.#detachedBlocked(operationId, ticket.intent);
-        const review = this.#storeOperationReview(ticket.intent, evidence, 'replace', ticket.returnRoute);
-        const result = { state: 'stale', operationId, review, ...this.#operationIdentity(ticket.intent) };
+        const review = this.#storeOperationReview(intent, evidence, 'replace', ticket.returnRoute);
+        const result = { state: 'stale', operationId, review, ...this.#operationIdentity(intent) };
         this.#result = result;
         this.#publish();
         return cloneFrozen(result);
     }
     #setBlocked(operationId, code, options) {
-        const message = code === 'portableSkillsCliInstallFailed'
-            ? 'Skills CLI 安装失败。请修改 Agent 或重试。'
-            : options?.writeMayHaveCompleted
-                ? '写入可能已完成，当前无法确认。请查看刷新后的平台或问题状态。'
-                : code === 'configResetStillPresent'
-                    ? '重置执行后设置层仍然存在。请重新检查设置问题。'
-                    : code === 'issueStillPresent'
-                        ? '写入已完成，但重新检查后原问题仍然存在。'
-                        : '操作未完成。请重新检查后重试。';
+        const message = code === 'managedCodexAuthorizationRequired'
+            ? '操作在插件写入前停止。请在 Review 中确认获取 Codex runtime，或在命令行传入 --allow-managed-codex-install。'
+            : code === 'codexSystemCliUnsupported'
+                ? '操作在插件写入前停止。系统 Codex CLI 版本不受支持。请升级官方 Codex CLI 后重试。'
+                : code === 'managedCodexUnavailable'
+                    ? '操作在插件写入前停止。Codex runtime 当前不可用。请重试、升级 AW，或安装官方 Codex CLI。'
+                    : code === 'portableSkillsCliInstallFailed'
+                        ? 'Skills CLI 安装失败。请修改 Agent 或重试。'
+                        : options?.writeMayHaveCompleted
+                            ? '写入可能已完成，当前无法确认。请查看刷新后的平台或问题状态。'
+                            : code === 'configResetStillPresent'
+                                ? '重置执行后设置层仍然存在。请重新检查设置问题。'
+                                : code === 'issueStillPresent'
+                                    ? '写入已完成，但重新检查后原问题仍然存在。'
+                                    : '操作未完成。请重新检查后重试。';
         const result = {
             state: 'blocked',
             operationId,
@@ -1843,13 +2122,17 @@ export class TuiController {
                         ? origin.actionId === 'cleanup' && action.writeAction === 'cleanup'
                             ? { action: 'cleanup', scope: issue.scope }
                             : undefined
-                        : issue.category === 'scopeConflict'
-                            ? origin.actionId === 'keepUserScope'
-                                ? { action: 'uninstall', scope: 'project' }
-                                : origin.actionId === 'keepProjectScope'
-                                    ? { action: 'uninstall', scope: 'user' }
-                                    : undefined
-                            : undefined;
+                        : issue.category === 'sourceMissing'
+                            ? origin.actionId === 'cleanup' && action.writeAction === 'cleanup'
+                                ? { action: 'cleanup', scope: issue.scope }
+                                : undefined
+                            : issue.category === 'scopeConflict'
+                                ? origin.actionId === 'keepUserScope'
+                                    ? { action: 'uninstall', scope: 'project' }
+                                    : origin.actionId === 'keepProjectScope'
+                                        ? { action: 'uninstall', scope: 'user' }
+                                        : undefined
+                                : undefined;
         const dependencyOriginValid = issue.category !== 'dependencyMissing' && issue.category !== 'dependencyNotReady'
             || (origin.consumerPluginId === issue.pluginId
                 && origin.consumerSourceIdentity === issue.sourceIdentity
@@ -1871,6 +2154,7 @@ export class TuiController {
         this.#cancelReviewPreparation();
         this.#cancelPortableRequest();
         this.#abort.abort();
+        this.#catalogRefreshCoordinator?.dispose();
         this.#cancelSourceRefreshes();
         this.#progressUnsubscribe?.();
         this.#tickets.clear();
@@ -1879,6 +2163,13 @@ export class TuiController {
     }
 }
 function operationResultSummary(intent, execution) {
+    if (intent.kind === 'catalogActivate') {
+        return {
+            code: 'operationSucceeded',
+            message: 'Catalog 更新已启用；插件列表和依赖关系已重新加载。',
+            messages: ['已安装插件没有自动升级。', '插件设置没有改变。'],
+        };
+    }
     if (intent.kind === 'portableInstall') {
         const receipt = execution;
         const verificationUnknown = receipt.failures.some((failure) => failure.code === 'portableSkillsCliVerificationFailed'
@@ -1950,7 +2241,10 @@ function operationResultSummary(intent, execution) {
                     requiredBy: planned.requiredBy,
                 } : {}),
                 ...(entry.errorCode === 'dependencyStillRequired'
-                    ? { errorCode: 'dependencyStillRequired' }
+                    || entry.errorCode === 'codexSystemCliUnsupported'
+                    || entry.errorCode === 'managedCodexAuthorizationRequired'
+                    || entry.errorCode === 'managedCodexUnavailable'
+                    ? { errorCode: entry.errorCode }
                     : {}),
             }];
     });