dsh-workspace-mover 2.2.0 → 2.3.0

package/lib/index.js

@@ -2,7 +2,7 @@
 //
 // ① 跨工作区「真迁移」原始会话：物理搬移 session.jsonl.zstd、改写头部 cwd、
 //    更新工作区注册表（侧边栏拖拽触发）。会话 id 与历史文件保持原样，
-//    不产生副本，不消耗 token。
+//    不复制第二条注册会话，不消耗 token；恢复快照独立存放在插件数据目录。
 // ② 孤儿会话救援（v0.3）：扫描存储根分类失联/未挂账/幽灵档案，
 //    relink 复用同一条迁移管线换路径重挂，attach 原地补记账。
 //    针对官方讨论 #3012（项目文件夹移动后历史"消失"）的社区修复。
@@ -32,10 +32,11 @@
 //   依赖官方「已记账 id 跳过校验」语义，先刷新 registry 三张索引并预置
 //   target.record.sessionIds 再 attach（版本敏感，失败自动回滚）。
 
-import { readFileSync, writeFileSync, renameSync, mkdirSync, existsSync, readdirSync, rmSync, statSync, cpSync, statfsSync } from 'node:fs';
+import { readFileSync, writeFileSync, renameSync, mkdirSync, existsSync, readdirSync, rmSync, statSync, cpSync, copyFileSync, statfsSync } from 'node:fs';
 import { realpathSync } from 'node:fs';
 import { zstdDecompressSync, zstdCompressSync, constants } from 'node:zlib';
