@logictan/dsh-config-manager 0.1.60

package/src/core/phase4-crash-injection.test.ts

@@ -0,0 +1,166 @@
+/**
+ * Phase 4 真实 child-process crash 注入（C1-C10）。
+ * 每个窗口用独立子进程执行 phase4-crash-child.ts（真实 runJournaled deferred + 真实 FileSnapshotStore），
+ * 在指定点 SIGKILL，父进程随后用真实 JournalStore/reconcile 判定：
+ *  - C1/C2：快照未 READY+绑定前 crash → 无 trusted bound snapshot，recovery required / 保守
+ *  - C3：READY snapshot 已绑定（SNAPSHOT_CREATED）但未 APPLYING → 无 destructive mutation，安全
+ *  - C5/C6/C7：partial/local file mutation 已发生 + trusted snapshot 绑定 → 绝不可静默 RECOVERED
+ *  - C8/C9/C10：业务成功/COMMITTED 后 → 不 rollback
+ * 这是 process.kill(SIGKILL) 真实注入，非 throw 替代。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import fssync from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { JournalStore } from './journal.ts';
+import { Phase3Recovery } from './phase3-host.ts';
+import { reconcileActive } from './reconcile.ts';
+import { verifySnapshot } from './backup.ts';
+
+const here = import.meta.dirname ?? path.dirname(fileURLToPath(import.meta.url));
+const childPath = path.join(here, 'phase4-crash-child.ts');
+
+function workdir(t: test.TestContext): string {
+  const dir = fssync.mkdtempSync(path.join(os.tmpdir(), 'dsh-cm-phase4-crash-'));
+  t.after(() => fssync.rmSync(dir, { recursive: true, force: true }));
+  return dir;
+}
+
+/** 跑一个 crash 窗口的子进程；返回 { workdir, store, dataDir }（事务可能已完成或残留 active） */
+async function runCrashPoint(t: test.TestContext, point: string): Promise<{ workDir: string; dataDir: string }> {
+  const workDir = workdir(t);
+  await new Promise<void>((resolve) => {
+    const child = spawn(process.execPath, [childPath, workDir, point], { stdio: 'ignore' });
+    child.on('close', () => resolve());
+  });
+  return { workDir, dataDir: path.join(workDir, 'data') };
+}
+
+async function readJournal(dataDir: string): Promise<import('./journal.ts').OperationJournal | null> {
+  const store = new JournalStore({ transactionsDir: path.join(dataDir, 'transactions') });
+  await store.ensureDirs();
+  const active = await store.scanActive();
+  for (const id of active) {
+    const j = await store.loadActive(id);
+    if (j) return j;
+  }
+  // 已规整到 completed 的（如 C8-C10 COMMITTED）
+  return null;
+}
+
+/** 断言某个 crash 窗口后：journal 状态 + snapshot 完整性 + safe mode */
+async function assertRecovery(
+  t: test.TestContext,
+  point: string,
+  expect: { journalState?: string[]; snapshotReady?: boolean; expectRecovered?: boolean },
+): Promise<void> {
+  const { workDir, dataDir } = await runCrashPoint(t, point);
+  const snapDir = path.join(dataDir, 'snapshots');
+  const j = await readJournal(dataDir);
+  const txnDir = path.join(dataDir, 'transactions');
+
+  if (expect.journalState !== undefined) {
+    assert.ok(j, `${point}: 应有 journal`);
+    assert.ok(
+      expect.journalState.includes(j!.state),
+      `${point}: journal state=${j!.state} 应为 ${expect.journalState.join('/')}`,
+    );
+  }
+
+  let snapReady = false;
+  if (j?.snapshotId) {
+    const v = await verifySnapshot(snapDir, j.snapshotId);
+    snapReady = v.ok;
+  }
+  assert.equal(snapReady, expect.snapshotReady ?? false, `${point}: snapshot READY=${snapReady} 期望 ${expect.snapshotReady}`);
+
+  // 真实 reconcile：保守 hooks（生产 startup 同强度）
+  const store = new JournalStore({ transactionsDir: txnDir });
+  const out = await reconcileActive(store, {
+    verifyStepFingerprint: async () => 'unable',
+    probeExternal: async () => 'unknown',
+    snapshotExists: async (id) => (id !== null ? (await verifySnapshot(snapDir, id)).ok : false),
+  }, { environmentFingerprint: 'fp-crash', isLiveOwner: async () => false });
+
+  const decisionKind = out.decisions[0]?.kind;
+  if (expect.expectRecovered === true) {
+    assert.equal(decisionKind, 'recovered', `${point}: 期望 recovered，实际 ${decisionKind}`);
+  } else if (expect.expectRecovered === false) {
+    assert.notEqual(decisionKind, 'recovered', `${point}: 绝不可静默 recovered（partial mutation）`);
+    assert.ok(
+      decisionKind === 'needs-attention' || decisionKind === 'rollback-recommended' || decisionKind === 'noop' || decisionKind === 'rollback-continue',
+      `${point}: 保守恢复（${decisionKind}）`,
+    );
+  }
+  return;
+}
+
+test('C1: after journal CREATED, before snapshot → 无 trusted snapshot，reconcile 保守（不 RECOVERED 掩盖部分态）', async (t) => {
+  await assertRecovery(t, 'C1', { expectRecovered: false });
+});
+
+test('C2: during snapshot write, before bind → 无 trusted bound snapshot，保守', async (t) => {
+  await assertRecovery(t, 'C2', { expectRecovered: false });
+});
+
+test('C3: READY snapshot 已绑定（SNAPSHOT_CREATED）但未 APPLYING → 无 destructive mutation，安全（non-RECOVERED 保守）', async (t) => {
+  await assertRecovery(t, 'C3', { snapshotReady: true, expectRecovered: false });
+});
+
+test('C4: after APPLYING, before mutation → trusted snapshot bound，保守（安全）', async (t) => {
+  await assertRecovery(t, 'C4', { snapshotReady: true, expectRecovered: false });
+});
+
+test('C5/C6/C7: partial/local file mutation + trusted snapshot → 绝不可静默 RECOVERED', async (t) => {
+  // C6（mid-mutation 后 local file 已写）是核心：有 trusted bound snapshot 且 local 已变
+  for (const point of ['C5', 'C6', 'C7']) {
+    await assertRecovery(t, point, { snapshotReady: true, expectRecovered: false });
+  }
+});
+
+test('C8/C9/C10: 业务成功/COMMITTED 后 → 不 rollback（journal COMMITTED 已规整，无 active 残留）', async (t) => {
+  for (const point of ['C8', 'C9', 'C10']) {
+    const { dataDir } = await runCrashPoint(t, point);
+    const snapDir = path.join(dataDir, 'snapshots');
+    const txDir = path.join(dataDir, 'transactions');
+    const store = new JournalStore({ transactionsDir: txDir });
+    // COMMITTED 后 journal 已规整到 completed → active 无残留 → 不需任何自动 rollback
+    const active = await store.scanActive();
+    assert.equal(active.length, 0, `${point}: COMMITTED 后不应有 active journal（无需回滚）`);
+    // 即便 reconcile 也只会 noop/recovered（不触发 destructive rollback）
+    const out = await reconcileActive(store, {
+      verifyStepFingerprint: async () => 'unable',
+      probeExternal: async () => 'unknown',
+      snapshotExists: async (id) => (id !== null ? (await verifySnapshot(snapDir, id)).ok : false),
+    }, { environmentFingerprint: 'fp-crash', isLiveOwner: async () => false });
+    const kind = out.decisions[0]?.kind;
+    assert.notEqual(kind, 'rollback-continue', `${point}: COMMITTED 后不得进入回滚`);
+    assert.notEqual(kind, 'needs-attention', `${point}: COMMITTED 后不得 needs-attention`);
+  }
+});
+
+// 明确断言「空 steps + partial mutation 绝不 RECOVERED」（F20 生产回归；对应 C5 后的磁盘态）
+test('C6: local file mutation 后 + trusted snapshot → reconcile snapshotExists 正向 → 推荐回滚而非 RECOVERED', async (t) => {
+  const { dataDir } = await runCrashPoint(t, 'C6');
+  const snapDir = path.join(dataDir, 'snapshots');
+  const txnDir = path.join(dataDir, 'transactions');
+  const store = new JournalStore({ transactionsDir: txnDir });
+  const j = await readJournal(dataDir);
+  assert.ok(j && j.snapshotId, 'C6 后 journal 已绑定 trusted snapshot');
+  const snapOk = await verifySnapshot(snapDir, j!.snapshotId!);
+  assert.equal(snapOk.ok, true, 'C6 后快照完整（READY+manifest+blob）');
+  // 生产 snapshotExists 正向：binding 匹配 → true
+  const out = await reconcileActive(store, {
+    verifyStepFingerprint: async () => 'unable',
+    probeExternal: async () => 'unknown',
+    snapshotExists: async (id) => (id !== null ? (await verifySnapshot(snapDir, id)).ok : false),
+  }, { environmentFingerprint: 'fp-crash', isLiveOwner: async () => false });
+  const kind = out.decisions[0]?.kind;
+  assert.notEqual(kind, 'recovered', 'partial mutation 绝不静默 recovered');
+  assert.ok(kind === 'needs-attention' || kind === 'rollback-recommended', `应为保守/回滚推荐，实际 ${kind}`);
+  assert.equal(out.safeModeRequired, true, 'partial mutation + 不可证明 → SAFE MODE');
+});

