@logictan/dsh-config-manager 0.1.60

package/src/core/rollback.ts

@@ -0,0 +1,151 @@
+/**
+ * Rollback（规范 §17 / 设计 §8.2）：导入失败时逆序执行快照条目的补偿动作。
+ *
+ * 诚实原则：
+ *  - 尽力回滚：单项失败不停止其余补偿，最终如实报告 full / partial；
+ *  - credential 值 DSH 永不回读 → existed=true 的凭据无法自动恢复原值，
+ *    如实标记 failed + manualHint（人工补录）；
+ *  - settings 回滚仍走 expectedRevision 乐观锁，避免覆盖导入后用户的新修改。
+ */
+import { resolveFileTarget } from './backup.ts';
+import { msgOf } from './messages.ts';
+import type {
+  ConfigAdapter, HostContext, RollbackReport, Snapshot, SnapshotEntry, SnapshotStore,
+} from './types.ts';
+
+export interface RollbackOptions {
+  ctx: HostContext;
+  snapshot: Snapshot;
+  store?: SnapshotStore;
+  adapters?: ConfigAdapter[];
+  /** 回滚 WAL（Phase 3）：每补偿完一条 entry 调用，供 Coordinator 记录 rollback.entryDone；
+   *   crash during rollback 后 reconcile 从 WAL 判定已补偿/未补偿，避免盲目从头重做。 */
+  entryDone?: (entryIndex: number) => Promise<void>;
+}
+
+/** 逆序补偿单条快照条目；返回 null=成功，否则为失败原因 */
+async function compensateOne(
+  entry: SnapshotEntry,
+  ctx: HostContext,
+  store: SnapshotStore | undefined,
+): Promise<{ reason: string; manualHint?: string } | null> {
+  switch (entry.kind) {
+    case 'settingsNamespace': {
+      try {
+        if (!entry.existed) {
+          // 原目标不存在该 namespace：若导入已创建它，DSH settings 无删除语义 → 无法恢复「不存在」
+          let current: unknown = null;
+          try {
+            current = await ctx.settings.describe(entry.ref);
+          } catch {
+            current = null;
+          }
+          if (current === null) return null; // 本来就没有且未创建 → 无需恢复
+          return {
+            reason: msgOf(ctx)('rollback.ns.createdNoDelete'),
+            manualHint: msgOf(ctx)('rollback.ns.manualHint', { ref: entry.ref }),
+          };
+        }
+        // 用当前 revision 作乐观锁基准：读时即锁，冲突则如实失败（不覆盖并发修改）
+        const current = await ctx.settings.describe(entry.ref);
+        await ctx.settings.replace(entry.ref, entry.before, current.revision);
+        return null;
+      } catch (err) {
+        return { reason: err instanceof Error ? err.message : String(err), manualHint: msgOf(ctx)('rollback.ns.conflictHint', { ref: entry.ref }) };
+      }
+    }
+    case 'credential': {
+      if (entry.existed) {
+        // 值不可回读：无法自动恢复原值
+        return {
+          reason: msgOf(ctx)('rollback.cred.noReadback'),
+          manualHint: msgOf(ctx)('rollback.cred.manualHint', { ref: entry.ref }),
+        };
+      }
+      try {
+        await ctx.credentials.unset(entry.ref);
+        return null;
+      } catch (err) {
+        return { reason: err instanceof Error ? err.message : String(err) };
+      }
+    }
+    case 'patchLine': {
+      try {
+        // 引擎只管理 profile 的 cordis.patch.yml（backup.ts 的 patchLine 快照只记 lineId 作 ref，
+        // 不含文件编码）——回滚固定写回该文件；切勿把 lineId 当文件名（否则 patchPath 抛「仅支持管理」）。
+        const file = 'cordis.patch.yml';
+        const lineId = entry.ref;
+        await ctx.patchFile.applyPatchChanges(file, [
+          { lineId, raw: entry.before, action: entry.before === null ? 'remove' : 'update' },
+        ]);
+        return null;
+      } catch (err) {
+        return { reason: err instanceof Error ? err.message : String(err), manualHint: msgOf(ctx)('rollback.patch.manualHint', { ref: entry.ref }) };
+      }
+    }
+    case 'file': {
+      try {
+        const abs = resolveFileTarget(ctx, entry.adapter, entry.ref);
+        if (entry.existed && entry.copiedTo && store) {
+          const data = await store.readBlob(entry.snapshotId ?? '', entry.copiedTo);
+          await ctx.fs.writeFile(abs, data);
+        } else if (!entry.existed) {
+          // 原文件不存在 → 删除导入写入的文件
+          if (await ctx.fs.exists(abs)) await ctx.fs.remove(abs);
+        }
+        return null;
+      } catch (err) {
+        return { reason: err instanceof Error ? err.message : String(err), manualHint: msgOf(ctx)('rollback.file.manualHint', { ref: entry.ref }) };
+      }
+    }
+    case 'workspaceRecord': {
+      try {
+        if (entry.before === null) {
+          await ctx.workspace.removeRecord?.(entry.ref);
+        } else {
+          await ctx.workspace.writeRecord(entry.before as never);
+        }
+        return null;
+      } catch (err) {
+        return { reason: err instanceof Error ? err.message : String(err), manualHint: msgOf(ctx)('rollback.workspace.manualHint', { ref: entry.ref }) };
+      }
+    }
+    default:
+      return { reason: msgOf(ctx)('rollback.unknownEntry', { kind: entry.kind }) };
+  }
+}
+
+/** 回滚：逆序补偿全部条目；返回诚实报告（full / partial） */
+export async function rollback(opts: RollbackOptions): Promise<RollbackReport> {
+  const { ctx, snapshot, store, adapters, entryDone } = opts;
+  const restored: string[] = [];
+  const failed: RollbackReport['failed'] = [];
+
+  // 逆序遍历；adapter 自带的 rollback? 优先，否则引擎通用补偿
+  const entries = [...snapshot.entries].reverse();
+  for (let index = 0; index < entries.length; index++) {
+    const entry = entries[index]!;
+    const adapter = adapters?.find((a) => a.id === entry.adapter);
+    let error: { reason: string; manualHint?: string } | null = null;
+    if (adapter?.rollback) {
+      try {
+        await adapter.rollback([entry], ctx);
+      } catch (err) {
+        error = { reason: err instanceof Error ? err.message : String(err) };
+      }
+    } else {
+      error = await compensateOne(entry, ctx, store);
+    }
+    // 回滚 WAL：每补偿一项记 entryDone（crash 后可判定进度）
+    try {
+      await opts.entryDone?.(index);
+    } catch { /* WAL 写失败不阻断回滚（best-effort） */ }
+    if (error === null) {
+      restored.push(`${entry.adapter}:${entry.ref}`);
+    } else {
+      failed.push({ item: `${entry.adapter}:${entry.ref}`, reason: error.reason, manualHint: error.manualHint });
+    }
+  }
+
+  return { full: failed.length === 0, restored, failed };
+}

