dsh-workspace-mover 2.0.3 → 2.1.1

package/docs/ARCHITECTURE.md

@@ -53,6 +53,20 @@ Single logical channel `/workspace-mover` via `ctx.connection.rpc.handle('/works
 
 Errors carry stable codes (`busy`, `conflict`, `not-found`, `rollback-failed`, …). Host logs write failures under `MOVE FAILED`.
 
+## Agent tools (DSH ≥ 0.1.5 with `dsh-tools`)
+
+When the host provides the `tools` service, `apply()` registers three plain (zero-dependency) tool definitions; each tool's execute re-enters the internal RPC dispatch, so agent calls share the panel's locks, error codes, and transaction semantics:
+
+| Tool | Gate | Purpose |
+| --- | --- | --- |
+| `mover_list_sessions` | none (read-only) | Compose scan + workspace list (sessions capped at 40, counts, ghosts, recoveryCount) for id resolution |
+| `mover_move_session` | user approval | Move one session (`sessionId`, `targetWorkspaceId`, optional `sessionTitle`) |
+| `mover_repair_sessions` | user approval | One `mover.repairAll` pass (accounting-only) |
+
+- Mutating tools call `ctx.approval.request({ agent, toolName, reason, signal })` before acting; `allowed-once` proceeds, anything else (`denied` / `cancelled` / `unavailable`) or a throwing seam fails closed. Hosts without the approval seam (no UI) rely on conversational confirmation and proceed.
+- `exec.signal` propagates into the RPC layer; cancellation lets the in-flight step finish rolling back to a consistent state.
+- Hosts without `dsh-tools` skip registration silently; `mover.status` reports the `agentTools` flag.
+
 ## Session archives (v3)
 
 - Naming: `session.v3.jsonl.zstd` or `session.v3.jsonl` (highest generation wins).
@@ -65,8 +79,8 @@ Order of operations for a cross-workspace move:
 
 1. **Running check** — reject only mid-turn sessions (`agents.get(id)?.status === 'running'`); idle resident sessions may move.
 2. **Read authority header** from disk; verify target ≠ source.
-3. **Preflight** — dual-accounting detect, target writability probe, disk-space hint.
-4. **Byte backup** to `$DSH_HOME/workspace-mover/backups/` (rolling 20 per session) **before any side effect**.
+3. **Byte backup** to `$DSH_HOME/workspace-mover/backups/` (rolling 20 per session) **before any side effect** — a backup failure aborts with `backup-failed` and nothing has been touched.
+4. **Preflight** — dual-accounting detect, target writability probe, disk-space hint.
 5. **Rewrite first frame** (header cwd) only.
 6. **Move directory** (Windows: exponential-backoff retry on EPERM; fallback copy+delete).
 7. **In-memory closeout** — invalidate three registry indexes; for resident sessions clear stale persistence-coordinator write state; retarget live header `cwd` before official `attachSession`.

package/lib/index.js

@@ -40,7 +40,9 @@ import { homedir } from 'node:os';
 import { spawn } from 'node:child_process';
 
 const name = 'workspace-mover';
-const inject = ['workspaceRegistry', 'sessionPersistence'];
+// tools/approval 由 dsh-tools / dsh-user-approval 提供（dsh-base 默认挂载）；
+// 缺失时 Inject.resolve 填 null，agent 工具与审批门相应降级。
+const inject = ['workspaceRegistry', 'sessionPersistence', 'tools', 'approval'];
 
 const CHANNEL = '/workspace-mover';
 const ZSTD_MAGIC = 4247762216;
@@ -145,22 +147,22 @@ function listGenerationArtifacts(dir) {
 	return out.sort((a, b) => b.version - a.version || a.name.localeCompare(b.name));
 }
 
-function findHighestArtifact(dir, compression = 'zstd') {
-	const entries = listGenerationArtifacts(dir);
-	const encodings = new Set(entries.map((entry) => entry.compression));
-	if (encodings.size > 1) {
-		const err = new Error(`mixed session compression encodings under: ${dir}`);
-		err.code = 'unsupported';
-		throw err;
-	}
-	if (entries.length > 0 && !encodings.has(compression)) {
-		const actual = [...encodings][0];
-		const err = new Error(`session compression ${actual} does not match configured ${compression} under: ${dir}`);
-		err.code = 'unsupported';
-		throw err;
-	}
-	return entries[0] ?? null;
-}
+function findHighestArtifact(dir, compression = 'zstd') {
+	const entries = listGenerationArtifacts(dir);
+	const encodings = new Set(entries.map((entry) => entry.compression));
+	if (encodings.size > 1) {
+		const err = new Error(`mixed session compression encodings under: ${dir}`);
+		err.code = 'unsupported';
+		throw err;
+	}
+	if (entries.length > 0 && !encodings.has(compression)) {
+		const actual = [...encodings][0];
+		const err = new Error(`session compression ${actual} does not match configured ${compression} under: ${dir}`);
+		err.code = 'unsupported';
+		throw err;
+	}
+	return entries[0] ?? null;
+}
 
 function preferredArtifactName(compression = 'zstd') {
 	return generationLogFilename(CURRENT_GENERATION, compression);
@@ -2245,8 +2247,232 @@ async function repairAllSessions(ctx) {
 	};
 }
 
+//#region agent tools（v2.1）：把救援/迁移能力暴露给模型
+// 注册的是裸 ToolDefinition 对象（零依赖）：dsh-tools 的 register 只要求
+// { name, description, parameters(JSON Schema), output:{schema, render}, execute }；
+// defineTool 只是参数校验语法糖，execute 内自行做轻校验即可。
+// 变更类工具统一走 ctx.approval.request（dsh-user-approval，dsh-base 默认挂载）
+// 弹用户确认——与面板 confirm 同级的人审；接缝缺失时降级为模型对话纪律。
+
+/** 通过审批接缝请求用户确认；未获准（denied/cancelled/unavailable）一律抛错拒绝。 */
+async function approveOrThrow(ctx, exec, toolName, reason) {
+	const approval = ctx?.approval;
+	if (!exec?.agent || typeof approval?.request !== 'function') return; // 无审批接缝（如无 UI 宿主）：由模型对话纪律兜底
+	let outcome;
+	try {
+		outcome = await approval.request({ agent: exec.agent, toolName, reason, signal: exec.signal });
+	} catch (err) {
+		// request 在回合外等异常情况会抛错：按未批准处理，不静默放行
+		throw new Error(`${toolName} approval could not be requested (${err?.message ?? err}); use the rescue panel in settings instead`);
+	}
+	if (outcome !== 'allowed-once') {
+		throw new Error(`user did not approve this ${toolName} call (outcome: ${outcome ?? 'unavailable'}); ask the user first and only retry after they agree, or use the rescue panel in settings`);
+	}
+}
+
+/** 统一把 dispatch 的 {ok:false,error} 信封转成模型可见的异常（错误码随行）。 */
+async function callDispatch(dispatchRef, endpoint, payload, signal) {
+	if (typeof dispatchRef?.fn !== 'function') throw new Error('workspace-mover RPC is not mounted on this host; the rescue panel is unavailable too');
+	const res = await dispatchRef.fn(endpoint, payload ?? {}, signal);
+	if (!res?.ok) {
+		const err = new Error(`[${res?.error?.code ?? 'internal-error'}] ${res?.error?.message ?? 'request failed'}`);
+		err.code = res?.error?.code;
+		throw err;
+	}
+	return res.value;
+}
+
+const JSON_TEXT = (args, value) => [{ type: 'text', text: JSON.stringify(value) }];
+const LIST_MAX_SESSIONS = 40;
+
+/**
+ * 构造三个 agent 工具（复用 RPC dispatch：锁、错误码、事务语义与面板完全一致）：
+ * - mover_list_sessions   只读：会话/分组清单，供模型把用户口中的名字解析成精确 id
+ * - mover_move_session    迁移单个会话（审批门）
+ * - mover_repair_sessions 一键修复（审批门，只动记账不动文件）
+ */
+function createAgentTools(ctx, dispatchRef) {
+	const SIGNAL_NOTE = 'Cancellation is cooperative: the in-flight step finishes rolling back to a consistent state before stopping.';
+	const tools = [
+		{
+			name: 'mover_list_sessions',
+			description: 'List DSH workspace groups and their sessions for the workspace-mover plugin. Read-only. Returns workspace ids/titles/paths, per-session id/title/path/rescue status (ok / orphaned / unregistered / misfiled / unreadable), aggregate counts, and how many records need manual recovery. Use it to resolve a user-named group or conversation into the exact ids required by mover_move_session and mover_repair_sessions.',
+			parameters: { type: 'object', properties: {}, additionalProperties: false },
+			output: { schema: { type: 'object' }, render: JSON_TEXT },
+			isConcurrencySafe: () => true,
+			timeoutMs: 30000,
+			async execute(args, exec) {
+				const scan = await callDispatch(dispatchRef, 'mover.scan', {}, exec?.signal);
+				const ws = await callDispatch(dispatchRef, 'mover.workspaces', {}, exec?.signal);
+				const sessions = (scan.items ?? []).slice(0, LIST_MAX_SESSIONS).map((it) => ({
+					sessionId: it.sessionId,
+					title: it.title,
+					cwd: it.cwd,
+					status: it.status,
+					ownerWorkspaceIds: it.ownerWorkspaceIds ?? []
+				}));
+				return {
+					workspaces: (ws.items ?? []).map((w) => ({
+						workspaceId: w.workspaceId,
+						title: w.title,
+						path: w.path,
+						sessionCount: Array.isArray(w.sessionIds) ? w.sessionIds.length : undefined
+					})),
+					sessions,
+					counts: scan.counts ?? {},
+					scanned: scan.scanned,
+					truncated: Boolean(scan.truncated) || (scan.items?.length ?? 0) > LIST_MAX_SESSIONS,
+					recoveryCount: scan.recoveryCount ?? 0,
+					ghosts: (scan.ghosts ?? []).slice(0, 20)
+				};
+			}
+		},
+		{
+			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.`,
+			parameters: {
+				type: 'object',
+				properties: {
+					sessionId: { type: 'string', description: 'Exact session id from mover_list_sessions' },
+					targetWorkspaceId: { type: 'string', description: 'Exact workspace id of the destination group from mover_list_sessions' },
+					sessionTitle: { type: 'string', description: 'Optional display title used in move history; omit to use the session\'s own title' }
+				},
+				required: ['sessionId', 'targetWorkspaceId'],
+				additionalProperties: false
+			},
+			output: { schema: { type: 'object' }, render: JSON_TEXT },
+			timeoutMs: 120000,
+			async execute(args, exec) {
+				const sessionId = validId(args?.sessionId, 'sessionId');
+				const targetWorkspaceId = validId(args?.targetWorkspaceId, 'targetWorkspaceId');
+				await approveOrThrow(ctx, exec, 'mover_move_session', `Move session "${sessionId}" into workspace group "${targetWorkspaceId}" (files are moved on disk with automatic backup and rollback).`);
+				return await callDispatch(dispatchRef, 'mover.move', { sessionId, targetWorkspaceId, sessionTitle: typeof args?.sessionTitle === 'string' ? args.sessionTitle : undefined }, exec?.signal);
+			}
+		},
+		{
+			name: 'mover_repair_sessions',
+			description: `Run one workspace-mover repair pass across all detected session issues: misfiled sessions are re-homed to the group matching their folder, unregistered sessions with a matching group get accounted. Accounting-only — no session files are moved. Anything needing a human decision (orphaned, damaged archives, no matching group) is skipped with a stated reason, and results report fixed / skipped / failed. ${SIGNAL_NOTE} Ask the user to confirm before calling.`,
+			parameters: { type: 'object', properties: {}, additionalProperties: false },
+			output: { schema: { type: 'object' }, render: JSON_TEXT },
+			timeoutMs: 120000,
+			async execute(args, exec) {
+				await approveOrThrow(ctx, exec, 'mover_repair_sessions', 'Run a workspace-mover repair pass (accounting-only fixes for misfiled / unregistered sessions; no files are moved).');
+				return await callDispatch(dispatchRef, 'mover.repairAll', {}, exec?.signal);
+			}
+		},
+		{
+			name: 'mover_doctor',
+			description: `Run the workspace-mover self-check (read-only diagnostics): host services (registry / persistence / projection cache / archive channel / agents / approval seam), agent-tool registration, data directories (recycle bin, backups, move history, tasks), pending manual-recovery records, and workspace folder presence. Returns per-check pass / warn / fail states with details and a summary — use it after a DSH upgrade or when a feature misbehaves, to see what is degraded before attempting anything else. No user approval needed; nothing is modified.`,
+			parameters: { type: 'object', properties: {}, additionalProperties: false },
+			output: { schema: { type: 'object' }, render: JSON_TEXT },
+			isConcurrencySafe: () => true,
+			timeoutMs: 30000,
+			async execute(args, exec) {
+				return await callDispatch(dispatchRef, 'mover.doctor', {}, exec?.signal);
+			}
+		}
+	];
+	return tools;
+}
+
+/** 宿主带 dsh-tools 时注册；逐工具隔离失败（一个失败不影响其余），缺服务时静默跳过。 */
+function registerAgentTools(ctx, dispatchRef, logger, agentToolsState = { registered: false }) {
+	if (typeof ctx?.tools?.register !== 'function') return;
+	for (const tool of createAgentTools(ctx, dispatchRef)) {
+		try {
+			ctx.tools.register(tool);
+			agentToolsState.registered = true;
+		} catch (err) {
+			logger?.warn?.(`workspace-mover: agent tool '${tool?.name}' registration failed: ${err?.message ?? err}`);
+		}
+	}
+}
+//#endregion
+
+//#region doctor（v2.2）：只读自检——服务、数据目录、恢复记录、工作区路径
+// 纯 ok(value)，无锁无变更；刻意不跑全量 scan，保证秒级返回。
+async function runDoctor(ctx, agentToolsState) {
+	const checks = [];
+	const add = (id, state, detail = '') => checks.push({ id, state, detail });
+	const pass = (id, detail) => add(id, 'pass', detail);
+	const warn = (id, detail) => add(id, 'warn', detail);
+	const fail = (id, detail) => add(id, 'fail', detail);
+
+	const registry = ctx?.workspaceRegistry;
+	const persistence = ctx?.sessionPersistence;
+
+	if (!registry) fail('host-registry', 'workspace registry service unavailable');
+	else {
+		let count = 0;
+		try { count = registry.list().length; } catch { /* list 失败按 0 报告 */ }
+		pass('host-registry', `${count} workspaces`);
+	}
+
+	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)'}`);
+
+	const projection = projectionTable(ctx);
+	const projectionRead = typeof projection?.get === 'function';
+	const projectionWrite = projectionRead && typeof projection?.put === 'function' && typeof projection?.delete === 'function';
+	if (projectionWrite) pass('host-projection', 'read + write');
+	else if (projectionRead) warn('host-projection', 'read-only — projection title restore degraded');
+	else warn('host-projection', 'absent — projection title restore degraded');
+
+	if (typeof registry?.enqueueOperation === 'function') pass('host-archive', 'archive-set channel ready');
+	else warn('host-archive', 'archive-set changes degraded');
+
+	if (peekService(ctx, 'agents')) pass('host-agents', 'running-state checks active');
+	else warn('host-agents', 'running-state checks degraded');
+
+	if (typeof ctx?.approval?.request === 'function') pass('host-approval', 'approval seam ready');
+	else warn('host-approval', 'agent approval seam absent — conversational moves rely on model discipline');
+
+	if (agentToolsState?.registered) pass('agent-tools', 'registered with dsh-tools');
+	else warn('agent-tools', 'not registered — dsh-tools absent on this host');
+
+	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`); }
+	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`); }
+	catch (err) { fail('data-history', String(err?.message ?? err).slice(0, 140)); }
+
+	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)); }
+
+	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`);
+
+	if (!registry) warn('workspaces', 'skipped — registry unavailable');
+	else {
+		let total = 0;
+		let missing = [];
+		try {
+			for (const entity of registry.list()) {
+				total++;
+				try { if (!dirExists(entity.path)) missing.push(String(entity.id)); }
+				catch { missing.push(String(entity.id)); }
+			}
+		} catch { /* 同上 */ }
+		if (total === 0) warn('workspaces', 'no registered workspaces');
+		else if (missing.length === 0) pass('workspaces', `${total} paths all present`);
+		else warn('workspaces', `${missing.length}/${total} folders missing: ${missing.slice(0, 5).join(', ')}`);
+	}
+
+	const summary = { pass: 0, warn: 0, fail: 0 };
+	for (const c of checks) summary[c.state]++;
+	return { checks, summary, generatedAt: new Date().toISOString() };
+}
+//#endregion
+
 export function apply(ctx) {
 	const logger = ctx.logger ?? console;
+	const dispatchRef = { fn: null }; // agent 工具在调用期才用到 dispatch，挂载时序无关
+	const agentToolsState = { registered: false };
 	const mount = (owner) => {
 		const connection = owner?.connection;
 		if (!connection?.rpc?.handle) return;
@@ -2254,7 +2480,7 @@ export function apply(ctx) {
 		// to this injected web context so rpc.handle() can register on webServer.
 		const rawConnection = connection[Symbol.for('cordis.original')] ?? connection;
 		const scopedConnection = rawConnection?.[Symbol.for('cordis.extend')]?.({ ctx: owner }) ?? connection;
-		const dispose = scopedConnection.rpc.handle(CHANNEL, async (endpoint, payload = {}, signal) => {
+		const dispatch = async (endpoint, payload = {}, signal) => {
 		if (signal?.aborted) return { ok: false, error: { code: 'cancelled', message: 'cancelled', details: {} } };
 		try {
 			switch (endpoint) {
@@ -2280,9 +2506,12 @@ export function apply(ctx) {
 						channel: CHANNEL,
 						capabilities,
 						degradedFeatures,
+						agentTools: agentToolsState.registered,
 						recoveryCount: recoveryCount()
 					});
 				}
+				case 'mover.doctor':
+					return ok(await runDoctor(ctx, agentToolsState));
 				case 'mover.workspaces':
 					return ok(await listWorkspaces(ctx));
 				case 'mover.history':
@@ -2432,7 +2661,9 @@ export function apply(ctx) {
 		} catch (err) {
 			return mapError(err);
 		}
-		}, { authority: 'loopback' });
+		};
+		dispatchRef.fn = dispatch;
+		const dispose = scopedConnection.rpc.handle(CHANNEL, dispatch, { authority: 'loopback' });
 		owner.effect?.(() => () => { try { dispose?.(); } catch { /* ignore */ } }, 'workspace-mover: rpc dispose');
 	};
 
@@ -2441,6 +2672,8 @@ export function apply(ctx) {
 	} else {
 		mount(ctx);
 	}
+
+	registerAgentTools(ctx, dispatchRef, logger, agentToolsState);
 }
 
 export { name, inject, CHANNEL, projectKey, encodeSegment, sessionDir, artifactPath, generationLogFilename, parseGenerationLogFilename, listGenerationArtifacts, findHighestArtifact, preferredArtifactName, moveDir, stashBackup, verifyRelocatedArtifact, deleteSessionToTrash, moveSession, moveSessionEntry, validId, SCAN_MAX_ITEMS };

package/package.json

@@ -1,62 +1,63 @@
-{
-  "name": "dsh-workspace-mover",
-  "version": "2.0.3",
-  "description": "在 DSH 侧边栏安全迁移会话：真迁移原始档案，支持失联会话恢复、移动历史和一键撤回。",
-  "type": "module",
-  "main": "lib/index.js",
-  "exports": {
-    ".": "./lib/index.js",
-    "./client": "./client/client.js",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "lib",
-    "client",
-    "test",
-    "cordis.patch.yml",
-    "README.md",
-    "docs/ARCHITECTURE.md",
-    "docs/media",
-    "LICENSE"
-  ],
-  "scripts": {
-    "test": "node --test test/core.test.mjs test/e2e-sandbox.test.mjs test/traffic-badge.test.mjs test/release-downloads.test.mjs",
-    "check:syntax": "node --check lib/index.js && node --check client/client.js",
-    "check:pack": "npm pack --dry-run",
-    "check": "npm run check:syntax && npm test && npm run check:pack"
-  },
-  "keywords": [
-    "deepseek-harness",
-    "dsh",
-    "dsh-plugin",
-    "workspace",
-    "session",
-    "session-migration",
-    "drag-and-drop"
-  ],
-  "engines": {
-    "node": ">=22",
-    "dsh": ">=0.1.5-rc.1"
-  },
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/PianoPrince/dsh-workspace-mover.git"
-  },
-  "bugs": {
-    "url": "https://github.com/PianoPrince/dsh-workspace-mover/issues"
-  },
-  "homepage": "https://github.com/PianoPrince/dsh-workspace-mover#readme",
-  "dsh": {
-    "bundle": {
-      "patch": "./cordis.patch.yml"
-    },
-    "client": {
-      "inject": [
-        "@deepseek-ai/dsh-client-connection",
-        "@deepseek-ai/dsh-client-ui-slots"
-      ],
-      "platform": "web"
-    }
-  }
-}
+{
+  "name": "dsh-workspace-mover",
+  "version": "2.1.1",
+  "description": "在 DSH 侧边栏安全迁移会话：真迁移原始档案，支持失联会话恢复、移动历史、一键撤回和 agent 工具。",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./client/client.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "client",
+    "test",
+    "cordis.patch.yml",
+    "README.md",
+    "docs/ARCHITECTURE.md",
+    "docs/media",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/core.test.mjs test/e2e-sandbox.test.mjs test/traffic-badge.test.mjs test/release-downloads.test.mjs",
+    "check:syntax": "node --check lib/index.js && node --check client/client.js",
+    "check:pack": "npm pack --dry-run",
+    "check": "npm run check:syntax && npm test && npm run check:pack"
+  },
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "dsh-plugin",
+    "workspace",
+    "session",
+    "session-migration",
+    "drag-and-drop",
+    "agent-tools"
+  ],
+  "engines": {
+    "node": ">=22",
+    "dsh": ">=0.1.5-rc.1"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PianoPrince/dsh-workspace-mover.git"
+  },
+  "bugs": {
+    "url": "https://github.com/PianoPrince/dsh-workspace-mover/issues"
+  },
+  "homepage": "https://github.com/PianoPrince/dsh-workspace-mover#readme",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-connection",
+        "@deepseek-ai/dsh-client-ui-slots"
+      ],
+      "platform": "web"
+    }
+  }
+}

package/test/e2e-sandbox.test.mjs

@@ -1802,3 +1802,161 @@ test('mover.session.delete: archived resident idle session still refuses delete'
   assert.ok(existsSync(artifactPath(root, A, 'session-aaa')), 'artifact untouched');
   assert.deepEqual(ctx.workspaceRegistry.archivedSessionIds, ['session-aaa']);
 });
+
+// ===== v2.1.0 agent 工具 =====
+
+/** 给 ctx 挂上 dsh-tools / dsh-user-approval 的测试替身，返回工具定义捕获数组和审批记录。 */
+function mountToolStubs(approvalOutcome = 'allowed-once') {
+  const registered = [];
+  const approvalCalls = [];
+  ctx.tools = { register: (def) => registered.push(def) };
+  ctx.approval = {
+    async request(req) {
+      approvalCalls.push(req);
+      if (typeof approvalOutcome === 'function') return approvalOutcome(req);
+      return approvalOutcome;
+    }
+  };
+  return { registered, approvalCalls };
+}
+
+const FAKE_EXEC = () => ({ agent: { session: {} }, signal: undefined });
+
+test('v2.1 apply 在带 dsh-tools 的宿主上注册三个 agent 工具，status 汇报能力位', async () => {
+  const { registered } = mountToolStubs();
+  apply(ctx);
+  assert.deepEqual(registered.map((t) => t.name), ['mover_list_sessions', 'mover_move_session', 'mover_repair_sessions', 'mover_doctor']);
+  for (const def of registered) {
+    assert.equal(typeof def.execute, 'function', `${def.name}.execute`);
+    assert.equal(typeof def.output?.render, 'function', `${def.name}.output.render`);
+    assert.equal(def.output?.schema?.type, 'object', `${def.name}.output.schema`);
+  }
+  assert.equal(registered[1].parameters.required.join(','), 'sessionId,targetWorkspaceId');
+  const status = await call('mover.status');
+  assert.equal(status.value.agentTools, true);
+});
+
+test('v2.1 无 dsh-tools 宿主上 apply 不受影响（静默跳过）', async () => {
+  apply(ctx);
+  const status = await call('mover.status');
+  assert.equal(status.ok, true);
+  assert.equal(status.value.agentTools, false);
+});
+
+test('v2.1 mover_list_sessions 合成 scan + workspaces（含状态与计数）', async () => {
+  const { registered } = mountToolStubs();
+  apply(ctx);
+  const list = registered.find((t) => t.name === 'mover_list_sessions');
+  entityA.record.sessionIds.push('session-aaa'); // 夹具本就未记账：记账后断言 ok 路径
+  const value = await list.execute({}, FAKE_EXEC());
+  assert.ok(value.workspaces.some((w) => w.workspaceId === 'wid-a'));
+  assert.ok(value.workspaces.some((w) => w.workspaceId === 'wid-b'));
+  const aaa = value.sessions.find((s) => s.sessionId === 'session-aaa');
+  assert.ok(aaa, 'fixture session listed');
+  assert.equal(aaa.status, 'ok');
+  assert.deepEqual(aaa.ownerWorkspaceIds, ['wid-a']);
+  assert.equal(typeof value.counts, 'object');
+  assert.equal(value.recoveryCount, 0);
+});
+
+test('v2.1 mover_move_session 审批通过后经 dispatch 迁移成功', async () => {
+  const { registered, approvalCalls } = mountToolStubs();
+  apply(ctx);
+  const move = registered.find((t) => t.name === 'mover_move_session');
+  const exec = FAKE_EXEC();
+  const value = await move.execute({ sessionId: 'session-aaa', targetWorkspaceId: 'wid-b' }, exec);
+  assert.equal(value.verified, true);
+  assert.equal(readHeader(readFileSync(findArtifact('session-aaa'))).cwd, B);
+  assert.equal(approvalCalls.length, 1);
+  assert.equal(approvalCalls[0].toolName, 'mover_move_session');
+  assert.equal(approvalCalls[0].agent, exec.agent);
+  assert.match(String(approvalCalls[0].reason), /session-aaa/);
+});
+
+test('v2.1 审批拒绝 / 接缝异常时 move 拒绝执行（fail-closed）', async () => {
+  for (const outcome of ['denied', 'cancelled', 'unavailable']) {
+    const { registered } = mountToolStubs(outcome);
+    apply(ctx);
+    const move = registered.find((t) => t.name === 'mover_move_session');
+    await assert.rejects(
+      move.execute({ sessionId: 'session-aaa', targetWorkspaceId: 'wid-b' }, FAKE_EXEC()),
+      new RegExp(outcome)
+    );
+    assert.equal(readHeader(readFileSync(findArtifact('session-aaa'))).cwd, A, `${outcome} 后文件未动`);
+  }
+  // 接缝抛错：同样不放行
+  const { registered: reg2 } = mountToolStubs(() => { throw new Error('no open turn'); });
+  apply(ctx);
+  const move2 = reg2.find((t) => t.name === 'mover_move_session');
+  await assert.rejects(move2.execute({ sessionId: 'session-aaa', targetWorkspaceId: 'wid-b' }, FAKE_EXEC()), /could not be requested/);
+  assert.equal(readHeader(readFileSync(findArtifact('session-aaa'))).cwd, A);
+});
+
+test('v2.1 mover_move_session 错误码透传；无效输入不惊动审批', async () => {
+  const { registered, approvalCalls } = mountToolStubs();
+  apply(ctx);
+  const move = registered.find((t) => t.name === 'mover_move_session');
+  await assert.rejects(
+    move.execute({ sessionId: 'session-aaa', targetWorkspaceId: 'wid-nope' }, FAKE_EXEC()),
+    /\[not-found\]/
+  );
+  await assert.rejects(
+    move.execute({ sessionId: 'x'.repeat(301), targetWorkspaceId: 'wid-b' }, FAKE_EXEC()),
+    /\[invalid-input\]|must be a non-empty string/
+  );
+  assert.equal(approvalCalls.length, 1, 'invalid-input 在审批前就被拦截');
+});
+
+test('v2.1 mover_repair_sessions 走审批并修复未记账夹具会话', async () => {
+  const { registered, approvalCalls } = mountToolStubs();
+  apply(ctx);
+  const repair = registered.find((t) => t.name === 'mover_repair_sessions');
+  // 夹具 session-aaa 有匹配分组（wid-a）但未记账：repairAll 应把它补账
+  const value = await repair.execute({}, FAKE_EXEC());
+  assert.equal(value.fixedCount, 1);
+  assert.equal(value.failedCount, 0);
+  assert.ok(entityA.record.sessionIds.includes('session-aaa'), 'repair 后已补账');
+  assert.equal(approvalCalls.length, 1);
+  assert.equal(approvalCalls[0].toolName, 'mover_repair_sessions');
+});
+
+// ===== v2.2.0 mover.doctor 自检 =====
+
+test('v2.2 mover.doctor 沙箱全绿：服务/数据/工作区全部 pass', async () => {
+  apply(ctx);
+  const res = await call('mover.doctor');
+  assert.equal(res.ok, true, JSON.stringify(res));
+  const { checks, summary } = res.value;
+  assert.ok(checks.length >= 12, `至少 12 项检查，实际 ${checks.length}`);
+  for (const c of checks) assert.ok(['pass', 'warn', 'fail'].includes(c.state), `state 合法: ${c.id}`);
+  assert.equal(summary.fail, 0, `不应有 fail: ${JSON.stringify(checks.filter((c) => c.state === 'fail'))}`);
+  const ids = new Set(checks.map((c) => c.id));
+  for (const expected of ['host-registry', 'host-persistence', 'host-projection', 'data-recycle', 'data-backups', 'recovery', 'workspaces']) {
+    assert.ok(ids.has(expected), `缺少检查项 ${expected}`);
+  }
+  assert.equal(typeof res.value.generatedAt, 'string');
+});
+
+test('v2.2 mover.doctor 降级：摘除注册表后 fail + warn，但不抛错', async () => {
+  apply(ctx);
+  ctx.workspaceRegistry = undefined;
+  const res = await call('mover.doctor');
+  assert.equal(res.ok, true, 'doctor 本身永远 ok');
+  const registryCheck = res.value.checks.find((c) => c.id === 'host-registry');
+  assert.equal(registryCheck.state, 'fail');
+  const workspacesCheck = res.value.checks.find((c) => c.id === 'workspaces');
+  assert.equal(workspacesCheck.state, 'warn');
+  assert.equal(res.value.summary.fail >= 1, true);
+});
+
+test('v2.2 mover.doctor 恢复记录告警：recovery.json 存在时 warn', async () => {
+  apply(ctx);
+  const dir = join(root, 'workspace-mover');
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'recovery.json'), JSON.stringify({ version: 1, records: [{ id: 'rec-x', kind: 'delete', phase: 'test', createdAt: new Date().toISOString() }] }));
+  const res = await call('mover.doctor');
+  assert.equal(res.ok, true);
+  const recovery = res.value.checks.find((c) => c.id === 'recovery');
+  assert.equal(recovery.state, 'warn');
+  assert.match(recovery.detail, /1 record/);
+});