dsh-workspace-mover 2.1.1 → 2.3.0

package/lib/index.js

@@ -2,7 +2,7 @@
 //
 // ① 跨工作区「真迁移」原始会话：物理搬移 session.jsonl.zstd、改写头部 cwd、
 //    更新工作区注册表（侧边栏拖拽触发）。会话 id 与历史文件保持原样，
-//    不产生副本，不消耗 token。
+//    不复制第二条注册会话，不消耗 token；恢复快照独立存放在插件数据目录。
 // ② 孤儿会话救援（v0.3）：扫描存储根分类失联/未挂账/幽灵档案，
 //    relink 复用同一条迁移管线换路径重挂，attach 原地补记账。
 //    针对官方讨论 #3012（项目文件夹移动后历史"消失"）的社区修复。
@@ -32,12 +32,14 @@
 //   依赖官方「已记账 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';
 
 const name = 'workspace-mover';
 // tools/approval 由 dsh-tools / dsh-user-approval 提供（dsh-base 默认挂载）；
@@ -49,7 +51,59 @@ 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 HISTORY_LIMIT = 100;
+const migrationRuntimes = new WeakMap();
+
+//#region 可调策略
+/**
+ * 策略读取：**在使用点调用**（与官方 Config 文档"按需读 .get()"的建议一致，
+ * 不在模块顶层冻结），优先级为 插件 Config → 环境变量 → 代码默认值。
+ *
+ * 环境变量是本插件持有的兜底通道：官方 Config 需要 schemastery（宿主 loader 提供，
+ * 插件目录下不可解析），所以任何静态 import 都可能打断 boot。这里只做纯读取，
+ * Config 接入见 lib/config.js。
+ */
+const POLICY_DEFAULTS = {
+	historyLimit: 100,
+	backupKeep: 20,
+	batchLimit: 50,
+	repointLimit: 200,
+	scanLimit: 400,
+	cleanupDays: 30
+};
+/** 环境变量名 → 策略键。 */
+const POLICY_ENV = {
+	DSH_WORKSPACE_MOVER_HISTORY_LIMIT: 'historyLimit',
+	DSH_WORKSPACE_MOVER_BACKUP_KEEP: 'backupKeep',
+	DSH_WORKSPACE_MOVER_BATCH_LIMIT: 'batchLimit',
+	DSH_WORKSPACE_MOVER_REPOINT_LIMIT: 'repointLimit',
+	DSH_WORKSPACE_MOVER_SCAN_LIMIT: 'scanLimit',
+	DSH_WORKSPACE_MOVER_CLEANUP_DAYS: 'cleanupDays'
+};
+
+/** 解析一个正整数策略值；非法/越界一律回退默认（配置错误不应让功能不可用）。 */
+function resolvePolicy(key, min, max) {
+	const raw = process.env[Object.keys(POLICY_ENV).find((env) => POLICY_ENV[env] === key)];
+	if (raw !== undefined && String(raw).trim() !== '') {
+		const n = Number(String(raw).trim());
+		if (Number.isFinite(n) && Number.isInteger(n) && n >= min && n <= max) return n;
+	}
+	return POLICY_DEFAULTS[key];
+}
+
+/** 历史保留条数。 */
+const historyLimit = () => resolvePolicy('historyLimit', 1, 10000);
+/** 每个会话保留的迁移备份份数。 */
+const backupKeep = () => resolvePolicy('backupKeep', 1, 1000);
+/** 单批移动/修复上限。 */
+const batchLimit = () => resolvePolicy('batchLimit', 1, 500);
+/** 单个工作区搬家上限。 */
+const repointLimit = () => resolvePolicy('repointLimit', 1, 5000);
+/** 救援扫描解析上限。 */
+const scanLimit = () => resolvePolicy('scanLimit', 1, 100000);
+/** 数据清理默认天数。 */
+const cleanupDays = () => resolvePolicy('cleanupDays', 1, 3650);
+//#endregion
+
 
 /** 路径等价判断：优先 realpath（大小写别名归一），目录缺失时退化为大小写不敏感字符串比较。 */
 function samePath(a, b) {
@@ -192,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()) {
@@ -362,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}'`);
 	}
@@ -372,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 份）
@@ -380,19 +575,142 @@ function backupDir() {
 	return join(home, 'workspace-mover', 'backups');
 }
 
