dsh-workspace-mover 2.1.1 → 2.3.0

package/test/e2e-sandbox.test.mjs

@@ -3,19 +3,21 @@
 // 备份目录通过 DSH_HOME 重定向到临时区，不污染真实环境。
 import { test, beforeEach, afterEach } from 'node:test';
 import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import { syncBuiltinESMExports } from 'node:module';
 import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSync, readdirSync, renameSync, realpathSync, utimesSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { zstdCompressSync, constants } from 'node:zlib';
 
-import { apply, scanFrames, readHeader, artifactPath, openInFileManager, moveDir, stashBackup, verifyRelocatedArtifact, deleteSessionToTrash, moveSession, SCAN_MAX_ITEMS } from '../lib/index.js';
+import { apply, scanFrames, readHeader, artifactPath, sessionDir, createPersistenceAdapter, openInFileManager, moveDir, stashBackup, verifyRelocatedArtifact, deleteSessionToTrash, moveSession, SCAN_MAX_ITEMS } from '../lib/index.js';
 
 const OPTS = { params: { [constants.ZSTD_c_checksumFlag]: 1 } };
 const DEAD = 'E:\\wsm-dead-path'; // 刻意不存在的路径（孤儿分类用）
 let A; // 每次用例指向真实临时目录（健康会话要求 cwd 在磁盘上存在）
 let B;
 let root;