package/src/core/plugin-cli.fs.test.ts

@@ -0,0 +1,184 @@
+/**
+ * plugin-cli 文件读取层测试（M5 补写，failing-first 目标：listInstalled 从文件实时读真实版本）。
+ * 使用真实临时目录（node:os tmpdir）+ 真实 fs，不 mock 磁盘——验证的是真实读取语义：
+ *   - readInstalledVersion 读 node_modules/<name>/package.json 落盘版本（不是声明 spec）
+ *   - readInstalled 过滤 in-box bundles（@deepseek-ai/dsh-base / dsh-web-app / dsh-headless）
+ *   - listInstalledPlugins 组装 PluginInfo（name/version/isBundle/inBundles）
+ *   - reconcileBundles 按已装状态维护 dsh.profile.bundles 并写回
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  listInstalledPlugins, readInstalled, readInstalledVersion, reconcileBundles,
+  resolveProfileDir,
+} from './plugin-cli.ts';
+import type { PluginInfo } from './types.ts';
+
+/** 建一个带真实文件的临时 profile（web），返回 { homeDir, profileDir, cleanup }。 */
+function makeTempProfile(deps: Record<string, string>, bundles: string[] = []): {
+  homeDir: string;
+  profileDir: string;
+  cleanup: () => void;
+} {
+  const homeDir = mkdtempSync(join(tmpdir(), 'dsh-cm-fs-'));
+  const profileDir = resolveProfileDir(homeDir, 'web');
+  mkdirSync(profileDir, { recursive: true });
+  writeFileSync(
+    join(profileDir, 'package.json'),
+    `${JSON.stringify({ name: 'dsh-profile-web', dependencies: deps, dsh: { profile: { bundles } } }, null, 2)}\n`,
+    'utf8',
+  );
+  return {
+    homeDir,
+    profileDir,
+    cleanup: () => rmSync(homeDir, { recursive: true, force: true }),
+  };
+}
+
+/** 写 node_modules/<name>/package.json。 */
+function writeInstalledPkg(profileDir: string, name: string, version: string, bundlePatch?: string): void {
+  const pkgDir = join(profileDir, 'node_modules', name);
+  mkdirSync(pkgDir, { recursive: true });
+  const manifest: Record<string, unknown> = { name, version };
+  if (bundlePatch !== undefined) manifest['dsh'] = { bundle: { patch: bundlePatch } };
+  writeFileSync(join(pkgDir, 'package.json'), `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+}
+
+test('readInstalledVersion: 读 node_modules 落盘真实版本；未装 / 无 version 字段 → null', () => {
+  const { profileDir, cleanup } = makeTempProfile({});
+  try {
+    writeInstalledPkg(profileDir, 'pkg-a', '0.2.3');
+    assert.equal(readInstalledVersion(profileDir, 'pkg-a'), '0.2.3');
+    assert.equal(readInstalledVersion(profileDir, 'not-installed'), null, '未装 → null');
+    // 落盘 package.json 存在但没有 version 字段 → null（不抛）
+    writeInstalledPkg(profileDir, 'broken', 'x');
+    writeFileSync(join(profileDir, 'node_modules', 'broken', 'package.json'), '{"name":"broken"}\n', 'utf8');
+    assert.equal(readInstalledVersion(profileDir, 'broken'), null);
+  } finally {
+    cleanup();
+  }
+});
+
+test('readInstalled: 返回真实依赖映射并过滤 in-box bundles，保留社区插件', () => {
+  const { profileDir, cleanup } = makeTempProfile({
+    '@deepseek-ai/dsh-base': '0.1.0-rc.6',
+    '@deepseek-ai/dsh-web-app': '0.1.0-rc.6',
+    '@deepseek-ai/dsh-headless': '0.1.0-rc.6',
+    '@linxin666/dsh-ssh': '^0.1.12',
+    'pkg-a': '1.0.0',
+  });
+  try {
+    const installed = readInstalled(profileDir);
+    assert.deepEqual(installed, { '@linxin666/dsh-ssh': '^0.1.12', 'pkg-a': '1.0.0' });
+  } finally {
+    cleanup();
+  }
+});
+
+test('listInstalledPlugins: 版本取 node_modules 真实落盘版本（声明 ^0.1.0 → 实际 0.1.12）', () => {
+  // failing-first 目标：listInstalled 从文件实时读真实版本，而非声明 spec。
+  const { homeDir, profileDir, cleanup } = makeTempProfile({
+    '@linxin666/dsh-ssh': '^0.1.0',
+    'pkg-a': '1.0.0',
+    'dsh-memory-evolve': 'github:csyangwen/dsh-memory-evolve',
+    '@deepseek-ai/dsh-base': '0.1.0-rc.6',
+  });
+  try {
+    writeInstalledPkg(profileDir, '@linxin666/dsh-ssh', '0.1.12', 'patch.yml');
+    writeInstalledPkg(profileDir, 'pkg-a', '1.0.0');
+    writeInstalledPkg(profileDir, 'dsh-memory-evolve', '1.0.0');
+    writeInstalledPkg(profileDir, '@deepseek-ai/dsh-base', '0.1.0-rc.6');
+
+    const list = listInstalledPlugins(homeDir, 'web');
+    const ssh = list.find((p) => p.name === '@linxin666/dsh-ssh');
+    const plain = list.find((p) => p.name === 'pkg-a');
+    const git = list.find((p) => p.name === 'dsh-memory-evolve');
+    assert.equal(ssh?.version, '0.1.12', '必须返回落盘真实版本，而不是声明的 ^0.1.0');
+    assert.equal(ssh?.isBundle, true);
+    assert.deepEqual(ssh?.inBundles, ['@linxin666/dsh-ssh'], '直接依赖的 bundle 自身就是 profile 层');
+    assert.equal(plain?.version, '1.0.0');
+    assert.equal(plain?.isBundle, false);
+    assert.deepEqual(plain?.inBundles, []);
+    // 声明 spec 原样保留：github 来源 / 版本区间都要随清单带出（导入重装依据）
+    assert.equal(git?.spec, 'github:csyangwen/dsh-memory-evolve');
+    assert.equal(ssh?.spec, '^0.1.0');
+    assert.equal(list.some((p) => p.name === '@deepseek-ai/dsh-base'), false, 'in-box bundle 不出现');
+    assert.equal(list.every((p: PluginInfo) => p.enabled === true), true, '文件视图依赖即视为启用');
+  } finally {
+    cleanup();
+  }
+});
+
+test('listInstalledPlugins: 声明了依赖但未实际安装 → version 空串不抛', () => {
+  const { homeDir, profileDir, cleanup } = makeTempProfile({ 'ghost-dep': '^9.9.9' });
+  try {
+    // 不写 node_modules/ghost-dep：node_modules 缺失不应让 listInstalled 抛错
+    const list = listInstalledPlugins(homeDir, 'web');
+    assert.equal(list.length, 1);
+    assert.equal(list[0]?.name, 'ghost-dep');
+    assert.equal(list[0]?.version, '', '未落盘 → 版本空串（不抛）');
+  } finally {
+    cleanup();
+  }
+});
+
+test('issue #28: 仅由 dsh.profile.bundles 声明的层必须出现在已装清单里（此前完全不可见）', () => {
+  // 场景：用户手动把社区 bundle 写进 dsh.profile.bundles（或某个安装路径只写了 bundles 而没写
+  // dependencies）。reconcileBundles 对这类条目是**保留**的（移除条件要求曾是依赖），
+  // 所以 DSH 启动时确实会挂载它 —— 但旧清单只遍历 dependencies，于是「装了却识别不到」。
+  const { homeDir, profileDir, cleanup } = makeTempProfile(
+    { 'pkg-a': '1.0.0', '@deepseek-ai/dsh-base': '0.1.0-rc.6' },
+    ['@linxin666/dsh-web-ui-all', 'stale-pkg', '@deepseek-ai/dsh-base'],
+  );
+  try {
+    writeInstalledPkg(profileDir, 'pkg-a', '1.0.0');
+    writeInstalledPkg(profileDir, '@linxin666/dsh-web-ui-all', '0.3.1', 'patch.yml');
+    writeInstalledPkg(profileDir, '@deepseek-ai/dsh-base', '0.1.0-rc.6');
+
+    const list = listInstalledPlugins(homeDir, 'web');
+    const bundleOnly = list.find((p) => p.name === '@linxin666/dsh-web-ui-all');
+    assert.ok(bundleOnly !== undefined, '仅 bundles 声明的层必须出现在清单里');
+    assert.equal(bundleOnly?.version, '0.3.1', '版本取 node_modules 落盘版本');
+    assert.equal(bundleOnly?.isBundle, true);
+    assert.deepEqual(bundleOnly?.inBundles, ['@linxin666/dsh-web-ui-all']);
+    assert.equal(bundleOnly?.spec, undefined, '无依赖声明 → 无 spec（导入按裸包名装最新版）');
+    // 从未落盘的 bundles 条目：仍列出（它确实是启动时会挂载的层），版本空串不抛
+    assert.equal(list.find((p) => p.name === 'stale-pkg')?.version, '');
+    // in-box bundle 依然不出现（无论来自 dependencies 还是 bundles）
+    assert.equal(list.some((p) => p.name === '@deepseek-ai/dsh-base'), false);
+    // 依赖里的普通插件不受影响
+    assert.equal(list.find((p) => p.name === 'pkg-a')?.spec, '1.0.0');
+  } finally {
+    cleanup();
+  }
+});
+
+test('reconcileBundles: 当前依赖但非 bundle 的条目移出；从未是依赖的手动条目保留；无变化不写回', () => {
+  // 语义对齐官方 dsh reconcilePlugins（plugin-9h8shc4d.js）：移除条件 =
+  // 「(之前或当前)是依赖 且 不再声明 bundle patch」——从未是依赖的 bundles 条目
+  // 视为手动维护的层，永远保留（in-box 同理不碰）。
+  const { homeDir, profileDir, cleanup } = makeTempProfile(
+    { 'pkg-bundle': '1.0.0', 'pkg-plain': '1.0.0' },
+    ['pkg-plain', 'stale-pkg'],
+  );
+  try {
+    writeInstalledPkg(profileDir, 'pkg-bundle', '1.0.0', 'patch.yml');
+    writeInstalledPkg(profileDir, 'pkg-plain', '1.0.0');
+
+    assert.equal(reconcileBundles(profileDir), true, '有变化 → 写回并返回 true');
+    const after = JSON.parse(readFileSync(join(profileDir, 'package.json'), 'utf8'));
+    assert.deepEqual(
+      after.dsh.profile.bundles,
+      ['stale-pkg', 'pkg-bundle'],
+      'pkg-plain 是当前依赖但非 bundle → 移出；stale-pkg 从未是依赖 → 保留；pkg-bundle 追加',
+    );
+
+    assert.equal(reconcileBundles(profileDir), false, '已一致 → 不写回返回 false');
+  } finally {
+    cleanup();
+  }
+});

package/src/core/plugin-cli.test.ts

@@ -0,0 +1,137 @@
+/**
+ * plugin-cli 失败分类器测试（M2）：classifyDshPluginFailure / isTransientDshPluginFailure /
+ * installErrorFor。纯函数，样本文本取自 pnpm 真实诊断形态（dshmarket pnpm-compat 矩阵）。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  classifyDshPluginFailure, installErrorFor, isTransientDshPluginFailure,
+  resolveProfileNameFromArgv,
+  type DshPluginResult,
+} from './plugin-cli.ts';
+
+test('resolveProfileNameFromArgv: --profile 取值 / 缺省 web / 非法值宽容回退', () => {
+  assert.equal(resolveProfileNameFromArgv(['--profile', 'tui']), 'tui');
+  assert.equal(resolveProfileNameFromArgv(['web', '--profile', 'headless', 'x']), 'headless');
+  assert.equal(resolveProfileNameFromArgv(['--profile']), 'web', '缺值回退');
+  assert.equal(resolveProfileNameFromArgv(['--profile', '--flag']), 'web', '值以 - 开头回退');
+  assert.equal(resolveProfileNameFromArgv([]), 'web');
+  assert.equal(resolveProfileNameFromArgv(['--profile', '../evil']), 'web', '非法值不抛错回退（消息构建路径安全）');
+});
+
+test('classify: ERR_PNPM_PUBLIC_HOIST_PATTERN_DIFF → hoist-pattern-diff (recoverable)', () => {
+  const f = classifyDshPluginFailure('ERR_PNPM_PUBLIC_HOIST_PATTERN_DIFF\nsome pnpm output');
+  assert.equal(f?.code, 'hoist-pattern-diff');
+  assert.equal(f?.recoverable, true);
+  assert.match(f!.message, /pnpm install/);
+});
+
+test('classify: ERR_PNPM_ADDING_TO_ROOT → adding-to-root', () => {
+  const f = classifyDshPluginFailure('ERR_PNPM_ADDING_TO_ROOT Running this command will add the dependency to the workspace root');
+  assert.equal(f?.code, 'adding-to-root');
+  assert.match(f!.message, /add -w/);
+});
+
+test('classify: --workspace-root may only be used inside a workspace → not-a-workspace', () => {
+  const f = classifyDshPluginFailure('ERR_PNPM_WORKSPACE_ROOT "--workspace-root may only be used inside a workspace"');
+  assert.equal(f?.code, 'not-a-workspace');
+  assert.equal(f?.recoverable, false);
+});
+
+test('classify: minimumReleaseAge（两个错误码）→ release-age-violation', () => {
+  const a = classifyDshPluginFailure('ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION');
+  const b = classifyDshPluginFailure('ERR_PNPM_NO_MATURE_MATCHING_VERSION');
+  assert.equal(a?.code, 'release-age-violation');
+  assert.equal(b?.code, 'release-age-violation');
+  assert.match(a!.message, /minimumReleaseAge/);
+});
+
+test('classify: git 构建脚本 allowBuilds 拦截（pnpm 10 句子 / pnpm 11 错误码）→ git-build-blocked', () => {
+  const sentence = 'The git-hosted package "dsh-memory-evolve@0.1.0" needs to execute build scripts but is not in the "allowBuilds" allowlist.';
+  const a = classifyDshPluginFailure(sentence);
+  const b = classifyDshPluginFailure('ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED');
+  assert.equal(a?.code, 'git-build-blocked');
+  assert.equal(b?.code, 'git-build-blocked');
+  assert.match(a!.message, /allowBuilds/);
+});
+
+test('classify: patchedDependencies 的 patch 文件缺失 → patch-file-missing（可操作）', () => {
+  const zhOut = 'Error: × adding a new package\n╰─▶ Failed to read patch file C:\\Users\\x\\.dsh\\profiles\\web\\patches/dsh-approval-gate.patch:\n    系统找不到指定的文件。 (os error 2)';
+  const f = classifyDshPluginFailure(zhOut);
+  assert.equal(f?.code, 'patch-file-missing');
+  assert.equal(f?.recoverable, false, '需要人工把 patch 文件放回或删掉声明，重试不会自愈');
+  assert.match(f!.message, /patches\/dsh-approval-gate\.patch/, '必须点名缺失的 patch 文件');
+  assert.match(f!.message, /patchedDependencies/);
+  // 英文形态同样识别
+  assert.equal(classifyDshPluginFailure('Failed to read patch file /home/u/.dsh/profiles/web/patches/a.patch: ENOENT')?.code, 'patch-file-missing');
+});
+
+test('classify: ERR_PNPM_FETCH_404 → fetch-404（含包名提取）', () => {
+  const out = 'ERR_PNPM_FETCH_404 GET https://registry.npmjs.org/some-ghost-pkg: Not Found - 404';
+  const f = classifyDshPluginFailure(out);
+  assert.equal(f?.code, 'fetch-404');
+  assert.match(f!.message, /some-ghost-pkg/);
+});
+
+test('classify: 瞬时网络（各形态）→ transient-network，recoverable', () => {
+  const samples = [
+    'ERR_PNPM_FETCH_503 Service Unavailable',
+    'ERR_PNPM_META_FETCH_FAIL GET https://registry.npmjs.org/x: request failed',
+    'FetchError: request to https://registry.npmjs.org/x failed, reason: socket hang up',
+    'fetch failed: ECONNRESET',
+    'ETIMEDOUT',
+    'EAI_AGAIN',
+    'ENETUNREACH',
+    'network timeout',
+  ];
+  for (const s of samples) {
+    assert.equal(classifyDshPluginFailure(s)?.code, 'transient-network', `sample: ${s}`);
+  }
+  assert.equal(isTransientDshPluginFailure('ERR_PNPM_FETCH_503'), true);
+  assert.equal(isTransientDshPluginFailure('ECONNRESET'), true);
+  assert.equal(isTransientDshPluginFailure('ERR_PNPM_FETCH_404'), false, '404 不算瞬时网络');
+});
+
+test('classify: pnpm not found → pnpm-missing', () => {
+  const f = classifyDshPluginFailure('dsh: pnpm not found on PATH — install pnpm to manage profile plugins');
+  assert.equal(f?.code, 'pnpm-missing');
+  assert.match(f!.message, /pnpm/);
+});
+
+test('classify: 未识别输出 → null', () => {
+  assert.equal(classifyDshPluginFailure('some random pnpm error text'), null);
+  assert.equal(classifyDshPluginFailure(''), null);
+});
+
+test('installErrorFor: spawnError(ENOENT) → dsh 不可用提示', () => {
+  const r: DshPluginResult = { exitCode: 127, timedOut: false, stdout: '', stderr: '', spawnError: 'spawn dsh ENOENT' };
+  const e = installErrorFor('pkg-a', r);
+  assert.match(e.message, /dsh CLI/);
+});
+
+test('installErrorFor: timedOut → 超时提示', () => {
+  const r: DshPluginResult = { exitCode: null, timedOut: true, stdout: '', stderr: '' };
+  const e = installErrorFor('pkg-a', r);
+  assert.match(e.message, /超时/);
+});
+
+test('installErrorFor: 已分类失败 → 双语可读消息 + code', () => {
+  const r: DshPluginResult = {
+    exitCode: 1, timedOut: false,
+    stdout: '', stderr: 'ERR_PNPM_FETCH_503 Service Unavailable',
+  };
+  const e = installErrorFor('pkg-a', r);
+  assert.match(e.message, /transient-network/);
+  assert.match(e.message, /网络临时失败/);
+  assert.match(e.message, /transient network/);
+});
+
+test('installErrorFor: 未识别 → stderr 尾部摘要', () => {
+  const r: DshPluginResult = {
+    exitCode: 1, timedOut: false,
+    stdout: 'line1', stderr: 'mystery error line\nanother line',
+  };
+  const e = installErrorFor('pkg-a', r);
+  assert.match(e.message, /exit 1/);
+  assert.match(e.message, /mystery error line/);
+});