-function stashBackup(id, buf) {
+/**
+ * New snapshots include a content fingerprint. Legacy timestamp-only names
+ * remain readable so existing user backups are not orphaned by the upgrade.
+ */
+/** 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 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}.${suffix}`);
+		if (!existsSync(candidate)) return candidate;
+	}
+	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 });
+	}
+}
+
+/**
+ * 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(join(dir, `${id}.${Date.now()}.zstd`), buf);
-		// 前缀收紧到 `${id}.`：相邻 id（如 session-x 与 session-x-1）的备份互不误删
-		const keep = readdirSync(dir).filter((f) => f.startsWith(`${id}.`)).sort();
-		while (keep.length > 20) 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');
@@ -411,7 +729,7 @@ function readHistory() {
 function writeHistory(entries) {
 	const path = historyPath();
 	mkdirSync(dirname(path), { recursive: true });
-	atomicWrite(path, Buffer.from(JSON.stringify(entries.slice(-HISTORY_LIMIT), null, 2) + '\n', 'utf8'));
+	atomicWrite(path, Buffer.from(JSON.stringify(entries.slice(-historyLimit()), null, 2) + '\n', 'utf8'));
 }
 
 function rememberMove(result, sourceWorkspaceId, targetWorkspaceId) {
@@ -423,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);
@@ -443,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();
@@ -589,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);
@@ -615,8 +941,7 @@ async function moveSession(ctx, { sessionId, targetWorkspaceId, sessionTitle, re
 	if (samePath(sourceCwd, targetPath)) {
 		// 磁盘头已指向目标：若目标工作区还没记账它（历史遗留的未归组会话），
 		// 自动补上归属而不是报错——用户意图就是「让它归到这个组」。
-		let accounted = false;
-		try { accounted = [...target.record.sessionIds].includes(String(sessionId)); } catch { /* ignore */ }
+		const accounted = rawRecordSessionIds(target).includes(String(sessionId));
 		if (!accounted) {
 			const r = await attachUnregistered(ctx, sessionId);
 			ctx.logger?.info?.(`workspace-mover: self-healed accounting for ${sessionId} -> ${r.workspaceId}`);
@@ -642,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';
@@ -687,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';
@@ -705,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 (!e.record.sessionIds.includes(sessionId)) await e.attachSession?.(sessionId); } catch { /* ignore */ } }
+		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');
@@ -727,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}`);
 	}
 
 	// ---- 内存一致性收尾（版本敏感，降级安全）----
@@ -782,18 +1132,23 @@ 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) {
-				try { if (!e.record.sessionIds.includes(sessionId)) await e.attachSession?.(sessionId); } catch { /* ignore */ }
+				try { if (!rawRecordSessionIds(e).includes(String(sessionId))) await e.attachSession?.(sessionId); } catch { /* ignore */ }
 			}
 		} 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()}`);