package/src/core/run-progress.test.ts

@@ -0,0 +1,237 @@
+/**
+ * m4 测试补齐（任务 t4）：m1 真实进度埋点 —— Exporter onSection / Analyzer onItem。
+ *
+ * 背景：m1 在 core 侧加入进度埋点（exporter.ts onSection、analyzer.ts onItem，
+ * importer.ts 透传），Host 路由用它们更新 RunRegistry（/progress 轮询数据源，
+ * m2 store / m3 ProgressBar 徽章消费）。既有 tests/core/exporter.test.ts 与
+ * tests/core/importer.test.ts 未覆盖埋点的参数语义与「埋点失败不影响业务」的
+ * 容错保证，本文件补齐（仅新增测试，不改业务代码）。
+ *
+ * 覆盖（验收 m4-green）：
+ *  - Exporter.onSection：每导出一个选中分区前调用一次；index 从 1 起严格递增、
+ *    total=选中分区总数、section=adapter id；only 过滤时只对选中分区触发；
+ *    回调抛错不得中断导出（进度是尽力而为）；
+ *  - Analyzer.executeImportPlan onItem（经 Importer 透传）：每个计划项完成后调用；
+ *    index 1-based 递增、total=将执行计划项总数（含 skip 类信息项）、
+ *    status=该项实际状态（ok/skipped…）、detail=计划项 id；
+ *    冲突未解决（skipped）与缺失秘密（skipped）同样计数；
+ *    回调抛错不得中断导入执行。
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+
+import { Exporter, type SectionProgress } from './exporter.ts'
+import { Importer } from './importer.ts'
+import type { PlanItemProgress } from './analyzer.ts'
+import { createAdapters } from '../adapters/index.ts'
+import { makeContext, MemSnapshotStore, type MockHostContext } from '../adapters/test-helpers.ts'
+import type { ImportPlan } from './types.ts'
+
+const NS = ['general', 'llm-deepseek']
+
+async function withTmp<T>(fn: (dir: string) => Promise<T>): Promise<T> {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-cm-run-progress-'))
+  try {
+    return await fn(dir)
+  } finally {
+    await fs.rm(dir, { recursive: true, force: true })
+  }
+}
+
+/** 最小源：settings(general + llm-deepseek 带 apiKeyEnv/secret 标记) + credentials
+ * （llm-deepseek 的 secret 标记使 credentialsStatus 分区产生 configured 凭据，
+ * 导入时成为 MissingSecret 补录占位 —— 与 tests/core/importer.test.ts 的 I-01 同款） */
+async function seedSource(ctx: MockHostContext): Promise<void> {
+  ctx.settings.ns.set('general', { value: { theme: 'dark', language: 'zh-CN' }, revision: 3, secrets: [] })
+  ctx.settings.ns.set('llm-deepseek', {
+    value: { apiKeyEnv: 'DEEPSEEK_API_KEY', baseURL: 'https://api.deepseek.com', model: 'deepseek-chat' },
+    revision: 5,
+    secrets: [{ path: ['apiKey'], set: true }],
+  })
+  ctx.credentials.values.set('DEEPSEEK_API_KEY', 'sk-super-secret-value-123')
+}
+
+async function exportFixture(src: MockHostContext, outPath: string): Promise<void> {
+  const adapters = createAdapters({ namespaces: NS })
+  await new Exporter({ ctx: src, adapters, now: () => new Date('2026-08-14T12:00:00.000Z') })
+    .export({ includeSecrets: false, outPath })
+}
+
+/** 与 Importer 默认参数一致的目标侧 importer */
+function makeImporter(dst: MockHostContext): Importer {
+  return new Importer({
+    ctx: dst,
+    adapters: createAdapters({ namespaces: NS }),
+    snapshotStore: new MemSnapshotStore(),
+  })
+}
+
+/* ================================================= Exporter onSection 埋点 */
+
+test('m1 埋点: onSection 每导出一个选中分区前调用（index 1-based 递增、total=选中数、section=adapter id）', async () => {
+  await withTmp(async (dir) => {
+    const src = makeContext('win32', 'C:\\Users\\alice')
+    await seedSource(src)
+    const adapters = createAdapters({ namespaces: NS })
+    const selected = adapters.filter((a) => a.defaultIncluded).map((a) => a.id)
+    assert.ok(selected.length >= 2, '默认选中分区应 ≥2（本最小源至少 settings+credentialsStatus）')
+
+    const calls: SectionProgress[] = []
+    await new Exporter({
+      ctx: src,
+      adapters,
+      now: () => new Date('2026-08-14T12:00:00.000Z'),
+      onSection: (info) => { calls.push(info) },
+    }).export({ includeSecrets: false, outPath: path.join(dir, 'sections.zip') })
+
+    assert.equal(calls.length, selected.length, '每个选中分区都应触发一次 onSection')
+    calls.forEach((c, i) => {
+      assert.equal(c.index, i + 1, `index 从 1 起严格递增（第 ${i} 次调用）`)
+      assert.equal(c.total, selected.length, 'total=选中分区总数')
+      assert.equal(c.section, selected[i], 'section=当前 adapter id，顺序与导出顺序一致')
+    })
+  })
+})
+
+test('m1 埋点: only 过滤时只对选中分区触发（index/total 按选中集计算）', async () => {
+  await withTmp(async (dir) => {
+    const src = makeContext('linux', '/home/alice')
+    await seedSource(src)
+    const adapters = createAdapters({ namespaces: NS })
+    const only = ['settings', 'plugins'] as const
+
+    const calls: SectionProgress[] = []
+    await new Exporter({
+      ctx: src,
+      adapters,
+      now: () => new Date('2026-08-14T12:00:00.000Z'),
+      onSection: (info) => { calls.push(info) },
+    }).export({ includeSecrets: false, only: [...only], outPath: path.join(dir, 'only.zip') })
+
+    assert.equal(calls.length, only.length, '只对 only 中选中的分区触发')
+    assert.deepEqual(calls.map((c) => c.section), [...only], '触发顺序与 adapters 注册顺序一致')
+    for (const c of calls) {
+      assert.equal(c.total, only.length, 'total=only 过滤后的选中分区数')
+    }
+    assert.equal(calls[0]?.index, 1, 'only 集内 index 从 1 起')
+  })
+})
+
+test('m1 埋点: onSection 抛错不影响导出（进度是尽力而为）', async () => {
+  await withTmp(async (dir) => {
+    const src = makeContext('win32', 'C:\\Users\\alice')
+    await seedSource(src)
+    const adapters = createAdapters({ namespaces: NS })
+    let calls = 0
+
+    const result = await new Exporter({
+      ctx: src,
+      adapters,
+      now: () => new Date('2026-08-14T12:00:00.000Z'),
+      onSection: (info) => {
+        calls += 1
+        if (calls === 1) throw new Error('埋点回调故障')
+      },
+    }).export({ includeSecrets: false, outPath: path.join(dir, 'resilient.zip') })
+
+    assert.ok(calls > 0, '埋点被触发过')
+    assert.ok(result.zipPath.endsWith('.zip'), '导出仍成功完成')
+    const stat = await fs.stat(result.zipPath)
+    assert.ok(stat.size > 0, 'ZIP 正常落盘')
+  })
+})
+
+/* ================================================= Analyzer onItem 埋点 */
+
+test('m1 埋点: onItem 每个计划项完成后调用（index 递增、total=计划项数、status/detail 正确）', async () => {
+  await withTmp(async (dir) => {
+    const src = makeContext('win32', 'C:\\Users\\alice')
+    await seedSource(src)
+    const zipPath = path.join(dir, 'items.zip')
+    await exportFixture(src, zipPath)
+
+    const dst = makeContext('win32', 'C:\\Users\\bob')
+    dst.settings.registered.add('general')
+    dst.settings.registered.add('llm-deepseek')
+    const importer = makeImporter(dst)
+
+    const plan: ImportPlan = await importer.createImportPlan(zipPath, { strategy: 'merge', resolutions: {}, pathMappings: [] })
+    assert.ok(plan.items.length > 0, '计划应包含待执行项')
+
+    const calls: PlanItemProgress[] = []
+    const result = await importer.executeImportPlan(zipPath, plan, {
+      confirm: true,
+      onItem: (info) => { calls.push(info) },
+    })
+
+    assert.equal(result.ok, true, '导入成功')
+    assert.equal(calls.length, plan.items.length, '每个计划项都应触发一次 onItem')
+    calls.forEach((c, i) => {
+      assert.equal(c.index, i + 1, 'index 从 1 起严格递增')
+      assert.equal(c.total, calls.length, 'total=将执行计划项总数（含 skip 类信息项）')
+      assert.ok(
+        c.status === 'ok' || c.status === 'skipped' || c.status === 'warning' || c.status === 'failed',
+        `status 应为合法值，实际 ${c.status}`,
+      )
+      assert.ok(typeof c.detail === 'string' && c.detail !== '', 'detail=计划项 id（非敏感）')
+    })
+  })
+})
+
+test('m1 埋点: 冲突未解决（skipped）与缺失秘密（skipped）同样计数', async () => {
+  await withTmp(async (dir) => {
+    const src = makeContext('win32', 'C:\\Users\\alice')
+    await seedSource(src)
+    const zipPath = path.join(dir, 'conflict.zip')
+    await exportFixture(src, zipPath)
+
+    const dst = makeContext('win32', 'C:\\Users\\bob')
+    // 目标已有同名 general → merge 无决策 → Conflict → skipped
+    dst.settings.ns.set('general', { value: { theme: 'light' }, revision: 7, secrets: [] })
+    const importer = makeImporter(dst)
+
+    const plan = await importer.createImportPlan(zipPath, { strategy: 'merge', resolutions: {}, pathMappings: [] })
+    assert.ok(plan.items.some((i) => i.id === 'settings:general' && i.kind === 'Conflict'), '应有未决策冲突项')
+    assert.ok(plan.items.some((i) => i.kind === 'MissingSecret'), '应有缺失秘密补录占位')
+
+    const calls: PlanItemProgress[] = []
+    await importer.executeImportPlan(zipPath, plan, {
+      confirm: true,
+      onItem: (info) => { calls.push(info) },
+    })
+
+    const conflict = calls.find((c) => c.detail === 'settings:general')
+    assert.equal(conflict?.status, 'skipped', '冲突未解决 → skipped 且上报')
+    const secret = calls.find((c) => c.detail === 'secret:DEEPSEEK_API_KEY')
+    assert.equal(secret?.status, 'skipped', '秘密未补录 → skipped 且上报（不泄露值）')
+    // skipped 项同样占用 index/total 计数（进度条整体推进）
+    assert.ok(conflict !== undefined && conflict.index > 0, '冲突项计入进度计数')
+    assert.ok(secret !== undefined && secret.index > conflict!.index, '秘密项在冲突项之后计数')
+  })
+})
+
+test('m1 埋点: onItem 抛错不影响导入执行（进度是尽力而为）', async () => {
+  await withTmp(async (dir) => {
+    const src = makeContext('win32', 'C:\\Users\\alice')
+    await seedSource(src)
+    const zipPath = path.join(dir, 'resilient.zip')
+    await exportFixture(src, zipPath)
+
+    const dst = makeContext('win32', 'C:\\Users\\bob')
+    dst.settings.registered.add('general')
+    dst.settings.registered.add('llm-deepseek')
+    const importer = makeImporter(dst)
+
+    const plan = await importer.createImportPlan(zipPath, { strategy: 'merge', resolutions: {}, pathMappings: [] })
+    const result = await importer.executeImportPlan(zipPath, plan, {
+      confirm: true,
+      onItem: () => { throw new Error('埋点回调故障') },
+    })
+
+    assert.equal(result.ok, true, '导入不受埋点故障影响')
+    assert.deepEqual(dst.settings.ns.get('general')?.value, { theme: 'dark', language: 'zh-CN' }, '数据正常写入')
+  })
+})