-let ctx, entityA, entityB, sharedIndex, workspaceEvents;
+let ctx, entityA, entityB, sharedIndex, workspaceEvents, cleanups;
 
 /** 测试根目录：优先 WSM_TEST_ROOT（受限环境下 Temp 可能禁止目录重命名），否则退回系统 Temp。 */
 function makeRoot() {
@@ -55,6 +57,11 @@ function makeEntity(id, path, hostRef) {
     detached: [],
     failAttach: false,
     async status() { return existsSync(record.path) ? 'ok' : 'missing-dir'; },
+    // 官方文档化的改名接口：只换标题，不碰 path / 成员名单。
+    async setTitle(next) {
+      record.title = String(next);
+      record.updatedAt = new Date().toISOString();
+    },
     async mutate(fn) {
       // 官方语义：整体换新快照（本插件借此同步改写 path/title），随后按索引剪枝成员
       const changed = fn(record);
@@ -70,7 +77,8 @@ function makeEntity(id, path, hostRef) {
       if (record.sessionIds.includes(sid)) return;
       // 官方语义：未记账 id 需通过「头部 cwd 规范化后 === path」校验，
       // 并经 rememberSessionPath 回填三张索引后才挂账
-      const header = readHeader(readFileSync(findArtifact(sid)));
+      const artifact = findArtifact(sid);
+      const header = readHeader(readFileSync(artifact), artifact.endsWith('.zstd') ? 'zstd' : 'none');
       let canonical;
       try { canonical = realpathSync(header.cwd); } catch {
         throw new Error(`cwd does not resolve: '${header.cwd}'`);
@@ -99,10 +107,10 @@ function findArtifact(sessionId) {
     const dir = join(root, proj, sessionId);
     if (!existsSync(dir)) continue;
     const names = readdirSync(dir)
-      .filter((name) => name === 'session.jsonl.zstd' || /^session\.v[1-9][0-9]*\.jsonl\.zstd$/.test(name))
+      .filter((name) => /^session(?:\.v[1-9][0-9]*)?\.jsonl(?:\.zstd)?$/.test(name))
       .sort((a, b) => {
-        const va = a === 'session.jsonl.zstd' ? 0 : Number(/^session\.v([0-9]+)/.exec(a)[1]);
-        const vb = b === 'session.jsonl.zstd' ? 0 : Number(/^session\.v([0-9]+)/.exec(b)[1]);
+        const va = Number(/^session\.v([1-9][0-9]*)\.jsonl/.exec(a)?.[1] ?? 0);
+        const vb = Number(/^session\.v([1-9][0-9]*)\.jsonl/.exec(b)?.[1] ?? 0);
         return vb - va;
       });
     if (names.length) return join(dir, names[0]);
@@ -115,6 +123,7 @@ beforeEach(() => {
   // 的唯一性约定）；macOS 的 Temp 位于 /var → /private/var 符号链接下，
   // 夹具若用未规范化路径会与 canonical 比对失配，因此创建后立即归一。
   root = realpathSync(makeRoot());
+  cleanups = [];
   A = join(root, 'proj-alpha');
   B = join(root, 'proj-beta');
   mkdirSync(A, { recursive: true });
@@ -150,6 +159,7 @@ beforeEach(() => {
   };
   const persistence = {
     root,
+    compression: 'zstd',
     async list() {
       // 动态扫描 root（与真实后端一致）：遍历 projectKey 目录读头部
       const out = [];
@@ -159,15 +169,15 @@ beforeEach(() => {
         const projPath = join(root, proj);
         for (const idDir of readdirSync(projPath)) {
           const dir = join(projPath, idDir);
-          const names = existsSync(dir) ? readdirSync(dir).filter((name) => name === 'session.jsonl.zstd' || /^session\.v[1-9][0-9]*\.jsonl\.zstd$/.test(name)) : [];
+          const names = existsSync(dir) ? readdirSync(dir).filter((name) => /^session(?:\.v[1-9][0-9]*)?\.jsonl(?:\.zstd)?$/.test(name)) : [];
           if (!names.length) continue;
           names.sort((a, b) => {
-            const va = a === 'session.jsonl.zstd' ? 0 : Number(/^session\.v([0-9]+)/.exec(a)[1]);
-            const vb = b === 'session.jsonl.zstd' ? 0 : Number(/^session\.v([0-9]+)/.exec(b)[1]);
+            const va = Number(/^session\.v([1-9][0-9]*)\.jsonl/.exec(a)?.[1] ?? 0);
+            const vb = Number(/^session\.v([1-9][0-9]*)\.jsonl/.exec(b)?.[1] ?? 0);
             return vb - va;
           });
           const f = join(dir, names[0]);
-          try { out.push(readHeader(readFileSync(f))); } catch { /* skip */ }
+          try { out.push(readHeader(readFileSync(f), f.endsWith('.zstd') ? 'zstd' : 'none')); } catch { /* skip */ }
         }
       }
       return out;
@@ -179,12 +189,17 @@ beforeEach(() => {
     sessionPersistence: persistence,
     logger: { info() {}, warn() {} },
     get: () => undefined,
+    effect(register) {
+      const cleanup = register();
+      if (typeof cleanup === 'function') cleanups.push(cleanup);
+    },
     connection: { rpc: { handle(_ch, h) { rpcHandler = h; return () => {}; } } }
   };
   ctx.__rpc = () => rpcHandler;
 });
 
 afterEach(() => {
+  for (const cleanup of cleanups) cleanup();
   delete process.env.DSH_HOME;
   rmSync(root, { recursive: true, force: true });
 });
@@ -198,6 +213,349 @@ test('mover.status 就绪', async () => {
   const res = await call('mover.status');
   assert.equal(res.ok, true);
   assert.equal(res.value.ready, true);
+  assert.equal(res.value.capabilities.backupSnapshots, true);
+});
+
+test('mover.preview：安全项报告目标与备份大小，目标冲突明确阻断', async () => {
+  apply(ctx);
+  const safe = await call('mover.preview', { sessionId: 'session-aaa', targetWorkspaceId: 'wid-b' });
+  assert.equal(safe.ok, true, JSON.stringify(safe));
+  assert.equal(safe.value.status, 'safe');
+  assert.equal(safe.value.target.path, B);
+  assert.ok(safe.value.estimatedBackupBytes > 0);
+  assert.equal(safe.value.adapter.mode, 'filesystem-fallback');
+
+  const collision = artifactPath(root, B, 'session-aaa');
+  mkdirSync(dirname(collision), { recursive: true });
+  writeFileSync(collision, makeArtifact({ type: 'session', id: 'session-aaa', cwd: B, title: 'Alpha discussion' }));
+  const blocked = await call('mover.preview', { sessionId: 'session-aaa', targetWorkspaceId: 'wid-b' });
+  assert.equal(blocked.ok, true, JSON.stringify(blocked));
+  assert.equal(blocked.value.status, 'blocked');
+  assert.match(blocked.value.warnings.join(' '), /already contains/);
+});
+
+test('往返迁移预览从实际位置读取，只有当前工作区被标为无需移动', async () => {
+  apply(ctx);
+  entityA.record.sessionIds.push('session-aaa');
+  const moved = await call('mover.move', { sessionId: 'session-aaa', targetWorkspaceId: 'wid-b' });
+  assert.equal(moved.ok, true, JSON.stringify(moved));
+  const same = await call('mover.preview', { sessionId: 'session-aaa', targetWorkspaceId: 'wid-b' });
+  assert.equal(same.value.status, 'blocked');
+  assert.equal(same.value.target.collision, false);
+  assert.equal(same.value.estimatedBackupBytes, 0);
+  assert.ok(same.value.warnings.includes('session already belongs to the target workspace'));
+  const back = await call('mover.preview', { sessionId: 'session-aaa', targetWorkspaceId: 'wid-a' });
+  assert.equal(back.value.source.cwd, B);
+  assert.equal(back.value.target.path, A);
+  assert.equal(back.value.status, 'safe');
+  const returned = await call('mover.move', { sessionId: 'session-aaa', targetWorkspaceId: 'wid-a' });
+  assert.equal(returned.ok, true, JSON.stringify(returned));
+  assert.equal(readHeader(readFileSync(findArtifact('session-aaa'))).cwd, A);
+  assert.equal(existsSync(sessionDir(root, B, 'session-aaa')), false);
+});
+
+test('预览允许修复同工作区未登记会话，且不报告副本冲突', async () => {
+  apply(ctx);
+  const plan = await call('mover.preview', { sessionId: 'session-aaa', targetWorkspaceId: 'wid-a' });
+  assert.equal(plan.value.status, 'safe');
+  assert.equal(plan.value.target.collision, false);
+  assert.equal(plan.value.estimatedBackupBytes, 0);
+  const repaired = await call('mover.move', { sessionId: 'session-aaa', targetWorkspaceId: 'wid-a' });
+  assert.equal(repaired.ok, true, JSON.stringify(repaired));
+  assert.equal(repaired.value.attached, true);
+});
+
+test('救援扫描将混合压缩编码标为 unsupported，继续返回其余诊断', async () => {
+  apply(ctx);
+  const plain = join(sessionDir(root, A, 'session-aaa'), 'session.v3.jsonl');
+  writeFileSync(plain, Buffer.from([
+    JSON.stringify({ type: 'session', id: 'session-aaa', cwd: A }),
+    JSON.stringify({ type: 'message', id: 'event-mixed' })
+  ].join('\n') + '\n', 'utf8'));
+
+  const scan = await call('mover.scan');
+  assert.equal(scan.ok, true, JSON.stringify(scan));
+  const item = scan.value.items.find((entry) => entry.sessionId === 'session-aaa');
+  assert.equal(item.status, 'unreadable');
+  assert.equal(item.diagnostic, 'unsupported');
+  assert.match(item.diagnosticDetail, /mixed session compression encodings/);
+  const status = await call('mover.status');
+  assert.equal(status.value.storageLayout.diagnostic, 'unsupported');
+  const doctor = await call('mover.doctor');
+  assert.match(doctor.value.checks.find((entry) => entry.id === 'data-layout').detail, /unsupported/);
+});
+
+test('救援扫描明确区分损坏档案', async () => {
+  apply(ctx);
+  writeFileSync(artifactPath(root, A, 'session-aaa'), Buffer.from('damaged archive'));
+
+  const scan = await call('mover.scan');
+  assert.equal(scan.ok, true, JSON.stringify(scan));
+  const item = scan.value.items.find((entry) => entry.sessionId === 'session-aaa');
+  assert.equal(item.status, 'unreadable');
+  assert.equal(item.diagnostic, 'corrupt-data');
+  assert.ok(item.diagnosticDetail);
+  const status = await call('mover.status');
+  assert.equal(status.value.storageLayout.diagnostic, 'corrupt-data');
+});
+
+test('v4 Zstd 档案迁移与撤回时保留代际和事件字节', async () => {
+  apply(ctx);
+  entityA.record.sessionIds.push('session-aaa');
+  const sourceV3 = artifactPath(root, A, 'session-aaa');
+  const sourceV4 = join(dirname(sourceV3), 'session.v4.jsonl.zstd');
+  renameSync(sourceV3, sourceV4);
+
+  const moved = await call('mover.move', { sessionId: 'session-aaa', targetWorkspaceId: 'wid-b' });
+  assert.equal(moved.ok, true, JSON.stringify(moved));
+  const targetV4 = join(sessionDir(root, B, 'session-aaa'), 'session.v4.jsonl.zstd');
+  assert.ok(existsSync(targetV4));
+  assert.equal(readHeader(readFileSync(targetV4)).cwd, B);
+
+  const undone = await call('mover.undo', { historyId: moved.value.historyId });
+  assert.equal(undone.ok, true, JSON.stringify(undone));
+  assert.ok(existsSync(sourceV4));
+  assert.equal(readHeader(readFileSync(sourceV4)).cwd, A);
+});
+
+test('v3/v4 同目录明确诊断最高代际，并保留旧代际文件', async () => {
+  apply(ctx);
+  entityA.record.sessionIds.push('session-aaa');
+  const sourceV3 = artifactPath(root, A, 'session-aaa');
+  const sourceV4 = join(dirname(sourceV3), 'session.v4.jsonl.zstd');
+  writeFileSync(sourceV4, readFileSync(sourceV3));
+
+  const status = await call('mover.status');
+  assert.match(status.value.storageLayout.generationWarning, /v4 is selected/);
+  const doctor = await call('mover.doctor');
+  assert.equal(doctor.value.checks.find((item) => item.id === 'data-layout')?.state, 'warn');
+
+  const preview = await call('mover.preview', { sessionId: 'session-aaa', targetWorkspaceId: 'wid-b' });
+  assert.deepEqual(preview.value.source.generations.map((item) => item.version), [4, 3]);
+  assert.match(preview.value.warnings.join(' '), /v4 is selected and older files are preserved/);
+  const moved = await call('mover.move', { sessionId: 'session-aaa', targetWorkspaceId: 'wid-b' });
+  assert.equal(moved.ok, true, JSON.stringify(moved));
+  assert.ok(existsSync(join(sessionDir(root, B, 'session-aaa'), 'session.v3.jsonl.zstd')));
+  assert.equal(readHeader(readFileSync(join(sessionDir(root, B, 'session-aaa'), 'session.v4.jsonl.zstd'))).cwd, B);
+});
+
+test('legacy v0 与当前 v3 plain JSONL 均可迁移并撤回，不强制升级代际', async () => {
+  apply(ctx);
+  ctx.sessionPersistence.compression = 'none';
+  const cases = [
+    { sessionId: 'session-aaa', filename: 'session.jsonl' },
+    { sessionId: 'session-plain-v3', filename: 'session.v3.jsonl' }
+  ];
+  for (const item of cases) {
+    entityA.record.sessionIds.push(item.sessionId);
+    const sourceDir = sessionDir(root, A, item.sessionId);
+    mkdirSync(sourceDir, { recursive: true });
+    if (item.sessionId === 'session-aaa') rmSync(artifactPath(root, A, item.sessionId), { force: true });
+    const source = join(sourceDir, item.filename);
+    writeFileSync(source, Buffer.from([
+      JSON.stringify({ type: 'session', id: item.sessionId, cwd: A }),
+      JSON.stringify({ type: 'message', id: `event-${item.sessionId}` })
+    ].join('\n') + '\n', 'utf8'));
+
+    const moved = await call('mover.move', { sessionId: item.sessionId, targetWorkspaceId: 'wid-b' });
+    assert.equal(moved.ok, true, JSON.stringify(moved));
+    const target = join(sessionDir(root, B, item.sessionId), item.filename);
+    assert.ok(existsSync(target));
+    assert.equal(readHeader(readFileSync(target), 'none').cwd, B);
+    assert.equal(readFileSync(target, 'utf8').split('\n')[1], JSON.stringify({ type: 'message', id: `event-${item.sessionId}` }));
+
+    const undone = await call('mover.undo', { historyId: moved.value.historyId });
+    assert.equal(undone.ok, true, JSON.stringify(undone));
+    assert.equal(readHeader(readFileSync(source), 'none').cwd, A);
+  }
+});
+
+test('文件名代际与显式 header 代际不符时，在迁移前拒绝且字节不变', async () => {
+  apply(ctx);
+  entityA.record.sessionIds.push('session-aaa');
+  const source = artifactPath(root, A, 'session-aaa');
+  const bytes = makeArtifact({ type: 'session', id: 'session-aaa', cwd: A, formatVersion: 4 });
+  writeFileSync(source, bytes);
+
+  const moved = await call('mover.move', { sessionId: 'session-aaa', targetWorkspaceId: 'wid-b' });
+  assert.equal(moved.ok, false);
+  assert.equal(moved.error.code, 'unsupported');
+  assert.deepEqual(readFileSync(source), bytes);
+  assert.ok(!existsSync(artifactPath(root, B, 'session-aaa')));
+});
+
+test('busy 迁移进入持久化队列，空闲后可重试完成', async () => {
+  apply(ctx);
+  entityA.record.sessionIds.push('session-aaa');
+  ctx.get = (key) => (key === 'agents' ? { get: () => ({ status: 'running' }) } : undefined);
+  const queued = await call('mover.move', { sessionId: 'session-aaa', targetWorkspaceId: 'wid-b' });
+  assert.equal(queued.ok, false);
+  assert.equal(queued.error.code, 'busy');
+  assert.ok(queued.error.details.queueTaskId);
+
+  const waiting = await call('mover.migrations.list');
+  const waitingItem = waiting.value.items.find((item) => item.id === queued.error.details.queueTaskId);
+  assert.equal(waitingItem.state, 'waiting-for-idle');
+
+  ctx.get = () => undefined;
+  const retried = await call('mover.migrations.retry', { taskId: waitingItem.id });
+  assert.equal(retried.ok, true, JSON.stringify(retried));
+  assert.equal(retried.value.item.state, 'done');
+  assert.ok(existsSync(artifactPath(root, B, 'session-aaa')));
+  const repeated = await call('mover.migrations.retry', { taskId: waitingItem.id });
+  assert.equal(repeated.value.item.state, 'done');
+  assert.equal(repeated.value.item.attempts, retried.value.item.attempts, 'completed retries are idempotent');
+});
+
+test('busy 队列在插件重新挂载后从持久化记录继续执行', async () => {
+  apply(ctx);
+  entityA.record.sessionIds.push('session-aaa');
+  ctx.get = (key) => (key === 'agents' ? { get: () => ({ status: 'running' }) } : undefined);
+  const queued = await call('mover.move', { sessionId: 'session-aaa', targetWorkspaceId: 'wid-b' });
+  const queueFile = join(root, 'workspace-mover', 'migrations.json');
+  assert.ok(existsSync(queueFile));
+
+  for (const cleanup of cleanups) cleanup();
+  cleanups = [];
+  ctx.get = () => undefined;
+  let restartedRpc;
+  const restartedCtx = {
+    ...ctx,
+    effect(register) {
+      const cleanup = register();
+      if (typeof cleanup === 'function') cleanups.push(cleanup);
+    },
+    connection: { rpc: { handle(_ch, handler) { restartedRpc = handler; return () => {}; } } }
+  };
+  apply(restartedCtx);
+  const recovered = await restartedRpc('mover.migrations.list', {});
+  assert.equal(recovered.ok, true, JSON.stringify(recovered));
+  const item = recovered.value.items.find((entry) => entry.id === queued.error.details.queueTaskId);
+  assert.equal(item.state, 'done');
+  assert.ok(existsSync(artifactPath(root, B, 'session-aaa')));
+});
+
+test('迁移队列支持批量重试并逐项隔离失败', async () => {
+  apply(ctx);
+  const queued = await call('mover.migrations.enqueue', {
+    targetWorkspaceId: 'wid-b',
+    sessions: [{ sessionId: 'session-missing-a' }, { sessionId: 'session-missing-b' }]
+  });
+  assert.equal(queued.ok, true, JSON.stringify(queued));
+  const taskIds = queued.value.queued.map((item) => item.id);
+  const retry = await call('mover.migrations.retry', { taskIds });
+  assert.equal(retry.ok, true, JSON.stringify(retry));
+  assert.equal(retry.value.retried, 2);
+  assert.deepEqual(retry.value.items.map((item) => item.state), ['failed', 'failed']);
+  assert.deepEqual(retry.value.items.map((item) => item.attempts), [2, 2]);
+});
+
+test('迁移队列执行中拒绝取消，损坏的队列数据由 status 和 doctor 显示', async () => {
+  apply(ctx);
+  entityA.record.sessionIds.push('session-aaa');
+  ctx.get = (key) => (key === 'agents' ? { get: () => ({ status: 'running' }) } : undefined);
+  const queued = await call('mover.move', { sessionId: 'session-aaa', targetWorkspaceId: 'wid-b' });
+  ctx.get = () => undefined;
+
+  const originalList = ctx.sessionPersistence.list.bind(ctx.sessionPersistence);
+  let entered;
+  const inMove = new Promise((resolve) => { entered = resolve; });
+  let release;
+  const hold = new Promise((resolve) => { release = resolve; });
+  ctx.sessionPersistence.list = async (...args) => {
+    entered();
+    await hold;
+    return originalList(...args);
+  };
+  const retrying = call('mover.migrations.retry', { taskId: queued.error.details.queueTaskId });
+  await inMove;
+  const cancel = await call('mover.migrations.cancel', { taskId: queued.error.details.queueTaskId });
+  assert.equal(cancel.ok, false);
+  assert.equal(cancel.error.code, 'busy');
+  release();
+  const done = await retrying;
+  assert.equal(done.value.item.state, 'done');
+
+  writeFileSync(join(root, 'workspace-mover', 'migrations.json'), '{broken', 'utf8');
+  const status = await call('mover.status');
+  assert.equal(status.ok, true);
+  assert.match(status.value.capabilities.migrationQueueState.error, /corrupt/);
+  assert.ok(status.value.degradedFeatures.includes('migration-queue-data'));
+  const doctor = await call('mover.doctor');
+  assert.equal(doctor.ok, true);
+  assert.equal(doctor.value.checks.find((item) => item.id === 'data-migrations')?.state, 'fail');
+});
+
+test('official handle-only persistence 被明确标记为降级而不是猜物理路径', async () => {
+  const official = createPersistenceAdapter({ sessionPersistence: {
+    async list() { return []; },
+    async stat() { return { formatStatus: 'jsonl' }; },
+    async open() { return {}; }
+  } });
+  assert.equal(official.mode, 'official-handle');
+  assert.equal(official.capabilities.physicalPath, false);
+  await assert.rejects(() => official.read({ kind: 'handle', sessionId: 'x' }), /raw-byte physical path/);
+});
+
+test('fork-tree 预览会列出后代，Portable Bundle 导入先 dry-run 再执行', async () => {
+  apply(ctx);
+  entityA.record.sessionIds.push('session-aaa');
+  const child = artifactPath(root, A, 'session-child');
+  mkdirSync(dirname(child), { recursive: true });
+  writeFileSync(child, makeArtifact({ type: 'session', id: 'session-child', parentSessionId: 'session-aaa', cwd: A, title: 'Child branch' }));
+
+  const preview = await call('mover.preview', { sessionId: 'session-aaa', targetWorkspaceId: 'wid-b', mode: 'include-descendants' });
+  assert.equal(preview.ok, true, JSON.stringify(preview));
+  assert.equal(preview.value.branches.count, 1);
+  assert.deepEqual(preview.value.branches.sessionIds, ['session-aaa', 'session-child']);
+
+  const bundlePath = join(root, 'portable-bundle');
+  const exported = await call('mover.bundle.export', { sessionId: 'session-aaa', bundlePath, mode: 'include-descendants' });
+  assert.equal(exported.ok, true, JSON.stringify(exported));
+  assert.equal(exported.value.sessionCount, 2);
+  assert.ok(existsSync(join(bundlePath, 'manifest.json')));
+  assert.ok(existsSync(join(bundlePath, 'checksums.json')));
+
+  entityA.record.sessionIds = [];
+  rmSync(dirname(artifactPath(root, A, 'session-aaa')), { recursive: true, force: true });
+  rmSync(dirname(artifactPath(root, A, 'session-child')), { recursive: true, force: true });
+  const dryRun = await call('mover.bundle.import', { bundlePath, targetWorkspaceId: 'wid-b' });
+  assert.equal(dryRun.ok, true, JSON.stringify(dryRun));
+  assert.equal(dryRun.value.dryRun, true);
+  assert.equal(dryRun.value.status, 'safe');
+  const imported = await call('mover.bundle.import', { bundlePath, targetWorkspaceId: 'wid-b', dryRun: false });
+  assert.equal(imported.ok, true, JSON.stringify(imported));
+  assert.equal(imported.value.importedCount, 2);
+  assert.ok(existsSync(artifactPath(root, B, 'session-aaa')));
+  assert.ok(existsSync(artifactPath(root, B, 'session-child')));
+});
+
+test('v2.2 mover.status 能力位：官方接口缺失时如实标记为降级（可观测，不静默）', async () => {
+  apply(ctx);
+  // 夹具的实体带官方 setTitle（与真实 Workspace 接口一致），但不带 unarchiveSession。
+  const res = await call('mover.status');
+  assert.equal(res.ok, true);
+  assert.equal(res.value.capabilities.setTitleApi, true, '实体带 setTitle 应被识别');
+  assert.equal(res.value.capabilities.unarchiveApi, false, '夹具无官方取消归档接口');
+  assert.ok(res.value.degradedFeatures.includes('unarchive-official-api'),
+    `缺失官方取消归档接口应列入降级: ${JSON.stringify(res.value.degradedFeatures)}`);
+  assert.ok(!res.value.degradedFeatures.includes('set-title-official-api'), '有 setTitle 不应报降级');
+});
+
+test('v2.2 mover.status 能力位：补上官方接口后不再报降级', async () => {
+  apply(ctx);
+  ctx.workspaceRegistry.unarchiveSession = async () => {};
+  const res = await call('mover.status');
+  assert.equal(res.value.capabilities.unarchiveApi, true);
+  assert.ok(!res.value.degradedFeatures.includes('unarchive-official-api'));
+});
+
+test('v2.2 mover.status 能力位：setTitle 缺失时也如实标记', async () => {
+  apply(ctx);
+  delete entityA.setTitle;
+  const res = await call('mover.status');
+  assert.equal(res.value.capabilities.setTitleApi, false);
+  assert.ok(res.value.degradedFeatures.includes('set-title-official-api'));
 });
 
 test('正常迁移：文件物理搬移 + 头部改写 + 双向记账 + 有备份', async () => {
@@ -841,6 +1199,22 @@ test('标题同步：默认名（=旧文件夹名）跟随改名，自定义标
   assert.equal(entityA.record.title, '我的项目', '自定义标题保留');
 });
 
+test('v2.2 标题同步失败不得影响已完成的 path 重定向（setTitle 与 mutate 解耦）', async () => {
+  apply(ctx);
+  setupMovedFolder2();
+  const ent = ctx.workspaceRegistry.entities.get('wid-t2');
+  const oldPath = ent.path;
+  const moved = oldPath + '-moved';
+  ent.record.title = oldPath.split(/[\\/]/).pop(); // 仍是旧文件夹名 → 会尝试同步
+  ent.setTitle = async () => { throw new Error('simulated setTitle failure'); };
+
+  const res = await call('mover.repoint', { workspaceId: 'wid-t2', newPath: moved });
+  assert.equal(res.ok, true, JSON.stringify(res));
+  assert.equal(res.value.pathUpdated, true, 'path 重定向必须完成');
+  assert.equal(realpathSync(ent.path), realpathSync(moved), '工作区已指向新路径');
+  assert.notEqual(ent.record.title, moved.split(/[\\/]/).pop(), '标题同步失败 → 保留原标题');
+});
+
 /** 独立夹具：避免用例间复用同一目录名导致的前置污染。 */
 function setupMovedFolder2() {
   const dir = join(root, 'ws-t2');
@@ -1005,13 +1379,51 @@ test('mover.unarchive 拒绝：未归档的会话；registry 缺状态写通道'
   assert.equal(miss.ok, false);
   assert.match(miss.error.message, /not archived/);
 
-  // 归档集里有它，但 registry 没有官方写通道（老版本宿主容错）
+  // 归档集里有它，但 registry 既无官方接口也无状态写通道（老版本宿主容错）
   ctx.workspaceRegistry.archivedSessionIds = ['session-aaa'];
   const res = await call('mover.unarchive', { sessionId: 'session-aaa' });
   assert.equal(res.ok, false);
   assert.match(res.error.message, /no state mutation API/);
 });
 
+test('v2.2 mover.unarchive 优先走官方 registry.unarchiveSession', async () => {
+  apply(ctx);
+  stubRegistryState();
+  entityA.record.sessionIds.push('session-aaa');
+  ctx.workspaceRegistry.archivedSessionIds = ['session-aaa'];
+  let officialCalls = 0;
+  let fallbackCalls = 0;
+  const enqueue = ctx.workspaceRegistry.enqueueOperation;
+  ctx.workspaceRegistry.unarchiveSession = async (id) => {
+    officialCalls++;
+    ctx.workspaceRegistry.archivedSessionIds = ctx.workspaceRegistry.archivedSessionIds.filter((x) => String(x) !== String(id));
+  };
+  ctx.workspaceRegistry.enqueueOperation = (...args) => { fallbackCalls++; return enqueue(...args); };
+
+  const res = await call('mover.unarchive', { sessionId: 'session-aaa' });
+  assert.equal(res.ok, true, JSON.stringify(res));
+  assert.equal(officialCalls, 1, '必须调用官方接口');
+  assert.equal(fallbackCalls, 0, '有官方接口时不得走回退通道');
+  assert.equal(ctx.workspaceRegistry.archivedSessionIds.includes('session-aaa'), false);
+  assert.deepEqual(entityA.record.sessionIds, ['session-aaa'], '记账槽不得被取消归档改动');
+});
+
+test('v2.2 mover.unarchive 官方接口缺失时回退到状态写通道', async () => {
+  apply(ctx);
+  stubRegistryState();
+  entityA.record.sessionIds.push('session-aaa');
+  ctx.workspaceRegistry.archivedSessionIds = ['session-aaa'];
+  let fallbackCalls = 0;
+  const enqueue = ctx.workspaceRegistry.enqueueOperation;
+  ctx.workspaceRegistry.enqueueOperation = (...args) => { fallbackCalls++; return enqueue(...args); };
+  assert.equal(typeof ctx.workspaceRegistry.unarchiveSession, 'undefined', '夹具默认无官方接口');
+
+  const res = await call('mover.unarchive', { sessionId: 'session-aaa' });
+  assert.equal(res.ok, true, JSON.stringify(res));
+  assert.equal(fallbackCalls, 1, '必须走回退通道');
+  assert.equal(ctx.workspaceRegistry.archivedSessionIds.includes('session-aaa'), false);
+});
+
 test('mover.openFolder 只允许已注册工作区路径；openInFileManager 按平台拼装命令', async () => {
   apply(ctx);
   // 未注册路径拒绝（不触发任何 spawn）
@@ -1136,7 +1548,7 @@ test('迁移流程级：残留目标目录给出明确错误，清理后同一
   assert.ok(!existsSync(artifactPath(root, A, 'session-aaa')));
 });
 
-test('stashBackup：相邻前缀 id 的备份互不误删（前缀收紧）', () => {
+test('stashBackup：相邻前缀 id 互不误删；同一毫秒的连续备份互不覆盖', () => {
   const a = 'session-aaa';
   const b = 'session-aaa-1'; // a 的前缀超集；'-' < '.' 使其排序在 a 的所有备份之前（最旧）
   const dir = join(root, 'workspace-mover', 'backups');
@@ -1147,13 +1559,59 @@ test('stashBackup：相邻前缀 id 的备份互不误删（前缀收紧）', ()
   const files = readdirSync(dir);
   assert.equal(files.filter((f) => f.startsWith(`${b}.`)).length, 1, '相邻前缀 id 的备份不被误删');
   assert.equal(files.filter((f) => f.startsWith(`${a}.`)).length, 20, 'a 恰好保留最近 20 份');
-  // 同毫秒连续 stash：文件名相同被原子覆盖（last-wins），不报错、不破坏裁剪计数
-  stashBackup(a, Buffer.from('same-ms-1'));
-  stashBackup(a, Buffer.from('same-ms-2'));
-  const files2 = readdirSync(dir);
-  assert.equal(files2.filter((f) => f.startsWith(`${a}.`)).length, 20, '同毫秒覆盖不改变保留计数');
-  const newest = files2.filter((f) => f.startsWith(`${a}.`)).sort().at(-1);
-  assert.equal(readFileSync(join(dir, newest)).toString(), 'same-ms-2', '最新内容 last-wins');
+  // 同一毫秒的连续 stash：必须各自留下独立文件（曾因文件名相撞而静默覆盖，
+  // 使 backupKeep 失效——Linux CI 就是这样挂掉的）。
+  const msA = 'session-ms';
+  const countMs = () => readdirSync(dir).filter((f) => f.startsWith(`${msA}.`)).length;
+  stashBackup(msA, Buffer.from('ms-1'));
+  stashBackup(msA, Buffer.from('ms-2'));
+  assert.equal(countMs(), 2,
+    `同一毫秒的两次备份必须留下 2 份而不是互相覆盖，实际 ${countMs()} 份：${JSON.stringify(readdirSync(dir).filter((f) => f.startsWith(`${msA}.`)))}`);
+  const msContents = readdirSync(dir).filter((f) => f.startsWith(`${msA}.`)).map((f) => readFileSync(join(dir, f)).toString()).sort();
+  assert.deepEqual(msContents, ['ms-1', 'ms-2'], `两份备份的内容都必须保留，实际 ${JSON.stringify(msContents)}`);
+
+  // 裁剪计数仍受 backupKeep 约束：把 a 撑回 21 份后应回落到 20。
+  for (let i = 2000; i < 2021; i++) writeFileSync(join(dir, `${a}.${i}.zstd`), Buffer.from('v' + i));
+  stashBackup(a, Buffer.from('after-prune'));
+  assert.equal(readdirSync(dir).filter((f) => f.startsWith(`${a}.`)).length, 20, 'a 仍恰好保留 20 份');
+  assert.equal(readdirSync(dir).filter((f) => f.startsWith(`${b}.`)).length, 1, '相邻前缀 id 仍不受影响');
+});
+
+test('stashBackup：忽略迁移 cwd 后复用同一快照，内容变化才新增物理文件', () => {
+  const dir = join(root, 'workspace-mover', 'backups');
+  const firstBytes = makeArtifact({ type: 'session', id: 'session-dedupe', cwd: A, title: 'Stable content' });
+  const sameContentAtOtherWorkspace = makeArtifact({ type: 'session', id: 'session-dedupe', cwd: B, title: 'Stable content' });
+  const first = stashBackup('session-dedupe', firstBytes, { compression: 'zstd', ignoreCwd: true });
+  const reused = stashBackup('session-dedupe', sameContentAtOtherWorkspace, { compression: 'zstd', ignoreCwd: true });
+  assert.equal(first.created, true);
+  assert.equal(reused.reused, true);
+  assert.equal(reused.addedBytes, 0);
+  assert.equal(readdirSync(dir).filter((f) => f.startsWith('session-dedupe.')).length, 1);
+
+  const changed = makeArtifact({ type: 'session', id: 'session-dedupe', cwd: B, title: 'Changed content' });
+  const second = stashBackup('session-dedupe', changed, { compression: 'zstd', ignoreCwd: true });
+  assert.equal(second.created, true);
+  assert.equal(readdirSync(dir).filter((f) => f.startsWith('session-dedupe.')).length, 2);
+});
+
+test('往返迁移：备份物理文件只保留一份，但每次移动历史都记录复用状态', async () => {
+  apply(ctx);
+  entityA.record.sessionIds.push('session-aaa');
+  const first = await call('mover.move', { sessionId: 'session-aaa', targetWorkspaceId: 'wid-b' });
+  assert.equal(first.ok, true, JSON.stringify(first));
+  const backPreview = await call('mover.preview', { sessionId: 'session-aaa', targetWorkspaceId: 'wid-a' });
+  assert.equal(backPreview.ok, true, JSON.stringify(backPreview));
+  assert.equal(backPreview.value.backup.reused, true);
+  assert.equal(backPreview.value.estimatedBackupBytes, 0);
+  const back = await call('mover.move', { sessionId: 'session-aaa', targetWorkspaceId: 'wid-a' });
+  assert.equal(back.ok, true, JSON.stringify(back));
+  const files = readdirSync(join(root, 'workspace-mover', 'backups')).filter((f) => f.startsWith('session-aaa.'));
+  assert.equal(files.length, 1, JSON.stringify(files));
+  const history = await call('mover.history');
+  assert.equal(history.ok, true);
+  assert.equal(history.value.items.length, 2);
+  assert.equal(history.value.items[0].backup.reused, true);
+  assert.equal(history.value.items[1].backup.created, true);
 });
 
 //#region v0.9：回收站 + 备份管理
@@ -1223,6 +1681,65 @@ test('mover.session.delete：移入回收站并完成四件套清理', async ()
   assert.equal(list.value.items[0].ownerWorkspaceId, 'wid-a');
 });
 
+test('v2.2 备份 GC：删除会话默认保留备份，purgeBackups=true 才清理，且不误删相邻 id', async () => {
+  apply(ctx);
+  sharedIndex.sessionPaths.set('session-aaa', A);
+  sharedIndex.sessionPaths.set('session-aaa-1', A);
+  entityA.record.sessionIds.push('session-aaa', 'session-aaa-1');
+  // 三个会话各留一份备份；session-aaa-1 是 session-aaa 的前缀超集，必须不被误删
+  stashBackup('session-aaa', Buffer.from('aaa-1'));
+  stashBackup('session-aaa-1', Buffer.from('neighbour'));
+  const dir = join(root, 'workspace-mover', 'backups');
+  const filesFor = (id) => readdirSync(dir).filter((f) => f.startsWith(`${id}.`));
+
+  // ① 默认：删除会话但保留备份
+  const del = await call('mover.session.delete', { sessionId: 'session-aaa' });
+  assert.equal(del.ok, true, JSON.stringify(del));
+  assert.equal(del.value.backupsDeleted, 0, '默认不得删除备份');
+  assert.equal(filesFor('session-aaa').length, 1, '备份仍在（回收站还原后可能还要用）');
+  assert.equal(filesFor('session-aaa-1').length, 1);
+
+  // ② 现在 session-aaa 档案已不存在 → 它的备份组成为孤儿
+  const listed = await call('mover.backups.list');
+  assert.equal(listed.ok, true);
+  const aaaGroup = listed.value.items.find((it) => it.sessionId === 'session-aaa');
+  const neighbourGroup = listed.value.items.find((it) => it.sessionId === 'session-aaa-1');
+  assert.equal(aaaGroup.orphan, true, '会话已删除 → 备份组标记为孤儿');
+  assert.equal(neighbourGroup.orphan, false, '仍存在的会话不得被误标为孤儿');
+  assert.equal(listed.value.orphanGroups, 1);
+  assert.ok(listed.value.orphanBytes > 0);
+
+  // ③ 彻底删除 + purgeBackups：连带清掉该会话备份，且相邻前缀 id 毫发无损
+  const purged = await call('mover.trash.purge', { sessionId: 'session-aaa', purgeBackups: true });
+  assert.equal(purged.ok, true, JSON.stringify(purged));
+  assert.equal(purged.value.purged, 1);
+  assert.equal(purged.value.backupsDeleted, 1);
+  assert.equal(filesFor('session-aaa').length, 0, '孤儿备份必须被清掉');
+  assert.equal(filesFor('session-aaa-1').length, 1, '相邻前缀 id 的备份绝不能被误删');
+  assert.equal(readFileSync(join(dir, filesFor('session-aaa-1')[0])).toString(), 'neighbour');
+});
+
+test('v2.2 备份 GC：doctor 汇总孤儿备份组数与占用', async () => {
+  apply(ctx);
+  // 只留一份"会话已不存在"的备份
+  stashBackup('session-ghost', Buffer.alloc(64, 7));
+  const doc = await call('mover.doctor');
+  assert.equal(doc.ok, true);
+  const backupsCheck = doc.value.checks.find((c) => c.id === 'data-backups');
+  assert.equal(backupsCheck.state, 'pass');
+  assert.match(backupsCheck.detail, /orphan group/, `应汇报孤儿组: ${backupsCheck.detail}`);
+});
+
+test('v2.2 备份 GC：moveMany 历史聚合的会话备份仍被视为存活', async () => {
+  apply(ctx);
+  sharedIndex.sessionPaths.set('session-aaa', A);
+  entityA.record.sessionIds.push('session-aaa');
+  stashBackup('session-aaa', Buffer.from('alive'));
+  const listed = await call('mover.backups.list');
+  const group = listed.value.items.find((it) => it.sessionId === 'session-aaa');
+  assert.equal(group.orphan, false, '注册表仍记账的会话不算孤儿');
+});
+
 test('mover.session.delete：常驻内存的会话拒绝删除', async () => {
   apply(ctx);
   entityA.record.sessionIds.push('session-aaa');
@@ -1760,6 +2277,43 @@ test('v1.4 scan 超限截断：先按 mtime 排序，保留最新 400 条', asyn
   assert.ok(ids.has('session-gen-409'), '最新的生成会话必须保留');
   assert.equal(ids.has('session-gen-000'), false, '最旧的生成会话必须被截掉');
   assert.ok(ids.has('session-aaa'), '整体最新的夹具会话保留');
+  assert.equal(res.value.scannedParsed, CAP, 'scannedParsed 报告实际解析条数');
+});
+
+test('v2.2 归档列表透传截断信息：大库上"不是全部"必须可说明', async () => {
+  apply(ctx);
+  const CAP = SCAN_MAX_ITEMS;
+  const EXTRA = 5;
+  const base = Date.now() - 1_000_000;
+  // 造一个很旧、且被归档的会话：它会被 mtime 截断挡在扫描窗口之外。
+  const oldId = 'session-archived-old';
+  const oldPath = artifactPath(root, A, oldId);
+  mkdirSync(dirname(oldPath), { recursive: true });
+  writeFileSync(oldPath, makeArtifact({ type: 'session', id: oldId, cwd: A, title: 'Ancient archived' }));
+  const oldTime = new Date(base - 500_000);
+  utimesSync(oldPath, oldTime, oldTime);
+
+  for (let i = 0; i < CAP + EXTRA; i++) {
+    const id = `session-arch-${String(i).padStart(3, '0')}`;
+    const p = artifactPath(root, A, id);
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, makeArtifact({ type: 'session', id, cwd: A, title: `Arch ${i}` }));
+    const t = new Date(base + i * 1000);
+    utimesSync(p, t, t);
+  }
+  // 官方归档集：把最旧的那个也标为归档
+  ctx.workspaceRegistry.archivedSessionIds = [oldId];
+
+  const res = await call('mover.archived');
+  assert.equal(res.ok, true, JSON.stringify(res));
+  assert.equal(res.value.truncated, true, '本次扫描必然被截断');
+  assert.equal(res.value.archivedTotal, 1);
+  assert.ok(res.value.scannedTotal > res.value.scannedParsed,
+    `必须同时给出"共多少"与"解析了多少": ${JSON.stringify({ total: res.value.scannedTotal, parsed: res.value.scannedParsed })}`);
+  // 关键：被截断挡住的归档会话确实不在列表里——所以 UI 必须能说明这件事
+  assert.equal(res.value.items.some((it) => it.sessionId === oldId), false,
+    '该归档会话落在扫描窗口之外（正是需要提示用户的场景）');
+  assert.equal(res.value.items.length, 0);
 });
 
 test('v1.4 回滚也失败 → 写 recovery 记录，scan 报告 recoveryCount', async () => {
@@ -1919,44 +2473,135 @@ test('v2.1 mover_repair_sessions 走审批并修复未记账夹具会话', async
   assert.equal(approvalCalls.length, 1);
   assert.equal(approvalCalls[0].toolName, 'mover_repair_sessions');
 });
-
-// ===== v2.2.0 mover.doctor 自检 =====
-
-test('v2.2 mover.doctor 沙箱全绿：服务/数据/工作区全部 pass', async () => {
-  apply(ctx);
-  const res = await call('mover.doctor');
-  assert.equal(res.ok, true, JSON.stringify(res));
-  const { checks, summary } = res.value;
-  assert.ok(checks.length >= 12, `至少 12 项检查，实际 ${checks.length}`);
-  for (const c of checks) assert.ok(['pass', 'warn', 'fail'].includes(c.state), `state 合法: ${c.id}`);
-  assert.equal(summary.fail, 0, `不应有 fail: ${JSON.stringify(checks.filter((c) => c.state === 'fail'))}`);
-  const ids = new Set(checks.map((c) => c.id));
-  for (const expected of ['host-registry', 'host-persistence', 'host-projection', 'data-recycle', 'data-backups', 'recovery', 'workspaces']) {
-    assert.ok(ids.has(expected), `缺少检查项 ${expected}`);
-  }
-  assert.equal(typeof res.value.generatedAt, 'string');
-});
-
-test('v2.2 mover.doctor 降级：摘除注册表后 fail + warn，但不抛错', async () => {
-  apply(ctx);
-  ctx.workspaceRegistry = undefined;
-  const res = await call('mover.doctor');
-  assert.equal(res.ok, true, 'doctor 本身永远 ok');
-  const registryCheck = res.value.checks.find((c) => c.id === 'host-registry');
-  assert.equal(registryCheck.state, 'fail');
-  const workspacesCheck = res.value.checks.find((c) => c.id === 'workspaces');
-  assert.equal(workspacesCheck.state, 'warn');
-  assert.equal(res.value.summary.fail >= 1, true);
-});
-
-test('v2.2 mover.doctor 恢复记录告警：recovery.json 存在时 warn', async () => {
-  apply(ctx);
-  const dir = join(root, 'workspace-mover');
-  mkdirSync(dir, { recursive: true });
-  writeFileSync(join(dir, 'recovery.json'), JSON.stringify({ version: 1, records: [{ id: 'rec-x', kind: 'delete', phase: 'test', createdAt: new Date().toISOString() }] }));
-  const res = await call('mover.doctor');
-  assert.equal(res.ok, true);
-  const recovery = res.value.checks.find((c) => c.id === 'recovery');
-  assert.equal(recovery.state, 'warn');
-  assert.match(recovery.detail, /1 record/);
-});
+
+// ===== v2.2.0 mover.doctor 自检 =====
+
+test('v2.2 mover.doctor 沙箱全绿：服务/数据/工作区全部 pass', async () => {
+  apply(ctx);
+  const res = await call('mover.doctor');
+  assert.equal(res.ok, true, JSON.stringify(res));
+  const { checks, summary } = res.value;
+  assert.ok(checks.length >= 12, `至少 12 项检查，实际 ${checks.length}`);
+  for (const c of checks) assert.ok(['pass', 'warn', 'fail'].includes(c.state), `state 合法: ${c.id}`);
+  assert.equal(summary.fail, 0, `不应有 fail: ${JSON.stringify(checks.filter((c) => c.state === 'fail'))}`);
+  const ids = new Set(checks.map((c) => c.id));
+  for (const expected of ['host-registry', 'host-persistence', 'host-projection', 'data-recycle', 'data-backups', 'recovery', 'workspaces']) {
+    assert.ok(ids.has(expected), `缺少检查项 ${expected}`);
+  }
+  assert.equal(typeof res.value.generatedAt, 'string');
+});
+
+test('v2.2 mover.doctor 降级：摘除注册表后 fail + warn，但不抛错', async () => {
+  apply(ctx);
+  ctx.workspaceRegistry = undefined;
+  const res = await call('mover.doctor');
+  assert.equal(res.ok, true, 'doctor 本身永远 ok');
+  const registryCheck = res.value.checks.find((c) => c.id === 'host-registry');
+  assert.equal(registryCheck.state, 'fail');
+  const workspacesCheck = res.value.checks.find((c) => c.id === 'workspaces');
+  assert.equal(workspacesCheck.state, 'warn');
+  assert.equal(res.value.summary.fail >= 1, true);
+});
+
+test('v2.2 mover.doctor 恢复记录告警：recovery.json 存在时 warn', async () => {
+  apply(ctx);
+  const dir = join(root, 'workspace-mover');
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'recovery.json'), JSON.stringify({ version: 1, records: [{ id: 'rec-x', kind: 'delete', phase: 'test', createdAt: new Date().toISOString() }] }));
+  const res = await call('mover.doctor');
+  assert.equal(res.ok, true);
+  const recovery = res.value.checks.find((c) => c.id === 'recovery');
+  assert.equal(recovery.state, 'warn');
+  assert.match(recovery.detail, /1 record/);
+});
+
+//#region v2.2 存储布局自证（插件复刻了 session-persistence-jsonl 的目录编码，
+// 且 persistence.root 并非文档化接口——宿主改布局时必须可检测而非静默失效）
+
+test('mover.status 报告 storageLayout=ok，且 doctor 有 data-layout 通过项', async () => {
+  apply(ctx);
+  const status = await call('mover.status');
+  assert.equal(status.ok, true);
+  assert.equal(status.value.capabilities.storageLayout, 'ok',
+    `沙箱夹具的布局必须自证通过: ${JSON.stringify(status.value.storageLayout)}`);
+  assert.ok(!status.value.degradedFeatures.includes('storage-layout'));
+
+  const doc = await call('mover.doctor');
+  const layoutCheck = doc.value.checks.find((c) => c.id === 'data-layout');
+  assert.ok(layoutCheck, 'doctor 必须包含 data-layout 检查项');
+  assert.equal(layoutCheck.state, 'pass');
+});
+
+test('宿主布局漂移时自证失败：storageLayout=degraded 且列为降级特性', async () => {
+  apply(ctx);
+  // 把持久化根指向别处：插件按自己的编码规则反推出的目录在那边不存在。
+  ctx.sessionPersistence.root = join(root, 'somewhere-else');
+  const status = await call('mover.status');
+  assert.equal(status.ok, true, 'status 本身永远 ok');
+  assert.equal(status.value.capabilities.storageLayout, 'degraded');
+  assert.equal(status.value.storageLayout.diagnostic, 'layout-unknown');
+  assert.ok(status.value.degradedFeatures.includes('storage-layout'),
+    `降级特性应包含 storage-layout: ${JSON.stringify(status.value.degradedFeatures)}`);
+  assert.equal(typeof status.value.storageLayout.reason, 'string');
+
+  const doc = await call('mover.doctor');
+  assert.equal(doc.ok, true, 'doctor 不因布局异常而抛错');
+  const layoutCheck = doc.value.checks.find((c) => c.id === 'data-layout');
+  assert.equal(layoutCheck.state, 'warn');
+});
+
+test('没有会话可校验时 storageLayout=empty（全新安装不误报降级）', async () => {
+  apply(ctx);
+  // 清空持久化根：list() 动态扫描，返回空即无样本可校验。
+  rmSync(root, { recursive: true, force: true });
+  const status = await call('mover.status');
+  assert.equal(status.ok, true);
+  assert.equal(status.value.capabilities.storageLayout, 'empty');
+  assert.ok(!status.value.degradedFeatures.includes('storage-layout'), '无样本不应报降级');
+});
+//#endregion
+
+
+test('默认恢复选择最新备份，显式指定时仍可恢复旧备份', async () => {
+  apply(ctx);
+  const dir = join(root, 'workspace-mover', 'backups');
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'session-aaa.1000.zstd'), makeArtifact({ type: 'session', id: 'session-aaa', cwd: A, title: 'Old content' }));
+  writeFileSync(join(dir, 'session-aaa.2000.zstd'), makeArtifact({ type: 'session', id: 'session-aaa', cwd: A, title: 'Latest content' }));
+  rmSync(dirname(artifactPath(root, A, 'session-aaa')), { recursive: true, force: true });
+  const restored = await call('mover.backups.restore', { sessionId: 'session-aaa' });
+  assert.equal(restored.ok, true, JSON.stringify(restored));
+  assert.equal(readHeader(readFileSync(artifactPath(root, A, 'session-aaa'))).title, 'Latest content');
+  entityA.record.sessionIds = [];
+  sharedIndex.sessionPaths.delete('session-aaa');
+  rmSync(dirname(artifactPath(root, A, 'session-aaa')), { recursive: true, force: true });
+  const old = await call('mover.backups.restore', { sessionId: 'session-aaa', fileName: 'session-aaa.1000.zstd' });
+  assert.equal(old.ok, true, JSON.stringify(old));
+  assert.equal(readHeader(readFileSync(artifactPath(root, A, 'session-aaa'))).title, 'Old content');
+});
+
+test('Bundle 空间估算包含附件，空间不足时 dry-run 阻断且执行不写入', async () => {
+  apply(ctx);
+  const attachment = Buffer.alloc(4096, 7);
+  writeFileSync(join(dirname(artifactPath(root, A, 'session-aaa')), 'attachment.bin'), attachment);
+  const bundlePath = join(root, 'space-bundle');
+  const exported = await call('mover.bundle.export', { sessionId: 'session-aaa', bundlePath });
+  assert.equal(exported.ok, true, JSON.stringify(exported));
+  const archiveBytes = readFileSync(artifactPath(root, A, 'session-aaa')).length;
+  rmSync(dirname(artifactPath(root, A, 'session-aaa')), { recursive: true, force: true });
+  const original = fs.statfsSync;
+  fs.statfsSync = () => ({ bfree: 1, bsize: 1 });
+  syncBuiltinESMExports();
+  try {
+    const plan = await call('mover.bundle.inspect', { bundlePath, targetWorkspaceId: 'wid-b' });
+    assert.equal(plan.ok, true, JSON.stringify(plan));
+    assert.equal(plan.value.requiredBytes, archiveBytes + attachment.length);
+    assert.equal(plan.value.status, 'blocked');
+    const imported = await call('mover.bundle.import', { bundlePath, targetWorkspaceId: 'wid-b', dryRun: false });
+    assert.equal(imported.ok, false);
+    assert.ok(!existsSync(artifactPath(root, B, 'session-aaa')));
+  } finally {
+    fs.statfsSync = original;
+    syncBuiltinESMExports();
+  }
+});