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

package/dist/src/tui/controller.js

@@ -1,6 +1,9 @@
 import crypto from 'node:crypto';
-import { buildTuiViewModel, hasInstalledPlacement, } from './model.js';
+import { CatalogGenerationError } from '../utils/catalog-generation-error.js';
+import { requestedIntentAction } from '../output/command-receipt.js';
+import { buildTuiViewModel, dependencyPlacementTargets, hasInstalledPlacement, } from './model.js';
 import { safeDiagnosticCode } from './diagnostics.js';
+import { targetHasArtifactCollision } from '../utils/target-eligibility.js';
 import { TuiRouter, } from './router.js';
 function reviewPreparationStageLabel(stage) {
     return {
@@ -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,22 @@ function operationLabels(intent) {
             destructive: false,
         };
     }
+    if (intent.kind === 'pluginWrite' && intent.dependencyPlacementOnly === 'desired') {
+        return {
+            title: '调整依赖位置',
+            description: '先更新当前项目的 desired placement；不会删除所有项目中的实际内容。',
+            primaryLabel: '更新 desired placement',
+            destructive: false,
+        };
+    }
+    if (intent.kind === 'pluginWrite' && intent.dependencyPlacementAdjustment) {
+        return {
+            title: '调整依赖位置',
+            description: '按最终依赖位置更新 desired intent，并应用非破坏性变更。',
+            primaryLabel: '应用依赖位置',
+            destructive: false,
+        };
+    }
     if (intent.kind === 'pluginWrite') {
         if (intent.originIssue) {
             if (intent.action === 'cleanup') {
@@ -100,6 +122,7 @@ function operationLabels(intent) {
             reinstall: ['重新安装插件', '清理 AW 管理的内容后完整重建。', true],
             uninstall: ['移除插件', '移除 AW 管理的安装内容。配置保持不变。', true],
             cleanup: ['清理插件', '只移除可证明属于 AW 的现场内容。配置保持不变。', true],
+            sync: ['同步插件', '按已保存的 desired intent 修复当前现场。', false],
         };
         const [title, description, destructive] = labels[intent.action];
         return { title, description, primaryLabel: title, destructive };
@@ -122,8 +145,8 @@ function operationLabels(intent) {
     }
     if (intent.kind === 'sourceMutation') {
         const labels = {
-            add: ['添加来源', '先保存来源配置，再尽力刷新来源。刷新失败时配置仍保留。', '保存并刷新', false],
-            update: ['修改来源', '先保存来源配置，再尽力刷新来源。刷新失败时配置仍保留。', '保存并刷新', false],
+            add: ['添加来源', '只保存来源配置。保存后请在终端运行 source sync。', '保存来源', false],
+            update: ['修改来源', '只保存来源配置。保存后请在终端运行 source sync。', '保存来源', false],
             setPrimary: ['设为主来源', '只改变默认 marketplace，不迁移安装。', '设为主来源', false],
             remove: ['移除来源', '移除来源配置；不会删除其它来源。', '移除来源', true],
         };
@@ -164,42 +187,138 @@ function reviewChanges(intent, evidence, dependencyOverview) {
         ];
     }
     if (intent.kind === 'pluginWrite') {
+        const desiredIntentKind = requestedIntentAction(intent.action);
+        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 codexChanges = (evidence?.codexReconcilePlans ?? []).flatMap((codexPlan) => [
+            ...codexPlan.sharedNativeActions.map((action) => ({
+                kind: action.action === 'reuse' || action.action === 'claim' || action.action === 'none' ? 'keep'
+                    : action.action === 'install' ? 'add' : 'change',
+                group: 'sharedCodexNative',
+                pluginId: action.pluginId,
+                title: action.action === 'claim'
+                    ? `${action.codexPluginId}：复用精确现有 shared native（不建立 ledger）`
+                    : action.codexPluginId,
+                description: action.action === 'claim'
+                    ? '复用已存在的精确 shared native；不建立 ownership ledger'
+                    : `${action.action} · shared${action.affectsOtherScopes ? ' · 可能影响其他项目' : ''}`,
+            })),
+            ...codexPlan.activationActions.user.map((action) => ({
+                kind: action.action === 'none' ? 'keep' : action.desired ? 'change' : 'remove',
+                group: 'userActivation',
+                pluginId: action.pluginId,
+                title: action.codexPluginId,
+                description: `desired=${String(action.desired)} · ${action.action}`,
+            })),
+            ...codexPlan.activationActions.project.map((action) => ({
+                kind: action.action === 'none' ? 'keep' : action.desired ? 'change' : 'remove',
+                group: 'projectActivation',
+                pluginId: action.pluginId,
+                title: action.codexPluginId,
+                description: `desired=${String(action.desired)} · ${action.action}`,
+            })),
+            ...[...codexPlan.extensionWrites, ...codexPlan.extensionRemovals]
+                .map((action) => ({
+                kind: action.action === 'write' ? 'change' : 'remove',
+                group: 'awExtensions',
+                pluginId: action.pluginId,
+                title: action.componentKey,
+                description: `${action.scope} · ${action.action}`,
+            })),
+        ]);
         const plan = evidence?.dependencyPlan;
-        if (plan && (intent.action === 'install' || intent.action === 'upgrade' || intent.action === 'reinstall')) {
+        if (plan && (intent.action === 'install' || intent.action === 'upgrade'
+            || intent.action === 'reinstall' || intent.action === 'sync')) {
             const changes = plan.targets.map((target) => {
                 const relation = dependencyRelation(plan, target.pluginId);
-                const actionKind = target.action === 'keep'
-                    ? 'keep'
-                    : target.action === 'install'
-                        ? 'add'
-                        : 'change';
                 return {
-                    kind: actionKind,
-                    group: relation === 'requested' ? 'requested' : 'dependencies',
+                    kind: desiredIntentKind,
+                    group: target.resolvedScope === 'project' ? 'projectIntent' : 'userIntent',
                     pluginId: target.pluginId,
                     relation,
                     title: pluginNameFromId(target.pluginId),
-                    description: `${target.platform === 'codex' ? 'Codex' : 'Claude Code'} · ${target.resolvedScope === 'user' ? '所有项目' : '当前项目'}${target.action === 'keep' ? ' · 已可用' : ''}`,
+                    description: `${target.platform === 'codex' ? 'Codex' : 'Claude Code'} · ${target.resolvedScope === 'user' ? '所有项目' : '当前项目'}${target.action === 'keep' ? ' · 已可用' : ''}${target.assignmentSource === 'existingWiderTarget' ? ' · 复用健康的所有项目安装' : target.assignmentSource === 'consumerPromotion' ? ' · 随上游依赖一并调整' : ''}`,
                 };
             });
             changes.push({
                 kind: 'keep',
                 group: 'preserved',
-                title: '插件设置和已有依赖保持不变',
-                description: '移除根插件时不会自动清理依赖。',
+                title: intent.dependencyPlacementAdjustment
+                    ? '根插件和插件设置保持不变'
+                    : '插件设置和已有依赖保持不变',
+                description: intent.dependencyPlacementAdjustment
+                    ? '这里只调整所列 dependency placement。'
+                    : '移除根插件时不会自动清理依赖。',
             });
-            return changes;
+            if (intent.dependencyPlacementOnly === 'desired') {
+                changes.push({
+                    kind: desiredIntentKind,
+                    group: 'projectIntent',
+                    title: '先更新依赖 desired placement',
+                    description: '这一步不删除所有项目中的实际内容。',
+                }, {
+                    kind: 'warning',
+                    group: 'preserved',
+                    title: '后续第 1 步：显式 user cleanup；不自动扫描/清理',
+                    description: '请在已知的所有项目位置确认 cleanup。',
+                }, {
+                    kind: 'keep',
+                    group: 'preserved',
+                    title: '后续第 2 步：同步当前项目',
+                    description: 'cleanup 完成后运行当前项目 sync。',
+                });
+                return changes;
+            }
+            return [...changes, ...codexChanges, ...runtimeChanges];
         }
         const platforms = intent.platform === 'both'
             ? ['codex', 'claude']
             : [intent.platform];
         const changes = platforms.map((platform) => ({
+            kind: desiredIntentKind,
+            group: intent.scope === 'project' ? 'projectIntent' : 'userIntent',
+            pluginId: intent.pluginId,
+            relation: 'requested',
+            title: pluginNameFromId(intent.pluginId),
+            description: `${platform === 'codex' ? 'Codex' : 'Claude Code'} · ${intent.scope === 'user' ? '所有项目' : '当前项目'}`,
+        }));
+        changes.push(...platforms.map((platform) => ({
             kind: intent.action === 'uninstall' || intent.action === 'cleanup' ? 'remove' : intent.action === 'install' ? 'add' : 'change',
+            group: 'requested',
+            pluginId: intent.pluginId,
+            relation: 'requested',
             title: `${platform === 'codex' ? 'Codex' : 'Claude Code'} · ${intent.scope === 'user' ? '所有项目' : '当前项目'}`,
             description: intent.action === 'uninstall' || intent.action === 'cleanup'
                 ? '插件设置不会删除。'
                 : '执行前会再次检查当前安装状态。',
-        }));
+        })));
+        if (intent.action === 'cleanup' && evidence?.offlineCleanup) {
+            const actionLabels = {
+                removeOwnedOutput: '移除 AW-owned 输出',
+                removeNativeRegistration: '移除原生插件注册',
+                removeLifecycleSnapshot: '移除 lifecycle snapshot',
+            };
+            changes.push(...evidence.offlineCleanup.plan.actions.map((action) => ({
+                kind: 'remove',
+                group: 'requested',
+                pluginId: evidence.offlineCleanup.pluginId,
+                relation: 'requested',
+                title: actionLabels[action.action],
+                description: action.target,
+            })));
+        }
         if (intent.action === 'uninstall' || intent.action === 'cleanup') {
             changes.push(...(dependencyOverview?.dependencies ?? []).map((dependency) => ({
                 kind: 'keep',
@@ -220,17 +339,31 @@ function reviewChanges(intent, evidence, dependencyOverview) {
         if (intent.originIssue) {
             changes.push({ kind: 'keep', title: '插件设置保持不变' }, { kind: 'warning', title: '执行前重新检查完整目标和来源证据' });
         }
-        return changes;
+        if (intent.recoveryDescription) {
+            changes.push({
+                kind: 'warning',
+                group: 'preserved',
+                title: `后续：${intent.scope === 'user' ? '当前项目' : '所有项目'} sync`,
+                description: intent.recoveryDescription,
+            });
+        }
+        return [...changes, ...codexChanges, ...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 +388,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 +423,51 @@ 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)}`);
+        details.push(`离线清理计划：${evidence.offlineCleanup.plan.actions.length} 个动作 · ${short(evidence.offlineCleanup.planDigest)}`);
+        for (const action of evidence.offlineCleanup.plan.actions) {
+            details.push(`离线清理动作：${action.action} · ${action.target}`);
+        }
+    }
     if (evidence.dependencyPlan)
         details.push(`安装计划：${evidence.dependencyPlan.resolvedPluginIds.length} 个插件`);
+    if (evidence.projectIntentDigest)
+        details.push(`Project intent：${short(evidence.projectIntentDigest)}`);
     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.proposedConfigDigest)}`);
+        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 +475,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';
     }
@@ -347,9 +507,6 @@ export class TuiController {
     #router = new TuiRouter();
     #listeners = new Set();
     #health = new Map();
-    #sourceTokens = new Map();
-    #successfulSourceRefreshes = new Map();
-    #sourceAborts = new Map();
     #tickets = new Map();
     #inflightOperations = new Map();
     #abort = new AbortController();
@@ -357,6 +514,8 @@ export class TuiController {
     #progressFeed;
     #phase = 'idle';
     #status;
+    #catalogGenerations = new Map();
+    #sessionGenerationKeys = new Map();
     #viewModel;
     #progress = { messages: [] };
     #progressTargets = [];
@@ -370,9 +529,10 @@ export class TuiController {
     #portableRequestToken = 0;
     #portableRequestAbort;
     #portablePending;
+    #installPlacementDraft;
+    #installPlacementRequestToken = 0;
+    #installPlacementRequestAbort;
     #generation = 0;
-    #refreshSequence = 0;
-    #appliedRefreshSequence = 0;
     #disposed = false;
     constructor(dependencies, progressFeed) {
         this.dependencies = dependencies;
@@ -407,9 +567,13 @@ 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')),
+            reloadRequiredSourceIds: [],
             progress: this.#progress,
             progressTargets: this.#progressTargets,
             ...(this.#activeReview ? { activeReview: this.#activeReview } : {}),
@@ -417,6 +581,20 @@ export class TuiController {
             ...(this.#result ? { result: this.#result } : {}),
             ...(this.#loadError ? { loadError: this.#loadError } : {}),
             ...(this.#portableDraft ? { portableDraft: this.#portableDraft } : {}),
+            ...(this.#installPlacementDraft
+                ? { installPlacementDraft: {
+                        pluginId: this.#installPlacementDraft.pluginId,
+                        rootScope: this.#installPlacementDraft.rootScope,
+                        platforms: this.#installPlacementDraft.platforms,
+                        dependencyScopeOverrides: this.#installPlacementDraft.dependencyScopeOverrides,
+                        state: this.#installPlacementDraft.state,
+                        targets: this.#installPlacementDraft.targets,
+                        canContinue: this.#installPlacementDraft.canContinue,
+                        ...(this.#installPlacementDraft.error
+                            ? { error: this.#installPlacementDraft.error }
+                            : {}),
+                    } }
+                : {}),
         });
     }
     subscribe(listener) {
@@ -467,6 +645,8 @@ export class TuiController {
             || route.name === 'pluginDependencies'
             || route.name === 'installPlacement'
             || route.name === 'installTargets'
+            || route.name === 'dependencyPlacement'
+            || route.name === 'dependencyPlacementEditor'
             || route.name === 'pluginDetail'
             || route.name === 'platform'
             || route.name === 'pluginAbout'
@@ -480,6 +660,7 @@ export class TuiController {
                 name: 'pluginList',
                 mode: route.name === 'pluginPreview' || route.name === 'pluginDependencies'
                     || route.name === 'installPlacement' || route.name === 'installTargets'
+                    || route.name === 'dependencyPlacement' || route.name === 'dependencyPlacementEditor'
                     ? 'browse'
                     : 'installed',
             };
@@ -505,74 +686,32 @@ 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.#sessionGenerationKeys.clear();
+        if (status.sessionGenerationKeys) {
+            for (const [sourceId, generationKey] of Object.entries(status.sessionGenerationKeys)) {
+                this.#sessionGenerationKeys.set(sourceId, generationKey);
+            }
+        }
         this.#health.clear();
         for (const source of status.payload.catalog.sources) {
             this.#health.set(source.id, {
                 sourceId: source.id,
                 state: source.error ? 'unavailable'
-                    : source.type === 'path' ? 'path'
-                        : source.freshness === 'cache' ? 'cache' : 'ready',
+                    : 'ready',
                 ...(source.error ? { message: '来源当前没有可用数据。' } : {}),
             });
-            const successful = this.#successfulSourceRefreshes.get(source.id);
-            if (successful?.generation === this.#generation
-                && successful.sourceIdentity === source.identity
-                && successful.requestedRef === source.requestedRef
-                && !source.error) {
-                this.#health.set(source.id, {
-                    sourceId: source.id,
-                    state: source.type === 'path' || source.freshness === 'path' ? 'path' : 'ready',
-                });
-            }
-        }
-        const sourceIds = new Set(status.payload.catalog.sources.map((source) => source.id));
-        for (const sourceId of this.#successfulSourceRefreshes.keys()) {
-            if (!sourceIds.has(sourceId))
-                this.#successfulSourceRefreshes.delete(sourceId);
         }
         this.#project();
         this.#normalizeCurrentRoute();
     }
-    #applyRefreshStatus(status, sourceId, health, refreshSequence) {
-        if (refreshSequence < this.#appliedRefreshSequence)
-            return false;
-        this.#appliedRefreshSequence = refreshSequence;
-        this.#applyStatus(status);
-        if (!status.payload.catalog.sources.some((source) => source.id === sourceId))
-            return true;
-        this.#health.set(sourceId, health);
-        this.#project();
-        return true;
-    }
-    #recordSuccessfulSourceRefresh(sourceId, checked, generation) {
-        const authoritative = this.#status?.payload.catalog.sources.find((source) => source.id === sourceId);
-        if (!authoritative || authoritative.type !== 'git' || authoritative.error
-            || authoritative.identity !== checked.sourceIdentity
-            || authoritative.requestedRef !== checked.requestedRef)
-            return;
-        this.#successfulSourceRefreshes.set(sourceId, {
-            generation,
-            sourceIdentity: checked.sourceIdentity,
-            requestedRef: checked.requestedRef,
-        });
-        this.#health.set(sourceId, {
-            sourceId,
-            state: 'ready',
-        });
-    }
-    #cancelSourceRefreshes() {
-        for (const abort of this.#sourceAborts.values())
-            abort.abort();
-        this.#sourceAborts.clear();
-    }
-    #startGitSourceRefreshes() {
-        for (const source of this.#status?.payload.catalog.sources ?? []) {
-            if (source.type === 'git')
-                void this.refreshSource(source.id).catch(() => undefined);
-        }
-    }
     async load() {
-        this.#cancelSourceRefreshes();
+        this.dependencies.beginCatalogSession?.();
         const generation = ++this.#generation;
         this.#phase = 'loading';
         this.#publish();
@@ -596,121 +735,11 @@ export class TuiController {
         this.#phase = 'ready';
         this.#loadError = undefined;
         this.#publish();
-        this.#startGitSourceRefreshes();
-    }
-    async refreshSource(sourceId) {
-        if (this.#disposed || !this.#status)
-            return;
-        this.#sourceAborts.get(sourceId)?.abort();
-        const sourceAbort = new AbortController();
-        this.#sourceAborts.set(sourceId, sourceAbort);
-        const finishRefresh = () => {
-            if (this.#sourceAborts.get(sourceId) === sourceAbort)
-                this.#sourceAborts.delete(sourceId);
-        };
-        const signal = AbortSignal.any([this.#abort.signal, sourceAbort.signal]);
-        const token = (this.#sourceTokens.get(sourceId) ?? 0) + 1;
-        this.#sourceTokens.set(sourceId, token);
-        const generation = this.#generation;
-        const current = this.#status.payload.catalog.sources.find((source) => source.id === sourceId);
-        if (!current) {
-            finishRefresh();
-            return;
-        }
-        const hadCache = current.type === 'git' && current.error === undefined
-            && (current.freshness === 'cache' || current.freshness === 'remote');
-        this.#health.set(sourceId, { sourceId, state: 'checking' });
-        this.#project();
-        this.#publish();
-        let checkError;
-        let checked;
-        try {
-            checked = await this.dependencies.checkSource(sourceId, signal);
-        }
-        catch (error) {
-            checkError = error;
-        }
-        if (this.#disposed || signal.aborted || generation !== this.#generation
-            || token !== this.#sourceTokens.get(sourceId)) {
-            finishRefresh();
-            return;
-        }
-        if (checkError)
-            this.#successfulSourceRefreshes.delete(sourceId);
-        const refreshSequence = ++this.#refreshSequence;
-        let status;
-        let authoritativeReloadSucceeded = true;
-        try {
-            status = await this.dependencies.loadStatus(signal);
-        }
-        catch (error) {
-            authoritativeReloadSucceeded = false;
-            if (!checkError)
-                checkError = error;
-            this.#successfulSourceRefreshes.delete(sourceId);
-            status = structuredClone(this.#status);
-        }
-        if (this.#disposed || signal.aborted || generation !== this.#generation
-            || token !== this.#sourceTokens.get(sourceId)) {
-            finishRefresh();
-            return;
-        }
-        if (checkError) {
-            await this.#logErrorSafe(checkError, 'catalogSourceRefreshFailed', {
-                privateConfigOperation: true,
-            });
-        }
-        const refreshed = status.payload.catalog.sources.find((source) => source.id === sourceId);
-        const refreshedMatchesCheck = checked !== undefined && refreshed !== undefined
-            && refreshed.type === 'git'
-            && !refreshed.error
-            && refreshed.identity === checked.sourceIdentity
-            && refreshed.requestedRef === checked.requestedRef;
-        const state = checkError
-            ? authoritativeReloadSucceeded
-                ? !refreshed || refreshed.error
-                    ? 'unavailable'
-                    : refreshed.type === 'path' || refreshed.freshness === 'path'
-                        ? 'path'
-                        : refreshed.freshness === 'cache' ? 'degraded' : 'unavailable'
-                : hadCache ? 'degraded' : 'unavailable'
-            : !refreshed
-                ? 'unavailable'
-                : refreshed.error
-                    ? 'unavailable'
-                    : !refreshedMatchesCheck
-                        ? refreshed.type === 'path' || refreshed.freshness === 'path'
-                            ? 'path'
-                            : refreshed.freshness === 'cache' ? 'cache' : 'unavailable'
-                        : refreshed.type === 'path' || refreshed.freshness === 'path'
-                            ? 'path'
-                            : 'ready';
-        this.#applyRefreshStatus(status, sourceId, {
-            sourceId,
-            state,
-            ...(state === 'degraded' || state === 'unavailable' ? {
-                issueId: `source:${sourceId}:${state === 'degraded' ? 'cache' : 'unavailable'}`,
-                message: checkError
-                    ? state === 'degraded'
-                        ? '远端检查失败。当前仍使用已验证的缓存数据。'
-                        : '远端检查失败，并且没有可用缓存数据。'
-                    : state === 'degraded'
-                        ? '远端检查后仍只能使用缓存数据。'
-                        : '来源检查后没有可用数据。',
-            } : {}),
-        }, refreshSequence);
-        if (!checkError && refreshedMatchesCheck && checked) {
-            this.#recordSuccessfulSourceRefresh(sourceId, checked, generation);
-        }
-        finishRefresh();
-        if (generation !== this.#generation)
-            return;
-        this.#project();
-        this.#publish();
     }
     push(route, context) {
         this.#cancelReviewPreparation();
         this.#cancelPortableRequest();
+        this.#cancelInstallPlacementRequest();
         this.#discardPortableDraftForRoute(route);
         this.#router.push(route, context);
         this.#publish();
@@ -881,6 +910,7 @@ export class TuiController {
     replace(route, context) {
         this.#cancelReviewPreparation();
         this.#cancelPortableRequest();
+        this.#cancelInstallPlacementRequest();
         const current = this.#router.snapshot.current.route;
         if (current.name === 'portableBlocker' && current.code === 'requiredConfigMissing'
             && route.name === 'configLayer' && route.pluginId === current.pluginId) {
@@ -907,9 +937,10 @@ export class TuiController {
         this.#publish();
     }
     back() {
+        const route = this.#router.snapshot.current.route;
         this.#cancelReviewPreparation();
         this.#cancelPortableRequest();
-        const route = this.#router.snapshot.current.route;
+        this.#cancelInstallPlacementRequest();
         if (route.name === 'review' && this.#activeReview?.operationId === route.operationId) {
             this.#tickets.delete(this.#activeReview.reviewToken);
             this.#activeReview = undefined;
@@ -1023,6 +1054,213 @@ export class TuiController {
             throw new DOMException('Portable request was cancelled.', 'AbortError');
         }
     }
+    beginInstallFlow(pluginId, rootScope, options = {}) {
+        this.#cancelInstallPlacementRequest();
+        this.#installPlacementDraft = {
+            pluginId,
+            rootScope,
+            platforms: [],
+            dependencyScopeOverrides: [],
+            state: 'selecting',
+            targets: [],
+            canContinue: false,
+            adjustingExisting: options.adjustingExisting === true,
+            revalidateOverrides: false,
+        };
+        this.#publish();
+    }
+    setInstallRootScope(rootScope) {
+        const draft = this.#installPlacementDraft;
+        if (!draft)
+            return;
+        this.#cancelInstallPlacementRequest();
+        draft.rootScope = rootScope;
+        draft.platforms = [];
+        draft.revalidateOverrides = true;
+        draft.plan = undefined;
+        draft.targets = [];
+        draft.state = 'selecting';
+        draft.canContinue = false;
+        draft.error = undefined;
+        this.#publish();
+    }
+    setInstallPlatforms(platforms) {
+        const draft = this.#installPlacementDraft;
+        if (!draft)
+            return;
+        this.#cancelInstallPlacementRequest();
+        const selected = [...new Set(platforms)].sort();
+        draft.platforms = selected;
+        draft.dependencyScopeOverrides = draft.dependencyScopeOverrides.filter((override) => selected.includes(override.platform));
+        draft.revalidateOverrides = true;
+        draft.plan = undefined;
+        draft.targets = [];
+        draft.state = 'selecting';
+        draft.canContinue = selected.length > 0;
+        draft.error = undefined;
+        this.#publish();
+    }
+    #cancelInstallPlacementRequest() {
+        const cancelled = this.#installPlacementRequestAbort !== undefined;
+        this.#installPlacementRequestToken += 1;
+        this.#installPlacementRequestAbort?.abort();
+        this.#installPlacementRequestAbort = undefined;
+        if (cancelled && this.#installPlacementDraft?.state === 'loading') {
+            this.#installPlacementDraft.plan = undefined;
+            this.#installPlacementDraft.targets = [];
+            this.#installPlacementDraft.state = 'selecting';
+            this.#installPlacementDraft.canContinue = false;
+            this.#installPlacementDraft.error = undefined;
+        }
+    }
+    #installPlacementIntent() {
+        const draft = this.#installPlacementDraft;
+        if (!draft || draft.platforms.length === 0) {
+            throw new TuiOperationBlockedError('installPlacementIncomplete', '请先明确选择目标平台。');
+        }
+        return {
+            kind: 'pluginWrite',
+            action: 'install',
+            pluginId: draft.pluginId,
+            platform: draft.platforms.length === 2 ? 'both' : draft.platforms[0],
+            scope: draft.rootScope,
+            ...(draft.dependencyScopeOverrides.length > 0
+                ? { dependencyScopeOverrides: draft.dependencyScopeOverrides }
+                : {}),
+            ...(draft.adjustingExisting ? { dependencyPlacementAdjustment: true } : {}),
+        };
+    }
+    async prepareInstallDependencyPlacement() {
+        const draft = this.#installPlacementDraft;
+        if (!draft)
+            throw new TuiOperationBlockedError('installPlacementMissing', '安装位置草稿不存在。');
+        this.#cancelInstallPlacementRequest();
+        const abort = new AbortController();
+        this.#installPlacementRequestAbort = abort;
+        const token = this.#installPlacementRequestToken;
+        draft.state = 'loading';
+        draft.canContinue = false;
+        draft.error = undefined;
+        this.#publish();
+        try {
+            const signal = AbortSignal.any([this.#abort.signal, abort.signal]);
+            const preview = async (intent) => this.dependencies.previewDependencyPlacement
+                ? this.dependencies.previewDependencyPlacement(structuredClone(intent), signal)
+                : (await this.dependencies.captureEvidence(structuredClone(intent), signal)).dependencyPlan;
+            const throwIfCancelled = () => {
+                if (this.#disposed || token !== this.#installPlacementRequestToken || abort.signal.aborted) {
+                    throw new DOMException('Dependency placement preview was cancelled.', 'AbortError');
+                }
+            };
+            const filterOverrides = (plan) => {
+                const before = draft.dependencyScopeOverrides;
+                const filtered = before.filter((override) => {
+                    const target = plan?.targets.find((candidate) => candidate.relation === 'dependency'
+                        && candidate.pluginId === override.pluginId
+                        && candidate.platform === override.platform);
+                    return Boolean(target
+                        && target.allowedScopes.includes(override.scope)
+                        && !(target.minimumScope === 'user' && override.scope === 'project'));
+                });
+                if (filtered.length === before.length)
+                    return false;
+                draft.dependencyScopeOverrides = filtered;
+                return true;
+            };
+            let plan;
+            if (draft.revalidateOverrides && draft.dependencyScopeOverrides.length > 0) {
+                const baselineIntent = this.#installPlacementIntent();
+                delete baselineIntent.dependencyScopeOverrides;
+                const baselinePlan = await preview(baselineIntent);
+                throwIfCancelled();
+                filterOverrides(baselinePlan);
+                plan = draft.dependencyScopeOverrides.length > 0
+                    ? await preview(this.#installPlacementIntent())
+                    : baselinePlan;
+                throwIfCancelled();
+                if (filterOverrides(plan)) {
+                    plan = await preview(this.#installPlacementIntent());
+                    throwIfCancelled();
+                }
+            }
+            else {
+                plan = await preview(this.#installPlacementIntent());
+            }
+            throwIfCancelled();
+            draft.revalidateOverrides = false;
+            if (!plan) {
+                draft.state = 'ready';
+                draft.plan = undefined;
+                draft.targets = [];
+                draft.canContinue = true;
+                this.#publish();
+                return false;
+            }
+            draft.plan = structuredClone(plan);
+            draft.targets = dependencyPlacementTargets(plan);
+            const blocker = plan.targets.find((target) => target.action === 'block');
+            draft.state = blocker ? 'blocked' : 'ready';
+            draft.canContinue = !blocker;
+            draft.error = blocker
+                ? {
+                    code: blocker.errorCode ?? 'dependencyPlacementBlocked',
+                    message: '依赖位置不能满足所选根插件和目标平台。',
+                }
+                : undefined;
+            this.#publish();
+            return draft.targets.some((target) => !target.locked);
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === 'AbortError')
+                throw error;
+            const code = issueCode(error);
+            draft.state = 'blocked';
+            draft.canContinue = false;
+            draft.error = { code, message: '无法计算可信的依赖位置。请返回检查选择。' };
+            this.#publish();
+            throw error;
+        }
+        finally {
+            if (token === this.#installPlacementRequestToken) {
+                this.#installPlacementRequestAbort = undefined;
+            }
+        }
+    }
+    async setDependencyScope(pluginId, platform, scope) {
+        const draft = this.#installPlacementDraft;
+        const target = draft?.targets.find((entry) => entry.pluginId === pluginId && entry.platform === platform);
+        if (!draft || !target || target.locked || !target.allowedScopes.includes(scope)
+            || target.minimumScope === 'user' && scope === 'project') {
+            throw new TuiOperationBlockedError('dependencyScopeOverrideInvalid', '这个依赖不支持所选位置。');
+        }
+        draft.dependencyScopeOverrides = [
+            ...draft.dependencyScopeOverrides.filter((override) => override.pluginId !== pluginId || override.platform !== platform),
+            { pluginId, platform, scope },
+        ].sort((left, right) => `${left.pluginId}\0${left.platform}`
+            .localeCompare(`${right.pluginId}\0${right.platform}`, 'en'));
+        draft.revalidateOverrides = false;
+        await this.prepareInstallDependencyPlacement();
+    }
+    async resetDependencyScopes() {
+        const draft = this.#installPlacementDraft;
+        if (!draft)
+            return;
+        draft.dependencyScopeOverrides = [];
+        draft.revalidateOverrides = false;
+        await this.prepareInstallDependencyPlacement();
+    }
+    installPlacementIntent() {
+        const intent = this.#installPlacementIntent();
+        const narrowsUserTarget = this.#installPlacementDraft?.plan?.targets.some((target) => {
+            if (target.relation !== 'dependency' || target.resolvedScope !== 'project')
+                return false;
+            const persistedScopes = new Set(this.#status?.payload.targets.flatMap((candidate) => candidate.pluginId === target.pluginId && candidate.platform === target.platform
+                ? candidate.desired?.scopes ?? []
+                : []) ?? []);
+            return persistedScopes.has('user') && !persistedScopes.has('project');
+        });
+        return narrowsUserTarget ? { ...intent, dependencyPlacementOnly: 'desired' } : intent;
+    }
     listPlugins(options) {
         const query = options.query?.trim().toLocaleLowerCase('en');
         return cloneFrozen((this.#viewModel?.plugins ?? []).filter((plugin) => (!options.sourceId || plugin.sourceId === options.sourceId)
@@ -1067,47 +1305,46 @@ export class TuiController {
             }));
         }
         return plugin.supportedPlatforms.map((platform) => {
-            const placement = plugin.installedPlacements.find((entry) => entry.platform === platform);
-            if (!placement)
-                return { platform, compatible: false, disabled: '当前没有可信的平台能力信息' };
-            if (placement.state === 'scopeConflict') {
-                return { platform, compatible: false, disabled: '安装位置冲突；请先处理问题' };
-            }
-            if (placement.state === 'installed') {
-                return {
-                    platform,
-                    compatible: false,
-                    disabled: `已安装到${placement.scope === 'user' ? '所有项目' : '当前项目'}；请先移除现有安装`,
-                };
-            }
-            if (!placement.supportedScopes.includes(scope)) {
+            const platformTargets = this.#status?.payload.targets.filter((target) => target.pluginId === pluginId && target.platform === platform) ?? [];
+            const rootSummary = this.#status?.pluginSummaries.find((summary) => summary.pluginId === pluginId);
+            const rootSupportedScopes = rootSummary?.supportedTargets?.[platform]
+                ?? platformTargets.filter((target) => !target.errors.some((error) => error.code === 'unsupportedTarget')).map((target) => target.scope);
+            if (!rootSupportedScopes.includes(scope)) {
                 return { platform, compatible: false, disabled: '不支持所选位置' };
             }
+            const statusTarget = platformTargets.find((target) => target.scope === scope)
+                ?? (platform === 'codex' ? platformTargets[0] : undefined);
+            if (statusTarget && targetHasArtifactCollision(statusTarget)) {
+                return { platform, compatible: false, disabled: '存在输出冲突；请先移除或迁移占用内容' };
+            }
             const overview = this.#viewModel?.dependencyOverviews.find((entry) => entry.pluginId === pluginId);
             for (const dependency of overview?.dependencies ?? []) {
-                const dependentPlugin = this.#viewModel?.plugins.find((entry) => entry.pluginId === dependency.pluginId);
-                if (!dependentPlugin || !dependentPlugin.supportedPlatforms.includes(platform)) {
+                const dependencySummary = this.#status?.pluginSummaries.find((summary) => summary.pluginId === dependency.pluginId);
+                const allowedScopes = dependencySummary?.supportedTargets?.[platform]
+                    ?? (this.#status?.payload.targets.filter((target) => target.pluginId === dependency.pluginId
+                        && target.platform === platform
+                        && !target.errors.some((error) => error.code === 'unsupportedTarget'))
+                        .map((target) => target.scope) ?? []);
+                const viableScopes = allowedScopes.filter((candidateScope) => scope === 'project' || candidateScope === 'user');
+                if (viableScopes.length === 0) {
                     return {
                         platform,
                         compatible: false,
-                        disabled: `${dependency.displayName} 不支持${platform === 'codex' ? 'Codex' : 'Claude Code'}`,
+                        disabled: `${dependency.displayName} 不支持${platform === 'codex' ? 'Codex' : 'Claude Code'}或所选位置`,
                     };
                 }
-                const dependencyPlacement = dependentPlugin.installedPlacements.find((entry) => entry.platform === platform);
-                if (dependencyPlacement?.state === 'scopeConflict') {
-                    return { platform, compatible: false, disabled: `${dependency.displayName} 的安装位置冲突` };
-                }
-                if (dependencyPlacement?.state === 'installed') {
-                    if (dependencyPlacement.health !== 'ready') {
-                        return { platform, compatible: false, disabled: `${dependency.displayName} 需要先处理` };
-                    }
-                    if (scope === 'user' && dependencyPlacement.scope === 'project') {
-                        return { platform, compatible: false, disabled: `${dependency.displayName} 只在当前项目可用` };
-                    }
-                }
-                if (dependencyPlacement?.state === 'notInstalled'
-                    && !dependencyPlacement.supportedScopes.includes(scope)) {
-                    return { platform, compatible: false, disabled: `${dependency.displayName} 不支持所选位置` };
+                const collisionAtEveryViableScope = viableScopes.every((candidateScope) => {
+                    const target = this.#status?.payload.targets.find((entry) => entry.pluginId === dependency.pluginId
+                        && entry.platform === platform
+                        && entry.scope === candidateScope);
+                    return Boolean(target && targetHasArtifactCollision(target));
+                });
+                if (collisionAtEveryViableScope) {
+                    return {
+                        platform,
+                        compatible: false,
+                        disabled: `${dependency.displayName} 存在输出冲突`,
+                    };
                 }
             }
             return { platform, compatible: true };
@@ -1128,6 +1365,40 @@ export class TuiController {
             health: this.#health.get(sourceId),
         });
     }
+    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;
+    }
+    async reloadCatalog(options) {
+        this.dependencies.beginCatalogSession?.();
+        const generation = ++this.#generation;
+        this.#phase = 'loading';
+        this.#publish();
+        try {
+            const status = await this.dependencies.loadStatus(this.#abort.signal);
+            if (this.#disposed || generation !== this.#generation)
+                return false;
+            this.#applyStatus(status);
+            this.#phase = 'ready';
+            this.#loadError = undefined;
+            this.#router.replace({ name: 'sourceDetail', sourceId: options.sourceId });
+            this.#publish();
+            return true;
+        }
+        catch (error) {
+            if (this.#disposed || generation !== this.#generation)
+                return false;
+            const code = issueCode(error);
+            await this.#logErrorSafe(error, code);
+            this.#phase = 'error';
+            this.#loadError = { code, message: '无法安全重新加载 Catalog。请检查诊断后重试。' };
+            this.#publish();
+            return false;
+        }
+    }
     async inspectSourceRemoval(sourceId) {
         if (!this.dependencies.inspectSourceRemoval) {
             throw new TuiOperationBlockedError('stateInventoryFailed', '来源引用清单不可用。');
@@ -1167,7 +1438,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 +1512,11 @@ 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);
     }
     async #runReviewPreparation(token) {
         const preparation = this.#reviewPreparation;
@@ -1281,13 +1554,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) {
@@ -1335,6 +1611,7 @@ export class TuiController {
         this.#pruneReviewTickets(now);
         const expiresAt = now
             + (this.dependencies.reviewTtlMs ?? 2 * 60_000);
+        const requiresConfirmation = (evidence.codexReconcilePlans ?? []).some((plan) => plan.review.requiresConfirmation);
         const pluginId = 'pluginId' in intent ? intent.pluginId : intent.sourceId;
         if ('pluginId' in intent)
             sourceIdFromPluginId(intent.pluginId);
@@ -1361,15 +1638,31 @@ 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' && intent.dependencyPlacementOnly !== 'desired'
+                ? { equivalentCommand: `aw ${intent.action} ${intent.pluginId} --platform ${intent.platform} --scope ${intent.scope}${(intent.dependencyScopeOverrides ?? []).map((override) => ` --dependency-scope ${override.pluginId}#${override.platform}=${override.scope}`).join('')}${intent.action === 'cleanup' && intent.force === true ? ' --force' : ''}${evidence.codexManager?.state === 'requires-install' ? ' --allow-managed-codex-install' : ''}${requiresConfirmation ? ' --yes' : ''}` }
                 : {}),
             primaryLabel: intent.kind === 'pluginWrite' && evidence.dependencyPlan
                 ? `${labels.primaryLabel} ${evidence.dependencyPlan.resolvedPluginIds.length} 个插件`
                 : labels.primaryLabel,
             ...(labels.destructive ? { destructive: true } : {}),
+            requiresConfirmation,
+            sharedImpact: {
+                pluginIds: [...new Set((evidence.codexReconcilePlans ?? []).flatMap((plan) => plan.review.sharedImpact.pluginIds))],
+                ...((evidence.codexReconcilePlans ?? []).find((plan) => plan.review.sharedImpact.warning)?.review.sharedImpact.warning
+                    ? { warning: (evidence.codexReconcilePlans ?? []).find((plan) => plan.review.sharedImpact.warning).review.sharedImpact.warning }
+                    : {}),
+            },
         };
         this.#tickets.set(reviewToken, {
             intent: structuredClone(intent),
@@ -1435,7 +1728,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,7 +1739,6 @@ export class TuiController {
             await this.#logOperationError(error, code, ticket.intent);
             if (!this.#operationIsCurrent(generation))
                 return this.#detachedBlocked(operationId, ticket.intent);
-            this.#cancelSourceRefreshes();
             generation = ++this.#generation;
             try {
                 const refreshed = await this.dependencies.loadStatus(this.#abort.signal);
@@ -1465,26 +1759,27 @@ 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);
+                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();
             generation = ++this.#generation;
         }
         try {
@@ -1497,9 +1792,11 @@ export class TuiController {
             });
             if (!this.#operationIsCurrent(generation))
                 return this.#detachedBlocked(operationId, ticket.intent);
-            this.#cancelSourceRefreshes();
             generation = ++this.#generation;
             if (ticket.intent.kind === 'sourceMutation') {
+                this.dependencies.beginCatalogSession?.({
+                    reuseValidatedGenerations: true,
+                });
                 try {
                     this.#progressFeed?.setCurrent({ target: 'Catalog 来源配置', phase: '读取最终状态' }, '来源操作：读取最终状态');
                 }
@@ -1545,6 +1842,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 +1945,6 @@ export class TuiController {
             this.#activeReview = undefined;
             this.#router.replace({ name: 'result', operationId });
             this.#publish();
-            this.#startGitSourceRefreshes();
             return cloneFrozen(result);
         }
         catch (error) {
@@ -1650,7 +1957,6 @@ export class TuiController {
             if (code === 'operationReviewStale') {
                 return this.#rebuildStaleReview(ticket, operationId, undefined, generation);
             }
-            this.#cancelSourceRefreshes();
             generation = ++this.#generation;
             try {
                 const refreshed = await this.dependencies.loadStatus(this.#abort.signal);
@@ -1688,7 +1994,7 @@ export class TuiController {
         });
     }
     async #rebuildStaleReview(ticket, operationId, currentEvidence, generation = this.#generation) {
-        this.#cancelSourceRefreshes();
+        this.dependencies.beginCatalogSession?.();
         generation = ++this.#generation;
         try {
             const refreshed = await this.dependencies.loadStatus(this.#abort.signal);
@@ -1706,15 +2012,16 @@ export class TuiController {
                 returnRoute: ticket.returnRoute,
             });
         }
+        const 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 +2029,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 +2043,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 +2156,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
@@ -1870,8 +2187,8 @@ export class TuiController {
         this.#disposed = true;
         this.#cancelReviewPreparation();
         this.#cancelPortableRequest();
+        this.#cancelInstallPlacementRequest();
         this.#abort.abort();
-        this.#cancelSourceRefreshes();
         this.#progressUnsubscribe?.();
         this.#tickets.clear();
         this.#phase = 'disposed';
@@ -1879,6 +2196,18 @@ export class TuiController {
     }
 }
 function operationResultSummary(intent, execution) {
+    if (intent.kind === 'pluginWrite' && intent.dependencyPlacementOnly === 'desired') {
+        return {
+            code: 'operationSucceeded',
+            message: '依赖 desired placement 已更新。',
+            pluginId: intent.pluginId,
+            action: intent.action,
+            messages: [
+                '第 1 步：AW 不会扫描未知项目或自动 cleanup；请在已知的所有项目位置显式确认 cleanup。',
+                '第 2 步：cleanup 完成后同步当前项目。',
+            ],
+        };
+    }
     if (intent.kind === 'portableInstall') {
         const receipt = execution;
         const verificationUnknown = receipt.failures.some((failure) => failure.code === 'portableSkillsCliVerificationFailed'
@@ -1950,7 +2279,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 }
                     : {}),
             }];
     });
@@ -1979,7 +2311,16 @@ function operationResultSummary(intent, execution) {
             action: intent.action,
         } : {}),
         ...(inferredTargets.length > 0 ? { targets: inferredTargets } : {}),
-        ...(sourceWarnings.length > 0 ? { messages: sourceWarnings } : {}),
+        ...(sourceWarnings.length > 0 || intent.kind === 'pluginWrite' && intent.recoveryDescription
+            ? { messages: [
+                    ...sourceWarnings,
+                    ...(intent.kind === 'pluginWrite' && intent.recoveryDescription
+                        ? [
+                            intent.recoveryDescription,
+                            `后续：${intent.scope === 'user' ? '当前项目' : '所有项目'} sync`,
+                        ] : []),
+                ] }
+            : {}),
     };
 }
 //# sourceMappingURL=controller.js.map