dsh-workspace-mover 2.1.1 → 2.2.0

package/lib/index.js

@@ -38,6 +38,7 @@ import { zstdDecompressSync, zstdCompressSync, constants } from 'node:zlib';
 import { join, dirname, basename } 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 +50,58 @@ 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;
+
+//#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) {
@@ -380,14 +432,42 @@ function backupDir() {
 	return join(home, 'workspace-mover', 'backups');
 }
 
+/**
+ * 备份文件名：`${id}.${epochMs}[-seq].zstd`。
+ *
+ * 为什么需要 `-seq`：毫秒时间戳不足以区分同一毫秒内的两次备份，而 Linux 的时钟/文件系统
+ * 时间戳粒度比 Windows 粗得多，连续两次 stash 极可能落在同一毫秒。此时文件名相撞，
+ * 第二次会**覆盖**第一次——用户配置的保留份数（backupKeep）于是静默失效，实际只留下
+ * 一份。这不是假设：CI 的 ubuntu / macos 作业就是这样挂掉的。
+ *
+ * 命名规则：
+ * - 无 `-seq`：`atomicWrite` 的 temp+rename 是覆盖语义，等于"同毫秒最后一次胜出"，
+ *   同时把该毫秒的文件数限制为 1（保留原有测试断言的"同毫秒覆盖"行为，也避免浪费空间）。
+ * - 带 `-seq`：该毫秒已被占用时递增，保证每次调用都留下独立的备份文件。
+ * 两种形态的排序都保持近似的"旧→新"顺序（`-` = 0x2D < `.` = 0x2E，所以 `ts` 排在
+ * `ts-seq` 之前，`ts-seq2` 又排在 `ts-seq10` 之前——同一毫秒内顺序仅影响裁剪，不影响正确性）。
+ */
+function backupPath(id) {
+	const dir = backupDir();
+	const ts = Date.now();
+	const base = join(dir, `${id}.${ts}.zstd`);
+	if (!existsSync(base)) return base;
+	for (let seq = 2; seq < 1000; seq++) {
+		const candidate = join(dir, `${id}.${ts}-${seq}.zstd`);
+		if (!existsSync(candidate)) return candidate;
+	}
+	// 极端情况：同一毫秒 1000 次备份。退化为加序号强制唯一，绝不覆盖既有备份。
+	return join(dir, `${id}.${ts}-${Math.random().toString(36).slice(2, 8)}.zstd`);
+}
+
 function stashBackup(id, buf) {
 	try {
 		const dir = backupDir();
 		mkdirSync(dir, { recursive: true });
-		atomicWrite(join(dir, `${id}.${Date.now()}.zstd`), buf);
+		atomicWrite(backupPath(id), 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 });
+		while (keep.length > backupKeep()) rmSync(join(dir, keep.shift()), { force: true });
 	} catch (err) {
 		throw new Error(`backup failed (refusing to move without a stash): ${err?.message ?? err}`);
 	}
@@ -411,7 +491,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) {
@@ -615,8 +695,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}`);
@@ -707,7 +786,7 @@ async function moveSession(ctx, { sessionId, targetWorkspaceId, sessionTitle, re
 	try {
 		atomicWrite(srcArtifact, 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}`);
 	}
 