-import { join, dirname, basename } from 'node:path';
+import { createHash } from 'node:crypto';
+import { join, dirname, basename, relative, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { spawn } from 'node:child_process';
 import { Config, POLICY_FIELDS, buildConfig, attachConfig } from './config.js';
@@ -50,6 +51,7 @@ const ZSTD_MAGIC = 4247762216;
 /** Current write generation: DSH 0.1.5 treats the highest canonical generation as source of truth. */
 const CURRENT_GENERATION = 3;
 const HISTORY_FILE = 'history.json';
+const migrationRuntimes = new WeakMap();
 
 //#region 可调策略
 /**
@@ -244,6 +246,143 @@ async function listPersistenceHeaders(persistence) {
 	if (!Array.isArray(snapshots)) return [];
 	return snapshots.map(persistenceHeader).filter((header) => header && typeof header === typeof {});
 }
+
+/**
+ * Describe the public persistence surface without assuming that the provider
+ * exposes its private filesystem layout. Physical moves still need the legacy
+ * JSONL path adapter; handle-only providers are kept read/diagnostic capable.
+ */
+function persistenceCapabilities(persistence) {
+	return {
+		list: typeof persistence?.list === 'function',
+		stat: typeof persistence?.stat === 'function',
+		open: typeof persistence?.open === 'function',
+		create: typeof persistence?.create === 'function',
+		flush: typeof persistence?.flush === 'function',
+		physicalPath: typeof persistence?.root === 'string' && persistence.root.length > 0,
+		formatStatus: typeof persistence?.formatStatus === 'function'
+	};
+}
+
+function createPersistenceAdapter(ctx) {
+	const persistence = ctx?.sessionPersistence;
+	const capabilities = persistenceCapabilities(persistence);
+	const mode = capabilities.physicalPath
+		? 'filesystem-fallback'
+		: (capabilities.list && capabilities.stat && capabilities.open ? 'official-handle' : 'unavailable');
+	const reason = mode === 'filesystem-fallback'
+		? 'public raw-byte path API is unavailable; physical JSONL path adapter is active'
+		: mode === 'official-handle'
+			? 'provider exposes public list/stat/open APIs but no public raw-byte path; physical moves are unavailable'
+			: 'provider does not expose enough public persistence APIs';
+	const unsupportedPhysical = () => {
+		const err = new Error('official persistence provider does not expose a raw-byte physical path operation');
+		err.code = 'unsupported';
+		throw err;
+	};
+	return {
+		mode,
+		reason,
+		capabilities,
+		root: capabilities.physicalPath ? persistence.root : null,
+		compression: persistenceCompression(persistence),
+		async list() {
+			if (!capabilities.list) return [];
+			return listPersistenceHeaders(persistence);
+		},
+		async locate(session) {
+			const sessionId = String(session?.sessionId ?? session?.id ?? '');
+			if (!sessionId) throw new Error('session id required');
+			if (mode === 'filesystem-fallback') {
+				const cwd = typeof session?.cwd === 'string' ? session.cwd : null;
+				if (!cwd) throw new Error(`session '${sessionId}' carries no cwd`);
+				const artifact = artifactPath(persistence.root, cwd, sessionId, this.compression);
+				return { kind: 'filesystem', sessionId, cwd, artifact };
+			}
+			if (capabilities.stat) {
+				const stat = await persistence.stat(sessionId);
+				return { kind: 'handle', sessionId, cwd: session?.cwd ?? null, stat };
+			}
+			throw new Error('persistence stat API unavailable');
+		},
+		async inspect(location) {
+			if (location?.kind === 'filesystem') {
+				if (!existsSync(location.artifact)) return { exists: false, sizeBytes: 0 };
+				const st = statSync(location.artifact);
+				const generations = listGenerationArtifacts(dirname(location.artifact)).map((entry) => ({
+					version: entry.version,
+					compression: entry.compression,
+					name: entry.name
+				}));
+				return { exists: st.isFile(), sizeBytes: st.isFile() ? st.size : 0, path: location.artifact, generations };
+			}
+			if (location?.kind === 'handle' && capabilities.stat) {
+				return { exists: true, stat: location.stat ?? await persistence.stat(location.sessionId) };
+			}
+			return { exists: false, sizeBytes: 0 };
+		},
+		async read(location) {
+			if (location?.kind === 'filesystem') return readFileSync(location.artifact);
+			unsupportedPhysical();
+		},
+		async write(location, bytes) {
+			if (location?.kind === 'filesystem') {
+				mkdirSync(dirname(location.artifact), { recursive: true });
+				atomicWrite(location.artifact, Buffer.from(bytes));
+				return;
+			}
+			unsupportedPhysical();
+		},
+		async replace(location, bytes) {
+			if (location?.kind === 'filesystem') {
+				atomicWrite(location.artifact, Buffer.from(bytes));
+				return;
+			}
+			unsupportedPhysical();
+		},
+		async relocate(location, destinationDir, { moveImpl = moveDir } = {}) {
+			if (location?.kind === 'filesystem') return moveImpl(dirname(location.artifact), destinationDir);
+			unsupportedPhysical();
+		},
+		async formatStatus(sessionId) {
+			if (typeof persistence.formatStatus === 'function') return persistence.formatStatus(sessionId);
+			if (capabilities.stat) {
+				try { return (await persistence.stat(sessionId))?.formatStatus ?? null; } catch { return null; }
+			}
+			return null;
+		}
+	};
+}
+
+function declaredHeaderGeneration(header) {
+	for (const key of ['generation', 'formatGeneration', 'formatVersion', 'sessionGeneration']) {
+		const value = header?.[key];
+		if (Number.isInteger(value) && value >= 0) return value;
+	}
+	return null;
+}
+
+function validateArtifactGeneration(filename, header) {
+	const file = parseGenerationLogFilename(basename(filename));
+	const declared = declaredHeaderGeneration(header);
+	if (file && declared !== null && file.version !== declared) {
+		const err = new Error(`session filename generation v${file.version} does not match header generation v${declared}: ${filename}`);
+		err.code = 'unsupported';
+		throw err;
+	}
+	return { filename: file, declaredGeneration: declared };
+}
+
+function storageDiagnostics(ctx) {
+	const adapter = createPersistenceAdapter(ctx);
+	return {
+		mode: adapter.mode,
+		reason: adapter.reason,
+		capabilities: adapter.capabilities,
+		physicalPath: adapter.capabilities.physicalPath,
+		format: adapter.compression
+	};
+}
 function findDestinationArtifact(dir, compression) {
 	try {
 		if (existsSync(dir) && !statSync(dir).isDirectory()) {
@@ -414,8 +553,8 @@ function moveDir(srcDir, dstDir, hooks = {}) {
  * 迁移后一致性校验：目标档案可回读、id 与 cwd 双确认。
  * 复制路径的静默截断、头改写遗漏都会在这里现形。
  */
-function verifyRelocatedArtifact(dstArtifact, sessionId, expectedCwd, compression = 'zstd') {
-	const header = readHeader(readFileSync(dstArtifact), compression);
+function verifyRelocatedBytes(bytes, sessionId, expectedCwd, compression = 'zstd') {
+	const header = readHeader(bytes, compression);
 	if (String(header?.id) !== String(sessionId)) {
 		throw new Error(`header id mismatch: expected '${sessionId}', got '${header?.id}'`);
 	}
@@ -424,6 +563,10 @@ function verifyRelocatedArtifact(dstArtifact, sessionId, expectedCwd, compressio
 	}
 	return true;
 }
+
+function verifyRelocatedArtifact(dstArtifact, sessionId, expectedCwd, compression = 'zstd') {
+	return verifyRelocatedBytes(readFileSync(dstArtifact), sessionId, expectedCwd, compression);
+}
 //#endregion
 
 //#region 备份管理（$DSH_HOME/workspace-mover/backups，保留最近 20 份）
@@ -433,46 +576,141 @@ function backupDir() {
 }
 
 /**
- * 备份文件名：`${id}.${epochMs}[-seq].zstd`。
- *
- * 为什么需要 `-seq`：毫秒时间戳不足以区分同一毫秒内的两次备份，而 Linux 的时钟/文件系统
- * 时间戳粒度比 Windows 粗得多，连续两次 stash 极可能落在同一毫秒。此时文件名相撞，
- * 第二次会**覆盖**第一次——用户配置的保留份数（backupKeep）于是静默失效，实际只留下
- * 一份。这不是假设：CI 的 ubuntu / macos 作业就是这样挂掉的。
- *
- * 命名规则：
- * - 无 `-seq`：`atomicWrite` 的 temp+rename 是覆盖语义，等于"同毫秒最后一次胜出"，
- *   同时把该毫秒的文件数限制为 1（保留原有测试断言的"同毫秒覆盖"行为，也避免浪费空间）。
- * - 带 `-seq`：该毫秒已被占用时递增，保证每次调用都留下独立的备份文件。
- * 两种形态的排序都保持近似的"旧→新"顺序（`-` = 0x2D < `.` = 0x2E，所以 `ts` 排在
- * `ts-seq` 之前，`ts-seq2` 又排在 `ts-seq10` 之前——同一毫秒内顺序仅影响裁剪，不影响正确性）。
+ * New snapshots include a content fingerprint. Legacy timestamp-only names
+ * remain readable so existing user backups are not orphaned by the upgrade.
  */
-function backupPath(id) {
+/** Parse both legacy `${id}.${ts}.zstd` and fingerprinted snapshot names. */
+function parseBackupFilename(name) {
+	const match = /^(.*)\.(\d+)(?:-([a-z0-9]+))?(?:\.([a-f0-9]{64}))?\.zstd$/i.exec(String(name));
+	if (!match) return null;
+	return { id: match[1], ts: Number(match[2]), sequence: match[3] ?? null, fingerprint: match[4]?.toLowerCase() ?? null };
+}
+
+/** Return a stable content digest, optionally ignoring the migration-only cwd header field. */
+function backupFingerprint(buf, { compression = 'zstd', ignoreCwd = false } = {}) {
+	let normalized = Buffer.from(buf);
+	if (ignoreCwd) {
+		try { normalized = rewriteHeaderCwd(normalized, '__workspace_mover_cwd__', compression); } catch { /* use raw bytes for malformed/unknown artifacts */ }
+	}
+	return createHash('sha256')
+		.update(`${compression}:${ignoreCwd ? 'content' : 'bytes'}\0`, 'utf8')
+		.update(normalized)
+		.digest('hex');
+}
+
+function backupFilesFor(id) {
+	const dir = backupDir();
+	if (!dirExists(dir)) return [];
+	const files = [];
+	for (const name of readdirSync(dir)) {
+		const parsed = parseBackupFilename(name);
+		if (!parsed || parsed.id !== String(id)) continue;
+		try {
+			const stat = statSync(join(dir, name));
+			if (!stat.isFile()) continue;
+			files.push({ ...parsed, name, sizeBytes: stat.size });
+		} catch { /* a concurrently removed snapshot is ignored */ }
+	}
+	return files;
+}
+
+function findExistingBackup(id, fingerprint, options = {}) {
+	const { compression = 'zstd', ignoreCwd = false } = options;
+	for (const file of backupFilesFor(id)) {
+		try {
+			const bytes = readFileSync(join(backupDir(), file.name));
+			if (backupFingerprint(bytes, { compression, ignoreCwd }) === fingerprint) return file;
+		} catch { /* unreadable legacy backups remain visible for manual cleanup */ }
+	}
+	return null;
+}
+
+function backupPath(id, fingerprint) {
 	const dir = backupDir();
 	const ts = Date.now();
-	const base = join(dir, `${id}.${ts}.zstd`);
+	const suffix = `${fingerprint}.zstd`;
+	const base = join(dir, `${id}.${ts}.${suffix}`);
 	if (!existsSync(base)) return base;
 	for (let seq = 2; seq < 1000; seq++) {
-		const candidate = join(dir, `${id}.${ts}-${seq}.zstd`);
+		const candidate = join(dir, `${id}.${ts}-${seq}.${suffix}`);
 		if (!existsSync(candidate)) return candidate;
 	}
-	// 极端情况：同一毫秒 1000 次备份。退化为加序号强制唯一，绝不覆盖既有备份。
-	return join(dir, `${id}.${ts}-${Math.random().toString(36).slice(2, 8)}.zstd`);
+	return join(dir, `${id}.${ts}-${Math.random().toString(36).slice(2, 8)}.${suffix}`);
+}
+
+function pruneBackups(id, protectedName = null) {
+	const dir = backupDir();
+	const keep = backupFilesFor(id).sort((a, b) => a.ts - b.ts || a.name.localeCompare(b.name));
+	while (keep.length > backupKeep()) {
+		let index = 0;
+		if (keep[index]?.name === protectedName) index = keep.findIndex((item) => item.name !== protectedName);
+		if (index < 0) break;
+		const [removed] = keep.splice(index, 1);
+		rmSync(join(dir, removed.name), { force: true });
+	}
 }
 
-function stashBackup(id, buf) {
+/**
+ * Save one recoverable snapshot. Migration calls this with ignoreCwd=true so
+ * moving the same session back and forth does not create another physical copy.
+ */
+function stashBackup(id, buf, options = {}) {
+	const bytes = Buffer.from(buf);
+	const compression = options.compression ?? 'zstd';
+	const ignoreCwd = Boolean(options.ignoreCwd);
 	try {
 		const dir = backupDir();
 		mkdirSync(dir, { recursive: true });
-		atomicWrite(backupPath(id), buf);
-		// 前缀收紧到 `${id}.`：相邻 id（如 session-x 与 session-x-1）的备份互不误删
-		const keep = readdirSync(dir).filter((f) => f.startsWith(`${id}.`)).sort();
-		while (keep.length > backupKeep()) rmSync(join(dir, keep.shift()), { force: true });
+		const fingerprint = backupFingerprint(bytes, { compression, ignoreCwd });
+		const existing = findExistingBackup(id, fingerprint, { compression, ignoreCwd });
+		if (existing) {
+			pruneBackups(id, existing.name);
+			return {
+				created: false,
+				reused: true,
+				fileName: existing.name,
+				fingerprint,
+				sizeBytes: existing.sizeBytes,
+				addedBytes: 0,
+				sourceBytes: bytes.length
+			};
+		}
+		const fileName = basename(backupPath(id, fingerprint));
+		atomicWrite(join(dir, fileName), bytes);
+		// Prefix filtering keeps neighbouring ids such as session-x / session-x-1 isolated.
+		pruneBackups(id, fileName);
+		return {
+			created: true,
+			reused: false,
+			fileName,
+			fingerprint,
+			sizeBytes: bytes.length,
+			addedBytes: bytes.length,
+			sourceBytes: bytes.length
+		};
 	} catch (err) {
 		throw new Error(`backup failed (refusing to move without a stash): ${err?.message ?? err}`);
 	}
 }
 
+async function inspectBackupPlan(id, location, sourceInfo, compression = 'zstd') {
+	if (!sourceInfo?.exists) return { reused: false, estimatedBytes: sourceInfo?.sizeBytes ?? 0, unavailable: true };
+	try {
+		const bytes = readFileSync(location.artifact);
+		const fingerprint = backupFingerprint(bytes, { compression, ignoreCwd: true });
+		const existing = findExistingBackup(id, fingerprint, { compression, ignoreCwd: true });
+		return {
+			reused: Boolean(existing),
+			estimatedBytes: existing ? 0 : bytes.length,
+			fileName: existing?.name ?? null,
+			fingerprint,
+			sourceBytes: bytes.length
+		};
+	} catch {
+		return { reused: false, estimatedBytes: sourceInfo.sizeBytes ?? 0, unavailable: true };
+	}
+}
+
 function historyPath() {
 
 	const home = process.env.DSH_HOME ?? join(homedir(), '.dsh');
@@ -503,7 +741,8 @@ function rememberMove(result, sourceWorkspaceId, targetWorkspaceId) {
 		targetWorkspaceId,
 		from: result.from.cwd,
 		to: result.to.cwd,
-		movedAt: new Date().toISOString()
+		movedAt: new Date().toISOString(),
+		backup: result.backup ?? null
 	};
 	const history = readHistory();
 	history.push(entry);
@@ -523,7 +762,8 @@ function rememberBatchMove(movedItems, targetWorkspaceId, targetPath) {
 			sessionId: String(item.sessionId),
 			title: item.title,
 			from: item.fromCwd,
-			sourceWorkspaceId: item.sourceWorkspaceId ?? null
+			sourceWorkspaceId: item.sourceWorkspaceId ?? null,
+			backup: item.backup ?? null
 		}))
 	};
 	const history = readHistory();
@@ -669,6 +909,12 @@ async function moveSession(ctx, { sessionId, targetWorkspaceId, sessionTitle, re
 	const registry = ctx.workspaceRegistry;
 	const persistence = ctx.sessionPersistence;
 	if (!registry || !persistence) throw new Error('workspace registry or session persistence service unavailable');
+	const storage = createPersistenceAdapter(ctx);
+	if (!storage.capabilities.physicalPath) {
+		const err = new Error(`${storage.reason}; physical session migration is unavailable`);
+		err.code = 'unsupported';
+		throw err;
+	}
 
 	// ---- 目标实体 ----
 	const target = registry.get(targetWorkspaceId);
@@ -721,21 +967,27 @@ async function moveSession(ctx, { sessionId, targetWorkspaceId, sessionTitle, re
 	}
 
 	// ---- 文件路径 ----
-	const root = persistence.root;
+	const root = storage.root;
 	if (typeof root !== 'string' || root.length === 0) throw new Error('session persistence backend exposes no root');
-	const compression = persistenceCompression(persistence);
-	const srcDir = sessionDir(root, sourceCwd, sessionId);
+	const compression = storage.compression;
+	const sourceLocation = await storage.locate({ sessionId, cwd: sourceCwd });
+	const sourceInfo = await storage.inspect(sourceLocation);
+	if (!sourceInfo.exists) throw new Error(`session artifact missing under: ${dirname(sourceLocation.artifact)}`);
+	const srcDir = dirname(sourceLocation.artifact);
 	const dstDir = sessionDir(root, targetPath, sessionId);
-	const srcFound = findHighestArtifact(srcDir, compression);
-	if (!srcFound) throw new Error(`session artifact missing under: ${srcDir}`);
-	const srcArtifact = srcFound.path;
-	if (findDestinationArtifact(dstDir, compression)) throw new Error(`destination artifact already exists under: ${dstDir}`);
-	const dstArtifact = join(dstDir, srcFound.name);
+	const destinationCheck = await storage.locate({ sessionId, cwd: targetPath });
+	const destinationInfo = await storage.inspect(destinationCheck);
+	if (destinationInfo.exists) throw new Error(`destination artifact already exists under: ${dstDir}`);
+	const srcArtifact = sourceLocation.artifact;
+	const dstArtifact = join(dstDir, basename(srcArtifact));
+	const destinationLocation = { ...destinationCheck, cwd: targetPath, artifact: dstArtifact };
 
 	// ---- 备份先行：备份失败 = 零副作用（尚未触碰记账/索引/目标路径）----
-	const original = readFileSync(srcArtifact);
+	const original = await storage.read(sourceLocation);
+	validateArtifactGeneration(srcArtifact, readHeader(original, compression));
+	let backup = null;
 	try {
-		stashImpl(String(sessionId), original);
+		backup = stashImpl(String(sessionId), original, { compression, ignoreCwd: true }) ?? null;
 	} catch (err) {
 		const e = new Error(`backup failed, nothing was changed: ${err?.message ?? err}`);
 		e.code = 'backup-failed';
@@ -766,7 +1018,7 @@ async function moveSession(ctx, { sessionId, targetWorkspaceId, sessionTitle, re
 		// 提示性检查（Windows 下与实际写入存在竞态）：不通过则尽早失败（此时零改动），
 		// 通过也不构成保证——真正的兜底是复制失败清理 + 迁移后回读校验。
 		const st = statfsSync(dirname(dstArtifact));
-		const needed = Math.max(Number(st.bsize) || 4096, statSync(srcArtifact).size * 2);
+		const needed = Math.max(Number(st.bsize) || 4096, Number(sourceInfo.sizeBytes) * 2);
 		if (typeof st.bfree === 'number' && st.bfree * Number(st.bsize || 4096) < needed) {
 			const e = new Error(`insufficient disk space at target (need ~${needed} bytes, free ~${st.bfree * Number(st.bsize || 4096)})`);
 			e.code = 'insufficient-space';
@@ -784,19 +1036,19 @@ async function moveSession(ctx, { sessionId, targetWorkspaceId, sessionTitle, re
 	const rewritten = rewriteHeaderCwd(original, targetPath, compression);
 
 	try {
-		atomicWrite(srcArtifact, rewritten);
+		await storage.replace(sourceLocation, rewritten);
 	} catch (err) {
 		for (const e of allOwners) { try { if (!rawRecordSessionIds(e).includes(String(sessionId))) await e.attachSession?.(sessionId); } catch { /* ignore */ } }
 		throw new Error(`move failed while rewriting header: ${err?.message ?? err}`);
 	}
 
 	try {
-		const how = moveDir(dirname(srcArtifact), dirname(dstArtifact));
+		const how = await storage.relocate(sourceLocation, dirname(dstArtifact));
+		const targetLocation = { ...sourceLocation, cwd: targetPath, artifact: dstArtifact };
 		// 迁移后一致性校验：目标档案可回读、id/cwd 双确认。失败视同搬运失败，整体回退。
 		try {
-			verifyRelocatedArtifact(dstArtifact, sessionId, targetPath, compression);
+			verifyRelocatedBytes(await storage.read(targetLocation), sessionId, targetPath, compression);
 		} catch (verifyErr) {
-			try { moveDir(dirname(dstArtifact), dirname(srcArtifact)); } catch { /* 尽力移回 */ }
 			throw new Error(`post-move verification failed: ${verifyErr?.message ?? verifyErr}`);
 		}
 		if (how !== 'rename') ctx.logger?.info?.('workspace-mover: directory rename fell back to copy+delete');
@@ -806,9 +1058,28 @@ async function moveSession(ctx, { sessionId, targetWorkspaceId, sessionTitle, re
 			if (existsSync(srcProject) && readdirSync(srcProject).length === 0) rmSync(srcProject, { recursive: true });
 		} catch { /* ignore */ }
 	} catch (err) {
-		// 搬运失败：把改写后的文件退回原文，再抛出
-		atomicWrite(srcArtifact, original);
-		throw new Error(`move failed at relocate step: ${err?.message ?? err}`);
+		let rollbackError = null;
+		try {
+			if (!(await storage.inspect(sourceLocation)).exists) {
+				await storage.relocate({ ...sourceLocation, cwd: targetPath, artifact: dstArtifact }, dirname(srcArtifact));
+			}
+			await storage.replace(sourceLocation, original);
+		} catch (cause) {
+			rollbackError = cause;
+			try { await storage.write(sourceLocation, original); } catch (writeErr) { rollbackError = writeErr; }
+			recordRecovery(ctx, {
+				kind: 'move', phase: 'physical-rollback', sessionId: String(sessionId),
+				source: sourceCwd, target: targetPath, backup: backup?.fileName ? join(backupDir(), backup.fileName) : backupDir(),
+				lastError: `relocate failed (${err?.message ?? err}) AND rollback failed (${cause?.message ?? cause})`
+			});
+		}
+		for (const owner of allOwners) {
+			try { if (!rawRecordSessionIds(owner).includes(String(sessionId))) await owner.attachSession?.(sessionId); } catch { /* recovery record/backup remains */ }
+		}
+		if (rollbackError) {
+			throw new Error(`move failed at relocate step (${err?.message ?? err}) AND rollback failed (${rollbackError?.message ?? rollbackError}); original bytes are preserved in the recovery backup`);
+		}
+		throw new Error(`move failed at relocate step, rolled back cleanly: ${err?.message ?? err}`);
 	}
 
 	// ---- 内存一致性收尾（版本敏感，降级安全）----
@@ -861,9 +1132,14 @@ async function moveSession(ctx, { sessionId, targetWorkspaceId, sessionTitle, re
 				if (priorHeader === undefined) registry.headers?.delete?.(sessionId);
 				else registry.headers?.set?.(sessionId, priorHeader);
 			}
-			rmSync(dirname(dstArtifact), { recursive: true, force: true });
-			mkdirSync(dirname(srcArtifact), { recursive: true });
-			writeFileSync(srcArtifact, original);
+			const targetLocation = { ...sourceLocation, cwd: targetPath, artifact: dstArtifact };
+			try {
+				await storage.relocate(targetLocation, dirname(srcArtifact));
+			} catch (relocateErr) {
+				await storage.write(sourceLocation, original);
+				throw new Error(`physical rollback could not move the target directory: ${relocateErr?.message ?? relocateErr}`);
+			}
+			await storage.replace(sourceLocation, original);
 			// 索引无需再清：非常驻路径在收尾时已清空、由源 attach 重新记账；
 			// 常驻路径上一段已按移动前快照还原。
 			for (const e of allOwners) {
@@ -872,7 +1148,7 @@ async function moveSession(ctx, { sessionId, targetWorkspaceId, sessionTitle, re
 		} catch (rollbackErr) {
 			recordRecovery(ctx, {
 				kind: 'move', phase: 'attach-rollback', sessionId: String(sessionId),
-				source: sourceCwd, target: targetPath, backup: backupDir(),
+				source: sourceCwd, target: targetPath, backup: backup?.fileName ? join(backupDir(), backup.fileName) : backupDir(),
 				lastError: `attach failed (${err?.message ?? err}) AND rollback failed (${rollbackErr?.message ?? rollbackErr})`
 			});
 			throw new Error(`move failed during attach (${err?.message ?? err}) AND rollback failed (${rollbackErr?.message ?? rollbackErr}). Original bytes stashed under ${backupDir()}`);
@@ -902,7 +1178,8 @@ async function moveSession(ctx, { sessionId, targetWorkspaceId, sessionTitle, re
 		to: { cwd: targetPath, workspaceId: targetWorkspaceId },
 		cacheInvalidated,
 		restartHint,
-		warnings
+		warnings,
+		backup
 	};
 	if (recordHistory) {
 		try {
@@ -945,6 +1222,31 @@ function dirExists(p) {
 	}
 }
 
+function findUnlistedFilesystemArtifact(root, compression) {
+	if (!dirExists(root)) return null;
+	for (const project of readdirSync(root)) {
+		if (!(project.startsWith('--') && project.endsWith('--'))) continue;
+		const projectPath = join(root, project);
+		if (!dirExists(projectPath)) continue;
+		for (const idDir of readdirSync(projectPath)) {
+			const sessionPath = join(projectPath, idDir);
+			if (!dirExists(sessionPath)) continue;
+			const names = readdirSync(sessionPath);
+			const artifacts = listGenerationArtifacts(sessionPath);
+			if (artifacts.length === 0) {
+				if (names.length > 0) return { unknownPath: sessionPath };
+				continue;
+			}
+			try {
+				return { found: findHighestArtifact(sessionPath, compression), sessionId: idDir };
+			} catch (error) {
+				return { error };
+			}
+		}
+	}
+	return null;
+}
+
 /**
  * 存储布局自证（只读，永不抛错）。
  *
@@ -962,38 +1264,118 @@ function dirExists(p) {
 async function verifyStorageLayout(ctx) {
 	const persistence = ctx?.sessionPersistence;
 	if (!persistence) return { status: 'unavailable', checked: 0, reason: 'session persistence service unavailable' };
-	const root = persistence.root;
-	if (typeof root !== 'string' || root.length === 0) {
-		return { status: 'degraded', checked: 0, reason: 'persistence backend exposes no root' };
+	const adapter = createPersistenceAdapter(ctx);
+	const root = adapter.root;
+	if (!adapter.capabilities.physicalPath) {
+		if (adapter.mode === 'official-handle') {
+			let checked = 0;
+			try { checked = (await adapter.list()).length; } catch { /* diagnostics below */ }
+			return {
+				status: 'ok',
+				adapter: adapter.mode,
+				physicalPath: false,
+				checked,
+				reason: adapter.reason
+			};
+		}
+		return { status: 'unavailable', checked: 0, adapter: adapter.mode, physicalPath: false, reason: adapter.reason };
 	}
 	let headers;
 	try {
-		headers = await listPersistenceHeaders(persistence);
+		headers = await adapter.list();
 	} catch (err) {
 		return { status: 'unavailable', checked: 0, reason: `persistence.list() failed: ${err?.message ?? err}` };
 	}
-	if (headers.length === 0) return { status: 'empty', checked: 0, path: root };
-	const compression = persistenceCompression(persistence);
+	const compression = adapter.compression;
+	if (headers.length === 0) {
+		let unlisted = null;
+		try { unlisted = findUnlistedFilesystemArtifact(root, compression); }
+		catch (err) {
+			return { status: 'degraded', diagnostic: 'layout-unknown', checked: 0, path: root, adapter: adapter.mode, physicalPath: true, reason: `cannot inspect session root: ${err?.message ?? err}` };
+		}
+		if (unlisted?.error) {
+			const diagnostic = unlisted.error?.code === 'unsupported' ? 'unsupported' : 'layout-unknown';
+			return { status: 'degraded', diagnostic, checked: 0, path: root, adapter: adapter.mode, physicalPath: true, reason: `${diagnostic}: ${unlisted.error?.message ?? unlisted.error}` };
+		}
+		if (unlisted?.unknownPath) {
+			return { status: 'degraded', diagnostic: 'layout-unknown', checked: 0, path: root, adapter: adapter.mode, physicalPath: true, reason: `no supported archive filename under: ${unlisted.unknownPath}` };
+		}
+		if (unlisted?.found) {
+			try {
+				const bytes = await adapter.read({ kind: 'filesystem', sessionId: unlisted.sessionId, cwd: null, artifact: unlisted.found.path });
+				const header = readHeader(bytes, compression);
+				validateArtifactGeneration(unlisted.found.path, header);
+				return {
+					status: 'degraded', diagnostic: 'layout-unknown', checked: 0, path: root, adapter: adapter.mode,
+					physicalPath: true,
+					reason: `archive exists under ${unlisted.found.path} but persistence.list() did not return it`
+				};
+			} catch (err) {
+				const diagnostic = err?.code === 'unsupported' ? 'unsupported' : 'corrupt-data';
+				return { status: 'degraded', diagnostic, checked: 0, path: root, adapter: adapter.mode, physicalPath: true, reason: `${diagnostic}: ${err?.message ?? err}` };
+			}
+		}
+		return { status: 'empty', checked: 0, path: root, adapter: adapter.mode, physicalPath: true };
+	}
 	// 取最新几条做样本：编码边界（多字节/分隔符/驱动器号）更容易在其中一条上暴露
 	const sample = headers.slice(0, 5);
 	for (const header of sample) {
 		const { id, cwd } = header;
 		if (id === undefined || typeof cwd !== 'string' || cwd.length === 0) continue;
 		const expectedDir = sessionDir(root, cwd, id);
+		let artifacts;
 		try {
-			if (findHighestArtifact(expectedDir, compression)) {
-				return { status: 'ok', checked: sample.length, path: root };
+			artifacts = listGenerationArtifacts(expectedDir);
+		} catch (err) {
+			return { status: 'degraded', diagnostic: 'layout-unknown', checked: sample.length, path: root, adapter: adapter.mode, physicalPath: true, reason: `cannot inspect derived directory: ${err?.message ?? err}` };
+		}
+		if (artifacts.length === 0) {
+			if (dirExists(expectedDir) && readdirSync(expectedDir).length > 0) {
+				return {
+					status: 'degraded', diagnostic: 'layout-unknown', checked: sample.length, path: root,
+					adapter: adapter.mode, physicalPath: true,
+					reason: `session directory contains no supported archive filename: ${expectedDir}`
+				};
 			}
+			continue;
+		}
+		try {
+			const found = findHighestArtifact(expectedDir, compression);
+			const location = { kind: 'filesystem', sessionId: String(id), cwd, artifact: found.path };
+			const archiveHeader = readHeader(await adapter.read(location), compression);
+			validateArtifactGeneration(found.path, archiveHeader);
+			if (String(archiveHeader?.id) !== String(id)) throw new Error(`archive id ${archiveHeader?.id} does not match persistence.list() id ${id}`);
+			if (typeof archiveHeader?.cwd !== 'string' || !samePath(archiveHeader.cwd, cwd)) {
+				return {
+					status: 'degraded', diagnostic: 'layout-unknown', checked: sample.length, path: root,
+					adapter: adapter.mode, physicalPath: true,
+					reason: `archive header cwd does not match persistence.list() for session ${id}`
+				};
+			}
+			const generations = artifacts.map((entry) => ({ version: entry.version, compression: entry.compression, name: entry.name }));
+			return {
+				status: 'ok', checked: sample.length, path: root, adapter: adapter.mode, physicalPath: true,
+				generations,
+				generationWarning: generations.length > 1
+					? `multiple generations present; v${generations[0].version} is selected and older files are preserved`
+					: null
+			};
 		} catch (err) {
-			// 混合压缩编码等显式拒绝：布局本身可能是对的，但当前配置读不了它
-			return { status: 'degraded', checked: sample.length, path: root, reason: `cannot read derived directory: ${err?.message ?? err}` };
+			const diagnostic = err?.code === 'unsupported' ? 'unsupported' : 'corrupt-data';
+			return {
+				status: 'degraded', diagnostic, checked: sample.length, path: root, adapter: adapter.mode,
+				physicalPath: true, reason: `${diagnostic}: ${err?.message ?? err}`
+			};
 		}
 	}
 	return {
 		status: 'degraded',
+		diagnostic: 'layout-unknown',
 		checked: sample.length,
 		path: root,
-		reason: 'no session archive found at the layout this plugin derives — the host storage layout may have changed'
+		adapter: adapter.mode,
+		physicalPath: true,
+		reason: 'layout-unknown: no session archive found at the derived path — the host storage layout may have changed'
 	};
 }
 
@@ -1031,9 +1413,15 @@ async function scanSessions(ctx) {
 	const registry = ctx.workspaceRegistry;
 	const persistence = ctx.sessionPersistence;
 	if (!registry || !persistence) throw new Error('workspace registry or session persistence service unavailable');
-	const root = persistence.root;
+	const storage = createPersistenceAdapter(ctx);
+	if (!storage.capabilities.physicalPath) {
+		const err = new Error(`${storage.reason}; physical session scanning is unavailable`);
+		err.code = 'unsupported';
+		throw err;
+	}
+	const root = storage.root;
 	if (typeof root !== 'string' || root.length === 0) throw new Error('session persistence backend exposes no root');
-	const compression = persistenceCompression(persistence);
+	const compression = storage.compression;
 
 	const entities = registry.list();
 	let archived = new Set();
@@ -1051,22 +1439,46 @@ async function scanSessions(ctx) {
 		const projPath = join(root, proj);
 		if (!dirExists(projPath)) continue;
 		for (const idDir of readdirSync(projPath)) {
-			const found = findHighestArtifact(join(projPath, idDir), compression);
+			const sessionPath = join(projPath, idDir);
+			let found;
+			let layoutError = null;
+			try {
+				found = findHighestArtifact(sessionPath, compression);
+			} catch (err) {
+				const artifacts = listGenerationArtifacts(sessionPath);
+				if (artifacts.length === 0) continue;
+				found = artifacts[0];
+				layoutError = err;
+			}
 			if (!found) continue;
 			const artifact = found.path;
 			let st;
 			try { st = statSync(artifact); } catch { continue; }
 			if (!st.isFile()) continue;
 			total++;
-			metas.push({ artifact, idDir, st });
+			metas.push({ artifact, idDir, st, layoutError });
 		}
 	}
 	metas.sort((a, b) => b.st.mtimeMs - a.st.mtimeMs);
 	const selected = metas.slice(0, scanLimit());
-	for (const { artifact, idDir, st } of selected) {
+	for (const { artifact, idDir, st, layoutError } of selected) {
 		seenArtifacts.add(artifact);
 		let header = null;
-		try { header = readHeader(readFileSync(artifact), compression); } catch { header = null; }
+		let diagnostic = null;
+		let diagnosticDetail = null;
+		if (layoutError) {
+			diagnostic = layoutError.code === 'unsupported' ? 'unsupported' : 'layout-unknown';
+			diagnosticDetail = String(layoutError?.message ?? layoutError);
+		} else {
+			try {
+				header = readHeader(await storage.read({ kind: 'filesystem', sessionId: idDir, cwd: null, artifact }), compression);
+				validateArtifactGeneration(artifact, header);
+			} catch (err) {
+				header = null;
+				diagnostic = err?.code === 'unsupported' ? 'unsupported' : 'corrupt-data';
+				diagnosticDetail = String(err?.message ?? err);
+			}
+		}
 		const sessionId = String(header?.id ?? idDir);
 		const cwd = typeof header?.cwd === 'string' ? header.cwd : null;
 		const alive = dirExists(cwd);
@@ -1096,6 +1508,8 @@ async function scanSessions(ctx) {
 			ownerWorkspaceIds: owners.map((e) => e.id),
 			sizeBytes: st.size,
 			mtimeMs: st.mtimeMs,
+			diagnostic,
+			diagnosticDetail,
 			archived: archived.has(sessionId)
 		});
 	}
@@ -1129,7 +1543,10 @@ async function scanSessions(ctx) {
 /** 仅拒绝回合进行中的会话（与宿主 UI「进行中」徽标同款判据）。 */
 function assertNotRunning(ctx, sessionId) {
 	if (peekService(ctx, 'agents')?.get?.(sessionId)?.status === 'running') {
-		throw new Error('session is currently running; wait for its turn to finish before moving');
+		const err = new Error('session is currently running; queued migration will retry after it becomes idle');
+		err.code = 'busy';
+		err.reason = 'session-running';
+		throw err;
 	}
 }
 
@@ -1206,11 +1623,448 @@ async function attachUnregistered(ctx, sessionId) {	const registry = ctx.workspa
 	return { workspaceId: entity.id, path: entity.path };
 }
 
+function parentSessionId(header) {
+	for (const key of ['parentSessionId', 'parentId', 'parentSession', 'forkOf']) {
+		const value = header?.[key];
+		if (typeof value === 'string' && value.length > 0) return value;
+	}
+	return null;
+}
+
+async function collectDescendantSessions(ctx, rootSessionId, adapter = createPersistenceAdapter(ctx)) {
+	const headers = await adapter.list();
+	const children = new Map();
+	for (const header of headers) {
+		const childId = String(header?.id ?? '');
+		const parentId = parentSessionId(header);
+		if (!childId || !parentId) continue;
+		const list = children.get(parentId) ?? [];
+		list.push({ sessionId: childId, title: header?.title ?? null, parentSessionId: parentId });
+		children.set(parentId, list);
+	}
+	const ids = [String(rootSessionId)];
+	const relations = [];
+	const seen = new Set(ids);
+	for (let cursor = 0; cursor < ids.length; cursor++) {
+		for (const child of children.get(ids[cursor]) ?? []) {
+			if (seen.has(child.sessionId)) continue;
+			seen.add(child.sessionId);
+			ids.push(child.sessionId);
+			relations.push(child);
+		}
+	}
+	return { ids, relations };
+}
+
+const PORTABLE_BUNDLE_VERSION = 1;
+const PLUGIN_VERSION = '2.2.0';
+
+function bundleSafeJoin(root, ...parts) {
+	const base = resolve(root);
+	const target = resolve(base, ...parts);
+	const rel = relative(base, target);
+	if (rel === '..' || rel.startsWith('..\\') || rel.startsWith('../') || resolve(base, rel) !== target) {
+		const err = new Error(`bundle path escapes its root: ${parts.join('/')}`);
+		err.code = 'invalid-input';
+		throw err;
+	}
+	return target;
+}
+
+function bundleRelative(path) {
+	return String(path).replaceAll('\\', '/');
+}
+
+function sha256Bytes(bytes) {
+	return createHash('sha256').update(bytes).digest('hex');
+}
+
+function walkFiles(root, prefix = '') {
+	const out = [];
+	for (const name of readdirSync(root)) {
+		const path = join(root, name);
+		const rel = prefix ? join(prefix, name) : name;
+		let st;
+		try { st = statSync(path); } catch { continue; }
+		if (st.isDirectory()) out.push(...walkFiles(path, rel));
+		else if (st.isFile()) out.push({ path, relativePath: bundleRelative(rel), sizeBytes: st.size });
+	}
+	return out;
+}
+
+function bundleManifestPath(bundlePath) {
+	if (typeof bundlePath !== 'string' || bundlePath.trim().length === 0) throw new Error('bundlePath required');
+	return resolve(bundlePath);
+}
+
+function loadPortableBundle(bundlePath) {
+	const root = bundleManifestPath(bundlePath);
+	const manifestPath = bundleSafeJoin(root, 'manifest.json');
+	if (!existsSync(manifestPath)) throw new Error(`bundle manifest missing: ${manifestPath}`);
+	let manifest;
+	try { manifest = JSON.parse(readFileSync(manifestPath, 'utf8')); } catch (err) { throw new Error(`bundle manifest is invalid: ${err?.message ?? err}`); }
+	if (manifest?.version !== PORTABLE_BUNDLE_VERSION || !Array.isArray(manifest.sessions)) {
+		const err = new Error(`unsupported portable bundle manifest version: ${manifest?.version ?? 'unknown'}`);
+		err.code = 'unsupported';
+		throw err;
+	}
+	let checksums = {};
+	try {
+		const checksumPath = bundleSafeJoin(root, 'checksums.json');
+		if (existsSync(checksumPath)) checksums = JSON.parse(readFileSync(checksumPath, 'utf8'));
+	} catch (err) {
+		throw new Error(`bundle checksums are invalid: ${err?.message ?? err}`);
+	}
+	const files = [];
+	const missing = [];
+	const checksumMismatches = [];
+	for (const session of manifest.sessions) {
+		if (typeof session?.sessionId !== 'string' || !Array.isArray(session.files)) continue;
+		for (const item of session.files) {
+			if (typeof item?.bundlePath !== 'string') continue;
+			const path = bundleSafeJoin(root, item.bundlePath);
+			if (!existsSync(path)) {
+				missing.push(item.bundlePath);
+				continue;
+			}
+			const bytes = readFileSync(path);
+			const expected = checksums[item.bundlePath] ?? item.sha256 ?? null;
+			if (expected && expected !== sha256Bytes(bytes)) checksumMismatches.push(item.bundlePath);
+			files.push({ ...item, sessionId: session.sessionId, path, bytes });
+		}
+	}
+	return { root, manifest, checksums, files, missing, checksumMismatches };
+}
+
+function workspaceForSession(registry, sessionId, cwd = null) {
+	try {
+		return registry?.list?.().find((entity) => rawRecordSessionIds(entity).includes(String(sessionId)))
+			?? registry?.list?.().find((entity) => cwd && samePath(entity.path, cwd))
+			?? null;
+	} catch { return null; }
+}
+
+async function exportPortableBundle(ctx, { sessionId, bundlePath, mode = 'current-only' } = {}) {
+	const rootSessionId = validId(sessionId, 'sessionId');
+	if (!['current-only', 'include-descendants'].includes(mode)) throw new Error(`unknown fork migration mode '${mode}'`);
+	const registry = ctx.workspaceRegistry;
+	const storage = createPersistenceAdapter(ctx);
+	if (!storage.capabilities.physicalPath) {
+		const err = new Error(`${storage.reason}; portable export needs a physical session path`);
+		err.code = 'unsupported';
+		throw err;
+	}
+	const destination = bundleManifestPath(bundlePath);
+	if (existsSync(destination) && readdirSync(destination).length > 0) throw new Error(`bundle destination is not empty: ${destination}`);
+	const headers = await storage.list();
+	const tree = mode === 'include-descendants' ? await collectDescendantSessions(ctx, rootSessionId, storage) : { ids: [rootSessionId], relations: [] };
+	const sessions = [];
+	const checksums = {};
+	const attachmentRelations = [];
+	const manifest = {
+		version: PORTABLE_BUNDLE_VERSION,
+		pluginVersion: PLUGIN_VERSION,
+		dshVersion: ctx.dshVersion ?? ctx.version ?? null,
+		exportedAt: new Date().toISOString(),
+		rootSessionId,
+		mode,
+		sessions: [],
+		attachments: attachmentRelations
+	};
+	try {
+		mkdirSync(destination, { recursive: true });
+		for (const id of tree.ids) {
+			const meta = headers.find((header) => String(header?.id) === id);
+			if (!meta) throw new Error(`session '${id}' not found in session persistence`);
+			const location = await storage.locate({ sessionId: id, cwd: meta.cwd });
+			const info = await storage.inspect(location);
+			if (!info.exists) throw new Error(`session archive missing for '${id}'`);
+			const bytes = await storage.read(location);
+			const parsed = validateArtifactGeneration(location.artifact, readHeader(bytes, storage.compression));
+			const sessionRoot = bundleSafeJoin(destination, 'sessions', encodeSegment(id));
+			mkdirSync(sessionRoot, { recursive: true });
+			const artifactName = basename(location.artifact);
+			const artifactRel = bundleRelative(join('sessions', encodeSegment(id), artifactName));
+			const artifactPathInBundle = bundleSafeJoin(destination, artifactRel);
+			writeFileSync(artifactPathInBundle, bytes);
+			checksums[artifactRel] = sha256Bytes(bytes);
+			const sourceWorkspace = workspaceForSession(registry, id, meta.cwd);
+			const sessionRecord = {
+				sessionId: id,
+				title: meta.title ?? null,
+				parentSessionId: parentSessionId(meta),
+				originalWorkspace: sourceWorkspace ? { id: sourceWorkspace.id, title: sourceWorkspace.title, path: sourceWorkspace.path } : null,
+				format: { generation: parsed.filename?.version ?? 0, compression: parsed.filename?.compression ?? storage.compression, artifactName },
+				files: [{ bundlePath: artifactRel, kind: 'session', originalPath: location.artifact, bytes: bytes.length, sha256: checksums[artifactRel] }],
+				attachments: []
+			};
+			for (const extra of walkFiles(dirname(location.artifact))) {
+				if (extra.path === location.artifact || parseGenerationLogFilename(basename(extra.path))) continue;
+				const rel = bundleRelative(join('attachments', encodeSegment(id), extra.relativePath));
+				const target = bundleSafeJoin(destination, rel);
+				mkdirSync(dirname(target), { recursive: true });
+				copyFileSync(extra.path, target);
+				checksums[rel] = sha256Bytes(readFileSync(target));
+				const attachment = { sessionId: id, bundlePath: rel, relativePath: extra.relativePath, bytes: extra.sizeBytes, sha256: checksums[rel] };
+				sessionRecord.files.push({ ...attachment, kind: 'attachment', originalPath: extra.path });
+				sessionRecord.attachments.push(attachment);
+				attachmentRelations.push(attachment);
+			}
+			manifest.sessions.push(sessionRecord);
+		}
+		writeFileSync(bundleSafeJoin(destination, 'workspace-metadata.json'), JSON.stringify({ sessions: manifest.sessions.map((item) => item.originalWorkspace), exportedAt: manifest.exportedAt }, null, 2) + '\n');
+		writeFileSync(bundleSafeJoin(destination, 'checksums.json'), JSON.stringify(checksums, null, 2) + '\n');
+		writeFileSync(bundleSafeJoin(destination, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n');
+	} catch (err) {
+		try { rmSync(destination, { recursive: true, force: true }); } catch { /* preserve the original error */ }
+		throw err;
+	}
+	return { exported: true, bundlePath: destination, sessionCount: manifest.sessions.length, attachmentCount: attachmentRelations.length, manifest };
+}
+
+async function inspectPortableBundle(ctx, { bundlePath, targetWorkspaceId } = {}) {
+	const targetId = validId(targetWorkspaceId, 'targetWorkspaceId');
+	const registry = ctx.workspaceRegistry;
+	const target = registry?.get?.(targetId);
+	if (!target) throw new Error(`unknown workspace '${targetId}'`);
+	const storage = createPersistenceAdapter(ctx);
+	const bundle = loadPortableBundle(bundlePath);
+	if (!storage.capabilities.physicalPath) {
+		return {
+			status: 'blocked',
+			bundlePath: bundle.root,
+			targetWorkspace: { id: target.id, title: target.title, path: target.path },
+			sessions: [],
+			conflicts: [],
+			missingFiles: bundle.missing,
+			checksumMismatches: bundle.checksumMismatches,
+			missingAttachments: [],
+			formatIncompatible: [{ reason: `${storage.reason}; physical bundle import is unavailable` }],
+			requiredBytes: 0,
+			freeBytes: null,
+			recoverableFiles: bundle.files.length - bundle.checksumMismatches.length,
+			adapter: storageDiagnostics(ctx)
+		};
+	}
+	const conflicts = [];
+	const incompatible = [];
+	const sessions = [];
+	let requiredBytes = 0;
+	for (const session of bundle.manifest.sessions) {
+		const artifact = bundle.files.find((item) => item.sessionId === session.sessionId && item.kind === 'session');
+		if (!artifact) continue;
+		requiredBytes += Number(artifact.bytes?.length ?? artifact.sizeBytes ?? 0);
+		for (const attachment of session.attachments ?? []) {
+			requiredBytes += Number(attachment.bytes ?? attachment.sizeBytes ?? 0);
+		}
+		if (session.format?.compression && session.format.compression !== storage.compression) incompatible.push({ sessionId: session.sessionId, reason: `compression ${session.format.compression} != target ${storage.compression}` });
+		let destinationArtifact = null;
+		try { destinationArtifact = findDestinationArtifact(sessionDir(storage.root, target.path, session.sessionId), storage.compression); } catch (err) { conflicts.push({ sessionId: session.sessionId, reason: String(err?.message ?? err) }); }
+		if (destinationArtifact) conflicts.push({ sessionId: session.sessionId, reason: 'target archive already exists' });
+		if (workspaceForSession(registry, session.sessionId)) conflicts.push({ sessionId: session.sessionId, reason: 'session id is already registered' });
+		sessions.push({ sessionId: session.sessionId, title: session.title ?? null, bytes: artifact.bytes?.length ?? 0, attachments: session.attachments?.length ?? 0, conflict: Boolean(destinationArtifact) });
+	}
+	let freeBytes = null;
+	try { const st = statfsSync(target.path); freeBytes = Number(st.bfree) * Number(st.bsize || 4096); } catch { /* report unknown free space */ }
+	const missingAttachments = bundle.manifest.attachments.filter((item) => bundle.missing.includes(item.bundlePath));
+	const status = bundle.missing.length || bundle.checksumMismatches.length || conflicts.length || incompatible.length
+		? 'blocked'
+		: (freeBytes !== null && freeBytes < requiredBytes * 2)
+			? 'blocked'
+			: missingAttachments.length
+				? 'warning'
+			: 'safe';
+	return {
+		status,
+		bundlePath: bundle.root,
+		targetWorkspace: { id: target.id, title: target.title, path: target.path },
+		sessions,
+		conflicts,
+		missingFiles: bundle.missing,
+		checksumMismatches: bundle.checksumMismatches,
+		missingAttachments,
+		formatIncompatible: incompatible,
+		requiredBytes,
+		freeBytes,
+		recoverableFiles: bundle.files.length - bundle.checksumMismatches.length,
+		adapter: storageDiagnostics(ctx)
+	};
+}
+
+async function importPortableBundle(ctx, { bundlePath, targetWorkspaceId, dryRun = true } = {}) {
+	const plan = await inspectPortableBundle(ctx, { bundlePath, targetWorkspaceId });
+	if (dryRun !== false) return { ...plan, dryRun: true, imported: false };
+	if (plan.status === 'blocked') {
+		const err = new Error('portable bundle dry-run is blocked; resolve conflicts, missing files, and format incompatibilities first');
+		err.code = 'conflict';
+		throw err;
+	}
+	const bundle = loadPortableBundle(bundlePath);
+	const storage = createPersistenceAdapter(ctx);
+	const target = ctx.workspaceRegistry.get(targetWorkspaceId);
+	const results = [];
+	for (const session of bundle.manifest.sessions) {
+		const artifact = bundle.files.find((item) => item.sessionId === session.sessionId && item.kind === 'session');
+		if (!artifact) continue;
+		const dstDir = sessionDir(storage.root, target.path, session.sessionId);
+		const dstArtifact = join(dstDir, basename(session.format?.artifactName || basename(artifact.bundlePath)));
+		let created = false;
+		const missingAttachments = [];
+		try {
+			const header = readHeader(artifact.bytes, storage.compression);
+			validateArtifactGeneration(dstArtifact, header);
+			const finalBytes = samePath(header.cwd, target.path) ? artifact.bytes : rewriteHeaderCwd(artifact.bytes, target.path, storage.compression);
+			stashBackup(session.sessionId, artifact.bytes, { compression: storage.compression, ignoreCwd: true });
+			mkdirSync(dstDir, { recursive: true });
+			await storage.write({ kind: 'filesystem', sessionId: session.sessionId, cwd: target.path, artifact: dstArtifact }, finalBytes);
+			created = true;
+			for (const attachment of session.attachments ?? []) {
+				const source = bundleSafeJoin(bundle.root, attachment.bundlePath);
+				if (!existsSync(source)) {
+					missingAttachments.push(attachment.bundlePath);
+					continue;
+				}
+				const destination = bundleSafeJoin(dstDir, attachment.relativePath);
+				mkdirSync(dirname(destination), { recursive: true });
+				copyFileSync(source, destination);
+			}
+			verifyRelocatedBytes(await storage.read({ kind: 'filesystem', sessionId: session.sessionId, cwd: target.path, artifact: dstArtifact }), session.sessionId, target.path, storage.compression);
+			await target.attachSession(session.sessionId);
+			results.push({ sessionId: session.sessionId, ok: true, targetWorkspaceId, missingAttachments });
+		} catch (err) {
+			if (created) { try { rmSync(dstDir, { recursive: true, force: true }); } catch { /* preserve recovery bytes */ } }
+			results.push({ sessionId: session.sessionId, ok: false, error: String(err?.message ?? err) });
+		}
+	}
+	return { ...plan, dryRun: false, imported: true, results, importedCount: results.filter((item) => item.ok).length, failedCount: results.filter((item) => !item.ok).length };
+}
+
+/** Read-only move plan used by the client confirmation dialog and agent callers. */
+async function inspectMovePlan(ctx, { sessionId, targetWorkspaceId, mode = 'current-only' } = {}) {
+	const id = validId(sessionId, 'sessionId');
+	const targetId = validId(targetWorkspaceId, 'targetWorkspaceId');
+	const registry = ctx.workspaceRegistry;
+	const persistence = ctx.sessionPersistence;
+	if (!registry || !persistence) throw new Error('workspace registry or session persistence service unavailable');
+	const target = registry.get(targetId);
+	if (!target) throw new Error(`unknown workspace '${targetId}'`);
+	const adapter = createPersistenceAdapter(ctx);
+	if (!['current-only', 'include-descendants'].includes(mode)) throw new Error(`unknown fork migration mode '${mode}'`);
+	const headers = await adapter.list();
+	const meta = headers.find((header) => String(header?.id) === id);
+	if (!meta) throw new Error(`session '${id}' not found in session persistence`);
+	if (typeof meta.cwd !== 'string' || meta.cwd.length === 0) throw new Error('session header carries no cwd');
+	const sourceWorkspace = registry.list().find((entity) => {
+		try { return samePath(entity.path, meta.cwd); } catch { return false; }
+	});
+	const running = peekService(ctx, 'agents')?.get?.(id)?.status === 'running';
+	const branches = mode === 'include-descendants'
+		? await collectDescendantSessions(ctx, id, adapter)
+		: { ids: [id], relations: [] };
+	const warnings = [];
+	const source = {
+		workspaceId: sourceWorkspace?.id ?? null,
+		cwd: meta.cwd,
+		sizeBytes: 0,
+		generation: null,
+		compression: adapter.compression,
+		path: null
+	};
+	const targetInfo = {
+		workspaceId: targetId,
+		path: target.path,
+		collision: false,
+		writable: false
+	};
+	const sameWorkspace = samePath(meta.cwd, target.path);
+	const repairMembership = sameWorkspace && !rawRecordSessionIds(target).includes(id);
+	let backupPlan = { reused: false, estimatedBytes: 0 };
+	let status = 'safe';
+	if (running) {
+		status = 'queued';
+		warnings.push('session is currently running and will wait for idle');
+	}
+	if (adapter.mode === 'filesystem-fallback') warnings.push('physical move uses the JSONL path fallback; official raw-byte path API is unavailable');
+	if (!adapter.capabilities.physicalPath) {
+		status = 'blocked';
+		warnings.push('provider exposes public handles but no physical raw-byte path; this version cannot relocate the archive directory');
+	} else {
+		const location = await adapter.locate({ sessionId: id, cwd: meta.cwd });
+		const info = await adapter.inspect(location);
+		source.path = location.artifact;
+		source.sizeBytes = info.sizeBytes ?? 0;
+		try { source.generation = parseGenerationLogFilename(basename(location.artifact))?.version ?? null; } catch { /* diagnostic only */ }
+		source.generations = info.generations ?? [];
+		if (source.generations.length > 1) {
+			warnings.push(`multiple generations found; v${source.generation} is selected and older files are preserved`);
+		}
+		if (!info.exists) {
+			status = 'blocked';
+			warnings.push('source session archive is missing or unreadable');
+		}
+		if (!sameWorkspace && info.exists) backupPlan = await inspectBackupPlan(id, location, info, adapter.compression);
+		const targetDir = sessionDir(adapter.root, target.path, id);
+		try {
+			const targetArtifact = findDestinationArtifact(targetDir, adapter.compression);
+			targetInfo.collision = Boolean(targetArtifact) && !sameWorkspace;
+			targetInfo.writable = !targetArtifact;
+			if (targetInfo.collision) {
+				status = 'blocked';
+				warnings.push('target workspace already contains an archive with this session id');
+			}
+		} catch (err) {
+			targetInfo.writable = false;
+			status = 'blocked';
+			warnings.push(String(err?.message ?? err));
+		}
+	}
+	if (sameWorkspace) {
+		if (repairMembership && status !== 'blocked') {
+			warnings.push('session archive is already at target; workspace membership will be repaired');
+		} else {
+			status = 'blocked';
+			warnings.push('session already belongs to the target workspace');
+		}
+	}
+	if (branches.relations.length > 0) warnings.push(`${branches.relations.length} descendant session(s) selected`);
+	return {
+		status,
+		canMove: status === 'safe' || status === 'warning' || status === 'queued',
+		sessionId: id,
+		title: meta.title ?? null,
+		source,
+		target: targetInfo,
+		running,
+		branches: { available: true, count: branches.relations.length, mode, sessionIds: branches.ids, relations: branches.relations },
+		estimatedBackupBytes: sameWorkspace ? 0 : backupPlan.estimatedBytes,
+		backup: sameWorkspace ? { reused: false, estimatedBytes: 0 } : backupPlan,
+		adapter: storageDiagnostics(ctx),
+		warnings
+	};
+}
+
 /** 批量迁移入口：逐会话复用 moveSession（各自独立备份/回滚，单条失败不牵连其余）；历史聚合成一条。 */
-async function moveManySessions(ctx, { sessions, targetWorkspaceId } = {}) {
+async function moveManySessions(ctx, { sessions, targetWorkspaceId, mode = 'current-only' } = {}) {
 	if (!Array.isArray(sessions) || sessions.length === 0) throw new Error('sessions must be a non-empty array');
 	if (sessions.length > batchLimit()) throw new Error(`too many sessions in one batch (max ${batchLimit()}, got ${sessions.length})`);
 	if (typeof targetWorkspaceId !== 'string' || targetWorkspaceId.length === 0) throw new Error('targetWorkspaceId required');
+	if (!['current-only', 'include-descendants'].includes(mode)) throw new Error(`unknown fork migration mode '${mode}'`);
+	const forkRelations = [];
+	if (mode === 'include-descendants') {
+		const expanded = [];
+		const adapter = createPersistenceAdapter(ctx);
+		for (const item of sessions) {
+			const sessionId = validId(item?.sessionId, 'sessionId');
+			const tree = await collectDescendantSessions(ctx, sessionId, adapter);
+			expanded.push({ ...item, sessionId });
+			for (const descendant of tree.relations) {
+				expanded.push({ sessionId: descendant.sessionId, sessionTitle: descendant.title });
+				forkRelations.push(descendant);
+			}
+		}
+		sessions = expanded;
+		if (sessions.length > batchLimit()) throw new Error(`fork tree expands beyond batch limit ${batchLimit()}`);
+	}
 	// 批内去重：同一会话在一次批量里只处理一次
 	const seenIds = new Set();
 	sessions = sessions.filter((item) => {
@@ -1222,6 +2076,7 @@ async function moveManySessions(ctx, { sessions, targetWorkspaceId } = {}) {
 	const registry = ctx.workspaceRegistry;
 	const results = [];
 	const moved = [];
+	let queuedCount = 0;
 	let movedCount = 0;
 	let attachedCount = 0;
 	for (const item of sessions) {
@@ -1242,10 +2097,21 @@ async function moveManySessions(ctx, { sessions, targetWorkspaceId } = {}) {
 			try {
 				sourceWorkspaceId = registry?.list?.().find((e) => { try { return samePath(e.path, result.from.cwd); } catch { return false; } })?.id ?? null;
 			} catch { sourceWorkspaceId = null; }
-			moved.push({ sessionId, title: result.title, fromCwd: result.from.cwd, sourceWorkspaceId });
+			moved.push({ sessionId, title: result.title, fromCwd: result.from.cwd, sourceWorkspaceId, backup: result.backup ?? null });
 			results.push({ sessionId, ok: true, moved: result.moved, to: result.to.cwd, title: result.title });
 		} catch (err) {
-			results.push({ sessionId, ok: false, error: err?.message ?? String(err) });
+			if (isBusyError(err)) {
+				const queued = createOrReuseMigration(ctx, {
+					sessionId,
+					targetWorkspaceId,
+					title: typeof item.sessionTitle === 'string' ? item.sessionTitle : null,
+					reason: String(err?.message ?? err)
+				});
+				queuedCount++;
+				results.push({ sessionId, ok: false, queued: true, state: 'queued', queueTaskId: queued.id, error: queued.lastError });
+			} else {
+				results.push({ sessionId, ok: false, error: err?.message ?? String(err) });
+			}
 		}
 	}
 	let historyId = null;
@@ -1263,15 +2129,16 @@ async function moveManySessions(ctx, { sessions, targetWorkspaceId } = {}) {
 	} catch (err) {
 		ctx.logger?.warn?.(`workspace-mover: task record write failed: ${err?.message ?? err}`);
 	}
-	return { results, movedCount, attachedCount, failedCount: results.length - movedCount - attachedCount, historyId, taskId };
+	return { results, movedCount, attachedCount, queuedCount, failedCount: results.length - movedCount - attachedCount, historyId, taskId, mode, forkRelations };
 }
 
-//#region 迁移任务中心（v1.2，记录式）
-// 任务 = 已执行批量的持久化记录 + 逐项可重试状态。不是后台队列：
-// 重试在 RPC 内同步执行，逐项隔离失败；来源位置在重试时实时解析
-// （记录里的 sourceCwd 仅作展示），因此用户在批后手动搬动过会话也不会用错路径。
+//#region 迁移任务中心与 busy 队列
+// tasks.json 记录已经执行的批量；migrations.json 记录尚未完成的 busy 迁移。
+// 两者都使用真实 session id，在重试时重新解析当前档案位置，不信任旧路径。
 const TASKS_FILE = 'tasks.json';
 const TASKS_LIMIT = 50;
+const MIGRATIONS_FILE = 'migrations.json';
+const MIGRATIONS_LIMIT = 200;
 
 function tasksPath() {
 	return join(pluginDataDir(), TASKS_FILE);
@@ -1291,6 +2158,305 @@ function writeTasks(tasks) {
 	atomicWrite(tasksPath(), Buffer.from(JSON.stringify({ version: 1, tasks: tasks.slice(0, TASKS_LIMIT) }, null, 2) + '\n', 'utf8'));
 }
 
+function migrationsPath() {
+	return join(pluginDataDir(), MIGRATIONS_FILE);
+}
+
+function readMigrations() {
+	if (!existsSync(migrationsPath())) return [];
+	let value;
+	try {
+		value = JSON.parse(readFileSync(migrationsPath(), 'utf8'));
+	} catch (cause) {
+		const err = new Error(`migration queue data is corrupt: ${cause?.message ?? cause}`);
+		err.code = 'data-corrupt';
+		throw err;
+	}
+	const validStates = new Set(['queued', 'waiting-for-idle', 'retrying', 'done', 'failed', 'cancelled']);
+	if (value?.version !== 1 || !Array.isArray(value?.tasks) || value.tasks.some((task) =>
+		!task || typeof task.id !== 'string' || typeof task.sessionId !== 'string'
+		|| typeof task.targetWorkspaceId !== 'string' || !validStates.has(task.state))) {
+		const err = new Error('migration queue data is corrupt: invalid schema');
+		err.code = 'data-corrupt';
+		throw err;
+	}
+	return value.tasks;
+}
+
+function migrationQueueSummary() {
+	const counts = { total: 0, queued: 0, waitingForIdle: 0, retrying: 0, failed: 0, done: 0, cancelled: 0 };
+	let tasks;
+	try {
+		tasks = readMigrations();
+	} catch (err) {
+		return { ...counts, pending: 0, error: String(err?.message ?? err) };
+	}
+	for (const task of tasks) {
+		counts.total++;
+		if (task.state === 'waiting-for-idle') counts.waitingForIdle++;
+		else if (Object.hasOwn(counts, task.state)) counts[task.state]++;
+	}
+	counts.pending = counts.queued + counts.waitingForIdle + counts.retrying;
+	return counts;
+}
+
+function writeMigrations(tasks) {
+	const pendingStates = new Set(['queued', 'waiting-for-idle', 'retrying']);
+	const pending = tasks.filter((task) => pendingStates.has(task.state));
+	if (pending.length > MIGRATIONS_LIMIT) {
+		const err = new Error(`migration queue is full (max ${MIGRATIONS_LIMIT} pending tasks)`);
+		err.code = 'queue-full';
+		throw err;
+	}
+	const terminalLimit = MIGRATIONS_LIMIT - pending.length;
+	const terminal = tasks.filter((task) => !pendingStates.has(task.state)).slice(0, terminalLimit);
+	const retainedSet = new Set([...pending, ...terminal]);
+	const retained = tasks.filter((task) => retainedSet.has(task));
+	mkdirSync(dirname(migrationsPath()), { recursive: true });
+	atomicWrite(migrationsPath(), Buffer.from(JSON.stringify({ version: 1, tasks: retained }, null, 2) + '\n', 'utf8'));
+}
+
+function isBusyError(err) {
+	return err?.code === 'busy' || /currently running|is busy|another operation is in flight|bulk operation is in flight/.test(String(err?.message ?? err));
+}
+
+function migrationId() {
+	return `migration-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+function migrationSummary(task) {
+	return {
+		id: task.id,
+		sessionId: task.sessionId,
+		title: task.title ?? null,
+		targetWorkspaceId: task.targetWorkspaceId,
+		sourceWorkspaceId: task.sourceWorkspaceId ?? null,
+		state: task.state,
+		attempts: task.attempts ?? 0,
+		createdAt: task.createdAt,
+		updatedAt: task.updatedAt,
+		lastError: task.lastError ?? null,
+		lastAttemptAt: task.lastAttemptAt ?? null,
+		completedAt: task.completedAt ?? null
+	};
+}
+
+function createOrReuseMigration(ctx, { sessionId, targetWorkspaceId, title, sourceWorkspaceId = null, reason = 'session is busy' }) {
+	const tasks = readMigrations();
+	const existing = tasks.find((task) => String(task.sessionId) === String(sessionId)
+		&& String(task.targetWorkspaceId) === String(targetWorkspaceId)
+		&& !['done', 'cancelled'].includes(task.state));
+	if (existing) {
+		existing.lastError = reason;
+		existing.state = 'waiting-for-idle';
+		existing.updatedAt = new Date().toISOString();
+		writeMigrations(tasks);
+		return existing;
+	}
+	const now = new Date().toISOString();
+	const task = {
+		id: migrationId(),
+		sessionId: String(sessionId),
+		title: title ?? null,
+		targetWorkspaceId: String(targetWorkspaceId),
+		sourceWorkspaceId: sourceWorkspaceId ?? null,
+		state: 'waiting-for-idle',
+		attempts: 0,
+		createdAt: now,
+		updatedAt: now,
+		lastError: reason,
+		lastAttemptAt: null,
+		completedAt: null
+	};
+	tasks.unshift(task);
+	writeMigrations(tasks);
+	return task;
+}
+
+function migrationTaskState(task, state, extra = {}) {
+	return {
+		...task,
+		...extra,
+		state,
+		updatedAt: new Date().toISOString()
+	};
+}
+
+async function processMigrationTask(ctx, task) {
+	const current = readMigrations().find((item) => item.id === task.id);
+	if (!current || ['done', 'cancelled'].includes(current.state)) return current ?? task;
+	if (peekService(ctx, 'agents')?.get?.(task.sessionId)?.status === 'running') {
+		return migrationTaskState(current, 'waiting-for-idle', { lastError: 'session is currently running; waiting for idle' });
+	}
+	const attemptAt = new Date().toISOString();
+	const retrying = migrationTaskState(current, 'retrying', {
+		attempts: (current.attempts ?? 0) + 1,
+		lastAttemptAt: attemptAt,
+		lastError: null
+	});
+	const tasks = readMigrations();
+	const index = tasks.findIndex((item) => item.id === task.id);
+	if (index < 0 || ['done', 'cancelled'].includes(tasks[index].state)) return tasks[index] ?? current;
+	tasks[index] = retrying;
+	writeMigrations(tasks);
+	try {
+		const result = await moveSessionEntry(ctx, {
+			sessionId: retrying.sessionId,
+			targetWorkspaceId: retrying.targetWorkspaceId,
+			sessionTitle: retrying.title ?? undefined,
+			recordHistory: true
+		});
+		return migrationTaskState(retrying, 'done', {
+			lastError: null,
+			completedAt: new Date().toISOString(),
+			result: { to: result.to, verified: result.verified }
+		});
+	} catch (err) {
+		if (isBusyError(err)) return migrationTaskState(retrying, 'waiting-for-idle', { lastError: String(err?.message ?? err) });
+		return migrationTaskState(retrying, 'failed', { lastError: String(err?.message ?? err) });
+	}
+}
+
+async function drainMigrationQueueRaw(ctx, { taskId = null } = {}) {
+	const tasks = readMigrations();
+	const eligible = new Set(['queued', 'waiting-for-idle', 'retrying']);
+	const selected = tasks.filter((task) => (taskId ? task.id === taskId : eligible.has(task.state)));
+	if (selected.length === 0) return { items: [], processed: 0 };
+	let processed = 0;
+	for (const task of selected) {
+		const current = readMigrations().find((item) => item.id === task.id);
+		if (!current || !eligible.has(current.state)) continue;
+		const next = await processMigrationTask(ctx, current);
+		const latest = readMigrations();
+		const index = latest.findIndex((item) => item.id === task.id);
+		if (index >= 0 && latest[index].state !== 'cancelled') {
+			latest[index] = next;
+			writeMigrations(latest);
+		}
+		processed++;
+	}
+	return { items: readMigrations().map(migrationSummary), processed };
+}
+
+async function drainMigrationQueue(ctx, options = {}) {
+	const runtime = migrationRuntimes.get(ctx);
+	if (!runtime) return drainMigrationQueueRaw(ctx, options);
+	const previous = runtime.draining ?? Promise.resolve();
+	const promise = previous.catch(() => {}).then(() => drainMigrationQueueRaw(ctx, options));
+	runtime.draining = promise;
+	try {
+		return await promise;
+	} finally {
+		if (runtime.draining === promise) runtime.draining = null;
+	}
+}
+
+function startMigrationRuntime(ctx, owner, logger) {
+	if (!ctx || typeof ctx !== 'object' || migrationRuntimes.has(ctx)) return;
+	const runtime = { timer: null, draining: null };
+	runtime.timer = setInterval(() => {
+		if (runtime.draining) return;
+		void drainMigrationQueue(ctx).catch((err) => {
+			logger?.warn?.(`workspace-mover: migration queue drain failed: ${err?.message ?? err}`);
+		});
+	}, 5000);
+	runtime.timer.unref?.();
+	migrationRuntimes.set(ctx, runtime);
+	owner?.effect?.(() => () => {
+		clearInterval(runtime.timer);
+		if (migrationRuntimes.get(ctx) === runtime) migrationRuntimes.delete(ctx);
+	}, 'workspace-mover: migration queue dispose');
+}
+
+async function enqueueMigrations(ctx, payload = {}) {
+	const targetWorkspaceId = validId(payload?.targetWorkspaceId, 'targetWorkspaceId');
+	const sourceItems = Array.isArray(payload?.sessions) ? payload.sessions : [{ sessionId: payload?.sessionId, title: payload?.sessionTitle }];
+	if (sourceItems.length === 0) throw new Error('sessions must be a non-empty array');
+	if (sourceItems.length > batchLimit()) throw new Error(`too many sessions in one batch (max ${batchLimit()}, got ${sourceItems.length})`);
+	const registry = ctx.workspaceRegistry;
+	const created = [];
+	for (const item of sourceItems) {
+		const sessionId = validId(item?.sessionId, 'sessionId');
+		let sourceWorkspaceId = null;
+		try {
+			sourceWorkspaceId = registry?.list?.().find((e) => rawRecordSessionIds(e).includes(sessionId))?.id ?? null;
+		} catch { /* source group is optional metadata */ }
+		created.push(createOrReuseMigration(ctx, {
+			sessionId,
+			targetWorkspaceId,
+			title: typeof item?.title === 'string' ? item.title : item?.sessionTitle,
+			sourceWorkspaceId,
+			reason: 'queued by user'
+		}));
+	}
+	await drainMigrationQueue(ctx);
+	const all = readMigrations();
+	return { queued: created.map(migrationSummary), items: all.map(migrationSummary) };
+}
+
+async function listMigrations(ctx) {
+	await drainMigrationQueue(ctx);
+	return { items: readMigrations().map(migrationSummary) };
+}
+
+async function retryMigration(ctx, payload = {}) {
+	const batch = Array.isArray(payload.taskIds);
+	const taskIds = batch ? [...new Set(payload.taskIds)] : [payload.taskId];
+	if (taskIds.length === 0 || taskIds.length > MIGRATIONS_LIMIT
+		|| taskIds.some((id) => typeof id !== 'string' || id.length === 0)) {
+		throw new Error(`taskId or taskIds with 1-${MIGRATIONS_LIMIT} ids required`);
+	}
+	const tasks = readMigrations();
+	const results = [];
+	let changed = false;
+	for (const id of taskIds) {
+		const task = tasks.find((item) => item.id === id);
+		if (!task) {
+			if (!batch) throw new Error(`migration task '${id}' not found`);
+			results.push({ id, state: 'missing', lastError: 'migration task not found' });
+			continue;
+		}
+		if (task.state === 'cancelled' || task.state === 'retrying' || task.state === 'done') {
+			results.push(migrationSummary(task));
+			continue;
+		}
+		task.state = 'queued';
+		task.lastError = null;
+		task.updatedAt = new Date().toISOString();
+		changed = true;
+		results.push(task);
+	}
+	if (changed) {
+		writeMigrations(tasks);
+		await drainMigrationQueue(ctx, batch ? {} : { taskId: taskIds[0] });
+	}
+	const latest = readMigrations();
+	const items = taskIds.map((id) => {
+		const task = latest.find((item) => item.id === id);
+		return task ? migrationSummary(task) : results.find((item) => item.id === id);
+	});
+	return batch ? { items, retried: results.filter((item) => item && !['missing', 'done', 'cancelled', 'retrying'].includes(item.state)).length }
+		: { item: items[0] };
+}
+
+async function cancelMigration({ taskId } = {}) {
+	if (typeof taskId !== 'string' || taskId.length === 0) throw new Error('taskId required');
+	const tasks = readMigrations();
+	const task = tasks.find((item) => item.id === taskId);
+	if (!task) throw new Error(`migration task '${taskId}' not found`);
+	if (task.state === 'retrying') {
+		const err = new Error('migration task is already in progress and cannot be cancelled');
+		err.code = 'busy';
+		throw err;
+	}
+	if (!['done', 'cancelled'].includes(task.state)) {
+		task.state = 'cancelled';
+		task.updatedAt = new Date().toISOString();
+	}
+	writeMigrations(tasks);
+	return { cancelled: task.state === 'cancelled', item: migrationSummary(task) };
+}
+
 /** 批量迁移完成后落任务记录：done/failed 逐项带来源与目标路径、最后错误与最后尝试时间。 */
 function recordMoveManyTask(ctx, { targetWorkspaceId, results, moved }) {
 	const target = ctx.workspaceRegistry?.list?.().find((e) => e.id === targetWorkspaceId);
@@ -1303,7 +2469,9 @@ function recordMoveManyTask(ctx, { targetWorkspaceId, results, moved }) {
 			sourceCwd: moved.find((mv) => mv.sessionId === r.sessionId)?.fromCwd ?? null,
 			targetCwd: target?.path ?? null,
 			state: r.ok ? 'done' : 'failed',
+			queued: Boolean(r.queued),
 			error: r.ok ? null : (r.error ?? 'unknown'),
+			queueTaskId: r.queueTaskId ?? null,
 			lastAttemptAt: new Date().toISOString()
 		});
 	}
@@ -1334,6 +2502,7 @@ async function listTasks() {
 			done: t.items.filter((i) => i.state === 'done').length,
 			failed: t.items.filter((i) => i.state === 'failed').length,
 			skipped: t.items.filter((i) => i.state === 'skipped').length,
+			queued: t.items.filter((i) => i.state === 'queued').length,
 			total: t.items.length,
 			items: t.items
 		}))
@@ -1364,7 +2533,7 @@ async function retryTask(ctx, { taskId } = {}) {
 			item.lastError = null;
 			item.lastAttemptAt = attemptAt;
 			item.targetCwd = result.to?.cwd ?? item.targetCwd;
-			movedNow.push({ sessionId: item.sessionId, title: item.title, fromCwd: result.from?.cwd ?? null, sourceWorkspaceId: null });
+			movedNow.push({ sessionId: item.sessionId, title: item.title, fromCwd: result.from?.cwd ?? null, sourceWorkspaceId: null, backup: result.backup ?? null });
 			results.push({ sessionId: item.sessionId, ok: true });
 		} catch (err) {
 			const msg = String(err?.message ?? err);
@@ -1432,10 +2601,9 @@ async function cleanupOldData(ctx, { days, dryRun = false } = {}) {
 	const bdir = backupDir();
 	if (dirExists(bdir)) {
 		for (const name of readdirSync(bdir)) {
-			// 兼容同毫秒去重后缀：`${id}.${ts}.zstd` 与 `${id}.${ts}-${seq}.zstd`
-			const m = /^(.+)\.(\d+)(?:-\d+)?\.zstd$/.exec(name);
-			if (!m) continue;
-			const ts = Number(m[2]);
+			const parsed = parseBackupFilename(name);
+			if (!parsed) continue;
+			const ts = parsed.ts;
 			if (!(ts < cutoff)) continue;
 			let size = 0;
 			try { size = statSync(join(bdir, name)).size; } catch { continue; }
@@ -1735,8 +2903,14 @@ async function repointWorkspaceLocked(ctx, { workspaceId, fromPath, newPath, dry
 		throw new Error(`该工作区牵涉 ${affected.length} 个会话，超出单次上限 ${repointLimit()}；请分批处理`);
 	}
 
-	const root = persistence.root;
-	const compression = persistenceCompression(persistence);
+	const storage = createPersistenceAdapter(ctx);
+	if (!storage.capabilities.physicalPath) {
+		const err = new Error(`${storage.reason}; physical workspace repoint is unavailable`);
+		err.code = 'unsupported';
+		throw err;
+	}
+	const root = storage.root;
+	const compression = storage.compression;
 	if (typeof root !== 'string' || root.length === 0) throw new Error('session persistence backend exposes no root');
 
 	if (dryRun) return { dryRun: true, from: stalePath, to: targetCanon, resumeMode, count: affected.length, items: affected };
@@ -1819,24 +2993,39 @@ async function repointWorkspaceLocked(ctx, { workspaceId, fromPath, newPath, dry
 		try {
 			assertNotRunning(ctx, sessionId);
 			const meta = headers.find((h) => String(h?.id) === String(sessionId));
-			const srcArtifact = artifactPath(root, typeof meta?.cwd === 'string' ? meta.cwd : stalePath, sessionId, compression);
-			if (!existsSync(srcArtifact)) throw new Error(`档案缺失：${srcArtifact}`);
-			const dstArtifact = artifactPath(root, targetCanon, sessionId, compression);
-			if (existsSync(dstArtifact)) throw new Error(`目标位置已有同名档案：${dstArtifact}`);
-
-			const original = readFileSync(srcArtifact);
-			stashBackup(String(sessionId), original);
-			atomicWrite(srcArtifact, rewriteHeaderCwd(original, targetCanon, compression));
+			const sourceLocation = await storage.locate({ sessionId, cwd: typeof meta?.cwd === 'string' ? meta.cwd : stalePath });
+			const sourceInfo = await storage.inspect(sourceLocation);
+			if (!sourceInfo.exists) throw new Error(`档案缺失：${sourceLocation.artifact}`);
+			const srcArtifact = sourceLocation.artifact;
+			const destinationProbe = await storage.locate({ sessionId, cwd: targetCanon });
+			if ((await storage.inspect(destinationProbe)).exists) throw new Error(`目标位置已有同名档案：${destinationProbe.artifact}`);
+			const dstArtifact = join(dirname(destinationProbe.artifact), basename(srcArtifact));
+			const destinationLocation = { ...destinationProbe, cwd: targetCanon, artifact: dstArtifact };
+
+			const original = await storage.read(sourceLocation);
+			stashBackup(String(sessionId), original, { compression, ignoreCwd: true });
+			await storage.replace(sourceLocation, rewriteHeaderCwd(original, targetCanon, compression));
 			try {
-				moveDir(dirname(srcArtifact), dirname(dstArtifact));
+				await storage.relocate(sourceLocation, dirname(dstArtifact));
 				// 迁移后一致性校验（同 moveSession），失败视同搬移失败回退源字节
 				try {
-					verifyRelocatedArtifact(dstArtifact, sessionId, targetCanon, compression);
+					verifyRelocatedBytes(await storage.read(destinationLocation), sessionId, targetCanon, compression);
 				} catch (verifyErr) {
 					throw new Error(`物理搬移校验失败：${verifyErr?.message ?? verifyErr}`);
 				}
 			} catch (err) {
-				atomicWrite(srcArtifact, original);
+				try {
+					if (!(await storage.inspect(sourceLocation)).exists) await storage.relocate(destinationLocation, dirname(srcArtifact));
+					await storage.replace(sourceLocation, original);
+				} catch (rollbackErr) {
+					try { await storage.write(sourceLocation, original); } catch { /* backup remains available */ }
+					recordRecovery(ctx, {
+						kind: 'repoint', phase: 'physical-rollback', sessionId: String(sessionId),
+						source: dirname(srcArtifact), target: dirname(dstArtifact), backup: null,
+						lastError: `move failed (${err?.message ?? err}) AND rollback failed (${rollbackErr?.message ?? rollbackErr})`
+					});
+					throw new Error(`物理搬移失败且回滚不完整；原始档案已尝试写回，备份和恢复记录已保留：${rollbackErr?.message ?? rollbackErr}`);
+				}
 				throw new Error(`物理搬移失败：${err?.message ?? err}`);
 			}
 			try {
@@ -1934,8 +3123,12 @@ async function locateArtifact(ctx, sessionId) {
 	const registry = ctx.workspaceRegistry;
 	const persistence = ctx.sessionPersistence;
 	if (!registry || !persistence) throw new Error('workspace registry or session persistence service unavailable');
-	const root = persistence.root;
-	const compression = persistenceCompression(persistence);
+	const storage = createPersistenceAdapter(ctx);
+	if (!storage.capabilities.physicalPath) {
+		const err = new Error(`${storage.reason}; physical artifact lookup is unavailable`);
+		err.code = 'unsupported';
+		throw err;
+	}
 	const candidates = [];
 	try { const p = registry.sessionPaths?.get?.(sessionId); if (typeof p === 'string' && p) candidates.push(p); } catch { /* ignore */ }
 	for (const e of registry.list()) {
@@ -1948,8 +3141,9 @@ async function locateArtifact(ctx, sessionId) {
 		}
 	} catch { /* ignore */ }
 	for (const cwd of candidates) {
-		const artifact = artifactPath(root, cwd, sessionId, compression);
-		if (existsSync(artifact)) return { artifact, cwd };
+		const location = await storage.locate({ sessionId, cwd });
+		const info = await storage.inspect(location);
+		if (info.exists) return { ...location, cwd };
 	}
 	throw new Error(`session archive not found for '${sessionId}'`);
 }
@@ -2103,9 +3297,10 @@ async function deleteSessionToTrashLocked(ctx, sessionId, hooks = {}) {
 		throw new Error('session is resident in memory (it may remain resident even when not focused; archiving does not unload it); close it or restart the harness before deleting');
 	}
 	assertNotRunning(ctx, sessionId);
-	const compression = persistenceCompression(persistence);
-	const { artifact, cwd: artifactCwd } = await locateArtifact(ctx, sessionId);
-	const header = readHeader(readFileSync(artifact), compression);
+	const storage = createPersistenceAdapter(ctx);
+	const location = await locateArtifact(ctx, sessionId);
+	const { artifact, cwd: artifactCwd } = location;
+	const header = readHeader(await storage.read(location), storage.compression);
 	const archived = readArchivedIds(registry).includes(sessionId);
 	const projection = captureProjection(ctx, sessionId);
 	const owners = listOwners(registry, sessionId);
@@ -2114,7 +3309,7 @@ async function deleteSessionToTrashLocked(ctx, sessionId, hooks = {}) {
 	// ① 物理移动先行
 	let how = 'rename';
 	try {
-		how = moveImpl(dirname(artifact), join(entryDir, 'session'));
+		how = await storage.relocate(location, join(entryDir, 'session'), { moveImpl });
 	} catch (err) {
 		try { rmSync(entryDir, { recursive: true, force: true }); } catch { /* ignore */ }
 		throw new Error(`move to recycle failed (nothing was changed): ${err?.message ?? err}`);
@@ -2134,7 +3329,9 @@ async function deleteSessionToTrashLocked(ctx, sessionId, hooks = {}) {
 	try {
 		writeManifestImpl(join(entryDir, TRASH_MANIFEST), manifest);
 	} catch (err) {
-		try { moveDir(join(entryDir, 'session'), dirname(artifact)); } catch (backErr) {
+		try {
+			await storage.relocate({ ...location, artifact: join(entryDir, 'session', basename(artifact)) }, dirname(artifact));
+		} catch (backErr) {
 			recordRecovery(ctx, {
 				kind: 'delete', phase: 'manifest-rollback', sessionId: String(sessionId),
 				source: dirname(artifact), target: entryDir, backup: null,
@@ -2203,6 +3400,12 @@ async function restoreFromTrashLocked(ctx, sessionId, targetWorkspaceId) {
 	const registry = ctx.workspaceRegistry;
 	const persistence = ctx.sessionPersistence;
 	if (!registry || !persistence) throw new Error('workspace registry or session persistence service unavailable');
+	const storage = createPersistenceAdapter(ctx);
+	if (!storage.capabilities.physicalPath) {
+		const err = new Error(`${storage.reason}; physical trash restore is unavailable`);
+		err.code = 'unsupported';
+		throw err;
+	}
 	const dir = recycleDir();
 	if (!dirExists(dir)) throw new Error(`no trashed session '${sessionId}'`);
 	let entryDir = null;
@@ -2213,22 +3416,25 @@ async function restoreFromTrashLocked(ctx, sessionId, targetWorkspaceId) {
 		if (m && String(m.sessionId) === String(sessionId)) { entryDir = candidate; manifest = m; break; }
 	}
 	if (!entryDir) throw new Error(`no trashed session '${sessionId}'`);
-	const compression = persistenceCompression(persistence);
+	const compression = storage.compression;
 	const sessionDir = join(entryDir, 'session');
 	const foundInTrash = findHighestArtifact(sessionDir, compression);
 	if (!foundInTrash) throw new Error(`trash entry has no session artifact: ${entryDir}`);
 	const artifactInTrash = foundInTrash.path;
 	if (!existsSync(artifactInTrash)) throw new Error(`trashed archive missing for '${sessionId}'`);
+	const trashLocation = { kind: 'filesystem', sessionId: String(sessionId), cwd: manifest.cwd ?? null, artifact: artifactInTrash };
 	if (peekService(ctx, 'sessions')?.get?.(sessionId) !== undefined) {
 		throw new Error('a live session with this id already exists; restart the harness before restoring');
 	}
 	let existingPath = null;
 	try { existingPath = registry.sessionPaths?.get?.(sessionId); } catch { /* ignore */ }
 	if (existingPath) throw new Error('session id already exists in the workspace registry');
-	const header = readHeader(readFileSync(artifactInTrash), compression);
+	const header = readHeader(await storage.read(trashLocation), compression);
 	const originalCwd = typeof header?.cwd === 'string' ? header.cwd : manifest.cwd;
 	if (typeof originalCwd !== 'string' || originalCwd.length === 0) throw new Error('trashed manifest carries no original path');
-	const originalArtifact = artifactPath(persistence.root, originalCwd, sessionId, compression);
+	const originalProbe = await storage.locate({ sessionId, cwd: originalCwd });
+	const originalLocation = { ...originalProbe, artifact: join(dirname(originalProbe.artifact), basename(artifactInTrash)) };
+	const originalInfo = await storage.inspect(originalProbe);
 	let destPath = originalCwd;
 	let targetEntity = registry.list().find((e) => { try { return samePath(e.path, originalCwd); } catch { return false; } }) ?? null;
 	if (typeof targetWorkspaceId === 'string' && targetWorkspaceId.length > 0) {
@@ -2236,16 +3442,15 @@ async function restoreFromTrashLocked(ctx, sessionId, targetWorkspaceId) {
 		if (!targetEntity) throw new Error(`unknown workspace '${targetWorkspaceId}'`);
 		destPath = targetEntity.path;
 	}
-	if (existsSync(originalArtifact)) {
+	if (originalInfo.exists) {
 		if (!targetEntity || samePath(targetEntity.path, originalCwd)) {
-			throw new Error(`original location is occupied by an archive with the same id: ${originalArtifact}; pass targetWorkspaceId to restore elsewhere`);
+			throw new Error(`original location is occupied by an archive with the same id: ${originalProbe.artifact}; pass targetWorkspaceId to restore elsewhere`);
 		}
 	} else if (!targetEntity) {
 		throw new Error(`original location '${originalCwd}' has no registered workspace; pass targetWorkspaceId to restore into one`);
 	}
 	// 先移回原位（头 cwd 与原位一致，attach 校验天然通过）
-	const bytes = readFileSync(artifactInTrash);
-	moveDir(sessionDir, dirname(originalArtifact));
+	await storage.relocate(trashLocation, dirname(originalLocation.artifact));
 	let restored = { restored: true, sessionId: String(sessionId), cwd: originalCwd, workspaceId: targetEntity?.id ?? null, moved: null };
 	try {
 		if (targetEntity && !samePath(originalCwd, destPath)) {
@@ -2289,7 +3494,7 @@ async function purgeTrash(ctx, { sessionId, all, purgeBackups = false } = {}) {
 }
 
 /**
- * 备份聚合清单：按会话分组（文件名 `${id}.${ts}.zstd`），附投影标题与总占用。
+ * 备份聚合清单：按会话分组，兼容旧文件名和带内容指纹的新快照文件名。
  *
  * 额外标注孤儿组：会话已被彻底删除（或档案已不存在）时，它历次迁移留下的备份
  * 不会再被任何操作引用——`stashBackup` 的 20 份裁剪只在"再次备份同一会话"时触发，
@@ -2301,10 +3506,9 @@ async function listBackups(ctx) {
 	const titles = readProjectionTitles();
 	const groups = new Map();
 	for (const name of readdirSync(dir)) {
-		// 兼容同毫秒去重后缀：`${id}.${ts}.zstd` 与 `${id}.${ts}-${seq}.zstd`
-		const m = /^(.+)\.(\d+)(?:-\d+)?\.zstd$/.exec(name);
-		if (!m) continue;
-		const [, id, ts] = m;
+		const parsed = parseBackupFilename(name);
+		if (!parsed) continue;
+		const { id, ts } = parsed;
 		let sizeBytes = 0;
 		try { sizeBytes = statSync(join(dir, name)).size; } catch { continue; }
 		const g = groups.get(id) ?? { sessionId: id, title: titles.get(id) ?? null, count: 0, totalBytes: 0, oldest: Number(ts), newest: Number(ts), files: [] };
@@ -2312,7 +3516,7 @@ async function listBackups(ctx) {
 		g.totalBytes += sizeBytes;
 		g.oldest = Math.min(g.oldest, Number(ts));
 		g.newest = Math.max(g.newest, Number(ts));
-		g.files.push({ name, ts: Number(ts), sizeBytes });
+		g.files.push({ name, ts: Number(ts), sizeBytes, fingerprint: parsed.fingerprint });
 		groups.set(id, g);
 	}
 
@@ -2332,7 +3536,7 @@ async function listBackups(ctx) {
 	const items = [...groups.values()].map((g) => ({
 		...g,
 		orphan: !alive.has(String(g.sessionId)),
-		files: g.files.sort((x, y) => y.ts - x.ts).map(({ name, ts, sizeBytes }) => ({ name, ts, sizeBytes }))
+		files: g.files.sort((x, y) => y.ts - x.ts || y.name.localeCompare(x.name)).map(({ name, ts, sizeBytes, fingerprint }) => ({ name, ts, sizeBytes, fingerprint }))
 	}));
 	items.sort((a, b) => b.newest - a.newest);
 	const orphanItems = items.filter((it) => it.orphan);
@@ -2361,6 +3565,12 @@ async function restoreBackupLocked(ctx, sessionId, fileName, targetWorkspaceId)
 	const registry = ctx.workspaceRegistry;
 	const persistence = ctx.sessionPersistence;
 	if (!registry || !persistence) throw new Error('workspace registry or session persistence service unavailable');
+	const storage = createPersistenceAdapter(ctx);
+	if (!storage.capabilities.physicalPath) {
+		const err = new Error(`${storage.reason}; physical backup restore is unavailable`);
+		err.code = 'unsupported';
+		throw err;
+	}
 	const dir = backupDir();
 	if (peekService(ctx, 'sessions')?.get?.(sessionId) !== undefined) {
 		throw new Error('a live session with this id exists; restart the harness before restoring');
@@ -2370,17 +3580,19 @@ async function restoreBackupLocked(ctx, sessionId, fileName, targetWorkspaceId)
 	if (existingPath) throw new Error('session id already exists in the workspace registry');
 	let path2 = null;
 	if (typeof fileName === 'string' && fileName.length > 0) {
-		if (!fileName.startsWith(`${sessionId}.`)) throw new Error('backup file does not belong to the given session');
-		path2 = join(dir, basename(fileName));
+		const safeName = basename(fileName);
+		const parsed = parseBackupFilename(safeName);
+		if (!parsed || parsed.id !== String(sessionId)) throw new Error('backup file does not belong to the given session');
+		path2 = join(dir, safeName);
 	} else {
-		const candidates = dirExists(dir)
-			? readdirSync(dir).filter((f) => f.startsWith(`${sessionId}.`)).sort()
-			: [];
+		const candidates = backupFilesFor(sessionId)
+			.sort((a, b) => b.ts - a.ts || String(b.sequence ?? '').localeCompare(String(a.sequence ?? '')))
+			.map((item) => item.name);
 		if (candidates.length === 0) throw new Error(`no backups found for '${sessionId}'`);
-		path2 = join(dir, candidates[candidates.length - 1]);
+		path2 = join(dir, candidates[0]);
 	}
 	if (!existsSync(path2)) throw new Error(`backup file not found: ${path2}`);
-	const compression = persistenceCompression(persistence);
+	const compression = storage.compression;
 	const bytes = readFileSync(path2);
 	const header = readHeader(bytes, compression);
 	if (String(header?.id) !== String(sessionId)) throw new Error(`backup header id mismatch: ${header?.id}`);
@@ -2394,17 +3606,19 @@ async function restoreBackupLocked(ctx, sessionId, fileName, targetWorkspaceId)
 		destCwd = targetEntity.path;
 	}
 	if (!targetEntity) throw new Error(`backup cwd '${backupCwd}' has no registered workspace; pass targetWorkspaceId to restore into one`);
-	const dstDir = sessionDir(persistence.root, destCwd, sessionId);
-	if (findDestinationArtifact(dstDir, compression)) throw new Error(`destination artifact already exists under: ${dstDir}`);
+	const destinationProbe = await storage.locate({ sessionId, cwd: destCwd });
+	if ((await storage.inspect(destinationProbe)).exists) throw new Error(`destination artifact already exists under: ${dirname(destinationProbe.artifact)}`);
+	const dstDir = dirname(destinationProbe.artifact);
 	const dstArtifact = join(dstDir, preferredArtifactName(compression));
+	const destinationLocation = { ...destinationProbe, cwd: destCwd, artifact: dstArtifact };
 	const final = samePath(backupCwd, destCwd) ? bytes : rewriteHeaderCwd(bytes, destCwd, compression);
 	let created = false;
 	try {
 		mkdirSync(dstDir, { recursive: true });
-		atomicWrite(dstArtifact, final);
+		await storage.write(destinationLocation, final);
 		created = existsSync(dstArtifact);
 		// 回读校验：id 与 cwd 双确认后才挂账
-		const verify = readHeader(readFileSync(dstArtifact), compression);
+		const verify = readHeader(await storage.read(destinationLocation), compression);
 		if (String(verify?.id) !== String(sessionId) || !verify?.cwd || !samePath(verify.cwd, destCwd)) {
 			throw new Error('restore verification failed (header round-trip mismatch)');
 		}
@@ -2423,10 +3637,12 @@ async function deleteBackup(ctx, { sessionId, fileName } = {}) {
 	if (!dirExists(dir)) return { deleted: 0 };
 	let targets = [];
 	if (typeof fileName === 'string' && fileName.length > 0) {
-		if (!fileName.startsWith(`${sessionId}.`)) throw new Error('backup file does not belong to the given session');
-		targets = [basename(fileName)];
+		const safeName = basename(fileName);
+		const parsed = parseBackupFilename(safeName);
+		if (!parsed || parsed.id !== String(sessionId)) throw new Error('backup file does not belong to the given session');
+		targets = [safeName];
 	} else {
-		targets = readdirSync(dir).filter((f) => f.startsWith(`${sessionId}.`));
+		targets = backupFilesFor(sessionId).map((item) => item.name);
 	}
 	let deleted = 0;
 	for (const name of targets) {
@@ -2553,7 +3769,7 @@ function createAgentTools(ctx, dispatchRef) {
 		},
 		{
 			name: 'mover_move_session',
-			description: `Move one DSH session into another workspace group with full protection: byte-level backup is taken before anything changes, then the session header is rewritten, the archive directory is moved atomically, the result is verified by re-reading, and any failure rolls everything back automatically. The session keeps its id and full history; a post-move record enables one-click undo. ${SIGNAL_NOTE} Ask the user to confirm the target group before calling, then pass the exact ids from mover_list_sessions.`,
+			description: `Move one DSH session into another workspace group with full protection: byte-level backup is taken before anything changes, then the session header is rewritten, the archive directory is moved atomically, the result is verified by re-reading, and any failure rolls everything back automatically. The session keeps its id and full history; a post-move record enables one-click undo. If the session is running, no file is touched: the move is persisted in the busy queue and the call returns busy with a queueTaskId. ${SIGNAL_NOTE} Ask the user to confirm the target group before calling, then pass the exact ids from mover_list_sessions.`,
 			parameters: {
 				type: 'object',
 				properties: {
@@ -2633,8 +3849,21 @@ async function runDoctor(ctx, agentToolsState) {
 	}
 
 	if (!persistence) fail('host-persistence', 'session persistence service unavailable');
-	else if (typeof persistence.root === 'string' && dirExists(persistence.root)) pass('host-persistence', String(persistence.root));
-	else fail('host-persistence', `sessions root missing: ${persistence.root ?? '(none)'}`);
+	else {
+		const storage = storageDiagnostics(ctx);
+		if (storage.mode === 'filesystem-fallback' && dirExists(persistence.root)) {
+			pass('host-persistence', `${storage.mode}: ${persistence.root}`);
+		} else if (storage.mode === 'official-handle') {
+			pass('host-persistence', `${storage.mode}: public list/stat/open available; physical path unavailable`);
+		} else {
+			fail('host-persistence', `${storage.mode}: ${storage.reason}`);
+		}
+	}
+
+	const storage = storageDiagnostics(ctx);
+	if (storage.mode === 'filesystem-fallback') warn('storage-adapter', storage.reason);
+	else if (storage.mode === 'official-handle') pass('storage-adapter', storage.reason);
+	else fail('storage-adapter', storage.reason);
 
 	const projection = projectionTable(ctx);
 	const projectionRead = typeof projection?.get === 'function';
@@ -2661,7 +3890,8 @@ async function runDoctor(ctx, agentToolsState) {
 	try {
 		const backups = await listBackups(ctx);
 		const orphanNote = backups.orphanGroups > 0 ? `, ${backups.orphanGroups} orphan group(s) (${backups.orphanBytes} bytes)` : '';
-		pass('data-backups', `${backups.items.length} session groups${orphanNote}`);
+		const snapshotCount = backups.items.reduce((sum, item) => sum + Number(item.count || 0), 0);
+		pass('data-backups', `${backups.items.length} session groups, ${snapshotCount} physical snapshot(s)${orphanNote}`);
 	}
 	catch (err) { fail('data-backups', String(err?.message ?? err).slice(0, 140)); }
 
@@ -2671,6 +3901,13 @@ async function runDoctor(ctx, agentToolsState) {
 	try { const tasks = await listTasks(); pass('data-tasks', `${tasks.items?.length ?? 0} records`); }
 	catch (err) { fail('data-tasks', String(err?.message ?? err).slice(0, 140)); }
 
+	try {
+		const queue = migrationQueueSummary();
+		if (queue.error) fail('data-migrations', queue.error.slice(0, 140));
+		else if (queue.pending > 0) warn('data-migrations', `${queue.pending} pending, ${queue.failed} failed, ${queue.done} done`);
+		else pass('data-migrations', `${queue.total} records`);
+	} catch (err) { fail('data-migrations', String(err?.message ?? err).slice(0, 140)); }
+
 	const recovered = recoveryCount();
 	if (recovered === 0) pass('recovery', 'no manual-recovery records');
 	else warn('recovery', `${recovered} record(s) need manual review — see the rescue panel`);
@@ -2678,7 +3915,9 @@ async function runDoctor(ctx, agentToolsState) {
 	// 存储布局自证：把"所有会话突然都找不到"提前变成一条可见的降级提示。
 	try {
 		const layout = await verifyStorageLayout(ctx);
-		if (layout.status === 'ok') pass('data-layout', `derived directory verified (${layout.checked} sample(s))`);
+		if (layout.generationWarning) warn('data-layout', layout.generationWarning);
+		else if (layout.status === 'ok' && layout.physicalPath === false) pass('data-layout', `official provider metadata available (${layout.checked} session(s); physical path adapter unavailable)`);
+		else if (layout.status === 'ok') pass('data-layout', `derived directory verified (${layout.checked} sample(s) via ${layout.adapter ?? 'filesystem'})`);
 		else if (layout.status === 'empty') warn('data-layout', 'no stored sessions to verify against (fresh install?)');
 		else if (layout.status === 'unavailable') warn('data-layout', layout.reason ?? 'storage layout cannot be verified');
 		else warn('data-layout', `storage layout may have changed — ${layout.reason ?? 'no archive found at the derived path'}`);
@@ -2726,6 +3965,7 @@ export function apply(ctx) {
 				case 'mover.status': {
 					const projection = projectionTable(ctx);
 					const layout = await verifyStorageLayout(ctx);
+					const storage = storageDiagnostics(ctx);
 					const capabilities = {
 						registry: Boolean(ctx.workspaceRegistry),
 						persistence: Boolean(ctx.sessionPersistence),
@@ -2739,7 +3979,15 @@ export function apply(ctx) {
 						coordinatorStates: Boolean(peekService(ctx, 'sessionPersistence')?.coordinator?.states),
 						fileReferences: Boolean(peekService(ctx, 'fileReferences')),
 						agents: Boolean(peekService(ctx, 'agents')),
-						storageLayout: layout.status
+						storageLayout: layout.status,
+						storageAdapter: storage.mode,
+						storageApi: storage.capabilities,
+						physicalPath: storage.physicalPath,
+						migrationQueue: true,
+						forkTree: true,
+						portableBundle: true,
+						backupSnapshots: true,
+						migrationQueueState: migrationQueueSummary()
 					};
 					const degradedFeatures = [];
 					if (!capabilities.projectionWrite) degradedFeatures.push('projection-title-restore');
@@ -2749,6 +3997,9 @@ export function apply(ctx) {
 					if (!capabilities.coordinatorStates) degradedFeatures.push('resident-hotfix');
 					if (!capabilities.fileReferences) degradedFeatures.push('file-reference-cleanup');
 					if (layout.status === 'degraded') degradedFeatures.push('storage-layout');
+					if (storage.mode === 'filesystem-fallback') degradedFeatures.push('storage-official-handle');
+					if (!storage.physicalPath) degradedFeatures.push('physical-path-migration');
+					if (capabilities.migrationQueueState.error) degradedFeatures.push('migration-queue-data');
 					return ok({
 						ready: Boolean(capabilities.registry && capabilities.persistence),
 						channel: CHANNEL,
@@ -2786,11 +4037,60 @@ export function apply(ctx) {
 						const targetWorkspaceId = payload?.targetWorkspaceId;
 						if (typeof sessionId !== 'string' || sessionId.length === 0) throw new Error('sessionId required');
 						if (typeof targetWorkspaceId !== 'string' || targetWorkspaceId.length === 0) throw new Error('targetWorkspaceId required');
+						if (payload?.mode === 'include-descendants') {
+							return ok(await moveManySessions(ctx, {
+								sessions: [{ sessionId, sessionTitle: payload?.sessionTitle }],
+								targetWorkspaceId,
+								mode: 'include-descendants'
+							}));
+						}
 						const result = await moveSessionEntry(ctx, { sessionId, targetWorkspaceId, sessionTitle: payload?.sessionTitle });
 						logger.info?.(`workspace-mover: moved ${sessionId} -> ${result.to.cwd}`);
 						return ok(result);
 					} catch (err) {
 						logger.warn?.(`workspace-mover: MOVE FAILED sessionId=${payload?.sessionId} target=${payload?.targetWorkspaceId}: ${err?.message ?? err}`);
+						if (isBusyError(err) && typeof payload?.sessionId === 'string' && typeof payload?.targetWorkspaceId === 'string') {
+							const queued = createOrReuseMigration(ctx, {
+								sessionId: payload.sessionId,
+								targetWorkspaceId: payload.targetWorkspaceId,
+								title: payload.sessionTitle,
+								reason: String(err?.message ?? err)
+							});
+							return fail('busy', String(err?.message ?? err), {
+								queueTaskId: queued.id,
+								queueState: queued.state,
+								sessionId: payload.sessionId,
+								targetWorkspaceId: payload.targetWorkspaceId
+							});
+						}
+						return mapError(err);
+					}
+				}
+				case 'mover.preview': {
+					try {
+						return ok(await inspectMovePlan(ctx, payload ?? {}));
+					} catch (err) {
+						return mapError(err);
+					}
+				}
+				case 'mover.bundle.export': {
+					try {
+						return ok(await exportPortableBundle(ctx, payload ?? {}));
+					} catch (err) {
+						return mapError(err);
+					}
+				}
+				case 'mover.bundle.inspect': {
+					try {
+						return ok(await inspectPortableBundle(ctx, payload ?? {}));
+					} catch (err) {
+						return mapError(err);
+					}
+				}
+				case 'mover.bundle.import': {
+					try {
+						return ok(await importPortableBundle(ctx, payload ?? {}));
+					} catch (err) {
 						return mapError(err);
 					}
 				}
@@ -2889,6 +4189,29 @@ export function apply(ctx) {
 						return mapError(err);
 					}
 				}
+				case 'mover.migrations.enqueue': {
+					try {
+						return ok(await enqueueMigrations(ctx, payload ?? {}));
+					} catch (err) {
+						return mapError(err);
+					}
+				}
+				case 'mover.migrations.list':
+					return ok(await listMigrations(ctx));
+				case 'mover.migrations.retry': {
+					try {
+						return ok(await retryMigration(ctx, payload ?? {}));
+					} catch (err) {
+						return mapError(err);
+					}
+				}
+				case 'mover.migrations.cancel': {
+					try {
+						return ok(await cancelMigration(payload ?? {}));
+					} catch (err) {
+						return mapError(err);
+					}
+				}
 				case 'mover.data.cleanup': {
 					try {
 						return ok(await cleanupOldData(ctx, payload ?? {}));
@@ -2923,6 +4246,7 @@ export function apply(ctx) {
 	}
 
 	registerAgentTools(ctx, dispatchRef, logger, agentToolsState);
+	startMigrationRuntime(ctx, ctx, logger);
 
 	// 官方 Config：**暂不注册**，只导出构造能力。
 	//
@@ -2936,4 +4260,4 @@ export function apply(ctx) {
 	// 环境变量（见 resolvePolicy）与代码默认值驱动，功能完整。
 }
 
-export { name, inject, CHANNEL, projectKey, encodeSegment, sessionDir, artifactPath, generationLogFilename, parseGenerationLogFilename, listGenerationArtifacts, findHighestArtifact, preferredArtifactName, moveDir, stashBackup, verifyRelocatedArtifact, deleteSessionToTrash, moveSession, moveSessionEntry, validId, SCAN_MAX_ITEMS, POLICY_DEFAULTS, resolvePolicy, verifyStorageLayout, rawRecordSessionIds, historyLimit, backupKeep, batchLimit, repointLimit, scanLimit, cleanupDays, Config, POLICY_FIELDS, buildConfig, attachConfig };
+export { name, inject, CHANNEL, projectKey, encodeSegment, sessionDir, artifactPath, generationLogFilename, parseGenerationLogFilename, listGenerationArtifacts, findHighestArtifact, preferredArtifactName, persistenceCapabilities, createPersistenceAdapter, storageDiagnostics, inspectMovePlan, moveDir, stashBackup, verifyRelocatedArtifact, deleteSessionToTrash, moveSession, moveSessionEntry, validId, SCAN_MAX_ITEMS, POLICY_DEFAULTS, resolvePolicy, verifyStorageLayout, rawRecordSessionIds, historyLimit, backupKeep, batchLimit, repointLimit, scanLimit, cleanupDays, Config, POLICY_FIELDS, buildConfig, attachConfig };