dsh-m 0.2.8 → 0.2.9

package/docs/DESIGN.md

@@ -63,12 +63,26 @@
 
 底层原语（本机实证）：`dsh plugin --profile web add|remove|update`（转发 pnpm，作用于 `$DSH_HOME/profiles/web`）。**profile 的 `package.json` 就是唯一事实源**——不引入任何额外状态文件。
 
-- **安装（npm 源）**：装最新版并以**精确版本锁定**（不用 `^` 范围；用户指定版本必须为精确 semver，经该精确版本 endpoint 查询）。安装前对 profile 的 `package.json` / `pnpm-lock.yaml` / `pnpm-workspace.yaml` 做**字节快照**；安装后核验 importer 依赖为该精确版本（旧版 CLI 写入的 `^v`/`~v` 锚定 range 视为等价放行，2026-09-05 实机实证；精确性由紧随的 lockfile 解析与 integrity 兜底，其余 spec 仍 fail closed），并在 lockfile `packages` 条目中比对与 npm dist 一致的 `resolution.integrity`——缺失或不一致 **fail closed** 并执行 **best-effort dependency rollback**：原子恢复快照字节 + frozen 自愈阶梯（`pnpm install --frozen-lockfile` → 仍报 `CONFIG_MISMATCH` 时把 lockfile 记录的 overrides 对齐回 `package.json#pnpm.overrides` 再复验 → `CONFIG_MISMATCH` / `OUTDATED_LOCKFILE` 顽固失配才降级 `--no-frozen-lockfile` 重建并明确告知「lockfile 已重建」；全阶梯失败才报「可能需要人工修复」）。成功路径若发现安装链丢失了 manifest 顶层未知键（如 `pnpm.overrides`，2026-09-05 升级回滚事故），从快照找回并复验 frozen 一致性，输出带 `[dsh-m 自愈]` 报告。刚发布 ~1 分钟内的 `ERR_PNPM_NO_MATCHING_VERSION` 多为 packument CDN 滞后：退避重试 2 次（5s/15s），每次重试前拉一次完整 packument 预热。不声称 node_modules 与间接依赖已字节级回滚。
-- **安装（GitHub 源）**：解析并**锁定 commit SHA**（`github:owner/repo#sha`），skillhub 同款。
+### 3.1 Profile 变更事务（`src/core/profile-transaction.ts`，2026-09-07 重构）
+
+npm 安装 / GitHub 安装 / 升级 / 自升级 / 卸载是**同一个事务模块的四个入口**（自升级 = `install-npm` + 自身包名）。编排层（market.ts / host-api.ts / tools.ts / cli.ts）只做「版本/收录条目解析（事务外）→ 开事务 → 包装结果」，互斥锁收编在模块内部（模块级 FIFO，进程内串行）。
+
+- **两阶段不变量（失败保证）**：变更失败时，①先把三个关键文件（package.json / pnpm-lock.yaml / pnpm-workspace.yaml）**逐字节还原到变更前快照**，还原后立即重读比对验证（`snapshotRestoreVerified` 报告此历史事实）；②再跑 frozen 收敛阶梯处理依赖一致性——阶梯中的 overrides 对齐 / `--no-frozen-lockfile` 重建允许对 manifest/lockfile 做**有记录的**受控改写（`healActions`）。失败终态承诺「**一致**」（`status='rolled-back'`）不必然「等同」；收敛耗尽则 `status='manual-repair'`（还原事实独立如实报告）。不声称 node_modules 字节级回滚。
+- **结果为四分支判别联合**：`committed` / `rejected`（快照失败、前置校验失败、排队期 abort——零写入）/ `rolled-back` / `manual-repair`；`healActions[{code, note}]` + `failure{code, note}`（英文稳定 code，机器可断言）；中文散文只在展示层由 `renderFailure` 生成（唯一产地）。消费方拿结构化结果自行渲染；host-api 失败体附 `detail` 白名单投影（不含 raw output，GUI 零改动只读 `error`）。
+- **pnpm 结果只以六类分类穿过接缝**（`dsh-cli.ts` 是分类器唯一产地）：ok / retryable-lag（CDN 滞后）/ config-drift（配置漂移）/ unused-patch / needs-builds / hard-fail；**分类发生在任何文案改写之前**，事务与 market 永不 regex pnpm 原始输出、只消费 `PNPM_OUTCOME_CODES` 常量。分类消费矩阵（add/remove/frozen/rebuild × 六类）由参数化测试全枚举钉死。
+- **自愈阶梯**（全部以 healActions 记录）：B1 安装链丢 manifest 顶层键 → 快照找回 + frozen 复验（复验失败 fail-closed 进回滚）；B2 frozen 收敛：CONFIG_MISMATCH → 把 lockfile 记录的 overrides 对齐回 `package.json#pnpm.overrides` 再复验 → 顽固失配（含 OUTDATED_LOCKFILE specifier 漂移）降级 `--no-frozen-lockfile` 重建；B3 刚发布 `ERR_PNPM_NO_MATCHING_VERSION` 退避重试 2 次（5s/15s，abort-aware），每次重试前预热完整 packument（生产绑定 `makeNpmWarmPackument`，失败吞错）；构建脚本被拦 → `dangerouslyAllowAllBuilds` 放行并**必须明确报告**（在途重试在 adapter 的 `makeAddViaLadder` 内耗尽）。
+- **signal 语义**：request 可带 AbortSignal，贯通 runner 四操作、预热与退避 sleep（abort 即醒）；mutate 前 abort → `rejected`；mutate 后 abort → 中止在途调用并执行**不可取消的**回滚（不变量优先于取消）；mutation 返回与提交前复查 signal——runner 返回 ok 但已取消的事务同样进 ABORTED 回滚，不提交。
+- **互斥边界（已知限制）**：FIFO 锁为**进程内**互斥——Web Host / GUI / Agent tools 与独立 `dshm` CLI 可能运行在不同进程、操作同一 web profile，跨进程并发不在覆盖范围。变更执行期间避免同时从 GUI/Agent/CLI 发起另一次变更；跨进程锁（lockfile + stale 恢复）留作后续演进。
+- **快照/原子写原语**（`npm-integrity.ts`）：快照仅吞 ENOENT（其他读取异常 fail closed 零写入）；原子写 POSIX 直接 rename（无「先删后改名」窗口），Windows EPERM/EEXIST 走备份协议；**任何失败路径（含 write/sync/close）都清理 tmp**，备份恢复自身失败时报告 backup 路径与双重错误。
+
+### 3.2 各入口语义
+
+- **安装（npm 源）**：装最新版并以**精确版本锁定**（不用 `^` 范围；用户指定版本必须为精确 semver，经该精确版本 endpoint 查询；dist integrity 缺失 fail closed 不进事务）。事务内核验 importer 依赖为该精确版本（旧版 CLI 写入的 `^v`/`~v` 锚定 range 视为等价放行并记录 `RANGE_ANCHOR_ACCEPTED`；精确性由紧随的 lockfile 解析与 integrity 兜底，其余 spec 仍 fail closed），并在 lockfile `packages` 条目中比对与 npm dist 一致的 `resolution.integrity`。
+- **安装（GitHub 源）**：解析并**锁定 commit SHA**（`github:owner/repo#sha`）。核验采用**前态比对**：新 spec 必须相对快照是新写入（预置同 spec 旧依赖不误命中），否则 `GITHUB_SPEC_MISMATCH` 回滚。
 - **已装识别**：读 profile `package.json` dependencies，与 registry 匹配 → 标注「市场安装」；不匹配的也列出，标注「非市场安装 / 来源未知」。卸载/升级对两类都可用。