@@ -788,7 +867,7 @@ async function moveSession(ctx, { sessionId, targetWorkspaceId, sessionTitle, re
 			// 索引无需再清：非常驻路径在收尾时已清空、由源 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, {
@@ -847,7 +926,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 +934,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 +945,58 @@ function dirExists(p) {
 	}
 }
 
+/**
+ * 存储布局自证（只读，永不抛错）。
+ *
+ * 本插件的整条管线都建立在两个**未文档化**的假设上：
+ *   ① `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 root = persistence.root;
+	if (typeof root !== 'string' || root.length === 0) {
+		return { status: 'degraded', checked: 0, reason: 'persistence backend exposes no root' };
+	}
+	let headers;
+	try {
+		headers = await listPersistenceHeaders(persistence);
+	} catch (err) {
+		return { status: 'unavailable', checked: 0, reason: `persistence.list() failed: ${err?.message ?? err}` };
+	}
+	if (headers.length === 0) return { status: 'empty', checked: 0, path: root };
+	const compression = persistenceCompression(persistence);
+	// 取最新几条做样本：编码边界（多字节/分隔符/驱动器号）更容易在其中一条上暴露
+	const 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);
+		try {
+			if (findHighestArtifact(expectedDir, compression)) {
+				return { status: 'ok', checked: sample.length, path: root };
+			}
+		} catch (err) {
+			// 混合压缩编码等显式拒绝：布局本身可能是对的，但当前配置读不了它
+			return { status: 'degraded', checked: sample.length, path: root, reason: `cannot read derived directory: ${err?.message ?? err}` };
+		}
+	}
+	return {
+		status: 'degraded',
+		checked: sample.length,
+		path: root,
+		reason: 'no session archive found at the layout this plugin derives — the host storage layout may have changed'
+	};
+}
+
 /**
  * 从投影缓存读会话标题（只读、防御性解析）。侧边栏显示的标题（官方自动命名/重命名）
  * 存在投影缓存里，磁盘档案头对这类会话是空的——标题必须以这里为准才能与侧边栏一致；
@@ -931,7 +1062,7 @@ async function scanSessions(ctx) {
 		}
 	}
 	metas.sort((a, b) => b.st.mtimeMs - a.st.mtimeMs);
-	const selected = metas.slice(0, SCAN_MAX_ITEMS);
+	const selected = metas.slice(0, scanLimit());
 	for (const { artifact, idDir, st } of selected) {
 		seenArtifacts.add(artifact);
 		let header = null;
@@ -943,7 +1074,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'
@@ -974,7 +1105,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 +1117,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; }, {}),
@@ -1077,7 +1209,7 @@ async function attachUnregistered(ctx, sessionId) {	const registry = ctx.workspa
 /** 批量迁移入口：逐会话复用 moveSession（各自独立备份/回滚，单条失败不牵连其余）；历史聚合成一条。 */
 async function moveManySessions(ctx, { sessions, targetWorkspaceId } = {}) {
 	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');
 	// 批内去重：同一会话在一次批量里只处理一次
 	const seenIds = new Set();
@@ -1275,8 +1407,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,7 +1432,8 @@ 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);
+			// 兼容同毫秒去重后缀：`${id}.${ts}.zstd` 与 `${id}.${ts}-${seq}.zstd`
+			const m = /^(.+)\.(\d+)(?:-\d+)?\.zstd$/.exec(name);
 			if (!m) continue;
 			const ts = Number(m[2]);
 			if (!(ts < cutoff)) continue;
@@ -1330,7 +1465,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 +1481,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 +1507,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 +1533,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 +1579,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 +1604,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,11 +1728,11 @@ 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;
@@ -1617,23 +1769,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) {
@@ -1699,7 +1855,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}`);
 			}
@@ -1783,7 +1939,7 @@ async function locateArtifact(ctx, sessionId) {
 	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 {
@@ -1856,19 +2012,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 +2088,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');
@@ -1965,7 +2150,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) {
@@ -2078,10 +2266,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,19 +2278,31 @@ 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`），附投影标题与总占用。 */
+/**
+ * 备份聚合清单：按会话分组（文件名 `${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);
+		// 兼容同毫秒去重后缀：`${id}.${ts}.zstd` 与 `${id}.${ts}-${seq}.zstd`
+		const m = /^(.+)\.(\d+)(?:-\d+)?\.zstd$/.exec(name);
 		if (!m) continue;
 		const [, id, ts] = m;
 		let sizeBytes = 0;
@@ -2114,12 +2315,34 @@ async function listBackups(ctx) {
 		g.files.push({ name, ts: Number(ts), sizeBytes });
 		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,
+		orphan: !alive.has(String(g.sessionId)),
 		files: g.files.sort((x, y) => y.ts - x.ts).map(({ name, ts, sizeBytes }) => ({ name, ts, sizeBytes }))
 	}));
 	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。回读校验。 */
@@ -2286,10 +2509,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.';
@@ -2434,7 +2658,11 @@ 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)` : '';
+		pass('data-backups', `${backups.items.length} session groups${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`); }
@@ -2447,6 +2675,17 @@ async function runDoctor(ctx, agentToolsState) {
 	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.status === 'ok') pass('data-layout', `derived directory verified (${layout.checked} sample(s))`);
+		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 +2725,36 @@ export function apply(ctx) {
 			switch (endpoint) {
 				case 'mover.status': {
 					const projection = projectionTable(ctx);
+					const layout = await verifyStorageLayout(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
 					};
 					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');
 					return ok({
 						ready: Boolean(capabilities.registry && capabilities.persistence),
 						channel: CHANNEL,
 						capabilities,
 						degradedFeatures,
+						storageLayout: layout,
 						agentTools: agentToolsState.registered,
 						recoveryCount: recoveryCount()
 					});
@@ -2674,6 +2923,17 @@ export function apply(ctx) {
 	}
 
 	registerAgentTools(ctx, dispatchRef, logger, agentToolsState);
+
+	// 官方 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, 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 };