@@ -823,7 +1178,8 @@ async function moveSession(ctx, { sessionId, targetWorkspaceId, sessionTitle, re
 		to: { cwd: targetPath, workspaceId: targetWorkspaceId },
 		cacheInvalidated,
 		restartHint,
-		warnings
+		warnings,
+		backup
 	};
 	if (recordHistory) {
 		try {
@@ -847,7 +1203,7 @@ async function listWorkspaces(ctx) {
 		status: undefined,
 		sessionIds: (() => { try { return [...entity.sessionIds]; } catch { return []; } })(),
 		// 原始记账数（含归档与幽灵成员）：空工作区判定必须看原始账本，藏了成员的组不能算空
-		rawSessionCount: (() => { try { return entity.record.sessionIds.length; } catch { return undefined; } })()
+		rawSessionCount: (() => { try { return rawRecordSessionIds(entity).length; } catch { return undefined; } })()
 	}));
 	let archivedSessionIds = [];
 	try { archivedSessionIds = [...registry.archivedSessionIds]; } catch { /* ignore */ }
@@ -855,7 +1211,7 @@ async function listWorkspaces(ctx) {
 }
 
 //#region 孤儿会话救援（v0.3）：扫描分类 + 批量重挂
-const SCAN_MAX_ITEMS = 400;
+const SCAN_MAX_ITEMS = 400; // 默认值（导出用于测试/文档）；实际生效扫描上限见 scanLimit()
 
 function dirExists(p) {
 	if (typeof p !== 'string' || p.length === 0) return false;
@@ -866,6 +1222,163 @@ 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;
+}
+
+/**
+ * 存储布局自证（只读，永不抛错）。
+ *
+ * 本插件的整条管线都建立在两个**未文档化**的假设上：
+ *   ① `persistence.root` 存在（`SessionPersistence` 的文档化接口只有 create/open/stat/list）；
+ *   ② 目录布局等于本地复刻的 `projectKey` / `encodeSegment`（见上面的"最小移植"注释）。
+ * 宿主一旦改变其中任何一项，`sessionDir()` 会静默指向不存在的路径，表现为
+ * "所有会话都找不到"而没有任何线索。
+ *
+ * 这里用真实会话反推一次目录：从 persistence.list() 拿 header，算出它**应该**在的位置，
+ * 再用 findHighestArtifact 验证该位置确实有档案。对不上就是 degraded。
+ *
+ * @returns {{status:'ok'|'degraded'|'empty'|'unavailable', checked:number, path?:string, reason?:string}}
+ */
+async function verifyStorageLayout(ctx) {
+	const persistence = ctx?.sessionPersistence;
+	if (!persistence) return { status: 'unavailable', checked: 0, reason: 'session persistence service unavailable' };
+	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 adapter.list();
+	} catch (err) {
+		return { status: 'unavailable', checked: 0, reason: `persistence.list() failed: ${err?.message ?? err}` };
+	}
+	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 {
+			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) {
+			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,
+		adapter: adapter.mode,
+		physicalPath: true,
+		reason: 'layout-unknown: no session archive found at the derived path — the host storage layout may have changed'
+	};
+}
+
 /**
  * 从投影缓存读会话标题（只读、防御性解析）。侧边栏显示的标题（官方自动命名/重命名）
  * 存在投影缓存里，磁盘档案头对这类会话是空的——标题必须以这里为准才能与侧边栏一致；
@@ -900,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();
@@ -920,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, SCAN_MAX_ITEMS);
-	for (const { artifact, idDir, st } of selected) {
+	const selected = metas.slice(0, scanLimit());
+	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);
@@ -943,7 +1486,7 @@ async function scanSessions(ctx) {
 		// 记账方按原始 record 计算（公开 getter 会过滤掉幽灵 id）；
 		// 「误放」= 有记账方但不是 cwd 匹配的那个工作区（克隆工具、路径漂移、改名后重建分组）。
 		const owners = entities.filter((e) => {
-			try { return [...e.record.sessionIds].includes(sessionId); } catch { return false; }
+			try { return rawRecordSessionIds(e).includes(String(sessionId)); } catch { return false; }
 		});
 		const correctlyOwned = owners.length === 1 && matching !== undefined && owners[0].id === matching.id;
 		const status = header === null ? 'unreadable'
@@ -965,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)
 		});
 	}
@@ -974,7 +1519,7 @@ async function scanSessions(ctx) {
 		let ids = [];
 		// 幽灵正是「有账无档」的 id，而官方公开的 sessionIds getter 会把它们
 		// 按索引过滤掉——必须遍历原始记账 record.sessionIds 才能看见它们。
-		try { ids = [...entity.record.sessionIds]; } catch { continue; }
+		try { ids = rawRecordSessionIds(entity); } catch { continue; }
 		for (const id of ids) {
 			try {
 				if (!existsSync(artifactPath(root, entity.path, id, compression))) ghosts.push({ workspaceId: entity.id, sessionId: String(id) });
@@ -986,6 +1531,7 @@ async function scanSessions(ctx) {
 	return {
 		root,
 		scanned: total,
+		scannedParsed: items.length,
 		truncated: total > items.length,
 		recoveryCount: recoveryCount(),
 		counts: items.reduce((acc, it) => { acc[it.status] = (acc[it.status] ?? 0) + 1; return acc; }, {}),
@@ -997,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;
 	}
 }
 
@@ -1074,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 > 50) throw new Error(`too many sessions in one batch (max 50, got ${sessions.length})`);
+	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) => {
@@ -1090,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) {
@@ -1110,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;
@@ -1131,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);
@@ -1159,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);
@@ -1171,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()
 		});
 	}
@@ -1202,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
 		}))
@@ -1232,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);
@@ -1275,8 +2576,10 @@ async function forgetTask(ctx, { taskId, all } = {}) {
  * 数据保护：按时间清理回收站条目与备份（两项独立判定，互不影响）。
  * dryRun=true 只统计不删除，供确认框展示将释放的数量与空间。
  */