-- **卸载**：live-disable（先让 client bundle 下线，避免 404）→ 摘除该包在 profile 的补丁条目（`pnpm-workspace.yaml` 顶层 `patchedDependencies` 与 `package.json#pnpm.patchedDependencies`；依赖移除后残留条目会令 pnpm 以 `ERR_PNPM_UNUSED_PATCH` 整单失败，只精确匹配 `pkg` / `pkg@ver`，补丁文件本体保留并计入残留报告）→ `dsh plugin remove`。**不清理插件产生的数据/配置**，但把检测到的疑似残留路径（如 `~/.dsh/<plugin>.json`）列出报告。
-- **升级**：**按需检查**（`dshm_outdated` / `dshm_list` 时实时比对本地版本 vs npm latest / GitHub main），半自动——展示升级计划，确认后执行。**不做后台定时器**。
-- **自更新**：dsh-m 对自己同样做版本比对 + 提示升级（设置页呈现）。
+- **卸载**（事务定序写死）：validate（严格读取：NOT_INSTALLED / NOT_DSH_PLUGIN / PLUGIN_METADATA_UNREADABLE，全部零写入零快照）→ 快照 → live-disable（先让 client bundle 下线，避免 404；回滚时尽力反向）→ 摘除该包补丁条目（`pnpm-workspace.yaml` 顶层 `patchedDependencies` 与 `package.json#pnpm.patchedDependencies`；残留条目会令 pnpm 以 `ERR_PNPM_UNUSED_PATCH` 整单失败，只精确匹配 `pkg` / `pkg@ver`，补丁文件本体保留并计入残留报告）→ remove → verify gone（仍在则回滚）。**不清理插件产生的数据/配置**，但把检测到的疑似残留路径（如 `~/.dsh/<plugin>.json`）列出报告。
+- **升级**：**按需检查**（`dshm_outdated` / `dshm_list` 时实时比对本地版本 vs npm latest / GitHub release，半自动——展示升级计划，确认后执行，即重开一次安装事务）。**不做后台定时器**。
+- **自更新**：dsh-m 对自己同样做版本比对 + 提示升级（设置页呈现）；执行即 `install-npm` 事务（integrity 缺失直接拒绝，不进事务）。
 - **重启**：内置**一键重启**，复用 skillhub 验证过的重启路径（本机 `dsh-web.service` 是转发 shim，不新建 systemd 单元、不监听 3080）。安装/卸载/升级完成后 GUI 弹「需重启生效 [一键重启]」横幅，工具返回重启提示。
 - **安全基线（5 条）**：
   1. 所有拉取仅 HTTPS + 响应大小上限 + 超时；

