dsh-m 0.9.23 → 0.9.25

package/lib/core/exclude-governance.js

@@ -0,0 +1,264 @@
+/**
+ * 排除条目代管（ADR-0009）：pnpm-workspace.yaml `minimumReleaseAgeExclude` 块的
+ * 纯文本变换（解析 / 治理合并 / 登记）与落盘封装（原子写 + 官方同款锁 + fail-open）。
+ *
+ * 规范形态：每包一条、版本并集复合（`name@a || b`）；包名级保持裸名；scoped 名在
+ * YAML 中必须单引号包裹（`@` 不能作 plain scalar 开头）。治理只修不建；登记可为
+ * 无块的文件创建块；解析失败（含 `#` 注释行）一律弃写——pnpm 仍是最终执行者。
+ *
+ * 机理（首条规则生效）：pnpm evaluateVersionPolicy 每包名只认第一条排除规则，
+ * 同名后续规则死亡（dshmarket #732 实证）——同名合并即消除死规则。
+ * 语义对照（只读参考）：.dsh-research/dsh-market-clone/src/profile.ts:1310-1385（merge）。
+ */
+import { readFile as readFileFs } from 'node:fs/promises';
+import { join } from 'node:path';
+import { writeFileAtomic, withFileLock } from '@deepseek-ai/dsh-atomic-write';
+import { isExactVersion } from './versions.js';
+import { cachedPackumentTimes, DEFAULT_MINIMUM_RELEASE_AGE_MIN, readWorkspacePolicy } from './release-age.js';
+/** 块形态（`minimumReleaseAgeExclude:` + 块内 `- <条目>` 行）；行内数组等其它形态不在此列。 */
+const BLOCK_RE = /^minimumReleaseAgeExclude:[ \t]*\r?\n((?:[ \t]+-[^\r\n]*\r?\n?)*)/m;
+/** 任意形态的键存在性（含行内）；登记据此避免产生重复键。 */
+const KEY_ANY_FORM_RE = /^[ \t]*minimumReleaseAgeExclude[ \t]*:/m;
+const WS_FILE = 'pnpm-workspace.yaml';
+function splitEntry(raw) {
+    let text = raw.trim();
+    if (text.length >= 2 && ((text.startsWith("'") && text.endsWith("'")) || (text.startsWith('"') && text.endsWith('"')))) {
+        text = text.slice(1, -1);
+    }
+    const at = text.startsWith('@') ? text.indexOf('@', 1) : text.indexOf('@');
+    if (at === -1)
+        return text === '' ? null : { name: text, selectors: null };
+    const name = text.slice(0, at);
+    const selector = text.slice(at + 1).trim();
+    if (name === '' || selector === '')
+        return null;
+    return { name, selectors: selector.split('||').map((s) => s.trim()) };
+}
+/** 解析排除块：absent = 键缺失；unparseable = 块内含 `#` 或无法精确读取的条目（调用方弃写）。 */
+export function parseExcludeBlock(yaml) {
+    const block = BLOCK_RE.exec(yaml);
+    if (block === null)
+        return { kind: 'absent' };
+    const eol = /\r\n/.test(yaml) ? '\r\n' : '\n';
+    const indentMatch = /^([ \t]+)-/.exec(block[1]);
+    const indent = indentMatch === null ? '  ' : indentMatch[1];
+    const entries = [];
+    const rawLines = [];
+    for (const line of block[1].split(/\r?\n/)) {
+        if (line.trim() === '')
+            continue;
+        const m = /^[ \t]+-[ \t]*(.*?)[ \t]*$/.exec(line);
+        if (m === null || m[1].includes('#'))
+            return { kind: 'unparseable' };
+        const split = splitEntry(m[1]);
+        if (split === null)
+            return { kind: 'unparseable' };
+        entries.push({ name: split.name, selectors: split.selectors, quoted: /^['"]/.test(m[1]), raw: line });
+        rawLines.push(line);
+    }
+    return { kind: 'ok', entries, rawLines, eol, indent };
+}
+/** 规范行渲染：单选择器 `name@v`、多选择器 `name@a || b`、包名级裸名；scoped 名加单引号。 */
+function renderEntryLine(name, selectors, indent) {
+    const text = selectors === null || selectors.length === 0
+        ? name
+        : selectors.length === 1
+            ? `${name}@${selectors[0]}`
+            : `${name}@${selectors.join(' || ')}`;
+    return `${indent}- ${text.startsWith('@') ? `'${text.replaceAll("'", "''")}'` : text}`;
+}
+/**
+ * 治理：同名规则合并为规范形态（每包一条、版本并集、原首现顺序）；只修不建；
+ * 块缺失 → changed=false；解析失败 → null（弃写）。changed 的判定逐名比较
+ * 「合并后渲染行 vs 原始行」，只有实际被改写的名字进入 mergedNames。
+ */
+export function mergeExcludeRules(yaml) {
+    const parse = parseExcludeBlock(yaml);
+    if (parse.kind === 'absent')
+        return { yaml, changed: false, mergedNames: [], blockAbsent: true };
+    if (parse.kind === 'unparseable')
+        return null;
+    const { entries, rawLines, eol, indent } = parse;
+    const groups = new Map();
+    const order = [];
+    entries.forEach((e, i) => {
+        let g = groups.get(e.name);
+        if (g === undefined) {
+            g = { selectors: [], seen: new Set(), firstRaw: rawLines[i], count: 0 };
+            groups.set(e.name, g);
+            order.push(e.name);
+        }
+        g.count += 1;
+        if (e.selectors === null) {
+            // 包名级吞掉同名一切版本段
+            g.selectors = null;
+            g.seen.clear();
+        }
+        else if (g.selectors !== null) {
+            for (const s of e.selectors) {
+                if (!g.seen.has(s)) {
+                    g.seen.add(s);
+                    g.selectors.push(s);
+                }
+            }
+        }
+    });
+    const mergedNames = order.filter((name) => {
+        const g = groups.get(name);
+        if (g === undefined)
+            return false;
+        return g.count > 1 || renderEntryLine(name, g.selectors, indent) !== g.firstRaw;
+    });
+    if (mergedNames.length === 0)
+        return { yaml, changed: false, mergedNames: [], blockAbsent: false };
+    const lines = order.map((name) => {
+        const g = groups.get(name);
+        return renderEntryLine(name, g?.selectors ?? null, indent);
+    });
+    const blockText = `minimumReleaseAgeExclude:${eol}${lines.join(eol)}${eol}`;
+    return { yaml: yaml.replace(BLOCK_RE, () => blockText), changed: true, mergedNames, blockAbsent: false };
+}
+function newRuleLine(target, indent) {
+    if (target.pkg.startsWith('@'))
+        return { line: renderEntryLine(target.pkg, [target.version], indent), form: 'created-scoped-exact' };
+    if (target.previousVersion !== undefined && target.previousVersion !== target.version) {
+        return { line: renderEntryLine(target.pkg, [target.version, target.previousVersion], indent), form: 'created-composite' };
+    }
+    return { line: renderEntryLine(target.pkg, [target.version], indent), form: 'created-exact' };
+}
+/**
+ * 登记：把目标精确版本并入该包**首条**规则（首条规则生效口径）；无既有规则时按
+ * scoped → 精确单条、非 scoped + 异版 previousVersion → 双选择器复合、其余 → 精确单条
+ * 新建；块缺失的文件在尾部创建块（键以行内等其它形式存在 → null，避免重复键）。
+ * 目标已被覆盖（包名级 / 选择器含该版本）→ noop。
+ */
+export function registerExclusionInYaml(yaml, target) {
+    const parse = parseExcludeBlock(yaml);
+    if (parse.kind === 'unparseable')
+        return null;
+    if (parse.kind === 'absent') {
+        if (KEY_ANY_FORM_RE.test(yaml))
+            return null;
+        const eol = /\r\n/.test(yaml) ? '\r\n' : '\n';
+        const { line, form } = newRuleLine(target, '  ');
+        const base = yaml === '' || yaml.endsWith(eol) ? yaml : yaml + eol;
+        return { yaml: `${base}minimumReleaseAgeExclude:${eol}${line}${eol}`, changed: true, form };
+    }
+    const { entries, rawLines, eol, indent } = parse;
+    const lines = [...rawLines];
+    const idx = entries.findIndex((e) => e.name === target.pkg);
+    if (idx >= 0) {
+        const e = entries[idx];
+        if (e.selectors === null)
+            return { yaml, changed: false, form: 'noop' };
+        if (e.selectors.includes(target.version))
+            return { yaml, changed: false, form: 'noop' };
+        lines[idx] = renderEntryLine(target.pkg, [...e.selectors, target.version], indent);
+        const blockText = `minimumReleaseAgeExclude:${eol}${lines.join(eol)}${eol}`;
+        return { yaml: yaml.replace(BLOCK_RE, () => blockText), changed: true, form: 'merged' };
+    }
+    const { line, form } = newRuleLine(target, indent);
+    lines.push(line);
+    const blockText = `minimumReleaseAgeExclude:${eol}${lines.join(eol)}${eol}`;
+    return { yaml: yaml.replace(BLOCK_RE, () => blockText), changed: true, form };
+}
+export function parseNpmSpec(spec) {
+    let text = spec.trim();
+    if (text.length >= 2 && ((text.startsWith("'") && text.endsWith("'")) || (text.startsWith('"') && text.endsWith('"')))) {
+        text = text.slice(1, -1);
+    }
+    if (text === '' || text.includes(':'))
+        return null;
+    const at = text.startsWith('@') ? text.indexOf('@', 1) : text.indexOf('@');
+    if (at <= 0)
+        return null;
+    const pkg = text.slice(0, at);
+    const version = text.slice(at + 1);
+    if (pkg === '' || version === '' || !isExactVersion(version))
+        return null;
+    return { pkg, version };
+}
+/**
+ * 委派前治理：读-改-写全程持官方同款锁（`withFileLock(<profile>/package.json)`，
+ * toggle 同先例），changed 才原子写。fail-open：任何失败返回结构化 reason，不抛——
+ * pnpm 是最终执行者。锁只串行持锁写者，不防不持锁的 pnpm 追加（残余风险见 ADR-0009）。
+ */
+export async function governExcludeBlock(profileDir, deps = {}) {
+    if (!profileDir)
+        return { ok: true, changed: false, reason: 'no-dir' };
+    const doRead = deps.readFile ?? ((path) => readFileFs(path, 'utf8'));
+    const doWrite = deps.writeFile ??
+        (async (path, text) => {
+            await writeFileAtomic(path, text, { mode: 0o600 });
+        });
+    const file = join(profileDir, WS_FILE);
+    try {
+        return await withFileLock(join(profileDir, 'package.json'), async () => {
+            let yaml;
+            try {
+                yaml = await doRead(file);
+            }
+            catch {
+                return { ok: false, changed: false, reason: 'no-file' };
+            }
+            if (!KEY_ANY_FORM_RE.test(yaml))
+                return { ok: true, changed: false, reason: 'no-block' };
+            const merged = mergeExcludeRules(yaml);
+            if (merged === null)
+                return { ok: false, changed: false, reason: 'unparseable' };
+            if (!merged.changed)
+                return { ok: true, changed: false, reason: 'clean' };
+            await doWrite(file, merged.yaml);
+            return { ok: true, changed: true, mergedNames: merged.mergedNames };
+        });
+    }
+    catch {
+        return { ok: false, changed: false, reason: 'write-failed' };
+    }
+}
+/**
+ * 成功后登记：仅对发布时刻可判「窗口内」（显式 age 值优先，缺省 1440 分钟）的目标
+ * 触发；时刻不可得一律不登记（不发明）。本地检查（文件缺席 → no-file）先于 registry
+ * 探测——缺省绑定下无块文件零网络。与治理同锁同 fail-open 纪律。
+ */
+export async function registerExclusion(profileDir, target, deps = {}) {
+    if (!profileDir)
+        return { applied: false, reason: 'no-dir' };
+    const doRead = deps.readFile ?? ((path) => readFileFs(path, 'utf8'));
+    const doWrite = deps.writeFile ??
+        (async (path, text) => {
+            await writeFileAtomic(path, text, { mode: 0o600 });
+        });
+    const file = join(profileDir, WS_FILE);
+    try {
+        return await withFileLock(join(profileDir, 'package.json'), async () => {
+            // 本地检查先行：文件缺席直接 no-file（不发 registry 探测——缺省绑定下测试离线可跑）
+            let yaml;
+            try {
+                yaml = await doRead(file);
+            }
+            catch {
+                return { applied: false, reason: 'no-file' };
+            }
+            const times = await (deps.packumentTimes ?? cachedPackumentTimes)(target.pkg, 12_000);
+            const now = deps.nowMs ?? Date.now();
+            const publishedAt = times ? Date.parse(times[target.version] ?? '') : NaN;
+            if (!Number.isFinite(publishedAt))
+                return { applied: false, reason: 'not-young' };
+            const policy = await readWorkspacePolicy(profileDir);
+            const windowMin = policy?.minimumReleaseAgeMin ?? DEFAULT_MINIMUM_RELEASE_AGE_MIN;
+            if (now >= publishedAt + windowMin * 60_000)
+                return { applied: false, reason: 'not-young' };
+            const next = registerExclusionInYaml(yaml, target);
+            if (next === null)
+                return { applied: false, reason: 'unparseable' };
+            if (!next.changed)
+                return { applied: false, reason: 'up-to-date', form: next.form };
+            await doWrite(file, next.yaml);
+            return { applied: true, form: next.form };
+        });
+    }
+    catch {
+        return { applied: false, reason: 'write-failed' };
+    }
+}

package/lib/core/market.js

@@ -455,6 +455,7 @@ export async function listMarket(cfg = {}, opts = {}, deps = {}) {
             offset: 0,
             limit: maxLimit,
             categoryCounts: zeroCounts(),
+            sourceCounts: { primary: 0, community: 0 },
             registryState: timeoutRegistryState(cfg),
             installedComplete: false,
             latestComplete: false,
@@ -509,6 +510,9 @@ export async function listMarket(cfg = {}, opts = {}, deps = {}) {
             .map((s) => s.entry)
         : afterSort;
     const total = ordered.length;
+    // sourceCounts 分桶（0.9.25 跨区搜索摘要行）：filtered（分区 ∩ query ∩ category）计数，与排序/分页无关
+    const communityHitCount = filtered.reduce((n, entry) => n + (isCommunityEntry(entry) ? 1 : 0), 0);
+    const sourceCounts = { primary: filtered.length - communityHitCount, community: communityHitCount };
     const limit = clampLimit(opts.limit, maxLimit);
     let offset = normalizeOffset(opts.offset);
     if (total > 0 && offset >= total)
@@ -584,6 +588,7 @@ export async function listMarket(cfg = {}, opts = {}, deps = {}) {
         offset,
         limit,
         categoryCounts: counts,
+        sourceCounts,
         registryState,
         installedComplete,
         latestComplete,

package/lib/core/profile-ops.js

@@ -31,6 +31,7 @@ import { npmLatest as defaultNpmLatest, githubLatestTag as defaultGithubLatestTa
 import { classifyUpgradeActivation } from './activation.js';
 import { togglePlugin, ToggleError } from './toggle.js';
 import { describeReleaseAgeFailure, releaseAgePrecheck } from './release-age.js';
+import { governExcludeBlock, registerExclusion } from './exclude-governance.js';
 // 0.9.19：等待期失败翻译移入 release-age.ts（describeReleaseAgeFailure）——全量违规解析 +
 // 目标/旁包分述。0.9.10 版只取第一条违规并把旁包名字当成本次目标、给「改用 DSH Web」的
 // 失配指引（本机 quota-watch 0.1.15 事件实证：被拦的是旁包 dsh-m@0.9.18，文案却让用户等
@@ -121,9 +122,23 @@ async function desktopInstallLocked(id, cfg, opts, deps) {
     else {
         throw new DesktopOpsError('install-refused', `收录条目 ${entry.id} 缺少 npm/github 来源，无法在 desktop 安装`);
     }
-    // 0.9.19：供应链等待期预检——pnpm 11 锁文件校验会拦死整次安装，且失败前目标已写入
-    // node_modules（账实分裂）；目标太新或锁内「独立精确排除条目」未满期 → 委派前结构化拒绝。
-    if (entry.source === 'npm' && version !== undefined) {
+    // ADR-0009：委派前治理（排除块规范形态，fail-open）+ 供应链等待期预检收敛——默认策略
+    // 放行并附陈述（官方管理器对显式点名的新版本直接安装并自动登记）；显式设置 age 或
+    // strict 开启才拒绝。治理已落盘的编辑在成功 output 与失败 message 双路留痕。
+    let governanceNote = '';
+    let releaseAgeNotice = '';
+    let governedMergedNames;
+    if (entry.source === 'npm' && version !== undefined && opts.profileDir) {
+        try {
+            const gov = await (deps.governExclude ?? governExcludeBlock)(opts.profileDir);
+            if (gov.changed && gov.mergedNames?.length) {
+                governanceNote = `；排除条目治理：合并 ${gov.mergedNames.join('、')}`;
+                governedMergedNames = gov.mergedNames;
+            }
+        }
+        catch {
+            // fail-open：治理失败不阻塞委派（pnpm 仍是最终执行者）
+        }
         const gate = await releaseAgePrecheck({
             pkg,
             version,
@@ -132,20 +147,35 @@ async function desktopInstallLocked(id, cfg, opts, deps) {
             signal: opts.signal,
             deps: { packumentTimes: deps.packumentTimes, workspacePolicy: deps.workspacePolicy },
         });
-        if (gate.blocked)
-            throw new DesktopOpsError('release-age-wait', gate.message, { blockers: gate.blockers });
+        if (gate.blocked) {
+            throw new DesktopOpsError('release-age-wait', gate.message + governanceNote, { blockers: gate.blockers, ...(governedMergedNames !== undefined ? { governanceMerged: governedMergedNames } : {}) });
+        }
+        if (gate.notice)
+            releaseAgeNotice = `；${gate.notice}`;
     }
     let change;
     let bundleName;
+    let registerNote;
+    let managed;
     try {
-        ({ change, bundleName } = await runManagedInstall(service, { pkg, spec, version, profileDir: opts.profileDir, approvedBuilds: opts.approvedBuilds, listInstalled: deps.listInstalled }));
+        managed = await runManagedInstall(service, { pkg, spec, version, profileDir: opts.profileDir, approvedBuilds: opts.approvedBuilds, listInstalled: deps.listInstalled }, { governExclude: deps.governExclude, registerExclude: deps.registerExclude, packumentTimes: deps.packumentTimes });
+        change = managed.change;
+        bundleName = managed.bundleName;
+        registerNote = managed.registerNote;
     }
     catch (err) {
         if (err instanceof DesktopBuildApprovalNeeded) {
-            return { ok: false, needsBuildApproval: true, id: entry.id, pkg, spec, pendingBuilds: err.pendingBuilds, message: err.message };
+            return { ok: false, needsBuildApproval: true, id: entry.id, pkg, spec, pendingBuilds: err.pendingBuilds, message: err.message + governanceNote };
+        }
+        if (err instanceof Error) {
+            if (governanceNote !== '' && !err.message.includes(governanceNote))
+                err.message += governanceNote;
+            if (managed?.governRetryNote !== undefined && !err.message.includes(managed.governRetryNote))
+                err.message += managed.governRetryNote;
         }
         throw err;
     }
+    const retryNote = managed.governRetryNote !== undefined && !governanceNote.includes(managed.governRetryNote) ? managed.governRetryNote : '';
     return {
         id: entry.id,
         pkg,
@@ -158,7 +188,7 @@ async function desktopInstallLocked(id, cfg, opts, deps) {
         ...(compat !== null ? { compat } : {}),
         ...(compatSkipped ? { compatSkipped } : {}),
         needsRestart: true,
-        output: `official pluginManager: application=${change.application ?? 'applied'}, bundle=${bundleName}${change.changed === false ? ', changed=false' : ''}`,
+        output: `official pluginManager: application=${change.application ?? 'applied'}, bundle=${bundleName}${change.changed === false ? ', changed=false' : ''}${governanceNote}${retryNote}${releaseAgeNotice}${registerNote ?? ''}`,
         via: 'desktop-manager',
         ...(change.application === 'overridden' ? { overridden: true } : {}),
     };
@@ -208,7 +238,17 @@ function enableStageFailureMessage(pkg, change) {
     }
     return `安装后启用阶段失败（${pkg}；application=failed、stage=enable${change.error?.code ? `、error=${change.error.code}` : ''}）：${writtenText}，请在官方 Desktop 插件页查看状态或重试`;
 }
-async function runManagedInstall(service, ctx) {
+const DUAL_CODE_RE = /ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION|ERR_PNPM_NO_MATURE_MATCHING_VERSION/;
+/** 可治理的失败形态：cancelled / build-blocked 不治理不重试（与 mapFailure 分类一致）。 */
+function isGovableFailure(change) {
+    if (change.application === 'cancelled')
+        return false;
+    const pending = Array.isArray(change.pendingBuilds) ? change.pendingBuilds.filter((n) => typeof n === 'string') : [];
+    if (change.packageResult?.kind === 'build-blocked' && pending.length > 0)
+        return false;
+    return change.application === 'failed' || change.error !== undefined;
+}
+async function runManagedInstall(service, ctx, deps = {}) {
     const installOnce = async () => changeOf(await service.installBundle(ctx.spec, {
         enabled: true,
         ...(ctx.approvedBuilds && ctx.approvedBuilds.length > 0 ? { approvedBuilds: ctx.approvedBuilds } : {}),
@@ -276,9 +316,46 @@ async function runManagedInstall(service, ctx) {
             await sleepMs(enableRetryDelayMs);
         change = await installOnce();
     }
-    if (change.application === 'failed' || change.application === 'cancelled' || change.error)
-        await mapFailure(change);
-    return verifyAndBundle(change);
+    // ADR-0009 挂点3：双码失败 → 治理 → changed 则重试该命令一次（每次调用至多一次；
+    // cancelled / build-blocked 不治理不重试）。仍败走既有 mapFailure（含账实分裂复读）；
+    // 挂点3 已落盘的合并以短语并入失败 message 与成功 output（留痕契约含挂点3）。
+    let governRetryNote;
+    if (isGovableFailure(change) && DUAL_CODE_RE.test(`${change.error?.diagnostic ?? ''}\n${change.error?.code ?? ''}`)) {
+        const gov = await (deps.governExclude ?? governExcludeBlock)(ctx.profileDir ?? '');
+        if (gov.changed) {
+            if (gov.mergedNames?.length)
+                governRetryNote = `；排除条目治理：合并 ${gov.mergedNames.join('、')}`;
+            change = await installOnce();
+        }
+    }
+    if (change.application === 'failed' || change.application === 'cancelled' || change.error) {
+        try {
+            await mapFailure(change);
+        }
+        catch (err) {
+            if (err instanceof Error && governRetryNote !== undefined && !err.message.includes(governRetryNote))
+                err.message += governRetryNote;
+            throw err;
+        }
+    }
+    const verified = await verifyAndBundle(change);
+    // ADR-0009 挂点2：成功后登记（仅 npm 源窗口内目标；fail-open，applied 短语由调用方并入 output）
+    let registerNote;
+    if (ctx.profileDir && ctx.version) {
+        try {
+            const reg = await (deps.registerExclude ?? registerExclusion)(ctx.profileDir, {
+                pkg: ctx.pkg,
+                version: ctx.version,
+                ...(ctx.previousVersion !== undefined ? { previousVersion: ctx.previousVersion } : {}),
+            }, deps.packumentTimes ? { packumentTimes: deps.packumentTimes } : {});
+            if (reg.applied && reg.form)
+                registerNote = `；排除条目已登记 ${ctx.pkg}@${ctx.version}（${reg.form}）`;
+        }
+        catch {
+            // fail-open：登记失败不影响安装/升级成功态
+        }
+    }
+    return { ...verified, ...(registerNote !== undefined || governRetryNote !== undefined ? { registerNote, governRetryNote } : {}) };
 }
 /**
  * Desktop 卸载（0.9.8，dsh-market 同策略）：removeBundle 委派 + ChangeResult 判定 +
@@ -383,8 +460,21 @@ async function desktopUpgradeLocked(pkg, cfg, opts, deps) {
     else {
         throw new DesktopOpsError('install-refused', `收录条目 ${entry.id} 缺少 npm/github 来源，无法在 desktop 升级`);
     }
-    // 0.9.19：供应链等待期预检（同 desktopInstallLocked；0:15 quota-watch 事件即此形态实证）
-    if (entry.source === 'npm' && version !== undefined) {
+    // ADR-0009：委派前治理 + 预检收敛（同 desktopInstallLocked；0:15 quota-watch 事件为治理前的旧形态实证）
+    let governanceNote = '';
+    let releaseAgeNotice = '';
+    let governedMergedNames;
+    if (entry.source === 'npm' && version !== undefined && opts.profileDir) {
+        try {
+            const gov = await (deps.governExclude ?? governExcludeBlock)(opts.profileDir);
+            if (gov.changed && gov.mergedNames?.length) {
+                governanceNote = `；排除条目治理：合并 ${gov.mergedNames.join('、')}`;
+                governedMergedNames = gov.mergedNames;
+            }
+        }
+        catch {
+            // fail-open：治理失败不阻塞委派
+        }
         const gate = await releaseAgePrecheck({
             pkg,
             version,
@@ -393,20 +483,35 @@ async function desktopUpgradeLocked(pkg, cfg, opts, deps) {
             signal: opts.signal,
             deps: { packumentTimes: deps.packumentTimes, workspacePolicy: deps.workspacePolicy },
         });
-        if (gate.blocked)
-            throw new DesktopOpsError('release-age-wait', gate.message, { blockers: gate.blockers });
+        if (gate.blocked) {
+            throw new DesktopOpsError('release-age-wait', gate.message + governanceNote, { blockers: gate.blockers, ...(governedMergedNames !== undefined ? { governanceMerged: governedMergedNames } : {}) });
+        }
+        if (gate.notice)
+            releaseAgeNotice = `；${gate.notice}`;
     }
     let change;
     let bundleName;
+    let registerNote;
+    let managed;
     try {
-        ({ change, bundleName } = await runManagedInstall(service, { pkg, spec, version, profileDir: opts.profileDir, approvedBuilds: opts.approvedBuilds, listInstalled: deps.listInstalled }));
+        managed = await runManagedInstall(service, { pkg, spec, version, previousVersion: target.version, profileDir: opts.profileDir, approvedBuilds: opts.approvedBuilds, listInstalled: deps.listInstalled }, { governExclude: deps.governExclude, registerExclude: deps.registerExclude, packumentTimes: deps.packumentTimes });
+        change = managed.change;
+        bundleName = managed.bundleName;
+        registerNote = managed.registerNote;
     }
     catch (err) {
         if (err instanceof DesktopBuildApprovalNeeded) {
-            return { ok: false, needsBuildApproval: true, id: entry.id, pkg, spec, pendingBuilds: err.pendingBuilds, message: err.message };
+            return { ok: false, needsBuildApproval: true, id: entry.id, pkg, spec, pendingBuilds: err.pendingBuilds, message: err.message + governanceNote };
+        }
+        if (err instanceof Error) {
+            if (governanceNote !== '' && !err.message.includes(governanceNote))
+                err.message += governanceNote;
+            if (managed?.governRetryNote !== undefined && !err.message.includes(managed.governRetryNote))
+                err.message += managed.governRetryNote;
         }
         throw err;
     }
+    const retryNote = managed.governRetryNote !== undefined && !governanceNote.includes(managed.governRetryNote) ? managed.governRetryNote : '';
     // 0.9.22 生效判定：npm 源升级在成功点分类；任何异常 fail-open 到 unknown，绝不影响升级成功态
     let activation;
     let needsRestart = true;
@@ -432,7 +537,7 @@ async function desktopUpgradeLocked(pkg, cfg, opts, deps) {
         ...(compat !== null ? { compat } : {}),
         ...(compatSkipped ? { compatSkipped } : {}),
         needsRestart,
-        output: `official pluginManager: application=${change.application ?? 'applied'}, bundle=${bundleName}${change.changed === false ? ', changed=false' : ''}`,
+        output: `official pluginManager: application=${change.application ?? 'applied'}, bundle=${bundleName}${change.changed === false ? ', changed=false' : ''}${governanceNote}${retryNote}${releaseAgeNotice}${registerNote ?? ''}`,
         via: 'desktop-manager',
         ...(change.application === 'overridden' ? { overridden: true } : {}),
         fromVersion: target.version,

package/lib/core/registry.js

@@ -825,3 +825,14 @@ export async function loadDefaultRegistry(cfg = {}, opts = {}) {
     }
     return loadDefaultChain(cfg, opts, { namespace, profile, includeBundled: true });
 }
+/**
+ * verified 污染检测（know-how 022）：`verified` 只记 **DSH 运行时**装机实测版本；
+ * 历史上反复出现把**插件自身版本号**误填进 verified 的事故（实证：dsh-quota-watch
+ * 条目曾出现 "0.1.0"——那是 quota-watch 的插件版本，不是任何 DSH 运行时版本）。
+ * 把条目 verified 与该插件自身 npm 已发布版本求交集，非空即高度可疑（warn 不 fail：
+ * 极小概率某代 DSH 与插件版本字面重合，人工复核后放行）。
+ */
+export function verifiedPollution(verified, publishedVersions) {
+    const own = new Set(publishedVersions);
+    return (verified ?? []).filter((v) => own.has(v));
+}