dsh-m 0.4.2 → 0.5.0

package/lib/core/market.js

@@ -10,7 +10,7 @@
 import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { dshHome } from './env.js';
+import { dshHome, webProfileDir } from './env.js';
 import { runProfileTransaction, makeNpmWarmPackument, TransactionError, } from './profile-transaction.js';
 import { listInstalledPlugins as defaultListInstalledPlugins, } from './installed.js';
 import { loaderHost } from './live-plugin.js';
@@ -18,6 +18,12 @@ import { precheckNpmCompat, IncompatibleError } from './compat-check.js';
 import { PROTECTED_MODULES, composeEnablement } from './enablement.js';
 import { readProfileOverrides } from './patch-yaml.js';
 import { loadRegistry as defaultLoadRegistry, } from './registry.js';
+import { fetchCommunityCatalog as defaultFetchCommunityCatalog, } from './community.js';
+import { adaptCommunityCatalog } from './community-adapter.js';
+import { GithubBudgetExhaustedError, createGithubRequestBudget, isExactVersion } from './versions.js';
+import { HttpError } from './httpx.js';
+import { verifyInstalledAdditions } from './install-guard.js';
+import { fetchTextLimited } from './httpx.js';
 import { githubLatestTag as defaultGithubLatestTag, isNewerVersion, npmLatest as defaultNpmLatest, npmVersion, } from './versions.js';
 /** profile package.json 的 dsh.profile.bundles 数组（读不到 → []；Task 13）。 */
 async function readProfileBundles(profileDir) {
@@ -189,6 +195,16 @@ function applyProbe(item, value) {
     if (value.sha !== undefined)
         item.latestSha = value.sha;
 }
+/** probe 错误 → 结构化 code（Task 7 ⑨）：预算/限流/超时/其他网络错误各自归类，不得一律归因预算。 */
+function classifyLatestError(err) {
+    if (err instanceof GithubBudgetExhaustedError)
+        return 'budget-exhausted';
+    if (err instanceof HttpError && err.status === 403)
+        return 'rate-limited';
+    if (err instanceof Error && /限额已用尽/.test(err.message))
+        return 'rate-limited';
+    return 'network-error';
+}
 function matchInstalledByEntry(entry, installed) {
     return installed.find((it) => {
         if (entry.npm && it.pkg === entry.npm)
@@ -203,6 +219,132 @@ function matchInstalledByEntry(entry, installed) {
         return false;
     });
 }
+/**
+ * 合并去重（Q41）：社区条目依次与主清单的 npm 名集 / github owner-repo 集 / id 集比对，
+ * 任一相撞即让位（每条只计一次）；社区内部 npm 名重复同样让位（首条优先）。
+ * 主清单恒优先——让位只影响社区条目，主条目原样保留。
+ */
+export function mergeRegistries(primary, community) {
+    const primaryNpm = new Set(primary.filter((e) => e.npm).map((e) => e.npm));
+    const primaryGithub = new Set(primary.filter((e) => e.github).map((e) => e.github));
+    const primaryIds = new Set(primary.map((e) => e.id));
+    const displaced = [];
+    const kept = [];
+    const seenNpm = new Set();
+    for (const c of community) {
+        if (c.npm !== undefined) {
+            if (primaryNpm.has(c.npm) || seenNpm.has(c.npm)) {
+                displaced.push(c.id);
+                continue;
+            }
+            seenNpm.add(c.npm);
+        }
+        if ((c.github !== undefined && primaryGithub.has(c.github)) || primaryIds.has(c.id)) {
+            displaced.push(c.id);
+            continue;
+        }
+        kept.push(c);
+    }
+    // Q45：主清单置顶（组内原顺序）+ 社区按 30 天下载量降序（无数据按名称）
+    const sorted = [...kept].sort((a, b) => {
+        const da = a.downloads ?? -1;
+        const db = b.downloads ?? -1;
+        if (da !== db)
+            return db - da;
+        return a.name.localeCompare(b.name);
+    });
+    const warnings = displaced.length > 0 ? [`${displaced.length} 条社区条目与主清单重复，已让位（主清单恒优先）`] : [];
+    return { items: [...primary, ...sorted], displaced: displaced.length, warnings };
+}
+function communitySummary(state, counts, extraWarnings) {
+    const unavailableLike = state.status === 'disabled' || state.status === 'unavailable';
+    return {
+        enabled: state.enabled,
+        status: state.status,
+        version: state.version,
+        checkedAt: state.checkedAt,
+        fetchedAt: state.fetchedAt,
+        route: state.route,
+        acceptedCount: unavailableLike ? 0 : (counts.acceptedCount ?? 0),
+        upstreamCount: unavailableLike ? (state.status === 'disabled' ? null : 0) : (counts.upstreamCount ?? state.count),
+        displaced: unavailableLike ? 0 : (counts.displaced ?? 0),
+        skippedDirty: unavailableLike ? 0 : (counts.skippedDirty ?? 0),
+        skippedSubpathNoNpm: unavailableLike ? 0 : (counts.skippedSubpathNoNpm ?? 0),
+        errors: [...state.errors],
+        warnings: [...state.warnings, ...extraWarnings],
+    };
+}
+function disabledCommunitySummary() {
+    return communitySummary({ enabled: false, status: 'disabled', version: null, checkedAt: null, fetchedAt: null, route: null, count: 0, errors: [], warnings: [] }, {}, []);
+}
+function communityTimeoutSummary() {
+    return communitySummary({ enabled: true, status: 'unavailable', version: null, checkedAt: null, fetchedAt: null, route: null, count: 0, errors: ['社区目录状态获取超时，可稍后刷新'], warnings: [] }, {}, []);
+}
+/**
+ * 社区 loader waiter 收敛（v9/v10 waiter-scoped 契约）：共享 flight 不接收调用者 deadline，
+ * 本函数作为 waiter 用剩余 deadline race 自己的等待；到点只结束本 waiter（summary 标超时），
+ * 共享 flight 照常继续。primaryOnly/未启用 → loader 零调用（task 传 null）。
+ * 导出供 community.ts getCommunitySummary 复用（summary 组装单一产地）。
+ */
+export async function communityOutcome(task, deadlineAt, primary) {
+    if (!task)
+        return { summary: disabledCommunitySummary(), merged: primary };
+    let loaded;
+    try {
+        loaded = await deadlineRace(task, deadlineAt - Date.now());
+    }
+    finally {
+        // race 输出后共享 promise 若仍悬挂（deadline 先到），收尾防 unhandled rejection
+        void task.catch(() => undefined);
+    }
+    if (loaded === 'deadline')
+        return { summary: communityTimeoutSummary(), merged: primary };
+    const state = loaded.state;
+    if (state.status === 'disabled')
+        return { summary: disabledCommunitySummary(), merged: primary };
+    if (state.status === 'unavailable' || !loaded.catalog) {
+        return {
+            summary: communitySummary(state, { acceptedCount: 0, upstreamCount: 0, displaced: 0, skippedDirty: 0, skippedSubpathNoNpm: 0 }, []),
+            merged: primary,
+        };
+    }
+    const adapted = adaptCommunityCatalog(loaded.catalog);
+    const merge = mergeRegistries(primary, adapted.entries);
+    const summary = communitySummary(state, {
+        acceptedCount: adapted.entries.length,
+        upstreamCount: loaded.catalog.plugins.length,
+        displaced: merge.displaced,
+        skippedDirty: adapted.skippedDirty,
+        skippedSubpathNoNpm: adapted.skippedSubpathNoNpm,
+    }, [...adapted.warnings, ...merge.warnings]);
+    return { summary, merged: merge.items };
+}
+function isCommunityEntry(entry) {
+    return entry.descriptionEn !== undefined;
+}
+/** 合并条目 → MarketItem：社区条目带 community 标记与旁路字段。 */
+function toMarketItem(entry, installedItems) {
+    const inst = matchInstalledByEntry(entry, installedItems);
+    const item = { ...entry, installed: Boolean(inst), outdated: false };
+    if (inst) {
+        item.installedPkg = inst.pkg;
+        item.installedVersion = inst.version;
+    }
+    if (isCommunityEntry(entry)) {
+        item.community = true;
+        item.stars = entry.stars;
+        item.downloads = entry.downloads;
+        item.capabilities = entry.capabilities;
+        item.capabilityRedLines = entry.capabilityRedLines;
+        item.screenshots = entry.screenshots;
+    }
+    return item;
+}
+/** 合并条目的搜索串：社区条目附英文描述原文（Q45 搜索同时匹配中英文）。 */
+function searchableText(entry) {
+    const base = `${entry.id} ${entry.name} ${entry.description} ${entry.tags.join(' ')}`;
+    return isCommunityEntry(entry) ? `${base} ${entry.descriptionEn}` : base;
+}
 // ---------- 市场列表 ----------
 function marketDeps() {
     return {
@@ -210,6 +352,7 @@ function marketDeps() {
         listInstalledPlugins: defaultListInstalledPlugins,
         npmLatest: defaultNpmLatest,
         githubLatestTag: defaultGithubLatestTag,
+        fetchCommunityCatalog: defaultFetchCommunityCatalog,
     };
 }
 export async function listMarket(cfg = {}, opts = {}, deps = {}) {
@@ -226,12 +369,16 @@ export async function listMarket(cfg = {}, opts = {}, deps = {}) {
     const remaining = () => deadlineAt - Date.now();
     const registryTask = d.loadRegistry(cfg, { namespace, signal, force: opts.force, deadlineMs });
     const installedTask = d.listInstalledPlugins().catch(() => null);
+    // 社区 flight 并发启动（primaryOnly 零调用）；共享 loader 不接收调用者 deadline——
+    // listMarket 作为 waiter 在 communityOutcome 内 race 自己的剩余 deadline/signal（v10 契约）
+    const communityTask = opts.primaryOnly === true ? null : d.fetchCommunityCatalog(cfg, { namespace, signal, force: opts.force });
     let loaded;
     try {
         loaded = await deadlineRace(registryTask, remaining());
     }
     catch (err) {
         void installedTask;
+        void communityTask?.catch(() => undefined);
         throw err;
     }
     if (loaded === 'deadline') {
@@ -246,32 +393,21 @@ export async function listMarket(cfg = {}, opts = {}, deps = {}) {
             installedComplete: false,
             latestComplete: false,
             latestTimedOut: true,
+            community: communityTimeoutSummary(),
         };
     }
     const registryState = stateOf(loaded);
-    if (loaded.status === 'unavailable') {
-        void installedTask;
-        return {
-            items: [],
-            total: 0,
-            offset: 0,
-            limit: maxLimit,
-            categoryCounts: zeroCounts(),
-            registryState,
-            installedComplete: false,
-            latestComplete: false,
-            latestTimedOut: false,
-        };
-    }
     const installed = await installedTask;
     // 完整性两层来源：枚举 throw → null；枚举 partial resolve → complete:false（installed.ts 完整性契约）
     const installedComplete = installed !== null && installed.complete === true;
     const installedItems = installed?.items ?? [];
+    // 社区 waiter 收敛：主 unavailable 时 merged = 存活社区条目（Q42 出页不返空）；两层皆不可用 → 空页契约
+    const community = await communityOutcome(communityTask, deadlineAt, loaded.registry.plugins);
     // 全量统计 + query/category 过滤 + 分页（同步，极轻）
-    const all = loaded.registry.plugins;
+    const all = community.merged;
     const counts = zeroCounts();
     for (const entry of all)
-        counts[entry.category] += 1;
+        counts[entry.category] = (counts[entry.category] ?? 0) + 1;
     const q = (opts.query ?? '').trim().toLowerCase();
     const cat = opts.category ?? null;
     const filtered = all.filter((entry) => {
@@ -279,22 +415,14 @@ export async function listMarket(cfg = {}, opts = {}, deps = {}) {
             return false;
         if (!q)
             return true;
-        return `${entry.id} ${entry.name} ${entry.description} ${entry.tags.join(' ')}`.toLowerCase().includes(q);
+        return searchableText(entry).toLowerCase().includes(q);
     });
     const total = filtered.length;
     const limit = clampLimit(opts.limit, maxLimit);
     let offset = normalizeOffset(opts.offset);
     if (total > 0 && offset >= total)
         offset = Math.floor((total - 1) / limit) * limit;
-    const items = filtered.slice(offset, offset + limit).map((entry) => {
-        const inst = matchInstalledByEntry(entry, installedItems);
-        const item = { ...entry, installed: Boolean(inst), outdated: false };
-        if (inst) {
-            item.installedPkg = inst.pkg;
-            item.installedVersion = inst.version;
-        }
-        return item;
-    });
+    const items = filtered.slice(offset, offset + limit).map((entry) => toMarketItem(entry, installedItems));
     let latestComplete = true;
     let latestTimedOut = false;
     if (withLatest && items.length > 0) {
@@ -305,12 +433,18 @@ export async function listMarket(cfg = {}, opts = {}, deps = {}) {
             if (cached)
                 applyProbe(item, cached);
         }
-        const todo = items.filter((it) => it.latestVersion === undefined && it.latestTag === undefined && it.latestSha === undefined);
+        const todo = items.filter((it) => it.latestVersion === undefined &&
+            it.latestTag === undefined &&
+            it.latestSha === undefined &&
+            // Q46 探测边界：社区 github 条目不做浏览页 REST 探测（配额不可控）；社区 npm 条目照常
+            !(it.community === true && it.source === 'github'));
         if (todo.length > 0) {
             const budget = remaining();
             if (budget <= 0) {
-                for (const item of todo)
-                    item.latestErrorCode = 'LATEST_TIMEOUT';
+                for (const item of todo) {
+                    item.latestError = '更新检查未完成：时间预算已用尽';
+                    item.latestErrorCode = 'timeout';
+                }
                 latestComplete = false;
                 latestTimedOut = true;
             }
@@ -324,7 +458,8 @@ export async function listMarket(cfg = {}, opts = {}, deps = {}) {
                         writeLatestCache(latestCacheKey(namespace, loaded.configuredAddress, item), outcome.value);
                     }
                     else if (outcome.timeout) {
-                        item.latestErrorCode = 'LATEST_TIMEOUT';
+                        item.latestError = '更新检查未完成：超时';
+                        item.latestErrorCode = 'timeout';
                         latestComplete = false;
                         latestTimedOut = true;
                     }
@@ -332,7 +467,7 @@ export async function listMarket(cfg = {}, opts = {}, deps = {}) {
                         if (signal?.aborted)
                             throw abortError();
                         item.latestError = outcome.error instanceof Error ? outcome.error.message : String(outcome.error);
-                        item.latestErrorCode = 'LATEST_ERROR';
+                        item.latestErrorCode = classifyLatestError(outcome.error);
                     }
                 });
             }
@@ -350,7 +485,18 @@ export async function listMarket(cfg = {}, opts = {}, deps = {}) {
             }
         }
     }
-    return { items, total, offset, limit, categoryCounts: counts, registryState, installedComplete, latestComplete, latestTimedOut };
+    return {
+        items,
+        total,
+        offset,
+        limit,
+        categoryCounts: counts,
+        registryState,
+        installedComplete,
+        latestComplete,
+        latestTimedOut,
+        community: community.summary,
+    };
 }
 // ---------- 已装列表 ----------
 export async function listInstalledWithMeta(cfg = {}, opts = {}, deps = {}) {
@@ -365,6 +511,9 @@ export async function listInstalledWithMeta(cfg = {}, opts = {}, deps = {}) {
     const remaining = () => deadlineAt - Date.now();
     const installedPromise = d.listInstalledPlugins();
     const registryTask = d.loadRegistry(cfg, { namespace, signal, force: opts.force, deadlineMs });
+    // 社区 flight 并发启动 + request-scoped GitHub 预算（本次检查 ≤25 个 wire 请求、宿主滚动 50/h）
+    const communityTask = d.fetchCommunityCatalog(cfg, { namespace, signal, force: opts.force });
+    const githubBudget = createGithubRequestBudget();
     const installed = await installedPromise;
     // enablement join（Task 13，ADR-0001 读路径自读）：loader ⋈ bundles ⋈ profile 覆盖行
     const compose = d.composeEnablement ?? composeEnablement;
@@ -386,47 +535,63 @@ export async function listInstalledWithMeta(cfg = {}, opts = {}, deps = {}) {
     catch {
         loaded = 'deadline';
     }
+    const community = await communityOutcome(communityTask, deadlineAt, loaded === 'deadline' ? [] : loaded.registry.plugins);
     if (loaded === 'deadline' || loaded.status === 'unavailable') {
-        // registry 不可用：不做 matching，直接返回已装列表
+        // registry 不可用：不做 matching/探测（原行为），但社区 summary 照常携带（CLI outdated 双源判定）
         const registryState = loaded === 'deadline' ? timeoutRegistryState(cfg) : stateOf(loaded);
-        return { items, others: installed.others, profileDir: installed.profileDir, registryState };
+        void community.merged;
+        return { items, others: installed.others, profileDir: installed.profileDir, registryState, community: community.summary };
     }
     const registryState = stateOf(loaded);
-    const ttlMin = Math.max(0, cfg.cacheTtlMin ?? 60);
+    matchInstalled(items, community.merged);
+    await probeLatest(items, { merged: community.merged, registryAddress: loaded.configuredAddress, ttlMin: Math.max(0, cfg.cacheTtlMin ?? 60) }, d, { namespace, signal, githubBudget, remaining, timeoutMs: cfg.timeoutMs ?? 20_000 });
+    return { items, others: installed.others, profileDir: installed.profileDir, registryState, community: community.summary };
+}
+/** matching（主+社区合并条目）：命中主条目或社区条目都写 registryId；社区命中再标 community。 */
+function matchInstalled(items, merged) {
+    for (const item of items) {
+        const entry = merged.find((e) => matchInstalledByEntry(e, [item]));
+        if (!entry)
+            continue;
+        item.registryId = entry.id;
+        item.registryGithub = entry.github ?? null;
+        item.registryIcon = entry.icon ?? null;
+        if (isCommunityEntry(entry))
+            item.community = true;
+    }
+}
+/** 已装页 latest 探测（Q46 已装页豁免，但 GitHub 计入 request 预算 + 宿主滚动窗口）。 */
+async function probeLatest(items, ctx, d, rt) {
     await mapWithConcurrency(items, LATEST_WORKERS, async (item) => {
-        const entry = loaded.registry.plugins.find((e) => matchInstalledByEntry(e, [item]));
-        if (entry) {
-            item.registryId = entry.id;
-            item.registryGithub = entry.github ?? null;
-            item.registryIcon = entry.icon ?? null;
-        }
+        const entry = ctx.merged.find((e) => matchInstalledByEntry(e, [item]));
         // latest 探测沿用 listMarket 的 TTL cache
         const cacheKey = entry
-            ? latestCacheKey(namespace, loaded.configuredAddress, entry)
+            ? latestCacheKey(rt.namespace, ctx.registryAddress ?? '', entry)
             : item.source === 'npm'
-                ? `npm-only|${namespace}|npm:${item.pkg}`
+                ? `npm-only|${rt.namespace}|npm:${item.pkg}`
                 : null;
         if (cacheKey) {
-            const cached = readLatestCache(cacheKey, ttlMin);
+            const cached = readLatestCache(cacheKey, ctx.ttlMin);
             if (cached) {
                 applyProbe(item, cached);
             }
-            else if (remaining() > 0) {
-                const budget = Math.max(1, remaining());
+            else if (rt.remaining() > 0) {
+                // 绝对剩余预算贯穿整个 probe（多跳 githubLatestTag 不逐子请求重置——v9 ②）
+                const budget = rt.remaining();
                 try {
                     let value = null;
                     if (!entry && item.source === 'npm') {
-                        const latest = await d.npmLatest(item.pkg, Math.min(cfg.timeoutMs ?? 20_000, budget), signal);
+                        const latest = await d.npmLatest(item.pkg, Math.min(rt.timeoutMs, budget), rt.signal);
                         value = { version: latest.version };
                     }
                     else if (entry?.source === 'npm' && entry.npm) {
-                        const latest = await d.npmLatest(entry.npm, Math.min(cfg.timeoutMs ?? 20_000, budget), signal);
+                        const latest = await d.npmLatest(entry.npm, Math.min(rt.timeoutMs, budget), rt.signal);
                         value = { version: latest.version };
                     }
                     else if (item.source === 'github') {
                         const m = /^github:([^#]+)/.exec(item.spec);
                         if (m) {
-                            const latest = await d.githubLatestTag(m[1], Math.min(cfg.timeoutMs ?? 20_000, budget), signal);
+                            const latest = await d.githubLatestTag(m[1], Math.min(rt.timeoutMs, budget), rt.signal, rt.githubBudget);
                             value = { tag: latest.tag, sha: latest.sha };
                         }
                     }
@@ -437,15 +602,20 @@ export async function listInstalledWithMeta(cfg = {}, opts = {}, deps = {}) {
                 }
                 catch (err) {
                     item.latestError = err instanceof Error ? err.message : String(err);
+                    item.latestErrorCode = classifyLatestError(err);
                 }
             }
+            else {
+                // deadline 已到且未启动：标未完成并停止派发（v9 ②「未启动条目也标未完成」）
+                item.latestError = '更新检查未完成：时间预算已用尽';
+                item.latestErrorCode = 'timeout';
+            }
         }
         if (item.latestVersion !== undefined && item.version)
             item.outdated = isNewerVersion(item.latestVersion, item.version);
         else if (item.latestSha !== undefined)
             item.outdated = !item.spec.includes(item.latestSha);
     });
-    return { items, others: installed.others, profileDir: installed.profileDir, registryState };
 }
 /** 从 registry 收录条目安装（npm → 精确锁定最新版；github → 锁 HEAD SHA）。 */
 export async function installFromRegistry(id, cfg = {}, opts = {}, deps) {
@@ -458,14 +628,316 @@ export async function installFromRegistry(id, cfg = {}, opts = {}, deps) {
         throw new Error(`registry 中没有该条目: ${id}`);
     return installEntry(entry, cfg, opts, deps);
 }
+// ---------- M2 Task 3：统一 mutation session + 装后守卫 + 补偿接线 ----------
+let sessionTail = Promise.resolve();
+/**
+ * 统一 mutation 串行区间（模块级 FIFO，非重入）：包住全部五个 profile mutation 入口
+ * （installFromRegistry / upgradePlugin / uninstallPlugin / selfUpgrade / toggle）。
+ * session 单点获取——只在 core façade 获取（toggle 在 togglePlugin 本体），host-api/tools/CLI
+ * 层不得重复获取（session 非重入，多层重复获取会死锁）。锁序：mutation session 外层 →
+ * toggle file lock / 事务 FIFO 内层。
+ */
+export async function withMutationSession(fn) {
+    const run = sessionTail.then(() => fn(), () => fn());
+    sessionTail = run.then(() => undefined, () => undefined);
+    return run;
+}
+/** 守卫拦截的结构化错误（非成功状态）：三端按 kind/needsRestart/restartSafe 渲染，无 force 通道。 */
+export class InstallGuardError extends Error {
+    kind;
+    violations;
+    needsRestart;
+    restartSafe;
+    /** 补偿终态摘要（rolled-back/manual-repair/rejected 的 note） */
+    compensation;
+    /** manual-repair 的修复依据（旧 manifestSpec/installSpec/mapping） */
+    repairBasis;
+    constructor(fields) {
+        super(fields.message);
+        this.name = 'InstallGuardError';
+        this.kind = fields.kind;
+        this.violations = fields.violations;
+        this.needsRestart = fields.needsRestart;
+        this.restartSafe = fields.restartSafe;
+        this.compensation = fields.compensation;
+        this.repairBasis = fields.repairBasis;
+    }
+}
+/** lockfile packages 段的目标包 resolution 提取（行扫描：键行 `pkg@ver:` → 收集至下一键行；引号/嵌套键兼容）。 */
+function lockResolutionOf(lockText, pkg) {
+    // 只扫顶层 packages: 段（importer 段的同名键不参与；packages: 后条目缩进两空格）
+    const pkgsAt = lockText.split('\n').findIndex((l) => l.trim() === 'packages:');
+    if (pkgsAt < 0)
+        return null;
+    const lines = lockText.split('\n').slice(pkgsAt + 1);
+    let body = null;
+    for (const line of lines) {
+        if (body !== null && /^\S/.test(line))
+            break; // 顶层新段 → 收集结束
+        const keyMatch = /^  '?(?:[^'\n]*node_modules\/)?([^\s':]+):\s*$/.exec(line);
+        if (keyMatch) {
+            if (body)
+                break;
+            const key = keyMatch[1] ?? '';
+            if (key === pkg || key.startsWith(`${pkg}@`))
+                body = [];
+            continue;
+        }
+        if (body)
+            body.push(line);
+    }
+    if (body === null)
+        return null;
+    const text = body.join('\n');
+    const version = /version:\s*'?([^'\n]+)/.exec(text)?.[1]?.trim();
+    const integrity = /integrity:\s*(\S+)/.exec(text)?.[1]?.trim();
+    const commit = /commit:\s*'?([0-9a-f]{40})/.exec(text)?.[1]?.trim();
+    if (!version && !integrity && !commit)
+        return null;
+    return { ...(version ? { version } : {}), ...(integrity ? { integrity } : {}), ...(commit ? { commit } : {}) };
+}
+/** 变更前全量快照（v6）：deps / lock resolutions / 双落点 mapping。读取失败 → unavailable（fail-closed 拒绝安装）。 */
+export async function capturePreMutationState(profileDir) {
+    try {
+        // manifest ENOENT = 无已装依赖的空 profile（与 guard readDeps 同语义）；其他读取/解析失败 → fail-closed
+        let manifestText = '';
+        try {
+            manifestText = await readFile(join(profileDir, 'package.json'), 'utf8');
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT')
+                throw err;
+        }
+        const doc = manifestText
+            ? JSON.parse(manifestText)
+            : {};
+        const deps = {};
+        if (doc.dependencies && typeof doc.dependencies === 'object' && !Array.isArray(doc.dependencies)) {
+            for (const [name, spec] of Object.entries(doc.dependencies)) {
+                if (typeof spec === 'string')
+                    deps[name] = spec;
+            }
+        }
+        const manifestMapping = [];
+        const patched = doc.pnpm?.patchedDependencies;
+        if (patched && typeof patched === 'object' && !Array.isArray(patched)) {
+            for (const [key, patchPath] of Object.entries(patched)) {
+                if (typeof patchPath === 'string')
+                    manifestMapping.push({ key, patchPath });
+            }
+        }
+        let lockText = '';
+        try {
+            lockText = await readFile(join(profileDir, 'pnpm-lock.yaml'), 'utf8');
+        }
+        catch {
+            lockText = '';
+        }
+        const lockResolutions = {};
+        for (const name of Object.keys(deps)) {
+            const res = lockResolutionOf(lockText, name);
+            if (res)
+                lockResolutions[name] = res;
+        }
+        const workspaceMapping = [];
+        try {
+            const ws = await readFile(join(profileDir, 'pnpm-workspace.yaml'), 'utf8');
+            const inBlock = /^patchedDependencies:/m;
+            if (inBlock.test(ws)) {
+                const section = ws.split(/^patchedDependencies:/m)[1]?.split(/^\S/m)?.[0] ?? '';
+                for (const line of section.split('\n')) {
+                    const m = /^\s+'?([^':]+)'?:\s*(\S+)/.exec(line);
+                    if (m)
+                        workspaceMapping.push({ key: m[1].trim(), patchPath: m[2].trim() });
+                }
+            }
+        }
+        catch {
+            /* 无 workspace 文件 = 无 workspace mapping */
+        }
+        return { kind: 'snapshot', snapshot: { deps, lockResolutions, mapping: { workspace: workspaceMapping, manifest: manifestMapping } } };
+    }
+    catch (err) {
+        return { kind: 'unavailable', reason: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** mapping 条目按真实 key 精确关联（key === realKey 或版本化 key `realKey@x`）；不按 repo/id/相似名猜。 */
+function mappingFor(mapping, realKey) {
+    const pick = (rows) => rows.filter((r) => r.key === realKey || r.key.startsWith(`${realKey}@`));
+    return { workspace: pick(mapping.workspace), manifest: pick(mapping.manifest) };
+}
+/**
+ * prior 派生（add 返回真实 key 后、守卫前）：严格按真实 key 关联快照；判定表唯一映射。
+ * 来源白名单（独立实现，不复用 parseSpecSource）：精确 npm version（含 ^/~ 书写）与
+ * pinned github commit + lock identity 可自动恢复；alias/workspace/tarball URL/git+ssh/link/file 一律 restorable:false。
+ */
+export function derivePrior(snapshot, realKey) {
+    const spec = snapshot.deps[realKey];
+    const mapping = mappingFor(snapshot.mapping, realKey);
+    if (spec === undefined) {
+        if (mapping.workspace.length > 0 || mapping.manifest.length > 0) {
+            return { kind: 'mappingOnly', patchMapping: mapping };
+        }
+        return { kind: 'none' };
+    }
+    const lock = snapshot.lockResolutions[realKey] ?? null;
+    let sourceKind = 'other';
+    let restorable = false;
+    if (isExactVersion(spec)) {
+        sourceKind = 'npm';
+        restorable = Boolean(lock?.integrity);
+    }
+    else if (/^[~^]\d/.test(spec) && isExactVersion(spec.slice(1))) {
+        // ^/~ 锚定（0.4.x 旧 CLI 书写）：恢复后接受规范化并明示
+        sourceKind = 'npm';
+        restorable = Boolean(lock?.integrity);
+    }
+    else if (/^github:[A-Za-z0-9][A-Za-z0-9-]*\/[A-Za-z0-9._-]+#[0-9a-f]{40}$/.test(spec)) {
+        sourceKind = 'github';
+        restorable = Boolean(lock?.commit);
+    }
+    return {
+        kind: 'dependency',
+        state: {
+            manifestSpec: spec,
+            installSpec: spec,
+            resolvedVersion: lock?.version,
+            sourceKind,
+            ...(lock?.integrity ? { integrity: lock.integrity } : {}),
+            ...(lock ? { lockResolution: lock } : {}),
+            patchMapping: mapping,
+            restorable,
+        },
+    };
+}
+/** GitHub candidate preflight：只读抓取 pinned SHA 的 package.json 解析 name（预算外 read-only 通道，不写 profile）。 */
+async function candidateKeyOf(repo, sha, timeoutMs) {
+    const text = await fetchTextLimited(`https://raw.githubusercontent.com/${repo}/${sha}/package.json`, { timeoutMs, maxBytes: 512 * 1024 });
+    const doc = JSON.parse(text);
+    return typeof doc.name === 'string' && doc.name.trim() !== '' ? doc.name.trim() : null;
+}
+function errText(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** 补偿执行 + InstallGuardError 抛出（四态 → needsRestart/restartSafe 映射；rejected 复读 profile 实况）。 */
+async function throwCompensated(args) {
+    const { pkg, guard, deps, evidence, prior } = args;
+    const violations = guard.violations;
+    const violationText = violations.map((v) => `${v.code}: ${v.detail}`).join('；');
+    let comp;
+    const priorForTx = prior.kind === 'mappingOnly'
+        ? { kind: 'mappingOnly', patchMapping: prior.patchMapping }
+        : prior.kind === 'dependency'
+            ? { kind: 'dependency', state: prior.state }
+            : { kind: 'none' };
+    try {
+        comp = await runProfileTransaction({ kind: 'compensate-install', pkg, evidence, prior: priorForTx }, deps);
+    }
+    catch (err) {
+        throw new InstallGuardError({
+            kind: 'manual_required',
+            message: `安装违例（${violationText}），补偿事务执行异常：${err instanceof Error ? err.message : String(err)}——需人工处理`,
+            violations,
+            needsRestart: true,
+            restartSafe: false,
+            compensation: { status: 'manual-repair', note: errText(err) },
+        });
+    }
+    if (comp.ok) {
+        // committed(fresh/restore) + 补偿验证完整 → 可一键重启
+        throw new InstallGuardError({
+            kind: 'compensated',
+            message: `安装违例（${violationText}），已${prior.kind === 'dependency' ? '恢复原版本' : '自动卸载'}（补偿事务 committed）`,
+            violations,
+            needsRestart: true,
+            restartSafe: true,
+            compensation: { status: 'committed', note: comp.output },
+            ...(prior.kind === 'dependency' ? { repairBasis: `prior: ${prior.state.manifestSpec}（${prior.state.resolvedVersion ?? 'version 未知'}）` } : {}),
+        });
+    }
+    const status = comp.status;
+    const note = comp.failure?.note ?? '';
+    if (status === 'rejected') {
+        // 复读 profile 实况决定 restartSafe（不因零写入直接 false）
+        let pkgStillThere = false;
+        try {
+            const now = await capturePreMutationState(deps?.profileDir ?? webProfileDir());
+            pkgStillThere = now.kind === 'snapshot' && pkg in now.snapshot.deps;
+        }
+        catch {
+            pkgStillThere = true;
+        }
+        throw new InstallGuardError({
+            kind: 'compensated',
+            message: `安装违例（${violationText}），补偿未执行（profile 状态已变化：${note}）`,
+            violations,
+            needsRestart: pkgStillThere,
+            restartSafe: !pkgStillThere,
+            compensation: { status: 'rejected', note },
+        });
+    }
+    if (status === 'rolled-back') {
+        throw new InstallGuardError({
+            kind: 'compensated',
+            message: `安装违例（${violationText}），补偿未完成：已回到补偿前状态，坏包可能仍在，需人工处理（${note}）`,
+            violations,
+            needsRestart: true,
+            restartSafe: false,
+            compensation: { status: 'rolled-back', note },
+        });
+    }
+    // manual-repair：状态未知；post-add 兜底场景附修复依据，任何端不显示「已恢复原版本/已安装成功」
+    throw new InstallGuardError({
+        kind: 'manual_required',
+        message: `安装违例（${violationText}），补偿进入 manual-repair：需人工处理（${note}）`,
+        violations,
+        needsRestart: true,
+        restartSafe: false,
+        compensation: { status: 'manual-repair', note },
+        ...(prior.kind === 'dependency'
+            ? { repairBasis: `旧 manifestSpec=${prior.state.manifestSpec}；installSpec=${prior.state.installSpec}；mapping=${JSON.stringify(prior.state.patchMapping)}` }
+            : prior.kind === 'mappingOnly'
+                ? { repairBasis: `旧 mapping=${JSON.stringify(prior.patchMapping)}` }
+                : {}),
+    });
+}
+function guardManualRequired(message, violations) {
+    // 零副作用：未进 mutation → needsRestart=false、restartSafe=false
+    return new InstallGuardError({
+        kind: 'manual_required',
+        message,
+        violations,
+        needsRestart: false,
+        restartSafe: false,
+        compensation: { status: 'pre-mutation', note: '未开始变更，profile 零写入' },
+    });
+}
 export async function installEntry(entry, cfg = {}, opts = {}, deps) {
+    return withMutationSession(() => installEntryLocked(entry, cfg, opts, deps));
+}
+/** installEntry 主体（session 区间内；installEntry 是唯一外部入口——upgradePlugin 复用本 helper）。 */
+async function installEntryLocked(entry, cfg = {}, opts = {}, deps) {
     const timeoutMs = cfg.timeoutMs ?? 20_000;
+    const profileDir = deps?.transaction?.profileDir ?? webProfileDir();
     const d = {
         npmLatest: deps?.npmLatest ?? defaultNpmLatest,
         npmVersion: deps?.npmVersion ?? npmVersion,
     };
     if (entry.source === 'npm' && entry.npm) {
         const pkg = entry.npm;
+        // 变更前全量快照（unavailable → fail-closed，零写入）
+        const pre = await capturePreMutationState(profileDir);
+        if (pre.kind === 'unavailable') {
+            throw new Error(`变更前状态捕获失败：${pre.reason}；拒绝安装（fail-closed）`);
+        }
+        // npm key 事务前已知：prior 派生与 restorable 检查在事务前完成
+        const prior = derivePrior(pre.snapshot, pkg);
+        if (prior.kind === 'unavailable') {
+            throw new Error(`prior 关联歧义：${prior.reason}；拒绝安装（fail-closed）`);
+        }
+        if (prior.kind === 'dependency' && !prior.state.restorable) {
+            throw guardManualRequired(`「${pkg}」的原安装形态（${prior.state.sourceKind === 'other' ? 'link/file 等非 registry 来源' : '缺少 integrity 的 npm 依赖'}）无法自动回退，请先手动处理（卸载或修复后重试）`, [{ pkg, code: 'NO_DSH_MARKER', detail: `prior restorable:false（sourceKind=${prior.state.sourceKind}）` }]);
+        }
         // npm：无论 latest 还是用户指定 exact，都先读取该精确版本的 dist metadata（事务外解析）
         let version;
         let expectedIntegrity;
@@ -502,6 +974,43 @@ export async function installEntry(entry, cfg = {}, opts = {}, deps) {
         });
         if (!result.ok)
             throw new TransactionError(result);
+        // 装后守卫（session 区间内；fail-open 仅限结论不可定）
+        const guard = await verifyInstalledAdditions({
+            profileDir,
+            addedPkgs: [result.pkg ?? pkg],
+            ...(prior.kind === 'dependency' ? { priorPkgs: [pkg] } : {}),
+        });
+        if (guard.unavailable.length > 0) {
+            return {
+                id: entry.id,
+                pkg: result.pkg ?? pkg,
+                spec: result.spec ?? `${pkg}@${version}`,
+                version: result.version ?? version,
+                buildApprovals: result.buildApprovals ?? [],
+                fallbackAllBuilds: result.fallbackAllBuilds === true,
+                ...(result.bundleWarning ? { bundleWarning: result.bundleWarning } : {}),
+                compat: compat ?? null,
+                needsRestart: true,
+                output: result.output,
+                healActions: result.healActions,
+                guardWarning: `装后守卫不可用（${guard.unavailable.map((u) => u.reason).slice(0, 2).join('；')}），未执行三项检查——如异常请人工核查`,
+            };
+        }
+        if (!guard.ok) {
+            await throwCompensated({
+                pkg: result.pkg ?? pkg,
+                guard,
+                deps: deps?.transaction,
+                evidence: {
+                    source: 'npm',
+                    // manifestSpec = 安装后 manifest deps 值（pnpm add 写入裸 version）；validate 对当前 manifest 实读比对
+                    manifestSpec: result.version ?? version,
+                    resolvedVersion: result.version ?? version,
+                    integrity: expectedIntegrity ?? '',
+                },
+                prior,
+            });
+        }
         const notes = result.healActions.map((h) => h.note).filter((n) => n !== '');
         return {
             id: entry.id,
@@ -518,15 +1027,98 @@ export async function installEntry(entry, cfg = {}, opts = {}, deps) {
         };
     }
     if (entry.github) {
-        // 版本解析在事务外（DI 修正：githubLatestTag 此前绕过注入）
+        // 变更前全量快照（fail-closed）
+        const pre = await capturePreMutationState(profileDir);
+        if (pre.kind === 'unavailable') {
+            throw new Error(`变更前状态捕获失败：${pre.reason}；拒绝安装（fail-closed）`);
+        }
+        // candidate preflight（M2 Task 0 gate 已证明 name→key 映射）：只读抓取 pinned package.json；
+        // 抓取失败/解析歧义 → fail-closed 拒绝安装（零写入）；candidate 命中 link/file 或 restorable:false
+        // prior → mutation 前 GUARD_MANUAL_REQUIRED（runner.add 零调用）
         const { tag, sha } = await (deps?.githubLatestTag ?? defaultGithubLatestTag)(entry.github, timeoutMs, opts.signal);
+        let candidate;
+        try {
+            candidate = await (deps?.candidateKey ?? candidateKeyOf)(entry.github, sha, timeoutMs);
+        }
+        catch (err) {
+            throw new Error(`GitHub candidate key 预解析失败（${entry.github}@${sha.slice(0, 7)}）：${err instanceof Error ? err.message : String(err)}；拒绝安装（fail-closed）`);
+        }
+        if (candidate === null || !/^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/.test(candidate)) {
+            throw new Error(`GitHub candidate key 不可用（${candidate ?? 'name 缺失'}）：拒绝安装（fail-closed）`);
+        }
+        const candidatePrior = derivePrior(pre.snapshot, candidate);
+        if (candidatePrior.kind === 'unavailable') {
+            throw new Error(`prior 关联歧义：${candidatePrior.reason}；拒绝安装（fail-closed）`);
+        }
+        if (candidatePrior.kind === 'dependency' && !candidatePrior.state.restorable) {
+            throw guardManualRequired(`「${candidate}」的原安装形态（link/file 等非 registry 来源）无法自动回退，请先手动处理（卸载或修复后重试）`, [{ pkg: candidate, code: 'NO_DSH_MARKER', detail: 'candidate 命中 restorable:false prior（link/file）' }]);
+        }
         const result = await runProfileTransaction({ kind: 'install-github', repo: entry.github, sha, tag, signal: opts.signal }, deps?.transaction ?? {});
         if (!result.ok)
             throw new TransactionError(result);
+        const realKey = result.pkg ?? candidate;
+        // post-add derivePrior 复核（兜底网）：真实 key 与 candidate 不符且发现不可自动恢复 prior
+        // → manual-repair 非成功状态（不冒充 pre-mutation 拒绝、不承诺 prior 无损）
+        let prior = candidatePrior;
+        if (realKey !== candidate) {
+            const real = derivePrior(pre.snapshot, realKey);
+            if (real.kind === 'unavailable') {
+                throw new Error(`prior 关联歧义（真实 key ${realKey}）：${real.reason}；拒绝继续（fail-closed）`);
+            }
+            if (real.kind === 'dependency' && !real.state.restorable) {
+                throw new InstallGuardError({
+                    kind: 'manual_required',
+                    message: `安装违例后复核：真实 dependency key（${realKey}）与预解析 candidate（${candidate}）不符，且旧 prior 为 link/file 等不可自动恢复来源——旧 prior 可能已被覆盖，需人工恢复`,
+                    violations: [{ pkg: realKey, code: 'NO_DSH_MARKER', detail: 'candidate 与真实 key 不符且 prior restorable:false' }],
+                    needsRestart: true,
+                    restartSafe: false,
+                    compensation: { status: 'manual-repair', note: '真实 key ≠ candidate 且旧 prior 不可自动恢复' },
+                    repairBasis: `旧 manifestSpec=${real.state.manifestSpec}；installSpec=${real.state.installSpec}；mapping=${JSON.stringify(real.state.patchMapping)}`,
+                });
+            }
+            if (real.kind !== 'none')
+                prior = real;
+        }
+        // 装后守卫
+        const guard = await verifyInstalledAdditions({
+            profileDir,
+            addedPkgs: [realKey],
+            ...(prior.kind === 'dependency' ? { priorPkgs: [realKey] } : {}),
+        });
+        if (guard.unavailable.length > 0) {
+            const notes = result.healActions.map((h) => h.note).filter((n) => n !== '');
+            return {
+                id: entry.id,
+                pkg: realKey,
+                spec: result.spec ?? `github:${entry.github}#${sha}`,
+                sha: result.sha ?? sha,
+                tag: result.tag ?? tag,
+                buildApprovals: result.buildApprovals ?? [],
+                fallbackAllBuilds: result.fallbackAllBuilds === true,
+                ...(result.bundleWarning ? { bundleWarning: result.bundleWarning } : {}),
+                compatSkipped: 'github-source',
+                needsRestart: true,
+                output: result.output + (notes.length > 0 ? `\n[dsh-m 自愈] ${notes.join('；')}` : ''),
+                healActions: result.healActions,
+                guardWarning: `装后守卫不可用（${guard.unavailable.map((u) => u.reason).slice(0, 2).join('；')}），未执行三项检查——如异常请人工核查`,
+            };
+        }
+        if (!guard.ok) {
+            // lock commit identity 从实际 pnpm-lock.yaml 解析（InstallResult.sha 是请求时期望值，非独立观测）
+            const lockText = await readFile(join(profileDir, 'pnpm-lock.yaml'), 'utf8');
+            const lockCommit = lockResolutionOf(lockText, realKey)?.commit ?? sha;
+            await throwCompensated({
+                pkg: realKey,
+                guard,
+                deps: deps?.transaction,
+                evidence: { source: 'github', pinnedSpec: `github:${entry.github}#${sha}`, sha, lockCommitIdentity: lockCommit },
+                prior,
+            });
+        }
         const notes = result.healActions.map((h) => h.note).filter((n) => n !== '');
         return {
             id: entry.id,
-            pkg: result.pkg ?? entry.github,
+            pkg: realKey,
             spec: result.spec ?? `github:${entry.github}#${sha}`,
             sha: result.sha ?? sha,
             tag: result.tag ?? tag,
@@ -542,7 +1134,10 @@ export async function installEntry(entry, cfg = {}, opts = {}, deps) {
     throw new Error(`条目 ${entry.id} 缺少可安装来源`);
 }
 /** 卸载：validate（严格读取）→ live-disable → 摘补丁 → pnpm remove → verify gone（DESIGN.md §3：删包不删数据）。 */
-export async function uninstallPlugin(pkg, _cfg = {}, opts = {}, deps = {}) {
+export function uninstallPlugin(pkg, cfg = {}, opts = {}, deps = {}) {
+    return withMutationSession(() => uninstallPluginLocked(pkg, cfg, opts, deps));
+}
+async function uninstallPluginLocked(pkg, _cfg = {}, opts = {}, deps = {}) {
     // 保护门（Task 12，grilling Q3）：dsh-m 自身与官方宿主命脉拒绝卸载（升级不受影响）
     if (pkg === 'dsh-m' || PROTECTED_MODULES.includes(pkg)) {
         throw new Error(`拒绝卸载受保护插件: ${pkg}（dsh-m 自身或官方宿主命脉）。如确需移除，请使用官方插件管理页或 dsh plugin CLI`);
@@ -561,7 +1156,10 @@ export async function uninstallPlugin(pkg, _cfg = {}, opts = {}, deps = {}) {
     };
 }
 /** 升级 = 按最新重新安装（npm 拉最新精确版；github 重新锁 HEAD）。 */
-export async function upgradePlugin(pkg, cfg = {}, opts = {}, deps) {
+export function upgradePlugin(pkg, cfg = {}, opts = {}, deps) {
+    return withMutationSession(() => upgradePluginLocked(pkg, cfg, opts, deps));
+}
+async function upgradePluginLocked(pkg, cfg = {}, opts = {}, deps) {
     const loaded = await (deps?.loadRegistry ?? defaultLoadRegistry)(cfg, { namespace: opts.namespace ?? 'host' });
     if (loaded.status === 'unavailable') {
         throw new Error(`收录清单不可用，无法升级 ${pkg}；请检查 registry 配置或网络后重试`);
@@ -576,6 +1174,31 @@ export async function upgradePlugin(pkg, cfg = {}, opts = {}, deps) {
     const result = await installEntry(entry, cfg, opts, deps);
     return { ...result, fromVersion: target.version };
 }
+/** 自升级（0.5.0 收编：host-api 直调事务的旁路封死）：npmLatest + integrity fail-closed + installEntryLocked（session/守卫经 installEntry）。 */
+export async function selfUpgrade(pkgName, currentVersion, cfg = {}, opts = {}, deps) {
+    return withMutationSession(async () => {
+        const timeoutMs = cfg.timeoutMs ?? 20_000;
+        const latest = await (deps?.npmLatest ?? defaultNpmLatest)(pkgName, timeoutMs, opts.signal);
+        if (!latest.integrity) {
+            throw new Error(`npm metadata 缺少 dist integrity：${pkgName}@${latest.version}，拒绝升级`);
+        }
+        const result = await runProfileTransaction({ kind: 'install-npm', pkg: pkgName, version: latest.version, integrity: latest.integrity, signal: opts.signal }, { ...(deps?.transaction ?? {}), warmPackument: deps?.transaction?.warmPackument ?? makeNpmWarmPackument(timeoutMs) });
+        if (!result.ok)
+            throw new TransactionError(result);
+        return {
+            id: pkgName,
+            pkg: result.pkg ?? pkgName,
+            spec: result.spec ?? `${pkgName}@${latest.version}`,
+            version: result.version ?? latest.version,
+            buildApprovals: result.buildApprovals ?? [],
+            fallbackAllBuilds: result.fallbackAllBuilds === true,
+            ...(result.bundleWarning ? { bundleWarning: result.bundleWarning } : {}),
+            needsRestart: true,
+            output: result.output,
+            healActions: result.healActions,
+        };
+    });
+}
 /** 疑似残留路径（存在才列出）：删包不删数据，只报告。 */
 export function leftoverCandidates(pkg) {
     const home = dshHome();