package/lib/cli.js

@@ -5,7 +5,7 @@
  * 独立 CLI 固定 namespace:'cli'（与 Host 的 host namespace cache 互不影响）；
  * registry/search/list/outdated 在清单不可用时打印配置/实际生效地址并 exit 1。
  */
-import { installFromRegistry, listInstalledWithMeta, listMarket, uninstallPlugin, upgradePlugin, withMutationLock, } from './core/market.js';
+import { installFromRegistry, listInstalledWithMeta, listMarket, uninstallPlugin, upgradePlugin, } from './core/market.js';
 import { loadRegistry } from './core/registry.js';
 import { scheduleRestart } from './core/restart.js';
 import { pathToFileURL } from 'node:url';
@@ -92,6 +92,7 @@ const HELP = `dshm — DSH Marketplace（个人自用 DSH 插件市场）
   dshm upgrade --pkg <包名> --yes
   dshm uninstall --pkg <包名> --yes
   dshm restart --yes
+  注意：变更互斥仅在进程内生效——变更执行期间不要同时从 GUI / Agent 工具发起另一次变更。
 
 环境变量：DSHM_REGISTRY_URL（registry 源覆盖）、DSHM_TIMEOUT_MS、DSHM_CACHE_TTL_MIN、DSHM_CACHE_DIR
 `;