-async function cleanupOldData(ctx, { days = 30, dryRun = false } = {}) {
-	const keepDays = Math.min(3650, Math.max(1, Number(days) || 30)); // 输入钳制：1–3650 天
+async function cleanupOldData(ctx, { days, dryRun = false } = {}) {
+	// 注意：不能写 `{ days = 30 }`——解构默认值会把 undefined 变成 30，
+	// 于是下面的策略回退永远看不到"未传值"，策略配置被默认值静默遮蔽。
+	const keepDays = Math.min(3650, Math.max(1, days === undefined ? cleanupDays() : (Number(days) || cleanupDays()))); // 输入钳制：1–3650 天
 	const cutoff = Date.now() - keepDays * 86400000;
 	let freedBytes = 0;
 	let recyclePurged = 0;
@@ -1298,9 +2601,9 @@ async function cleanupOldData(ctx, { days = 30, dryRun = false } = {}) {
 	const bdir = backupDir();
 	if (dirExists(bdir)) {
 		for (const name of readdirSync(bdir)) {
-			const m = /^(.+)\.(\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; }
@@ -1330,7 +2633,7 @@ async function homeMisfiledSession(ctx, sessionId) {
 	for (const entity of registry.list()) {
 		if (entity.id === home.id) continue;
 		let listed = false;
-		try { listed = [...entity.record.sessionIds].includes(String(sessionId)); } catch { /* ignore */ }
+		try { listed = rawRecordSessionIds(entity).includes(String(sessionId)); } catch { /* ignore */ }
 		if (!listed) continue;
 		try {
 			await entity.detachSession(sessionId);
@@ -1346,7 +2649,7 @@ async function homeMisfiledSession(ctx, sessionId) {
 /** 批量修复入口：relink（换路径真迁移）+ attach（原地补记账）+ home（误放归位）。 */
 async function repairSessions(ctx, actions = []) {
 	if (!Array.isArray(actions)) throw new Error('actions must be an array');
-	if (actions.length > 50) throw new Error('too many actions in one batch (max 50)');
+	if (actions.length > batchLimit()) throw new Error(`too many actions in one batch (max ${batchLimit()})`);
 	const results = [];
 	for (const action of actions) {
 		const sessionId = action?.sessionId;
@@ -1372,7 +2675,7 @@ async function repairSessions(ctx, actions = []) {
 //#endregion
 
 //#region 工作区搬家向导（v0.5）：体检 + 注册表原地重定向 + 成员批量迁移
-const REPOINT_MAX_SESSIONS = 200;
+const REPOINT_MAX_SESSIONS = 200; // 默认值；实际生效上限见 repointLimit()
 
 /** 规范化一个必须真实存在的目录；失败抛用户可读错误。与官方 realpath 唯一性约定一致。 */
 function canonicalDir(p, label) {
@@ -1398,7 +2701,7 @@ async function auditWorkspaces(ctx) {
 			if (typeof entity.status === 'function') status = await entity.status();
 		} catch { /* 保持 stat 兜底结果 */ }
 		let memberCount = 0;
-		try { memberCount = entity.record.sessionIds.length; } catch { /* ignore */ }
+		try { memberCount = rawRecordSessionIds(entity).length; } catch { /* ignore */ }
 		items.push({ workspaceId: entity.id, title: entity.title, path: entity.path, status, memberCount });
 	}
 	return { items };
@@ -1444,14 +2747,24 @@ async function listArchivedSessions(ctx) {
 		});
 	}
 	items.sort((a, b) => String(a.title).localeCompare(String(b.title), 'zh'));
-	return { items, truncated: scan.truncated };
+	// 归档会话通常很旧，而扫描只解析按 mtime 排序的前 SCAN_MAX_ITEMS 条——
+	// 大库上它们会整体从本列表消失。把"扫过多少 / 共多少"如实带出去，
+	// 让 UI 能说明"这里不是全部"，而不是静默展示一个残缺清单。
+	return {
+		items,
+		truncated: scan.truncated,
+		scannedParsed: scan.scannedParsed ?? scan.items.length,
+		scannedTotal: scan.scanned,
+		archivedTotal: archivedIds.size
+	};
 }
 
 /**
- * 取消归档：走官方 registry 的持久状态写通道（与官方 archiveSession 同款
- * enqueueOperation + setState，域 schema 校验兜底），把 id 从 registry 全局归档集移除；
- * 归档从不摘记账槽，取消后自动回到原工作区原位置。带 targetWorkspaceId 且 ≠ 归属时，
- * 接着走常规迁移（备份/历史/撤销/防运行中全套保护）。
+ * 取消归档。优先使用官方文档化的 `registry.unarchiveSession(sessionId)`——
+ * 它的语义与本插件一致（归档从不摘记账槽，因此取消后自动回到原工作区原位置，
+ * 且不需要会话存在性检查）。官方接口不可用时回退到等价的持久状态写通道
+ * （enqueueOperation + setState，与官方 archiveSession 同款）。
+ * 带 targetWorkspaceId 且 ≠ 归属时，接着走常规迁移（备份/历史/撤销/防运行中全套保护）。
  */
 async function unarchiveSession(ctx, { sessionId, targetWorkspaceId } = {}) {
 	if (typeof sessionId !== 'string' || sessionId.length === 0) throw new Error('sessionId required');
@@ -1459,20 +2772,27 @@ async function unarchiveSession(ctx, { sessionId, targetWorkspaceId } = {}) {
 	if (!registry) throw new Error('workspace registry unavailable');
 	const archivedIds = readArchivedIds(registry);
 	if (!archivedIds.includes(sessionId)) throw new Error(`session '${sessionId}' is not archived`);
-	if (typeof registry.enqueueOperation !== 'function' || typeof registry.setState !== 'function' || typeof registry.requireState !== 'function') {
-		throw new Error('host workspace registry exposes no state mutation API; unarchive is unsupported on this DSH version');
-	}
-	await registry.enqueueOperation(async () => {
-		const state = registry.requireState();
-		await registry.setState({
-			...state,
-			archivedSessionIds: state.archivedSessionIds.filter((id) => String(id) !== sessionId)
+
+	if (typeof registry.unarchiveSession === 'function') {
+		// 官方通道：去掉归档集里的 id 即完成任务（记账槽原样保留）。
+		await registry.unarchiveSession(sessionId);
+	} else {
+		if (typeof registry.enqueueOperation !== 'function' || typeof registry.setState !== 'function' || typeof registry.requireState !== 'function') {
+			throw new Error('host workspace registry exposes no state mutation API; unarchive is unsupported on this DSH version');
+		}
+		await registry.enqueueOperation(async () => {
+			const state = registry.requireState();
+			await registry.setState({
+				...state,
+				archivedSessionIds: state.archivedSessionIds.filter((id) => String(id) !== sessionId)
+			});
 		});
-	});
+	}
+
 	let moved = null;
 	if (typeof targetWorkspaceId === 'string' && targetWorkspaceId.length > 0) {
 		const owner = registry.list().find((e) => {
-			try { return [...e.record.sessionIds].includes(sessionId); } catch { return false; }
+			try { return rawRecordSessionIds(e).includes(String(sessionId)); } catch { return false; }
 		});
 		if (!owner || owner.id !== targetWorkspaceId) {
 			moved = await moveSession(ctx, { sessionId, targetWorkspaceId });
@@ -1576,15 +2896,21 @@ async function repointWorkspaceLocked(ctx, { workspaceId, fromPath, newPath, dry
 		if (typeof header?.cwd !== 'string' || !samePath(header.cwd, stalePath)) continue;
 		addAffected(header.id, typeof header.title === 'string' && header.title.trim() ? header.title.trim() : null);
 	}
-	try { for (const id of entity.record.sessionIds) addAffected(id, registry.headers?.get?.(id)?.title ?? null); } catch { /* 记账不可读时以磁盘扫描为准 */ }
+	try { for (const id of rawRecordSessionIds(entity)) addAffected(id, registry.headers?.get?.(id)?.title ?? null); } catch { /* 记账不可读时以磁盘扫描为准 */ }
 
 	const affected = [...byId.entries()].map(([sessionId, title]) => ({ sessionId, title }));
-	if (affected.length > REPOINT_MAX_SESSIONS) {
-		throw new Error(`该工作区牵涉 ${affected.length} 个会话，超出单次上限 ${REPOINT_MAX_SESSIONS}；请分批处理`);
+	if (affected.length > repointLimit()) {
+		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 };
@@ -1617,23 +2943,27 @@ async function repointWorkspaceLocked(ctx, { workspaceId, fromPath, newPath, dry
 			}
 		}
 		try {
-			await entity.mutate((record) => ({
-				...record,
-				path: targetCanon,
-				// 标题跟随文件夹改名：仅当标题仍是旧文件夹名（官方 create 的默认值）时同步；
-				// 用户自定义过的标题原样保留
-				...(typeof record.title === 'string' && record.title.length > 0
-					&& record.title.toLowerCase() === basename(stalePath).toLowerCase()
-					? { title: basename(targetCanon) }
-					: {})
-			}));
+			await entity.mutate((record) => ({ ...record, path: targetCanon }));
 			pathUpdated = true;
+			// 标题跟随文件夹改名：仅当标题仍是旧文件夹名（官方 create 的默认值）时同步，
+			// 用户自定义过的标题原样保留。走官方 entity.setTitle，与 mutate 解耦——
+			// 标题同步失败不应影响已经完成的 path 重定向。
+			try {
+				const currentTitle = entity.title;
+				if (typeof currentTitle === 'string' && currentTitle.length > 0
+					&& currentTitle.toLowerCase() === basename(stalePath).toLowerCase()
+					&& typeof entity.setTitle === 'function') {
+					await entity.setTitle(basename(targetCanon));
+				}
+			} catch (err) {
+				ctx.logger?.warn?.(`workspace-mover: title sync after repoint failed (path is already updated): ${err?.message ?? err}`);
+			}
 			// 剪枝保护网：mutate 若因索引预置失败清掉了某些成员，立即按官方
 			// attach 语义补回（头部已被预置成新路径，校验必过），失败则记入 skipped。
 			try {
 				for (const { sessionId } of affected) {
 					let accounted = false;
-					try { accounted = entity.record.sessionIds.includes(sessionId); } catch { /* ignore */ }
+					try { accounted = rawRecordSessionIds(entity).includes(String(sessionId)); } catch { /* ignore */ }
 					if (!accounted) await entity.attachSession(sessionId);
 				}
 			} catch (err) {
@@ -1663,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 {
@@ -1699,7 +3044,7 @@ async function repointWorkspaceLocked(ctx, { workspaceId, fromPath, newPath, dry
 			}
 			// 旧路径散件（从未记账）落位后补挂账；已记账成员为幂等跳过
 			try {
-				if (!entity.record.sessionIds.includes(sessionId)) await entity.attachSession(sessionId);
+				if (!rawRecordSessionIds(entity).includes(String(sessionId))) await entity.attachSession(sessionId);
 			} catch (err) {
 				throw new Error(`迁移完成但补挂账失败（可在会话修复面板重试）：${err?.message ?? err}`);
 			}
@@ -1778,12 +3123,16 @@ 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()) {
-		try { if ([...e.record.sessionIds].includes(sessionId)) candidates.push(e.path); } catch { /* ignore */ }
+		try { if (rawRecordSessionIds(e).includes(String(sessionId))) candidates.push(e.path); } catch { /* ignore */ }
 	}
 	try { const h = registry.headers?.get?.(sessionId); if (typeof h?.cwd === 'string') candidates.push(h.cwd); } catch { /* ignore */ }
 	try {
@@ -1792,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}'`);
 }
@@ -1856,19 +3206,48 @@ async function modifyArchiveSet(ctx, sessionId, add) {
 	}
 }
 
+/**
+ * 注册表实体上是否存在某个官方文档化的方法（只读探测，永不抛错）。
+ * 用于 mover.status 的能力位：官方接口缺失时插件会静默回退到等价实现，
+ * 从外部看不出差异，因此必须显式可观测。
+ */
+function hasEntityApi(registry, method) {
+	try {
+		const first = registry?.list?.()?.[0];
+		return typeof first?.[method] === 'function';
+	} catch {
+		return false;
+	}
+}
+
 /** 非空字符串 id 校验（≤300 字符）。 */
-function validId(value, name = 'id') {
-	if (typeof value !== 'string' || value.length === 0 || value.length > 300) {
+function validId(value, name = 'id') {	if (typeof value !== 'string' || value.length === 0 || value.length > 300) {
 		throw new Error(`${name} must be a non-empty string of at most 300 characters`);
 	}
 	return value;
 }
 
+/**
+ * 读取工作区实体的**原始**记账名单（含幽灵 id）。
+ *
+ * 这是本插件唯一允许触碰的私有成员：官方公开的 `sessionIds` getter 会按
+ * canonical-cwd 索引过滤掉"有账无档"的幽灵 id，而救援扫描正是要看见它们。
+ * 官方 `Workspace` 接口没有等价的未过滤视图，因此这里集中收敛为一个访问器——
+ * 未来宿主改变内部结构时只需改这一处，而不是散落全文件的 15 个 `try/catch`。
+ * 读取失败返回空数组（与"无记账"同义，调用方按只读处理）。
+ */
+function rawRecordSessionIds(entity) {
+	try {
+		const ids = entity?.record?.sessionIds;
+		return Array.isArray(ids) ? ids.map(String) : [...ids].map(String);
+	} catch {
+		return [];
+	}
+}
+
 /** 扫描所有记账该会话的实体（只读，不改动）。 */
 function listOwners(registry, sessionId) {
-	return registry.list().filter((e) => {
-		try { return [...e.record.sessionIds].includes(sessionId); } catch { return false; }
-	});
+	return registry.list().filter((e) => rawRecordSessionIds(e).includes(String(sessionId)));
 }
 
 /** 从所有记账方摘除会话（moveSession 的 owners 扫描同款），返回被摘实体。 */
@@ -1903,14 +3282,14 @@ async function deleteSessionToTrash(ctx, payload = {}, hooks = {}) {
 	const sessionId = validId(payload?.sessionId, 'sessionId');
 	const release = acquireLocks(`session:${sessionId}`);
 	try {
-		return await deleteSessionToTrashLocked(ctx, sessionId, hooks);
+		return await deleteSessionToTrashLocked(ctx, sessionId, { ...hooks, purgeBackups: payload?.purgeBackups === true });
 	} finally {
 		release();
 	}
 }
 
 async function deleteSessionToTrashLocked(ctx, sessionId, hooks = {}) {
-	const { moveImpl = moveDir, writeManifestImpl = (path, manifest) => writeFileSync(path, JSON.stringify(manifest, null, 2)) } = hooks;
+	const { moveImpl = moveDir, writeManifestImpl = (path, manifest) => writeFileSync(path, JSON.stringify(manifest, null, 2)), purgeBackups = false } = hooks;
 	const registry = ctx.workspaceRegistry;
 	const persistence = ctx.sessionPersistence;
 	if (!registry || !persistence) throw new Error('workspace registry or session persistence service unavailable');
@@ -1918,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);
@@ -1929,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}`);
@@ -1949,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,
@@ -1965,7 +3347,10 @@ async function deleteSessionToTrashLocked(ctx, sessionId, hooks = {}) {
 	forgetSessionIndexes(registry, sessionId);
 	if (archived) await modifyArchiveSet(ctx, sessionId, false);
 	await dropProjection(ctx, String(sessionId));
-	return { deleted: true, sessionId: String(sessionId), title: manifest.title, how };
+	// 可选：连同该会话的迁移备份一起清掉（默认保留——回收站还原后仍可能要用）。
+	let backupsDeleted = 0;
+	if (purgeBackups) backupsDeleted = (await deleteBackup(ctx, { sessionId: String(sessionId) })).deleted;
+	return { deleted: true, sessionId: String(sessionId), title: manifest.title, how, backupsDeleted };
 }
 
 function readTrashEntry(entryDir) {
@@ -2015,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;
@@ -2025,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) {
@@ -2048,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)) {
@@ -2078,10 +3471,11 @@ async function restoreFromTrashLocked(ctx, sessionId, targetWorkspaceId) {
 }
 
 /** 彻底删除：rm 回收站条目。all=true 清空。 */
-async function purgeTrash(ctx, { sessionId, all } = {}) {
+async function purgeTrash(ctx, { sessionId, all, purgeBackups = false } = {}) {
 	const dir = recycleDir();
-	if (!dirExists(dir)) return { purged: 0 };
+	if (!dirExists(dir)) return { purged: 0, backupsDeleted: 0 };
 	let purged = 0;
+	let backupsDeleted = 0;
 	for (const entry of readdirSync(dir)) {
 		const entryDir = join(dir, entry);
 		if (!dirExists(entryDir)) continue;
@@ -2089,21 +3483,32 @@ async function purgeTrash(ctx, { sessionId, all } = {}) {
 		if (all || (typeof sessionId === 'string' && manifest?.sessionId === String(sessionId))) {
 			rmSync(entryDir, { recursive: true, force: true });
 			purged++;
+			// 彻底删除（不可还原）时才顺带清备份：留在回收站里的会话仍可能靠备份兜底。
+			if (purgeBackups && manifest?.sessionId) {
+				try { backupsDeleted += (await deleteBackup(ctx, { sessionId: String(manifest.sessionId) })).deleted; }
+				catch { /* 备份清理失败不影响回收站条目已删除的事实 */ }
+			}
 		}
 	}
-	return { purged };
+	return { purged, backupsDeleted };
 }
 
-/** 备份聚合清单：按会话分组（文件名 `${id}.${ts}.zstd`），附投影标题与总占用。 */
+/**
+ * 备份聚合清单：按会话分组，兼容旧文件名和带内容指纹的新快照文件名。
+ *
+ * 额外标注孤儿组：会话已被彻底删除（或档案已不存在）时，它历次迁移留下的备份
+ * 不会再被任何操作引用——`stashBackup` 的 20 份裁剪只在"再次备份同一会话"时触发，
+ * 所以这些字节会永久留在磁盘上。标出来用户才可能清掉。
+ */
 async function listBackups(ctx) {
 	const dir = backupDir();
-	if (!dirExists(dir)) return { items: [], totalBytes: 0, dir };
+	if (!dirExists(dir)) return { items: [], totalBytes: 0, dir, orphanBytes: 0, orphanGroups: 0 };
 	const titles = readProjectionTitles();
 	const groups = new Map();
 	for (const name of readdirSync(dir)) {
-		const m = /^(.+)\.(\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: [] };
@@ -2111,15 +3516,37 @@ 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);
 	}
+
+	// 存活集合：注册表原始记账 ∪ 持久化档案头。任一命中都视为"会话仍在"。
+	const alive = new Set();
+	try {
+		for (const entity of ctx.workspaceRegistry?.list?.() ?? []) {
+			for (const id of rawRecordSessionIds(entity)) alive.add(String(id));
+		}
+	} catch { /* 注册表不可用：只靠档案头判断 */ }
+	try {
+		for (const header of await listPersistenceHeaders(ctx.sessionPersistence)) {
+			if (header?.id !== undefined) alive.add(String(header.id));
+		}
+	} catch { /* 持久化不可用：只靠记账判断 */ }
+
 	const items = [...groups.values()].map((g) => ({
 		...g,
-		files: g.files.sort((x, y) => y.ts - x.ts).map(({ name, ts, sizeBytes }) => ({ name, ts, sizeBytes }))
+		orphan: !alive.has(String(g.sessionId)),
+		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);
-	return { items, totalBytes: items.reduce((sum, it) => sum + it.totalBytes, 0), dir };
+	const orphanItems = items.filter((it) => it.orphan);
+	return {
+		items,
+		totalBytes: items.reduce((sum, it) => sum + it.totalBytes, 0),
+		orphanGroups: orphanItems.length,
+		orphanBytes: orphanItems.reduce((sum, it) => sum + it.totalBytes, 0),
+		dir
+	};
 }
 
 /** 从备份恢复会话：默认回备份里的原 cwd；占用/缺分组时给 targetWorkspaceId。回读校验。 */
@@ -2138,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');
@@ -2147,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}`);
@@ -2171,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)');
 		}
@@ -2200,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) {
@@ -2286,10 +3725,11 @@ const JSON_TEXT = (args, value) => [{ type: 'text', text: JSON.stringify(value)
 const LIST_MAX_SESSIONS = 40;
 
 /**
- * 构造三个 agent 工具（复用 RPC dispatch：锁、错误码、事务语义与面板完全一致）：
+ * 构造四个 agent 工具（复用 RPC dispatch：锁、错误码、事务语义与面板完全一致）：
  * - mover_list_sessions   只读：会话/分组清单，供模型把用户口中的名字解析成精确 id
  * - mover_move_session    迁移单个会话（审批门）
  * - mover_repair_sessions 一键修复（审批门，只动记账不动文件）
+ * - mover_doctor          只读自检（无审批门）
  */
 function createAgentTools(ctx, dispatchRef) {
 	const SIGNAL_NOTE = 'Cancellation is cooperative: the in-flight step finishes rolling back to a consistent state before stopping.';
@@ -2329,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: {
@@ -2409,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';
@@ -2434,7 +3887,12 @@ async function runDoctor(ctx, agentToolsState) {
 	try { const trash = await listTrash(ctx); pass('data-recycle', `${trash.items.length} entries`); }
 	catch (err) { fail('data-recycle', String(err?.message ?? err).slice(0, 140)); }
 
-	try { const backups = await listBackups(ctx); pass('data-backups', `${backups.items.length} session groups`); }
+	try {
+		const backups = await listBackups(ctx);
+		const orphanNote = backups.orphanGroups > 0 ? `, ${backups.orphanGroups} orphan group(s) (${backups.orphanBytes} bytes)` : '';
+		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)); }
 
 	try { const history = await listHistory(); pass('data-history', `${history.items?.length ?? 0} records`); }
@@ -2443,10 +3901,30 @@ 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`);
 
+	// 存储布局自证：把"所有会话突然都找不到"提前变成一条可见的降级提示。
+	try {
+		const layout = await verifyStorageLayout(ctx);
+		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'}`);
+	} catch (err) {
+		warn('data-layout', String(err?.message ?? err).slice(0, 140));
+	}
+
 	if (!registry) warn('workspaces', 'skipped — registry unavailable');
 	else {
 		let total = 0;
@@ -2486,26 +3964,48 @@ export function apply(ctx) {
 			switch (endpoint) {
 				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),
 						projectionRead: typeof projection?.get === 'function',
 						projectionWrite: typeof projection?.put === 'function' && typeof projection?.delete === 'function',
 						archiveChannel: typeof ctx.workspaceRegistry?.enqueueOperation === 'function',
+						// v2.2 起优先使用的官方文档化接口。是否走官方通道必须**可观测**：
+						// 缺失时会静默回退到等价实现（功能不变），但从外部看不出差异。
+						unarchiveApi: typeof ctx.workspaceRegistry?.unarchiveSession === 'function',
+						setTitleApi: hasEntityApi(ctx.workspaceRegistry, 'setTitle'),
 						coordinatorStates: Boolean(peekService(ctx, 'sessionPersistence')?.coordinator?.states),
 						fileReferences: Boolean(peekService(ctx, 'fileReferences')),
-						agents: Boolean(peekService(ctx, 'agents'))
+						agents: Boolean(peekService(ctx, 'agents')),
+						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');
 					if (!capabilities.archiveChannel) degradedFeatures.push('archive-set-changes');
+					if (!capabilities.unarchiveApi) degradedFeatures.push('unarchive-official-api');
+					if (!capabilities.setTitleApi) degradedFeatures.push('set-title-official-api');
 					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,
 						capabilities,
 						degradedFeatures,
+						storageLayout: layout,
 						agentTools: agentToolsState.registered,
 						recoveryCount: recoveryCount()
 					});
@@ -2537,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);
 					}
 				}
@@ -2640,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 ?? {}));
@@ -2674,6 +4246,18 @@ export function apply(ctx) {
 	}
 
 	registerAgentTools(ctx, dispatchRef, logger, agentToolsState);
+	startMigrationRuntime(ctx, ctx, logger);
+
+	// 官方 Config：**暂不注册**，只导出构造能力。
+	//
+	// 官方 schema 来自 @deepseek-ai/schemastery，由宿主 loader 提供；本插件目录下
+	// 实测无法解析该模块（npm 上的 schemastery 也没有 .volatile）。而静态 import
+	// 一个不可解析的模块会打断 **boot**（官方记录的 bundle 层事故类别）。
+	//
+	// 因此这里刻意不向任何未文档化的服务名做 inject——那只会让 fiber 处于半装载
+	// 状态。setup 已经就绪：宿主一旦提供文档化的 schema 接缝，把构造器交给
+	// lib/config.js 的 buildConfig() 即可（已单测覆盖）。在此之前，全部策略都由
+	// 环境变量（见 resolvePolicy）与代码默认值驱动，功能完整。
 }
 
-export { name, inject, CHANNEL, projectKey, encodeSegment, sessionDir, artifactPath, generationLogFilename, parseGenerationLogFilename, listGenerationArtifacts, findHighestArtifact, preferredArtifactName, moveDir, stashBackup, verifyRelocatedArtifact, deleteSessionToTrash, moveSession, moveSessionEntry, validId, SCAN_MAX_ITEMS };
+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 };