package/src/core/run-registry.test.ts

@@ -0,0 +1,232 @@
+/**
+ * RunRegistry 基础单测（m1 自测，m4 会补全埋点/路由/轮询测试）：
+ *  - register：不可猜 runId、running 初始态、同 kind 并发拒绝（不同 kind 互不阻塞）
+ *  - update：进度字段落账并刷新 updatedAt；完成/失败后晚到更新被忽略
+ *  - finish/fail：状态与 result/error 落账
+ *  - get/listActive：过滤语义与不存在处理
+ *  - 保留期清理：超过 retentionMs 后不可见（含长期 running 僵死任务）
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  DEFAULT_RUN_RETENTION_MS, MAX_RUN_LOG_LINES, RunConflictError, RunRegistry,
+} from './run-registry.ts'
+
+test('register: 生成不可猜的 32 hex runId 且初始为 running', () => {
+  const reg = new RunRegistry()
+  const run = reg.register('export')
+  assert.match(run.runId, /^[0-9a-f]{32}$/)
+  assert.equal(run.status, 'running')
+  assert.equal(run.kind, 'export')
+  assert.equal(run.section, null)
+  assert.equal(run.item, null)
+  assert.ok(run.createdAt > 0)
+  assert.equal(run.updatedAt, run.createdAt)
+})
+
+test('register: 同 kind 进行中拒绝新 run（RunConflictError 携带既有 runId）', () => {
+  const reg = new RunRegistry()
+  const first = reg.register('export')
+  assert.throws(
+    () => reg.register('export'),
+    (err: unknown) => {
+      assert.ok(err instanceof RunConflictError)
+      assert.equal((err as RunConflictError).runId, first.runId)
+      return true
+    },
+  )
+})
+
+test('register: 不同 kind 互不阻塞（导出进行中可导入）', () => {
+  const reg = new RunRegistry()
+  reg.register('export')
+  const imp = reg.register('import')
+  assert.equal(imp.kind, 'import')
+  assert.equal(reg.listActive().length, 2)
+})
+
+test('register: 完成/失败后的 run 不阻塞同 kind 新 run', () => {
+  const reg = new RunRegistry()
+  const first = reg.register('export')
+  reg.finish(first.runId, { ok: true })
+  const second = reg.register('export')
+  assert.notEqual(second.runId, first.runId)
+
+  const failed = reg.register('import')
+  reg.fail(failed.runId, 'boom')
+  const retry = reg.register('import')
+  assert.notEqual(retry.runId, failed.runId)
+})
+
+test('update: 进度字段落账并刷新 updatedAt', () => {
+  let now = 1000
+  const reg = new RunRegistry({ now: () => now })
+  const run = reg.register('import')
+  now = 1200
+  reg.update(run.runId, { section: 'plugins', item: 3, itemTotal: 10, detail: 'plugin:pkg-a' })
+  const state = reg.get(run.runId)
+  assert.equal(state?.section, 'plugins')
+  assert.equal(state?.item, 3)
+  assert.equal(state?.itemTotal, 10)
+  assert.equal(state?.detail, 'plugin:pkg-a')
+  assert.equal(state?.updatedAt, 1200, 'update 必须刷新 updatedAt')
+})
+
+test('update: 完成/失败后的晚到更新被忽略（异步回调竞态防御）', () => {
+  const reg = new RunRegistry()
+  const run = reg.register('export')
+  reg.update(run.runId, { detail: 'settings' })
+  reg.finish(run.runId, { zipPath: 'x.zip' })
+  reg.update(run.runId, { detail: 'late-write' })
+  const state = reg.get(run.runId)
+  assert.equal(state?.status, 'done')
+  assert.equal(state?.detail, 'settings', 'finish 后的 update 不得覆盖')
+  assert.deepEqual(state?.result, { zipPath: 'x.zip' })
+})
+
+test('appendLog: 追加执行日志行并刷新 updatedAt；不存在/已结束的 run 忽略', () => {
+  let now = 1000
+  const reg = new RunRegistry({ now: () => now })
+  const run = reg.register('import')
+  assert.deepEqual(run.log, [], '初始 log 为空数组')
+  now = 1100
+  reg.appendLog(run.runId, '▶ settings:general')
+  reg.appendLog(run.runId, '$ dsh plugin --profile web add @scope/pkg')
+  const state = reg.get(run.runId)
+  assert.deepEqual(state?.log, ['▶ settings:general', '$ dsh plugin --profile web add @scope/pkg'])
+  assert.equal(state?.updatedAt, 1100, 'appendLog 必须刷新 updatedAt')
+
+  // 完成后晚到追加被忽略（防御异步回调竞态）
+  reg.finish(run.runId, { ok: true })
+  reg.appendLog(run.runId, 'late')
+  assert.deepEqual(reg.get(run.runId)?.log, ['▶ settings:general', '$ dsh plugin --profile web add @scope/pkg'], 'finish 后的 appendLog 不得写入')
+
+  // 不存在 → undefined
+  assert.equal(reg.appendLog('nope', 'x'), undefined)
+})
+
+test('appendLog: 日志行数封顶 MAX_RUN_LOG_LINES（超限截断保留最新）', () => {
+  const reg = new RunRegistry()
+  const run = reg.register('import')
+  for (let i = 0; i < MAX_RUN_LOG_LINES + 10; i++) {
+    reg.appendLog(run.runId, `line-${i}`)
+  }
+  const state = reg.get(run.runId)
+  assert.equal(state?.log.length, MAX_RUN_LOG_LINES)
+  assert.equal(state?.log[0], 'line-10', '截断后保留最新行')
+  assert.equal(state?.log[state!.log.length - 1], `line-${MAX_RUN_LOG_LINES + 9}`)
+})
+
+test('appendLog: 不可变追加——每次 append 换新数组引用（React memo 感知新行；封顶后长度恒定但引用仍变）', () => {
+  const reg = new RunRegistry()
+  const run = reg.register('import')
+  const initial = reg.get(run.runId)!.log
+  reg.appendLog(run.runId, 'line-1')
+  const second = reg.get(run.runId)!.log
+  assert.notEqual(second, initial, 'append 必须生成新数组引用（不得原地 push）')
+  assert.deepEqual(second, ['line-1'])
+
+  // 500 行封顶后：长度恒定（memo 按长度比较会漏），但每次 append 引用必变
+  const capRun = reg.register('export')
+  const refs = new Set<unknown[]>()
+  for (let i = 0; i < MAX_RUN_LOG_LINES + 5; i++) {
+    reg.appendLog(capRun.runId, `line-${i}`)
+    refs.add(reg.get(capRun.runId)!.log)
+  }
+  assert.equal(reg.get(capRun.runId)!.log.length, MAX_RUN_LOG_LINES)
+  assert.equal(refs.size, MAX_RUN_LOG_LINES + 5, '每次 append 都是新引用（含封顶后）——前端以引用比较不会漏渲染')
+})
+
+test('register: 快照恢复（restore）同 kind 进行中拒绝（P1-1 并发恢复防护）', () => {
+  const reg = new RunRegistry()
+  const first = reg.register('restore')
+  assert.throws(
+    () => reg.register('restore'),
+    (err: unknown) => {
+      assert.ok(err instanceof RunConflictError)
+      assert.equal((err as RunConflictError).runId, first.runId)
+      return true
+    },
+  )
+  // 恢复中允许导出（不同 kind 互不阻塞）
+  const exp = reg.register('export')
+  assert.equal(exp.kind, 'export')
+  // 完成后的 restore 不阻塞新 restore
+  reg.finish(first.runId, {})
+  const second = reg.register('restore')
+  assert.notEqual(second.runId, first.runId)
+})
+
+test('register: recovery 同 kind 进行中拒绝（并发 recovery 防护）', () => {
+  const reg = new RunRegistry()
+  const first = reg.register('recovery')
+  assert.throws(
+    () => reg.register('recovery'),
+    (err: unknown) => {
+      assert.ok(err instanceof RunConflictError)
+      assert.equal((err as RunConflictError).runId, first.runId)
+      return true
+    },
+  )
+  // 恢复中允许导出（不同 kind 互不阻塞）
+  const exp = reg.register('export')
+  assert.equal(exp.kind, 'export')
+  // 完成后的 recovery 不阻塞新 recovery
+  reg.finish(first.runId, {})
+  const second = reg.register('recovery')
+  assert.notEqual(second.runId, first.runId)
+})
+
+test('finish/fail: 状态与 result/error 落账', () => {
+  const reg = new RunRegistry()
+  const done = reg.register('export')
+  reg.finish(done.runId, { zipPath: 'dsh-config.zip', manifest: { schemaVersion: 1 } })
+  const after = reg.get(done.runId)
+  assert.equal(after?.status, 'done')
+  assert.deepEqual(after?.result, { zipPath: 'dsh-config.zip', manifest: { schemaVersion: 1 } })
+
+  const failed = reg.register('import')
+  reg.fail(failed.runId, '安装插件失败')
+  const f = reg.get(failed.runId)
+  assert.equal(f?.status, 'failed')
+  assert.equal(f?.error, '安装插件失败')
+})
+
+test('get/listActive: 只列出 running run；不存在返回 undefined', () => {
+  const reg = new RunRegistry()
+  assert.equal(reg.get('nope'), undefined)
+  const a = reg.register('export')
+  const b = reg.register('import')
+  reg.finish(a.runId, {})
+  const active = reg.listActive()
+  assert.equal(active.length, 1)
+  assert.equal(active[0]?.runId, b.runId)
+  // 返回副本：外部改动不影响内部状态
+  active[0]!.detail = 'hacked'
+  assert.notEqual(reg.get(b.runId)?.detail, 'hacked')
+})
+
+test('保留期清理: 超过 retentionMs 后不可见（含长期 running 僵死任务）', () => {
+  let now = 0
+  const reg = new RunRegistry({ retentionMs: 1000, now: () => now })
+  const run = reg.register('export')
+  now = 500
+  reg.finish(run.runId, { ok: true })
+  assert.ok(reg.get(run.runId), '保留期内可见')
+  now = 1501
+  assert.equal(reg.get(run.runId), undefined, '超过保留期清理')
+  assert.equal(reg.listActive().length, 0)
+})
+
+test('保留期清理: 长时间不 settle 的 running run 同样被清理', () => {
+  let now = 0
+  const reg = new RunRegistry({ retentionMs: 60000, now: () => now })
+  reg.register('import')
+  now = 60001
+  assert.equal(reg.listActive().length, 0, '僵死 running run 也要清理')
+})
+
+test('默认保留期常量为 30 分钟', () => {
+  assert.equal(DEFAULT_RUN_RETENTION_MS, 30 * 60 * 1000)
+})