@@ -214,7 +215,7 @@ async function runCliDispatch(argv, deps, io) {
         case 'install': {
             const id = needFlag(flags, 'id');
             const version = typeof flags.version === 'string' ? flags.version : undefined;
-            const res = await withMutationLock(() => d.installFromRegistry(id, cfg, { version, namespace: 'cli' }));
+            const res = await d.installFromRegistry(id, cfg, { version, namespace: 'cli' });
             out(`✅ 已安装 ${res.pkg}（${res.spec}）`);
             if (res.usedAllowAllBuilds)
                 out('⚠️  该插件执行了构建脚本（已按策略放行）。');
@@ -224,7 +225,7 @@ async function runCliDispatch(argv, deps, io) {
         case 'upgrade': {
             const target = needFlag(flags, 'pkg');
             requireYes(flags, '升级');
-            const res = await withMutationLock(() => d.upgradePlugin(target, cfg, { namespace: 'cli' }));
+            const res = await d.upgradePlugin(target, cfg, { namespace: 'cli' });
             const from = res.fromVersion ? `v${res.fromVersion} → ` : '';
             const to = res.version ? `v${res.version}` : res.sha ? res.sha.slice(0, 7) : '最新';
             out(`✅ 已升级 ${res.pkg}（${from}${to}）`);
@@ -236,7 +237,7 @@ async function runCliDispatch(argv, deps, io) {
         case 'uninstall': {
             const target = needFlag(flags, 'pkg');
             requireYes(flags, '卸载');
-            const res = await withMutationLock(() => d.uninstallPlugin(target, cfg, { namespace: 'cli' }));
+            const res = await d.uninstallPlugin(target, cfg, { namespace: 'cli' });
             out(`✅ 已卸载 ${res.pkg}${res.liveDisabled ? '（运行中的界面已先下线）' : ''}`);
             if (res.leftovers.length)
                 out(`ℹ️  疑似残留数据（未删除）：${res.leftovers.join('、')}`);

package/lib/core/dsh-cli.js

@@ -201,6 +201,46 @@ function syncProgress(tracker) {
     if (snap.error !== null)
         progress.error = snap.error;
 }
+export const PNPM_OUTCOME_CODES = {
+    CONFIG_MISMATCH: 'ERR_PNPM_LOCKFILE_CONFIG_MISMATCH',
+    OUTDATED_LOCKFILE: 'ERR_PNPM_OUTDATED_LOCKFILE',
+    NO_MATCHING_VERSION: 'ERR_PNPM_NO_MATCHING_VERSION',
+    UNUSED_PATCH: 'ERR_PNPM_UNUSED_PATCH',
+    PUBLIC_HOIST_PATTERN_DIFF: 'ERR_PNPM_PUBLIC_HOIST_PATTERN_DIFF',
+};
+/**
+ * 对 pnpm/dsh 原始输出文本做六类归一解释。分类发生在任何文案改写之前；
+ * 上层（事务/market）只消费 class + code 常量，永不 regex 原始输出。
+ */
+export function classifyPnpmError(text) {
+    const raw = String(text ?? '');
+    if (raw.includes(PNPM_OUTCOME_CODES.NO_MATCHING_VERSION)) {
+        return { class: 'retryable-lag', code: PNPM_OUTCOME_CODES.NO_MATCHING_VERSION };
+    }
+    if (raw.includes(PNPM_OUTCOME_CODES.CONFIG_MISMATCH)) {
+        return { class: 'config-drift', code: PNPM_OUTCOME_CODES.CONFIG_MISMATCH };
+    }
+    if (raw.includes(PNPM_OUTCOME_CODES.OUTDATED_LOCKFILE)) {
+        return { class: 'config-drift', code: PNPM_OUTCOME_CODES.OUTDATED_LOCKFILE };
+    }
+    if (raw.includes(PNPM_OUTCOME_CODES.UNUSED_PATCH)) {
+        return { class: 'unused-patch', code: PNPM_OUTCOME_CODES.UNUSED_PATCH };
+    }
+    if (isPrepareBlocked(raw))
+        return { class: 'needs-builds' };
+    const m = /(ERR_PNPM_[A-Z0-9_]+)/.exec(raw);
+    return { class: 'hard-fail', code: m?.[1] };
+}
+/** 统一的命令取消错误形态（runCommand 调用前已取消与运行中取消同款）。 */
+function commandAbortError() {
+    const err = new Error('命令已取消');
+    err.name = 'AbortError';
+    return err;
+}
+function truncateOutput(text) {
+    const raw = String(text ?? '');
+    return raw.length <= 800 ? raw : raw.slice(-800);
+}
 export function webProfileName() {
     return WEB_PROFILE;
 }
@@ -327,8 +367,33 @@ export function errorDigest(out, maxChars = 800) {
     }
     return text.slice(-maxChars);
 }
+/**
+ * 停止宽限（毫秒）归一：允许显式 0（立即 SIGKILL）；负数/NaN/Infinity/垃圾值一律回落
+ * 缺省。Y1（第四轮复审）：`Number(raw) || 5000` 会把 -1 当真值、把显式 0 吞成缺省。
+ */
+const KILL_GRACE_DEFAULT_MS = 5_000;
+function normalizeKillGrace(raw) {
+    const value = typeof raw === 'number' ? raw : Number(raw);
+    return Number.isFinite(value) && value >= 0 ? value : null;
+}
+export { normalizeKillGrace };
+function killGraceDefault() {
+    const raw = process.env.DSH_KILL_GRACE_MS;
+    if (raw === undefined || raw.trim() === '')
+        return KILL_GRACE_DEFAULT_MS;
+    return normalizeKillGrace(raw) ?? KILL_GRACE_DEFAULT_MS;
+}
+/** SIGKILL 后组存活轮询的硬上限（毫秒）：防 D 态进程导致永不 settle。 */
+const GROUP_POLL_CAP_MS = 10_000;
 export async function runCommand(command, args, options) {
     return new Promise((resolvePromise, reject) => {
+        // R4a（终审复审）：AbortSignal 的事件不会对后注册的 listener 重放——调用前已取消的
+        // signal 必须在 spawn 前拒绝，否则命令会完整执行副作用。检查与 listener 注册之间为
+        // 同步代码，无交织窗口。
+        if (options.signal?.aborted) {
+            reject(commandAbortError());
+            return;
+        }
         const child = spawn(command, args, {
             cwd: options.cwd,
             env: { ...process.env, ...options.env, CI: 'true' },
@@ -338,41 +403,89 @@ export async function runCommand(command, args, options) {
         });
         let out = '';
         let settled = false;
+        let stopping = false;
+        let pendingError;
+        let killTimer;
+        let pollTimer;
+        let pollDeadline = 0;
+        // 组语义仅 POSIX + detached（child 是组长）才成立；Windows/非 detached 只保证 direct child
+        const groupSupported = process.platform !== 'win32' && child.pid !== undefined;
+        const groupAlive = () => {
+            if (!groupSupported)
+                return false;
+            try {
+                process.kill(-child.pid, 0);
+                return true;
+            }
+            catch (err) {
+                // ESRCH = 组不存在；EPERM 等保守视为仍存活
+                return err.code !== 'ESRCH';
+            }
+        };
         const finish = (err) => {
             if (settled)
                 return;
             settled = true;
             clearTimeout(timer);
+            if (killTimer !== undefined)
+                clearTimeout(killTimer);
+            if (pollTimer !== undefined)
+                clearTimeout(pollTimer);
             options.signal?.removeEventListener('abort', onAbort);
             if (err)
                 reject(err);
             else
                 resolvePromise(out);
         };
-        const killChild = () => {
-            if (process.platform !== 'win32' && child.pid !== undefined) {
+        const signalGroup = (sig) => {
+            if (groupSupported) {
                 try {
-                    process.kill(-child.pid, 'SIGTERM');
+                    process.kill(-child.pid, sig);
                     return;
                 }
                 catch {
-                    /* fall through */
+                    /* fall through：组可能已消失 */
                 }
             }
             try {
-                child.kill('SIGTERM');
+                child.kill(sig);
             }
             catch {
                 /* already gone */
             }
         };
+        const pollGroupGone = () => {
+            if (settled)
+                return;
+            // SIGKILL 已发：组消失（或超过轮询硬上限，防 D 态进程）才 settle
+            if (!groupAlive() || Date.now() > pollDeadline) {
+                finish(pendingError);
+                return;
+            }
+            pollTimer = setTimeout(pollGroupGone, 25);
+        };
+        /**
+         * F1-R（第三轮复审）：停止协议以「进程组不存在」为 settle 前提——SIGTERM 进程组 →
+         * 宽限后 SIGKILL → 轮询确认组消失。direct child 提前 close 不清除 kill 定时器
+         * （同组后代可能仍忽略 SIGTERM 并写 profile）。
+         */
+        const stopChild = (err) => {
+            if (settled || stopping)
+                return;
+            stopping = true;
+            pendingError = err;
+            signalGroup('SIGTERM');
+            killTimer = setTimeout(() => {
+                signalGroup('SIGKILL');
+                pollDeadline = Date.now() + GROUP_POLL_CAP_MS;
+                pollGroupGone();
+            }, normalizeKillGrace(options.killGraceMs) ?? killGraceDefault());
+        };
         const timer = setTimeout(() => {
-            killChild();
-            finish(new Error(`命令超时 ${options.timeoutMs}ms`));
+            stopChild(new Error(`命令超时 ${options.timeoutMs}ms`));
         }, options.timeoutMs);
         const onAbort = () => {
-            killChild();
-            finish(new Error('命令已取消'));
+            stopChild(commandAbortError());
         };
         options.signal?.addEventListener('abort', onAbort, { once: true });
         child.stdout?.on('data', (chunk) => {
@@ -385,8 +498,20 @@ export async function runCommand(command, args, options) {
             out = (out + text).slice(-256 * 1024);
             options.onChunk?.(text);
         });
-        child.on('error', (err) => finish(err));
+        child.on('error', (err) => {
+            // F1-R：停止协议进行中，迟到的 error（如 kill 竞态）只作诊断，不得提前收口
+            if (stopping)
+                return;
+            finish(err);
+        });
         child.on('close', (code) => {
+            if (stopping) {
+                // direct child close ≠ 进程组停止：组仍存活 → 保留 SIGKILL 定时器/轮询，不 settle
+                if (groupAlive())
+                    return;
+                finish(pendingError);
+                return;
+            }
             if (code === 0)
                 finish();
             else
@@ -409,6 +534,7 @@ export async function runDshPlugin(profile, pluginArgs, deps = {}) {
         return await run(argv.file, [...argv.args, 'plugin', '--profile', profile, ...prepared], {
             cwd: argv.cwd,
             timeoutMs: deps.timeoutMs ?? installTimeoutMs(),
+            signal: deps.signal,
             env: { CI: 'true' },
             viaShell: argv.viaShell,
             detached: process.platform !== 'win32',
@@ -430,47 +556,143 @@ export async function runDshPlugin(profile, pluginArgs, deps = {}) {
     }
 }
 /**
- * 安装。返回 usedAllowAllBuilds 供 UI 明确报告「该插件执行了构建脚本」。
- * source 形如：`pkg@1.2.3`（npm 精确锁定）或 `github:owner/repo#sha`（锁 SHA）。
+ * 加装阶梯工厂（导出、可注入、可测试；生产与测试共用同一实现）。
+ * 阶梯：add → prepare 被拦时写 dangerouslyAllowAllBuilds 重试 →
+ * PUBLIC_HOIST_PATTERN_DIFF 时 `install --no-frozen-lockfile` 重建后重试 →
+ * 耗尽归类返回。对**原始错误文本**分类；永不 throw，一律返回 RunnerOutcome。
  */
-export async function addDshPlugin(source, deps = {}) {
-    const run = deps.runDshPlugin ?? runDshPlugin;
+export function makeAddViaLadder(deps) {
+    const run = deps.runDshPlugin;
     const allowAllBuilds = deps.allowAllBuilds ?? writeDangerouslyAllowAllBuilds;
-    const retryAfterPrepare = async () => {
-        const changed = allowAllBuilds(deps.profileDir ?? webProfileDir());
-        try {
-            return { output: await run(WEB_PROFILE, ['add', source]), usedAllowAllBuilds: true };
-        }
-        catch (retryErr) {
-            throw rewritePnpmError(retryErr);
-        }
-    };
-    try {
-        return { output: await run(WEB_PROFILE, ['add', source]), usedAllowAllBuilds: false };
-    }
-    catch (err) {
-        const text = err instanceof Error ? err.message : String(err);
-        if (text.includes('ERR_PNPM_PUBLIC_HOIST_PATTERN_DIFF')) {
-            await run(WEB_PROFILE, ['install', '--no-frozen-lockfile']);
+    const opts = (signal) => (signal !== undefined ? { signal } : undefined);
+    return async (source, profileDir, signal) => {
+        const retryAfterPrepare = async () => {
+            // Y2（终审复审）：allowAll 写入本身失败也必须转换为结果，维持「永不 throw」契约
+            try {
+                allowAllBuilds(profileDir);
+            }
+            catch (err) {
+                const text = errText(err);
+                return { class: 'hard-fail', output: truncateOutput(text) };
+            }
             try {
-                return { output: await run(WEB_PROFILE, ['add', source]), usedAllowAllBuilds: false };
+                const output = await run(WEB_PROFILE, ['add', source], opts(signal));
+                return { class: 'ok', output: truncateOutput(output), usedAllowAllBuilds: true };
             }
             catch (retryErr) {
-                if (!isPrepareBlocked(retryErr instanceof Error ? retryErr.message : String(retryErr))) {
-                    throw rewritePnpmError(retryErr);
+                return { ...classifyPnpmError(errText(retryErr)), output: truncateOutput(errText(retryErr)) };
+            }
+        };
+        try {
+            const output = await run(WEB_PROFILE, ['add', source], opts(signal));
+            return { class: 'ok', output: truncateOutput(output), usedAllowAllBuilds: false };
+        }
+        catch (err) {
+            const text = errText(err);
+            if (text.includes(PNPM_OUTCOME_CODES.PUBLIC_HOIST_PATTERN_DIFF)) {
+                try {
+                    await run(WEB_PROFILE, ['install', '--no-frozen-lockfile'], opts(signal));
+                }
+                catch (rebuildErr) {
+                    const rebuildText = errText(rebuildErr);
+                    return { ...classifyPnpmError(rebuildText), output: truncateOutput(rebuildText) };
+                }
+                try {
+                    const output = await run(WEB_PROFILE, ['add', source], opts(signal));
+                    return { class: 'ok', output: truncateOutput(output), usedAllowAllBuilds: false };
+                }
+                catch (retryErr) {
+                    const retryText = errText(retryErr);
+                    if (isPrepareBlocked(retryText))
+                        return retryAfterPrepare();
+                    return { ...classifyPnpmError(retryText), output: truncateOutput(retryText) };
                 }
-                return retryAfterPrepare();
             }
+            if (!isPrepareBlocked(text)) {
+                return { ...classifyPnpmError(text), output: truncateOutput(text) };
+            }
+            return retryAfterPrepare();
         }
-        if (!isPrepareBlocked(text))
-            throw rewritePnpmError(err);
-        return retryAfterPrepare();
+    };
+}
+function errText(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * 安装。返回 usedAllowAllBuilds 供 UI 明确报告「该插件执行了构建脚本」。
+ * source 形如：`pkg@1.2.3`（npm 精确锁定）或 `github:owner/repo#sha`（锁 SHA）。
+ * 薄包装：调 makeAddViaLadder，非 ok 时 throw（对 legacy 调用方保持现行报错形状）。
+ */
+export async function addDshPlugin(source, deps = {}) {
+    const ladder = makeAddViaLadder({
+        runDshPlugin: deps.runDshPlugin ?? runDshPlugin,
+        allowAllBuilds: deps.allowAllBuilds,
+    });
+    const outcome = await ladder(source, deps.profileDir ?? webProfileDir());
+    if (outcome.class === 'ok') {
+        return { output: outcome.output, usedAllowAllBuilds: outcome.usedAllowAllBuilds === true };
     }
+    throw rewritePnpmError(new Error(outcome.output));
 }
 /** 卸载（转发 pnpm remove；调用方须先做 live-disable）。 */
 export async function removeDshPlugin(pkg, deps = {}) {
     if (!isSafePluginTarget(pkg))
         throw new Error(`无效插件包名: ${pkg}`);
     const run = deps.runDshPlugin ?? runDshPlugin;
-    return run(WEB_PROFILE, ['remove', pkg]);
+    return run(WEB_PROFILE, ['remove', pkg], deps.profileDir !== undefined || deps.signal !== undefined
+        ? { profileDir: deps.profileDir, signal: deps.signal }
+        : undefined);
+}
+function rawOutcome(text) {
+    const out = String(text ?? '');
+    return { ...classifyPnpmError(out), output: out.length <= 800 ? out : out.slice(-800) };
+}
+/**
+ * 生产 runner：add 走 makeAddViaLadder（prepare/hoist 在途自愈在 adapter 内耗尽）；
+ * remove 包 removeDshPlugin（原始文本分类）；frozen/rebuild 直接 spawn pnpm。
+ * 四操作统一收 signal；output 截 800。
+ */
+export function makeDshRunner(profileDir) {
+    const ladder = makeAddViaLadder({ runDshPlugin });
+    return {
+        async add(spec, signal) {
+            return ladder(spec, profileDir, signal);
+        },
+        async remove(pkg, signal) {
+            try {
+                const output = await removeDshPlugin(pkg, { profileDir, signal });
+                return { class: 'ok', output: output.length <= 800 ? output : output.slice(-800) };
+            }
+            catch (err) {
+                return rawOutcome(errText(err));
+            }
+        },
+        async frozenInstall(signal) {
+            try {
+                // F1-R：detached 使 pnpm（及其后代）进入独立进程组，abort/超时可整组终止
+                const output = await runCommand('pnpm', ['--dir', profileDir, 'install', '--frozen-lockfile'], {
+                    timeoutMs: installTimeoutMs(),
+                    signal,
+                    detached: process.platform !== 'win32',
+                });
+                return { class: 'ok', output: output.length <= 800 ? output : output.slice(-800) };
+            }
+            catch (err) {
+                return rawOutcome(errText(err));
+            }
+        },
+        async rebuildInstall(signal) {
+            try {
+                const output = await runCommand('pnpm', ['--dir', profileDir, 'install', '--no-frozen-lockfile'], {
+                    timeoutMs: installTimeoutMs(),
+                    signal,
+                    detached: process.platform !== 'win32',
+                });
+                return { class: 'ok', output: output.length <= 800 ? output : output.slice(-800) };
+            }
+            catch (err) {
+                return rawOutcome(errText(err));
+            }
+        },
+    };
 }

package/lib/core/host-api.js

@@ -6,8 +6,9 @@
  * 顶层必须是非 null/非数组对象且有 method → `ping` 跳过 guard，否则
  * trustedRestartRequest host-equivalence guard → typed method/业务错误映射 → 其他 500。
  */
-import { BOOT_ID, addDshPlugin, publicInstallStatus } from './dsh-cli.js';
+import { BOOT_ID, publicInstallStatus } from './dsh-cli.js';
 import { listInstalledWithMeta, listMarket, installFromRegistry, uninstallPlugin, upgradePlugin, } from './market.js';
+import { runProfileTransaction, TransactionError, makeNpmWarmPackument } from './profile-transaction.js';
 import { readInstalledPluginReadme } from './installed.js';
 import { isNewerVersion, npmLatest } from './versions.js';
 import { RegistryConfigError } from './registry-controller.js';
@@ -129,6 +130,25 @@ function errorStatus(err) {
     }
     if (err instanceof ApiProtocolError)
         return { status: err.status, payload: { ok: false, error: err.message } };
+    if (err instanceof TransactionError) {
+        // detail 白名单投影：结构化事实，不含 raw output（GUI 只读 error，零改动）
+        const r = err.result;
+        return {
+            status: 500,
+            payload: {
+                ok: false,
+                error: err.message,
+                detail: {
+                    status: r.status,
+                    kind: r.kind,
+                    failure: r.failure,
+                    healActions: r.healActions,
+                    snapshotRestoreVerified: r.snapshotRestoreVerified,
+                    profileConverged: r.profileConverged,
+                },
+            },
+        };
+    }
     return { status: 500, payload: { ok: false, error: err instanceof Error ? err.message : String(err) } };
 }
 export function createApiDispatcher(ctx) {
@@ -140,6 +160,7 @@ export function createApiDispatcher(ctx) {
         upgradePlugin: ctx.deps?.upgradePlugin ?? upgradePlugin,
         checkRegistryEntries: ctx.deps?.checkRegistryEntries ?? checkRegistryEntries,
         npmLatest: ctx.deps?.npmLatest ?? npmLatest,
+        runTransaction: ctx.deps?.runTransaction ?? runProfileTransaction,
     };
     const cfg = () => ctx.controller.config;
     return async function handleApi(req, res) {
@@ -165,8 +186,19 @@ export function createApiDispatcher(ctx) {
                 }
                 case 'self-upgrade': {
                     const latest = await d.npmLatest(ctx.pkg.name, cfg().timeoutMs ?? 20_000);
-                    const result = await ctx.onMutation(() => addDshPlugin(`${ctx.pkg.name}@${latest.version}`));
-                    payload = { pkg: ctx.pkg.name, version: latest.version, usedAllowAllBuilds: result.usedAllowAllBuilds, needsRestart: true };
+                    // 缺 integrity 一律 fail closed，不进事务
+                    if (!latest.integrity) {
+                        throw new Error(`npm metadata 缺少 dist integrity：${ctx.pkg.name}@${latest.version}，拒绝升级`);
+                    }
+                    const result = await d.runTransaction({ kind: 'install-npm', pkg: ctx.pkg.name, version: latest.version, integrity: latest.integrity, signal }, { warmPackument: makeNpmWarmPackument(cfg().timeoutMs ?? 20_000) });
+                    if (!result.ok)
+                        throw new TransactionError(result);
+                    payload = {
+                        pkg: ctx.pkg.name,
+                        version: latest.version,
+                        usedAllowAllBuilds: result.usedAllowAllBuilds === true,
+                        needsRestart: true,
+                    };
                     break;
                 }
                 case 'registry': {
@@ -220,7 +252,7 @@ export function createApiDispatcher(ctx) {
                     if (!id)
                         throw new ApiProtocolError(400, '缺少 id');
                     const version = typeof body.version === 'string' ? body.version : undefined;
-                    const result = await ctx.onMutation(() => d.installFromRegistry(id, cfg(), { version, namespace: 'host' }));
+                    const result = await d.installFromRegistry(id, cfg(), { version, namespace: 'host', signal });
                     payload = { ...result };
                     break;
                 }
@@ -228,7 +260,7 @@ export function createApiDispatcher(ctx) {
                     const target = strArg(body, 'pkg');
                     if (!target)
                         throw new ApiProtocolError(400, '缺少 pkg');
-                    const result = await ctx.onMutation(() => d.uninstallPlugin(target, cfg(), { namespace: 'host' }));
+                    const result = await d.uninstallPlugin(target, cfg(), { namespace: 'host', signal });
                     payload = { ...result };
                     break;
                 }
@@ -236,7 +268,7 @@ export function createApiDispatcher(ctx) {
                     const target = strArg(body, 'pkg');
                     if (!target)
                         throw new ApiProtocolError(400, '缺少 pkg');
-                    const result = await ctx.onMutation(() => d.upgradePlugin(target, cfg(), { namespace: 'host' }));
+                    const result = await d.upgradePlugin(target, cfg(), { namespace: 'host', signal });
                     payload = { ...result };
                     break;
                 }