dsh-manage-session 0.4.8 → 0.5.3

package/lib/index.js

@@ -1,19 +1,36 @@
+import { createRequire } from "node:module";
 import z from "@deepseek-ai/schemastery";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
-import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import zlib from "node:zlib";
+import { mkdir, readdir, rename, rm, unlink } from "node:fs/promises";
 //#region src/config.ts
 /** 缺省值。 */
 const DEFAULT_CONFIG = {
 	enabled: true,
 	historyFiles: true,
-	healthCheck: true
+	healthCheck: true,
+	search: true
 };
 /** host 半身注册的设置命名空间（与 src/index.ts 保持一致）。 */
 const STEWARD_SETTINGS_NAMESPACE = "session-steward";
-/** host 路由前缀（与搜索索引插件的 /switch-search/api 互不干扰）。 */
+/** host 路由前缀（管家子域；与搜索子域的 /switch-search/api 互不干扰）。 */
 const STEWARD_API_PREFIX = "/session-steward/api";
+/** ------------------------------------------------------------------ 搜索子域 */
+/** 搜索子域的历史设置命名空间（存储键稳定承诺，永不迁移）。 */
+const SWITCH_SEARCH_SETTINGS_NAMESPACE = "switch-search";
+/** 搜索子域路由前缀（历史值，浏览器旧 bundle 与快照文件名依赖它，保持不变）。 */
+const SWITCH_API_PREFIX = "/switch-search/api";
+/** 搜索子域缺省值。 */
+const SWITCH_DEFAULT_CONFIG = {
+	enabled: true,
+	defaultMode: "title",
+	autoSync: true,
+	syncIntervalMs: 3e4,
+	archiveKeep: 2,
+	indexDir: ""
+};
 //#endregion
 //#region src/host/history/archive-source.ts
 /**
@@ -33,11 +50,11 @@ const STEWARD_API_PREFIX = "/session-steward/api";
 * 调用方必须提示需要重启 DSH。
 */
 /** workspace domain 的 DSH 存储中枢候选路径（json 后端）。 */
-function storageFileCandidates() {
+function storageFileCandidates$1() {
 	return [join(homedir(), ".dsh", "storages", "workspace.json")];
 }
 /** 解析存储文件 global.archivedSessionIds；内容畸形时抛错。 */
-function readStorageFile(path) {
+function readStorageFile$1(path) {
 	const ids = JSON.parse(readFileSync(path, "utf8")).global?.archivedSessionIds;
 	if (!Array.isArray(ids)) throw new Error(`storage hub "${path}" holds no global.archivedSessionIds array`);
 	return ids.filter((id) => typeof id === "string");
@@ -65,11 +82,11 @@ function readRegistryIds(registry) {
 */
 function readArchiveSet(registry, searchPaths) {
 	const registryIds = readRegistryIds(registry);
-	for (const path of searchPaths ?? storageFileCandidates()) {
+	for (const path of searchPaths ?? storageFileCandidates$1()) {
 		if (!existsSync(path)) continue;
 		try {
 			return {
-				ids: readStorageFile(path),
+				ids: readStorageFile$1(path),
 				source: "storage-file",
 				...registryIds === void 0 ? {} : { registryIds }
 			};
@@ -152,7 +169,7 @@ function editWorkspaceDocument(path, edit, log) {
 function pruneArchiveFile(ids, log, searchPaths) {
 	const wanted = new Set(ids);
 	let lastReason = "workspace storage file not found (searched ~/.dsh/storages/workspace.json)";
-	for (const path of searchPaths ?? storageFileCandidates()) {
+	for (const path of searchPaths ?? storageFileCandidates$1()) {
 		let removed = 0;
 		let remaining = 0;
 		const outcome = editWorkspaceDocument(path, (document) => {
@@ -182,6 +199,55 @@ function pruneArchiveFile(ids, log, searchPaths) {
 	}
 	throw new Error(lastReason);
 }
+/**
+* 把会话 id 加入存储中枢的 `global.archivedSessionIds`（= 归档,prune 的逆操作）。
+*
+* 与 prune 同一写入口与协议（备份 + 临时文件 + 原子改名）；已在集合中的 id
+* 不重复追加。运行中的宿主把集合留在内存里、只在启动时重载 —— 调用方必须
+* 提示需要重启 DSH。
+* @param ids - 要加入归档数组的会话 id。
+* @param log - 可选日志出口。
+* @param searchPaths - 可选候选路径覆盖（测试注入用）。
+* @returns 实际新增数量与操作后的集合总数。
+*/
+function archiveArchiveFile(ids, log, searchPaths) {
+	new Set(ids);
+	let lastReason = "workspace storage file not found (searched ~/.dsh/storages/workspace.json)";
+	for (const path of searchPaths ?? storageFileCandidates$1()) {
+		let added = 0;
+		let total = 0;
+		const outcome = editWorkspaceDocument(path, (document) => {
+			const global = document.global;
+			const current = global?.archivedSessionIds;
+			if (!Array.isArray(current)) throw new Error(`storage hub "${path}" holds no global.archivedSessionIds array`);
+			const existing = new Set(current.filter((id) => typeof id === "string"));
+			const fresh = ids.filter((id) => !existing.has(id));
+			if (fresh.length === 0) {
+				added = 0;
+				total = existing.size;
+				return false;
+			}
+			document.global = {
+				...global,
+				archivedSessionIds: [...current, ...fresh]
+			};
+			added = fresh.length;
+			total = existing.size + fresh.length;
+			return true;
+		}, log);
+		if (!outcome.ok) {
+			lastReason = outcome.reason;
+			continue;
+		}
+		if (outcome.changed) log?.(`archive: added ${added} ids; total ${total}`);
+		return {
+			added,
+			total,
+			file: outcome.file
+		};
+	}
+	throw new Error(lastReason);
+}
 //#endregion
 //#region src/host/health/decode.ts
 /**
@@ -1202,6 +1268,354 @@ function pruneHistory(payload, log, searchPaths) {
 		requiresRestart: true
 	};
 }
+/** 单次归档的最大 id 数（与 prune/purge 一致）。 */
+const MAX_ARCHIVE_IDS = 5e3;
+/**
+* `session-history-archive`：把会话批量加入官方归档集合（prune 的逆操作）。
+* 与 prune 同一条纪律：校验入参 → 备份并原子替换存储文件 → 读回校验 →
+* 要求重启（宿主内存集合只在启动时重载）。会话文件不动、工作区成员表不动
+* （归档只改可见性,与宿主 archiveSession 的文件语义一致）。
+* @param payload - `{ sessionIds: string[] }`。
+* @param log - 可选日志出口。
+* @param searchPaths - 可选候选路径覆盖（测试注入用）。
+*/
+function archiveHistory(payload, log, searchPaths) {
+	const record = payload;
+	if (!Array.isArray(record?.sessionIds) || record.sessionIds.length === 0) return {
+		ok: false,
+		error: "缺少 sessionIds 数组"
+	};
+	const ids = [...new Set(record.sessionIds.filter((id) => typeof id === "string" && id !== ""))];
+	if (ids.length === 0) return {
+		ok: false,
+		error: "sessionIds 无有效值"
+	};
+	if (ids.length > 5e3) return {
+		ok: false,
+		error: `单次最多归档 ${MAX_ARCHIVE_IDS} 个`
+	};
+	let result;
+	try {
+		result = archiveArchiveFile(ids, log, searchPaths);
+	} catch (err) {
+		return {
+			ok: false,
+			error: String(err instanceof Error ? err.message : err)
+		};
+	}
+	const after = readArchiveSet(void 0, searchPaths);
+	if (after.source !== "storage-file") return {
+		ok: false,
+		error: "写入后无法读回存储文件，无法确认归档结果"
+	};
+	const now = new Set(after.ids);
+	const missing = ids.filter((id) => !now.has(id));
+	if (missing.length > 0) return {
+		ok: false,
+		error: `存储文件在写入后仍缺少 ${missing.length} 个目标 id，归档未生效`
+	};
+	log?.(`archive requested ${ids.length}, added ${result.added}, total ${result.total}`);
+	return {
+		ok: true,
+		added: result.added,
+		total: result.total,
+		requiresRestart: true
+	};
+}
+//#endregion
+//#region src/host/history/favorites.ts
+/**
+* 收藏域（R6）—— 插件自有的 JSON 文件，与索引文件/官方存储彻底分离：
+* 索引会因 schema 重置/影子切换整体更换，收藏不能放里面；官方存储中枢
+* 只读不写（唯一写方纪律不破）。文件形如
+* `<dshHome>/storages/session-steward-favorites.json`：
+* `{ unit: { name, version }, favoriteSessionIds: string[] }`
+* 原子写（tmp+rename），丢失可重建（收藏只是标记，不是数据）。
+*/
+/** 读取收藏集合；文件缺失/畸形一律空数组（收藏只是标记，丢失不致命）。 */
+function listFavorites(searchPaths) {
+	for (const path of searchPaths ?? []) {
+		if (!existsSync(path)) continue;
+		try {
+			const parsed = JSON.parse(readFileSync(path, "utf8"));
+			if (!Array.isArray(parsed.favoriteSessionIds)) return [];
+			return parsed.favoriteSessionIds.filter((id) => typeof id === "string");
+		} catch {
+			return [];
+		}
+	}
+	return [];
+}
+/** 设置单条收藏状态（原子写）。 */
+function setFavoriteState(sessionId, favorite, searchPaths) {
+	const path = searchPaths?.[0];
+	if (path === void 0 || path === "") return {
+		ok: false,
+		error: "缺少收藏文件路径"
+	};
+	let ids = [];
+	if (existsSync(path)) try {
+		const parsed = JSON.parse(readFileSync(path, "utf8"));
+		if (Array.isArray(parsed.favoriteSessionIds)) ids = parsed.favoriteSessionIds.filter((id) => typeof id === "string");
+	} catch {}
+	const without = ids.filter((id) => id !== sessionId);
+	const next = favorite ? [...without, sessionId] : without;
+	try {
+		mkdirSync(dirname(path), { recursive: true });
+		const tmp = `${path}.fav-tmp`;
+		writeFileSync(tmp, `${JSON.stringify({
+			unit: {
+				name: "session-steward-favorites",
+				version: 1
+			},
+			favoriteSessionIds: next
+		}, null, 2)}\n`, "utf8");
+		renameSync(tmp, path);
+		return {
+			ok: true,
+			total: next.length
+		};
+	} catch (err) {
+		return {
+			ok: false,
+			error: String(err instanceof Error ? err.message : err)
+		};
+	}
+}
+//#endregion
+//#region src/host/settings-bridge.ts
+/**
+* Legacy 设置桥（宿主半身，≤0.1.5 专用）：老宿主的服务端 settings 服务保留
+* register/get/update 三件套 —— 这是 context-compression legacy 租约（六格
+* 实证 POST 200 + 持久化）验证过的持久化写路径。0.1.7+ 宿主删掉了 register
+* （审计 P1-13：API 不存在，不是探测跳过），配置活在 entry-config volatile
+* 字段里、client configForms 原生可用 —— 本桥在那些线上解析为 undefined，
+* describe/mutate 方法降级为「显式拒绝写」。
+*
+* 两个命名空间**并存且互不迁移**（config.ts 的存储键稳定承诺）：
+* `session-steward`（管家字段）与 `switch-search`（搜索字段）。schema 必须
+* **纯 plain**（不 withVolatile）—— volatile 节点会被 legacy register 拒收
+* （`$.enabled expected boolean`，TL beta.18 教训）。
+*
+* 同一 settings 服务上重复 apply（HMR/双 loader 行）的防重：Symbol.for 键挂
+* 在服务对象上（cordis 同服务的所有代理共享该属性，cci 租约同款），首见者
+* 注册，后来者直接共享。
+*/
+const SHARED_LEASE = Symbol.for("dsh-manage-session/legacy-settings-bridge");
+/** 管家命名空间 schema（纯 plain，无 volatile —— 老线 register 拒收 volatile 节点）。 */
+const StewardNsSchema = z.object({
+	enabled: z.boolean().default(true),
+	historyFiles: z.boolean().default(true),
+	healthCheck: z.boolean().default(true),
+	search: z.boolean().default(true)
+});
+/** 搜索命名空间 schema（同上；存储键与 config.ts 承诺一致）。 */
+const SwitchNsSchema = z.object({
+	enabled: z.boolean().default(true),
+	defaultMode: z.union(["title", "content"]).default("title"),
+	autoSync: z.boolean().default(true),
+	syncIntervalMs: z.number().default(3e4),
+	archiveKeep: z.number().default(2),
+	indexDir: z.string().default("")
+});
+/** settings.get 返回值是否像一份文档（老宿主对未写过的 ns 可能回 undefined）。 */
+function asDoc(value) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return void 0;
+	return value;
+}
+/**
+* 在老宿主上租约注册两个命名空间；返回**同步创建的可变 holder**，桥面在
+* `ctx.inject(['settings'], …)` 回调里填入（cordis 作用域注入——settings 服务
+* 只在回调的 sctx 上可见，`ctx.get('settings')` 在 0.1.0 拿不到；0.1.7+ 无
+* register，回调即 return，holder 永远空桥 = describe 只读、mutate 显式拒绝）。
+* 重复 apply 经 Symbol 租约只注册一次；回调体内全部 try/catch——桥的任何
+* 失败都不允许拖死插件树（0.1.0 实机教训：严格 ctx 上裸属性读即 fatal）。
+*/
+function installLegacySettingsBridge(ctx) {
+	const state = {
+		bridge: void 0,
+		revision: 0
+	};
+	const injectFn = ctx.inject;
+	if (typeof injectFn !== "function") return state;
+	try {
+		injectFn.call(ctx, ["settings"], (sctx) => {
+			try {
+				const settings = sctx?.settings;
+				if (settings === void 0 || typeof settings.register !== "function") return;
+				const carrier = settings;
+				if (carrier[SHARED_LEASE] !== true) {
+					settings.register(STEWARD_SETTINGS_NAMESPACE, StewardNsSchema);
+					settings.register(SWITCH_SEARCH_SETTINGS_NAMESPACE, SwitchNsSchema);
+					try {
+						Object.defineProperty(carrier, SHARED_LEASE, {
+							configurable: false,
+							enumerable: false,
+							writable: false,
+							value: true
+						});
+					} catch {}
+				}
+				state.bridge = {
+					get: (ns) => {
+						try {
+							return asDoc(settings.get?.(ns));
+						} catch {
+							return;
+						}
+					},
+					update: async (ns, patch) => {
+						await settings.update?.(ns, patch);
+					}
+				};
+				console.log(`[dsh-manage-session] legacy settings bridge engaged (${STEWARD_SETTINGS_NAMESPACE} + ${SWITCH_SEARCH_SETTINGS_NAMESPACE})`);
+			} catch (err) {
+				console.log(`[dsh-manage-session] legacy settings bridge FAILED (cards degrade to read-only): ${String(err instanceof Error ? err.message : err)}`);
+			}
+		});
+	} catch {}
+	return state;
+}
+function asBoolean(v) {
+	return typeof v === "boolean" ? {
+		ok: true,
+		value: v
+	} : {
+		ok: false,
+		error: "期望布尔值"
+	};
+}
+/** 各命名空间允许写入的字段与校验（未列出的字段一律拒绝——桥不是任意写缝）。 */
+const FIELD_VALIDATORS = {
+	[STEWARD_SETTINGS_NAMESPACE]: {
+		enabled: asBoolean,
+		historyFiles: asBoolean,
+		healthCheck: asBoolean,
+		search: asBoolean
+	},
+	[SWITCH_SEARCH_SETTINGS_NAMESPACE]: {
+		enabled: asBoolean,
+		defaultMode: (v) => v === "title" || v === "content" ? {
+			ok: true,
+			value: v
+		} : {
+			ok: false,
+			error: "defaultMode 只接受 title|content"
+		},
+		autoSync: asBoolean,
+		syncIntervalMs: (v) => {
+			if (typeof v !== "number" || !Number.isFinite(v)) return {
+				ok: false,
+				error: "syncIntervalMs 必须是有限数字"
+			};
+			return {
+				ok: true,
+				value: Math.min(36e5, Math.max(5e3, Math.round(v)))
+			};
+		},
+		archiveKeep: (v) => {
+			if (typeof v !== "number" || !Number.isInteger(v)) return {
+				ok: false,
+				error: "archiveKeep 必须是整数"
+			};
+			return {
+				ok: true,
+				value: Math.min(20, Math.max(0, v))
+			};
+		},
+		indexDir: (v) => {
+			if (typeof v !== "string") return {
+				ok: false,
+				error: "indexDir 必须是字符串"
+			};
+			const trimmed = v.trim();
+			if (trimmed.length > 500) return {
+				ok: false,
+				error: "indexDir 过长（>500 字符）"
+			};
+			return {
+				ok: true,
+				value: trimmed
+			};
+		}
+	}
+};
+/** 汇总两份命名空间文档：legacy 读盘上文档合并缺省；modern 返回空投影（writable=false）。 */
+function describeNamespaces(state) {
+	const { bridge } = state;
+	if (bridge !== void 0) return {
+		[STEWARD_SETTINGS_NAMESPACE]: {
+			...DEFAULT_CONFIG,
+			...bridge.get("session-steward") ?? {}
+		},
+		[SWITCH_SEARCH_SETTINGS_NAMESPACE]: {
+			...SWITCH_DEFAULT_CONFIG,
+			...bridge.get("switch-search") ?? {}
+		}
+	};
+	return {
+		[STEWARD_SETTINGS_NAMESPACE]: {},
+		[SWITCH_SEARCH_SETTINGS_NAMESPACE]: {}
+	};
+}
+/** describe 响应。 */
+function settingsDescribe(state) {
+	return {
+		ok: true,
+		namespaces: describeNamespaces(state),
+		writable: state.bridge !== void 0,
+		revision: state.revision
+	};
+}
+/** 合并写一个命名空间；任何校验/宿主拒绝都显式失败，成功回权威文档。 */
+async function settingsMutate(state, payload) {
+	if (state.bridge === void 0) return {
+		ok: false,
+		error: "本宿主无 legacy settings 服务（0.1.7+ 走 configForms 原生句柄），桥不可写"
+	};
+	const request = payload ?? {};
+	if (typeof request.ns !== "string" || !(request.ns in FIELD_VALIDATORS)) return {
+		ok: false,
+		error: `未知设置命名空间：${String(request.ns)}`
+	};
+	if (request.fields === null || typeof request.fields !== "object" || Array.isArray(request.fields)) return {
+		ok: false,
+		error: "fields 必须是对象"
+	};
+	const validators = FIELD_VALIDATORS[request.ns];
+	const clean = {};
+	for (const [field, value] of Object.entries(request.fields)) {
+		const validate = validators[field];
+		if (validate === void 0) return {
+			ok: false,
+			error: `命名空间 ${request.ns} 不接受字段 "${field}"`
+		};
+		const verdict = validate(value);
+		if (!verdict.ok) return {
+			ok: false,
+			error: `${field}: ${verdict.error}`
+		};
+		clean[field] = verdict.value;
+	}
+	if (Object.keys(clean).length === 0) return {
+		ok: false,
+		error: "fields 为空"
+	};
+	try {
+		await state.bridge.update(request.ns, clean);
+	} catch (err) {
+		return {
+			ok: false,
+			error: `宿主拒绝写入：${String(err instanceof Error ? err.message : err)}`
+		};
+	}
+	state.revision += 1;
+	return {
+		ok: true,
+		namespaces: describeNamespaces(state),
+		revision: state.revision
+	};
+}
 //#endregion
 //#region src/host/health/attribution.ts
 /**
@@ -2334,82 +2748,1477 @@ function scanSessions(options) {
 		...options.onlyProblems === true ? { filtered: true } : {}
 	};
 }
-//#endregion
-//#region src/index.ts
-/** 本插件声明的宿主服务（与 toggle 相同的注入面）。 */
-const inject = ["webServer", "webRuntime"];
-/** Resolve one possibly-volatile field: a live ref on 0.1.7+, a plain value otherwise. */
-function readVolatileValue(value) {
-	if (value !== null && typeof value === "object" && typeof value.get === "function") return value.get();
-	return value;
-}
-/** 运行时配置 schema（与 src/config.ts 的形状保持一致）。0.1.7：volatile 字段即设置表单。 */
-const Config = z.object({
-	enabled: z.boolean().default(true).volatile(),
-	historyFiles: z.boolean().default(true).volatile(),
-	healthCheck: z.boolean().default(true).volatile()
-});
-/** 单次请求体的上限（防御无界读取）。 */
-const MAX_BODY_BYTES = 16 << 20;
-/** 归一化 Host authority，无法解析时为 undefined。 */
-function parseAuthority(authority) {
+/** Application id marking files owned by this plugin's index (ASCII "SWIS"). */
+const SWITCH_SEARCH_APPLICATION_ID = 1398229332;
+/**
+* Open the raw handle: better-sqlite3 (synchronous, faster statement
+* dispatch) when the optional dependency is present, node:sqlite otherwise.
+* Both expose the same prepare/exec/close shape this plugin uses.
+*/
+async function openRawHandle(actual) {
 	try {
-		return new URL(`http://${authority}`);
+		const mod = await import("better-sqlite3");
+		return {
+			db: new (mod.default ?? mod)(actual),
+			driver: "better-sqlite3"
+		};
 	} catch {
-		return;
+		const { DatabaseSync } = await import("node:sqlite");
+		return {
+			db: new DatabaseSync(actual),
+			driver: "node:sqlite"
+		};
 	}
 }
-/** 主机名是否本机回环。 */
-function isLoopbackHostname(hostname) {
-	if (hostname === "localhost" || hostname === "[::1]") return true;
-	const parts = hostname.split(".");
-	return parts.length === 4 && parts[0] === "127" && parts.every((part) => /^\d{1,3}$/.test(part) && Number(part) <= 255);
-}
-/** Host 是否命中 trustedHosts（精确或省略端口）。 */
-function isTrustedAuthority(hostUrl, trustedHosts) {
-	return trustedHosts.some((entry) => {
-		const entryUrl = parseAuthority(entry);
-		if (entryUrl === void 0) return false;
-		return (entryUrl.port === "" ? entryUrl.hostname : entryUrl.host) === hostUrl.host;
-	});
-}
-/** 浏览器可信围栏（与 /api 网关行为一致）：DNS 重绑定/跨站防御，不是鉴权。 */
-function isTrustedApiRequest(req, trustedHosts) {
-	const host = req.headers.host;
-	if (host === void 0) return false;
-	const hostUrl = parseAuthority(host);
-	if (hostUrl === void 0) return false;
-	if (!isLoopbackHostname(hostUrl.hostname) && !isTrustedAuthority(hostUrl, trustedHosts)) return false;
-	const fetchSite = req.headers["sec-fetch-site"];
-	if (typeof fetchSite === "string" && fetchSite === "cross-site") return false;
-	const origin = req.headers.origin;
-	if (origin === void 0) return true;
+/**
+* Open, validate, and initialize one switch-search index file.
+* Missing directories and files are created; a file that belongs to another
+* application (including the official session-query index) is refused.
+* @param path - absolute path to the index file.
+* @returns initialized database handle owned by the caller, plus the driver.
+*/
+async function openIndexDatabase(path) {
+	const actual = resolve(path);
+	await mkdir(dirname(actual), { recursive: true });
+	const { db, driver } = await openRawHandle(actual);
 	try {
-		return new URL(origin).host === hostUrl.host;
-	} catch {
-		return false;
+		const { application_id: applicationId } = db.prepare("PRAGMA application_id").get();
+		const { user_version: version } = db.prepare("PRAGMA user_version").get();
+		if (applicationId === 1146308689) throw new Error(`switch-search: "${actual}" is the official session-query index, refusing to open it`);
+		if (applicationId !== 0 && applicationId !== 1398229332) throw new Error(`switch-search: database at "${actual}" belongs to another application`);
+		if (applicationId === 1398229332 && version !== 5) resetSchema(db);
+		db.exec(`PRAGMA journal_mode = wal`);
+		ensureSchema(db);
+		db.exec(`PRAGMA synchronous = NORMAL`);
+		db.exec(`PRAGMA temp_store = MEMORY`);
+		db.exec(`PRAGMA cache_size = -65536`);
+		return {
+			db,
+			driver
+		};
+	} catch (error) {
+		db.close();
+		throw error;
 	}
 }
-/** 读原始请求体（有界）。 */
-async function readRawBody(req) {
-	const chunks = [];
-	let total = 0;
-	for await (const chunk of req) {
-		const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-		total += buffer.length;
-		if (total > MAX_BODY_BYTES) throw new Error("request body too large");
-		chunks.push(buffer);
-	}
-	return Buffer.concat(chunks).toString("utf8");
+/** Reset an incompatible database in place, preserving the owning application id. */
+function resetSchema(db) {
+	db.exec(`
+    PRAGMA writable_schema = OFF;
+    PRAGMA journal_mode = delete;
+  `);
+	for (const row of db.prepare(`
+    SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'
+  `).all()) db.exec(`DROP TABLE IF EXISTS "${row.name.replace(/"/g, "\"\"")}"`);
+	db.exec(`PRAGMA user_version = 0`);
 }
-/** 读 JSON 请求体（空体视为 {}）。 */
-async function readJsonBody(req) {
-	const text = await readRawBody(req);
-	if (text.trim() === "") return {};
-	try {
-		return JSON.parse(text);
-	} catch {
-		throw new Error("request body is not JSON");
+/** Create the persistent schema when absent. */
+function ensureSchema(db) {
+	db.exec(`
+    CREATE TABLE IF NOT EXISTS meta (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS sessions (
+      session_id TEXT PRIMARY KEY,
+      version INTEGER NOT NULL DEFAULT 0,
+      title TEXT NOT NULL DEFAULT '',
+      cwd TEXT NOT NULL DEFAULT '',
+      updated_at INTEGER NOT NULL DEFAULT 0,
+      indexed_at INTEGER NOT NULL DEFAULT 0,
+      archived INTEGER NOT NULL DEFAULT 0
+    );
+    CREATE TABLE IF NOT EXISTS docs (
+      doc_id INTEGER PRIMARY KEY AUTOINCREMENT,
+      session_id TEXT NOT NULL,
+      seq INTEGER NOT NULL,
+      type TEXT NOT NULL,
+      surface TEXT NOT NULL,
+      time INTEGER NOT NULL,
+      text TEXT NOT NULL,
+      index_text TEXT NOT NULL DEFAULT ''
+    );
+    CREATE UNIQUE INDEX IF NOT EXISTS docs_session_seq ON docs(session_id, seq);
+    CREATE INDEX IF NOT EXISTS docs_session ON docs(session_id);
+    CREATE VIRTUAL TABLE IF NOT EXISTS docs_fts USING fts5(
+      index_text,
+      content = 'docs',
+      content_rowid = 'doc_id',
+      tokenize = 'unicode61'
+    );
+  `);
+	db.exec(`PRAGMA application_id = ${SWITCH_SEARCH_APPLICATION_ID}`);
+	db.exec(`PRAGMA user_version = 5`);
+}
+//#endregion
+//#region src/host/index/extract.ts
+/**
+* 从会话事件流里抽出**最后一帧标题**（`session/title` log-only 事件）。
+*
+* 这是标题的基础层：入索引时随事件白拿，不依赖 readTitleSnapshots（后者
+* 对归档 id 可能整批失败——beta.4 标题全军覆没的根因）。数据形状按历史
+* 演变兼容三种：`{ title: string }`、`{ title: { title } }`、`{ title: { val } }`。
+*/
+function extractTitleFromEvents(events) {
+	for (let i = events.length - 1; i >= 0; i -= 1) {
+		const event = events[i];
+		if (event === null || typeof event !== "object") continue;
+		if (event.type !== "session/title") continue;
+		const title = event.data?.title;
+		if (typeof title === "string" && title.trim() !== "") return title;
+		if (title !== null && typeof title === "object") {
+			const inner = title;
+			if (typeof inner.title === "string" && inner.title.trim() !== "") return inner.title;
+			if (typeof inner.val === "string" && inner.val.trim() !== "") return inner.val;
+		}
+	}
+	return "";
+}
+/**
+* ICU word segmenter shared by index and query paths (Node >= 16 / all evergreen
+* browsers, zero dependency). 'zh' sensitivity keeps CJK word granularity.
+*/
+const SEGMENTER = typeof Intl !== "undefined" && typeof Intl.Segmenter === "function" ? new Intl.Segmenter("zh", { granularity: "word" }) : void 0;
+/**
+* Space-separate word boundaries so the FTS5 unicode61 tokenizer indexes
+* words instead of whole CJK runs: the index and query sides must apply the
+* exact same segmentation for a token to meet its match.
+* @param text - raw extracted text (or a query term).
+* @returns text with a single space at every word boundary.
+*/
+function segmentForIndex(text) {
+	if (SEGMENTER === void 0) return text;
+	const parts = [];
+	for (const { segment } of SEGMENTER.segment(text)) {
+		const piece = segment.trim();
+		if (piece !== "") parts.push(piece);
+	}
+	return parts.join(" ");
+}
+/**
+* Segment one whitespace-delimited query term into FTS5 phrase tokens.
+* @returns word-like segments, or the raw term when segmentation is unavailable.
+*/
+function segmentQueryTerm(term) {
+	if (SEGMENTER === void 0) return [term];
+	const words = [];
+	for (const { segment, isWordLike } of SEGMENTER.segment(term)) {
+		const piece = segment.trim();
+		if (piece !== "" && isWordLike === true) words.push(piece);
+	}
+	return words.length > 0 ? words : [term];
+}
+/** Whether a runtime value is a plain record. */
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Trimmed text of one string-or-undefined part list, joined by newlines. */
+function joinText(parts) {
+	return parts.map((part) => typeof part === "string" ? part.trim() : "").filter(Boolean).join("\n");
+}
+/** Extracted text of one content block; unknown blocks contribute nothing. */
+function blockText(block) {
+	if (!isRecord(block)) return [];
+	switch (block["type"]) {
+		case "text": return typeof block["text"] === "string" ? [block["text"]] : [];
+		case "reasoning": return [];
+		case "tool-call": return [block["name"], block["arguments"]].filter((v) => typeof v === "string");
+		case "tool-result": {
+			const content = block["content"];
+			return Array.isArray(content) ? content.flatMap(blockText) : [];
+		}
+		default: return [];
+	}
+}
+/** Text of one message content (array of blocks, or a plain string). */
+function contentText(content) {
+	if (typeof content === "string") return content.trim();
+	if (!Array.isArray(content)) return "";
+	return joinText(content.flatMap(blockText));
+}
+/** Turn-end reason text; completed turns contribute nothing. */
+function turnEndText(data) {
+	const reason = data["reason"];
+	if (!isRecord(reason)) return "";
+	switch (reason["kind"]) {
+		case "error": {
+			const error = reason["error"];
+			return joinText(["error", isRecord(error) && typeof error["message"] === "string" ? error["message"] : ""]);
+		}
+		case "aborted": return "aborted";
+		case "max-tokens":
+		case "interrupted": return String(reason["kind"]);
+		case "completed": return "";
+		default: return "";
+	}
+}
+/**
+* Extract searchable semantic text from one raw session event.
+* @param event - event to inspect.
+* @returns newline-joined semantic text, or an empty string when non-searchable.
+*/
+function extractSessionEventText(event) {
+	const data = isRecord(event.data) ? event.data : {};
+	switch (event.type) {
+		case "user/message": return contentText(data["content"]);
+		case "assistant/message": return contentText((isRecord(data["message"]) ? data["message"] : {})["content"]);
+		case "tool/call": return joinText([data["name"], data["arguments"]].filter((v) => typeof v === "string"));
+		case "tool/result": {
+			const message = isRecord(data["message"]) ? data["message"] : {};
+			const error = isRecord(data["error"]) ? data["error"] : {};
+			return joinText([
+				contentText(message["content"]),
+				typeof error["name"] === "string" ? error["name"] : "",
+				typeof error["code"] === "string" ? error["code"] : ""
+			]);
+		}
+		case "todo/write": return joinText((Array.isArray(data["todos"]) ? data["todos"] : []).flatMap((todo) => {
+			if (!isRecord(todo)) return [];
+			return [todo["status"], todo["content"]].filter((v) => typeof v === "string");
+		}));
+		case "turn/end": return turnEndText(data);
+		case "turn/start":
+		case "step/start":
+		case "step/end":
+		case "assistant/attempt":
+		case "request/header": return "";
+		default: return "";
+	}
+}
+/** Event types whose ops participate in the surface fold. */
+const SURFACE_ELIGIBLE_TYPES = /* @__PURE__ */ new Set([
+	"user/message",
+	"assistant/message",
+	"tool/call",
+	"tool/result"
+]);
+/**
+* Classify raw-log events into current vs shadowed surface membership.
+*
+* Simplified fold of the official `foldSurface`: append events join the
+* surface, and a `replace` op shadows the declared inclusive seq range plus
+* removes it from the surface. Validation is intentionally lax — a broken op
+* degrades to append rather than failing the whole index build.
+* @param events - complete contiguous raw event log.
+* @returns seq → surface map; entries absent from the map are log-only.
+*/
+function classifySurface(events) {
+	const surface = /* @__PURE__ */ new Map();
+	const nodes = [];
+	for (const event of events) {
+		if (!SURFACE_ELIGIBLE_TYPES.has(event.type)) continue;
+		const op = event.surfaceOp;
+		if (op === "append" || op === void 0) {
+			nodes.push(event.seq);
+			surface.set(event.seq, "current");
+			continue;
+		}
+		if (isRecord(op) && op["op"] === "replace" && typeof op["startSeq"] === "number" && typeof op["endSeq"] === "number") {
+			const shadowed = /* @__PURE__ */ new Set();
+			for (const seq of nodes) if (seq >= op["startSeq"] && seq <= op["endSeq"]) shadowed.add(seq);
+			const kept = nodes.filter((seq) => !shadowed.has(seq));
+			nodes.length = 0;
+			nodes.push(...kept, event.seq);
+			for (const seq of shadowed) surface.set(seq, "shadowed");
+			surface.set(event.seq, "current");
+			continue;
+		}
+		nodes.push(event.seq);
+		surface.set(event.seq, "current");
+	}
+	return surface;
+}
+/**
+* Project one complete raw log into searchable documents.
+* @param sessionId - session that owns the log.
+* @param events - complete contiguous raw event log.
+* @returns documents in ascending seq order; structural events are omitted.
+*/
+function buildIndexDocuments(sessionId, events) {
+	const surfaceBySeq = classifySurface(events);
+	const documents = [];
+	for (const event of events) {
+		const text = extractSessionEventText(event);
+		if (text.length === 0) continue;
+		documents.push({
+			sessionId,
+			seq: event.seq,
+			type: event.type,
+			time: typeof event.time === "number" ? event.time : 0,
+			surface: surfaceBySeq.get(event.seq) ?? "shadowed",
+			text
+		});
+	}
+	return documents;
+}
+//#endregion
+//#region src/host/index/engine.ts
+/** Coarse filter → raw event types. */
+const CONTENT_TYPE_GROUPS = {
+	user: ["user/message"],
+	reply: ["assistant/message"],
+	tool: ["tool/call", "tool/result"]
+};
+/** Search weight per event type (message content outranks tool chatter). */
+const TYPE_WEIGHT = {
+	"user/message": 3,
+	"assistant/message": 3,
+	"tool/call": 1,
+	"tool/result": 1
+};
+/** Maximum snippet length in characters, aligned with the official route. */
+const SNIPPET_CHARS = 240;
+/** Maximum FTS matches inspected per query before session grouping. */
+const MATCH_SCAN_LIMIT = 5e3;
+/**
+* Sanitize free text into a safe FTS5 query over the segmented index: each
+* whitespace term is segmented into word tokens, quoted as an adjacent
+* phrase, and the last token carries a prefix `*` so partial input matches
+* ("正在搜" hits 正在搜索). Terms AND together.
+*/
+function sanitizeFtsQuery(query) {
+	const terms = query.split(/\s+/u).filter(Boolean);
+	if (terms.length === 0) return "";
+	const phrases = [];
+	for (const term of terms) {
+		const words = segmentQueryTerm(term).map((word) => word.replace(/"/g, "\"\"")).filter((word) => word !== "");
+		if (words.length === 0) continue;
+		phrases.push(`"${words.join(" ")}"*`);
+	}
+	return phrases.join(" ");
+}
+/** Build a snippet around the first term occurrence, official-route aligned. */
+function buildSnippet(text, query, max = SNIPPET_CHARS) {
+	const flat = text.replace(/\s+/gu, " ").trim();
+	if (flat.length <= max) return flat;
+	const lower = flat.toLowerCase();
+	const terms = query.toLowerCase().split(/\s+/u).filter(Boolean);
+	let anchor = -1;
+	for (const term of terms) {
+		const at = lower.indexOf(term);
+		if (at >= 0 && (anchor < 0 || at < anchor)) anchor = at;
+	}
+	if (anchor < 0) return `${flat.slice(0, max)}…`;
+	const start = Math.max(0, anchor - Math.floor((max - 3) / 2));
+	const end = Math.min(flat.length, start + max - 3);
+	const head = start > 0 ? "…" : "";
+	const tail = end < flat.length ? "…" : "";
+	return `${head}${flat.slice(start, end)}${tail}`;
+}
+/** One open index handle. All mutating calls are synchronous; callers pace
+* them off the HTTP hot path (background sync / rebuild tasks). */
+var SwitchIndexEngine = class {
+	options;
+	db;
+	driver = "node:sqlite";
+	inBatch = false;
+	constructor(options) {
+		this.options = options;
+	}
+	/** Which SQLite driver is serving this handle. */
+	get driverLabel() {
+		return this.driver;
+	}
+	/**
+	* Run one write inside the current batched transaction, or its own
+	* IMMEDIATE transaction when not batching (nested calls join the batch).
+	*/
+	withWriteTx(fn) {
+		const db = this.requireDb();
+		if (this.inBatch) return fn();
+		db.exec("BEGIN IMMEDIATE");
+		this.inBatch = true;
+		try {
+			const result = fn();
+			db.exec("COMMIT");
+			return result;
+		} catch (error) {
+			try {
+				db.exec("ROLLBACK");
+			} catch {}
+			throw error;
+		} finally {
+			this.inBatch = false;
+		}
+	}
+	/**
+	* Run one function as a single batched transaction (one fsync checkpoint):
+	* upserts inside it join via withWriteTx instead of opening their own.
+	*/
+	runBatched(fn) {
+		return this.withWriteTx(fn);
+	}
+	/** Whether the handle is open. */
+	get isOpen() {
+		return this.db !== void 0;
+	}
+	/** Open (creating or migrating) the index file. Idempotent. */
+	async open() {
+		if (this.db !== void 0) return;
+		const opened = await openIndexDatabase(this.options.path);
+		this.db = opened.db;
+		this.driver = opened.driver;
+	}
+	/** Close the handle. Idempotent. */
+	close() {
+		this.db?.close();
+		this.db = void 0;
+	}
+	/** Remove one session's FTS entries for external-content bookkeeping. */
+	deleteSessionFts(db, sessionId) {
+		const existing = db.prepare("SELECT doc_id, index_text FROM docs WHERE session_id = ?").all(sessionId);
+		const deleteFts = db.prepare(`
+      INSERT INTO docs_fts(docs_fts, rowid, index_text) VALUES ('delete', ?, ?)
+    `);
+		for (const row of existing) deleteFts.run(Number(row.doc_id), row.index_text);
+	}
+	/** Insert or replace one session's documents and header row. */
+	upsertSession(input) {
+		const db = this.requireDb();
+		const documents = buildIndexDocuments(input.sessionId, input.events);
+		this.withWriteTx(() => {
+			this.deleteSessionFts(db, input.sessionId);
+			db.prepare("DELETE FROM docs WHERE session_id = ?").run(input.sessionId);
+			const insertDoc = db.prepare(`
+        INSERT INTO docs (session_id, seq, type, surface, time, text, index_text)
+        VALUES (?, ?, ?, ?, ?, ?, ?)
+      `);
+			const insertFts = db.prepare("INSERT INTO docs_fts (rowid, index_text) VALUES (?, ?)");
+			for (const doc of documents) {
+				const indexText = segmentForIndex(doc.text);
+				const result = insertDoc.run(doc.sessionId, doc.seq, doc.type, doc.surface, doc.time, doc.text, indexText);
+				insertFts.run(Number(result.lastInsertRowid), indexText);
+			}
+			db.prepare(`
+        INSERT INTO sessions (session_id, version, title, cwd, updated_at, indexed_at, archived)
+        VALUES (?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(session_id) DO UPDATE SET
+          version = excluded.version,
+          title = CASE WHEN excluded.title != '' THEN excluded.title ELSE sessions.title END,
+          cwd = excluded.cwd,
+          updated_at = excluded.updated_at,
+          indexed_at = excluded.indexed_at
+      `).run(input.sessionId, input.version, input.title ?? "", input.cwd ?? "", input.updatedAt ?? 0, Date.now(), input.archived === true ? 1 : 0);
+		});
+	}
+	/**
+	* Write an archived session's header row without any document content.
+	*
+	* @deprecated 旧"归档即软删"语义的遗物,合并包 R1 已改为归档保留 docs;仅剩
+	* 旧快照兼容路径可落 header 行。新代码一律 upsertSession + setArchived。
+	*/
+	upsertArchivedHeader(input) {
+		const db = this.requireDb();
+		this.withWriteTx(() => {
+			this.deleteSessionFts(db, input.sessionId);
+			db.prepare("DELETE FROM docs WHERE session_id = ?").run(input.sessionId);
+			db.prepare(`
+        INSERT INTO sessions (session_id, version, title, cwd, updated_at, indexed_at, archived)
+        VALUES (?, ?, ?, ?, ?, ?, 1)
+        ON CONFLICT(session_id) DO UPDATE SET
+          version = excluded.version,
+          title = CASE WHEN excluded.title != '' THEN excluded.title ELSE sessions.title END,
+          cwd = excluded.cwd,
+          updated_at = excluded.updated_at,
+          indexed_at = excluded.indexed_at,
+          archived = 1
+      `).run(input.sessionId, input.version, input.title ?? "", input.cwd ?? "", input.updatedAt ?? 0, Date.now());
+		});
+	}
+	/**
+	* Apply the official archive set: flip the archived flag both ways.
+	*
+	* 合表复用语义（R1）：归档**保留全部 docs 与 FTS**——正文在归档态不可变
+	* （归档门只拒新回合），翻转只是检索域成员资格的变化；恢复也不再需要重灌
+	* （旧实现的 version = -1 强制重读随"归档即删 docs"一并废除）。
+	*/
+	setArchived(archivedIds) {
+		const db = this.requireDb();
+		this.withWriteTx(() => {
+			const rows = db.prepare("SELECT session_id, archived FROM sessions").all();
+			for (const row of rows) {
+				const shouldBe = archivedIds.has(row.session_id) ? 1 : 0;
+				if (row.archived !== shouldBe) db.prepare("UPDATE sessions SET archived = ? WHERE session_id = ?").run(shouldBe, row.session_id);
+			}
+		});
+	}
+	/**
+	* Flip one session's archived flag (steward write-side linkage). No-op when
+	* the row does not exist — flag state on an unindexed session is meaningless.
+	*/
+	setArchivedOne(sessionId, archived) {
+		const db = this.requireDb();
+		this.withWriteTx(() => {
+			db.prepare("UPDATE sessions SET archived = ? WHERE session_id = ?").run(archived ? 1 : 0, sessionId);
+		});
+	}
+	/** One session's stored documents, ascending seq (snapshot export face). */
+	exportSessionDocs(sessionId) {
+		return this.requireDb().prepare(`
+      SELECT seq, type, surface, time, text FROM docs WHERE session_id = ? ORDER BY seq
+    `).all(sessionId);
+	}
+	/**
+	* Insert or replace one session from already-extracted documents
+	* (snapshot import face; no re-extraction, what was exported is restored;
+	* segmentation is recomputed for the current index format).
+	*/
+	importSessionDocs(input) {
+		const db = this.requireDb();
+		this.withWriteTx(() => {
+			this.deleteSessionFts(db, input.sessionId);
+			db.prepare("DELETE FROM docs WHERE session_id = ?").run(input.sessionId);
+			const insertDoc = db.prepare(`
+        INSERT INTO docs (session_id, seq, type, surface, time, text, index_text)
+        VALUES (?, ?, ?, ?, ?, ?, ?)
+      `);
+			const insertFts = db.prepare("INSERT INTO docs_fts (rowid, index_text) VALUES (?, ?)");
+			for (const doc of input.docs) {
+				const indexText = segmentForIndex(doc.text);
+				const result = insertDoc.run(input.sessionId, doc.seq, doc.type, doc.surface, doc.time, doc.text, indexText);
+				insertFts.run(Number(result.lastInsertRowid), indexText);
+			}
+			db.prepare(`
+        INSERT INTO sessions (session_id, version, title, updated_at, indexed_at, archived)
+        VALUES (?, ?, ?, 0, ?, ?)
+        ON CONFLICT(session_id) DO UPDATE SET
+          version = excluded.version,
+          title = excluded.title,
+          indexed_at = excluded.indexed_at,
+          archived = excluded.archived
+      `).run(input.sessionId, input.version, input.title ?? "", Date.now(), input.archived === true ? 1 : 0);
+		});
+	}
+	/** Remove one session and its documents entirely. */
+	removeSession(sessionId) {
+		const db = this.requireDb();
+		this.withWriteTx(() => {
+			this.deleteSessionFts(db, sessionId);
+			db.prepare("DELETE FROM docs WHERE session_id = ?").run(sessionId);
+			db.prepare("DELETE FROM sessions WHERE session_id = ?").run(sessionId);
+		});
+	}
+	/** Update only a session's header row (title backfill), keeping documents. */
+	updateSessionHeader(input) {
+		const db = this.requireDb();
+		if (db.prepare("SELECT version FROM sessions WHERE session_id = ?").get(input.sessionId) === void 0) return;
+		db.prepare(`
+      UPDATE sessions SET
+        title = CASE WHEN ? != '' THEN ? ELSE title END,
+        cwd = CASE WHEN ? != '' THEN ? ELSE cwd END,
+        updated_at = CASE WHEN ? > 0 THEN ? ELSE updated_at END
+      WHERE session_id = ?
+    `).run(input.title ?? "", input.title ?? "", input.cwd ?? "", input.cwd ?? "", input.updatedAt ?? 0, input.updatedAt ?? 0, input.sessionId);
+	}
+	/** One indexed session row, or undefined. */
+	getSession(sessionId) {
+		const row = this.requireDb().prepare("SELECT * FROM sessions WHERE session_id = ?").get(sessionId);
+		return row === void 0 ? void 0 : rowToSession(row);
+	}
+	/** All indexed sessions (active AND archived), newest first — the title
+	* corpus and the manage console both read this; the `archived` flag rides
+	* each row so clients filter locally. */
+	listIndexedSessions() {
+		return this.requireDb().prepare("SELECT * FROM sessions ORDER BY updated_at DESC").all().map(rowToSession);
+	}
+	/** Archived (soft-deleted) sessions, newest first — the archive viewer face. */
+	listArchived() {
+		return this.requireDb().prepare("SELECT * FROM sessions WHERE archived = 1 ORDER BY updated_at DESC").all().map(rowToSession);
+	}
+	/** Number of indexed sessions (active + archived — the whole corpus). */
+	countSessions() {
+		const row = this.requireDb().prepare("SELECT COUNT(*) AS n FROM sessions").get();
+		return Number(row.n);
+	}
+	/** Number of archived (soft-deleted) sessions. */
+	countArchived() {
+		const row = this.requireDb().prepare("SELECT COUNT(*) AS n FROM sessions WHERE archived = 1").get();
+		return Number(row.n);
+	}
+	/**
+	* Run one session-grouped full-text search.
+	*
+	* One statement: the FTS match is bounded by rank in a subquery (its rowid
+	* aligns with docs.doc_id), then the type/surface filters join in — no
+	* second round-trip, no large IN parameter lists.
+	* @param request - query text, coarse type filter, page size, ordering.
+	* @returns hits ordered by `sortBy` (relevance by default).
+	*/
+	search(request) {
+		const db = this.requireDb();
+		const match = sanitizeFtsQuery(request.query);
+		if (match === "") return [];
+		const limit = Math.min(Math.max(1, request.limit ?? 20), 100);
+		const types = resolveTypes(request.types);
+		const placeholders = types.map(() => "?").join(", ");
+		const archivedClause = request.archived === "active" ? "AND s.archived = 0" : request.archived === "archived" ? "AND s.archived = 1" : "";
+		const dateClauses = [];
+		const dateParams = [];
+		if (typeof request.from === "number" && Number.isFinite(request.from)) {
+			dateClauses.push("AND s.updated_at >= ?");
+			dateParams.push(request.from);
+		}
+		if (typeof request.to === "number" && Number.isFinite(request.to)) {
+			dateClauses.push("AND s.updated_at < ?");
+			dateParams.push(request.to);
+		}
+		const dateClause = dateClauses.join(" ");
+		const docs = db.prepare(`
+      SELECT d.doc_id AS docId, d.session_id AS sessionId, d.seq, d.type, d.time, d.text,
+             s.title, s.updated_at AS updatedAt, f.rank AS ftsRank
+      FROM (
+        SELECT rowid, rank FROM docs_fts WHERE docs_fts MATCH ? ORDER BY rank LIMIT ?
+      ) f
+      JOIN docs d ON d.doc_id = f.rowid
+      JOIN sessions s ON s.session_id = d.session_id
+      WHERE d.type IN (${placeholders}) AND d.surface = 'current' ${archivedClause} ${dateClause}
+    `).all(match, MATCH_SCAN_LIMIT, ...types, ...dateParams);
+		const bestBySession = /* @__PURE__ */ new Map();
+		for (const doc of docs) {
+			const weight = TYPE_WEIGHT[doc.type] ?? 1;
+			const score = -Number(doc.ftsRank) * weight;
+			const best = bestBySession.get(doc.sessionId);
+			if (best === void 0 || score > best.score) bestBySession.set(doc.sessionId, {
+				doc,
+				score
+			});
+		}
+		const grouped = [...bestBySession.values()];
+		if (request.sortBy === "time") grouped.sort((a, b) => b.doc.updatedAt - a.doc.updatedAt || b.score - a.score);
+		else grouped.sort((a, b) => b.score - a.score);
+		return grouped.slice(0, limit).map(({ doc }) => ({
+			sessionId: doc.sessionId,
+			title: doc.title,
+			seq: doc.seq,
+			type: doc.type,
+			time: doc.time,
+			updatedAt: Number(doc.updatedAt ?? 0),
+			snippet: buildSnippet(doc.text, request.query)
+		}));
+	}
+	requireDb() {
+		if (this.db === void 0) throw new Error("switch-search: index engine is not open");
+		return this.db;
+	}
+};
+/** Materialize the coarse filter into raw event types (absent → user+reply). */
+function resolveTypes(types) {
+	if (types === void 0 || types.length === 0) return ["user/message", "assistant/message"];
+	const picked = /* @__PURE__ */ new Set();
+	for (const entry of types) if (entry === "user" || entry === "reply" || entry === "tool") picked.add(entry);
+	else return [
+		"user/message",
+		"assistant/message",
+		"tool/call",
+		"tool/result"
+	];
+	if (picked.size === 0) return ["user/message", "assistant/message"];
+	return [...picked].flatMap((entry) => [...CONTENT_TYPE_GROUPS[entry]]);
+}
+/** Map one raw sessions row onto the public face. */
+function rowToSession(row) {
+	return {
+		sessionId: String(row["session_id"]),
+		version: Number(row["version"]),
+		title: String(row["title"] ?? ""),
+		cwd: String(row["cwd"] ?? ""),
+		updatedAt: Number(row["updated_at"] ?? 0),
+		indexedAt: Number(row["indexed_at"] ?? 0),
+		archived: Number(row["archived"] ?? 0) === 1
+	};
+}
+//#endregion
+//#region src/host/index/sync.ts
+/** 标题折叠的分块大小（一次 readTitleSnapshots 的 id 数上限,防整批一坏全坏）。 */
+const TITLE_CHUNK = 50;
+/**
+* One watermark syncer bound to one open engine. `poll()` is re-entrant-safe:
+* overlapping calls collapse into the running pass.
+*/
+var SwitchWatermarkSync = class {
+	engine;
+	sessionQuery;
+	readArchiveSource;
+	log;
+	readSessionFromFile;
+	readProjectionTitle;
+	running;
+	state = {
+		state: "idle",
+		lastSyncAt: 0,
+		indexed: 0,
+		total: 0,
+		updated: 0,
+		failures: []
+	};
+	/**
+	* @param readSessionFromFile - 可选的**文件级兜底读取器**（管家 health 侧的
+	* 多帧 zstd 读取器）：sessionQuery.readSession 对某些会话（典型:归档会话,
+	* 或服务面退化）失败时改读转录文件。返回 undefined 表示文件也不可用。
+	*/
+	constructor(engine, sessionQuery, readArchiveSource, log, readSessionFromFile, readProjectionTitle) {
+		this.engine = engine;
+		this.sessionQuery = sessionQuery;
+		this.readArchiveSource = readArchiveSource;
+		this.log = log;
+		this.readSessionFromFile = readSessionFromFile;
+		this.readProjectionTitle = readProjectionTitle;
+	}
+	/**
+	* 读取一个会话的日志:服务面优先,失败落文件兜底。两条路都失败时抛最后
+	* 一个错误,由调用方按会话隔离记失败。
+	*/
+	async readSessionLog(header) {
+		try {
+			return await this.sessionQuery.readSession(header.id);
+		} catch (serviceError) {
+			if (this.readSessionFromFile === void 0) throw serviceError;
+			const fromFile = await this.readSessionFromFile(header.id);
+			if (fromFile !== void 0) {
+				this.log?.(`session ${header.id}: sessionQuery read failed, served from transcript file (${String(serviceError instanceof Error ? serviceError.message : serviceError)})`);
+				return fromFile;
+			}
+			throw serviceError;
+		}
+	}
+	/** Current progress snapshot (cloned). */
+	snapshot() {
+		return {
+			...this.state,
+			failures: [...this.state.failures]
+		};
+	}
+	/**
+	* Fold titles for an explicit id set without running a full pass.
+	*
+	* Used by the `session/title` event listener so a rename lands immediately
+	* rather than at the next poll. It deliberately leaves watermarks alone: a
+	* title-only refresh can never make the index claim content it has not read,
+	* and the next poll still re-ingests the session off its bumped version.
+	* Safe for unknown ids — the header write is a no-op when no row exists.
+	* @param sessionIds - sessions whose titles should be re-folded.
+	*/
+	async refreshTitles(sessionIds) {
+		await this.backfillTitles(sessionIds);
+	}
+	/**
+	* Run one incremental pass (or await the running one).
+	* @returns the state after the pass completes.
+	*/
+	poll() {
+		if (this.running !== void 0) return this.running;
+		this.running = this.runPass().finally(() => {
+			this.running = void 0;
+		});
+		return this.running;
+	}
+	async runPass() {
+		this.state.state = "syncing";
+		const passStart = Date.now();
+		try {
+			const records = await this.sessionQuery.listSessions();
+			this.state.total = records.length;
+			const archiveSource = this.readArchiveSource?.();
+			const archivedSet = new Set(archiveSource?.archivedSessionIds ?? []);
+			this.engine.setArchived(archivedSet);
+			const failures = [];
+			let updated = 0;
+			const changedIds = [];
+			for (const record of records) {
+				const header = record.header;
+				const existing = this.engine.getSession(header.id);
+				if (existing !== void 0 && existing.version === header.version) continue;
+				changedIds.push(header.id);
+				try {
+					const log = await this.readSessionLog(header);
+					this.engine.upsertSession({
+						sessionId: header.id,
+						version: header.version,
+						cwd: log.session.cwd ?? header.cwd ?? "",
+						updatedAt: log.session.createdAt ?? header.createdAt ?? 0,
+						title: extractTitleFromEvents(log.events),
+						events: log.events,
+						archived: archivedSet.has(header.id)
+					});
+					updated += 1;
+				} catch (err) {
+					failures.push({
+						sessionId: header.id,
+						error: String(err instanceof Error ? err.message : err)
+					});
+				}
+			}
+			for (const archivedId of archivedSet) {
+				if (this.engine.getSession(archivedId) !== void 0) continue;
+				try {
+					const log = await this.readSessionLog({
+						id: archivedId,
+						version: -1
+					});
+					this.engine.upsertSession({
+						sessionId: archivedId,
+						version: log.session.version,
+						cwd: log.session.cwd ?? "",
+						updatedAt: log.session.createdAt ?? 0,
+						title: extractTitleFromEvents(log.events),
+						events: log.events,
+						archived: true
+					});
+					updated += 1;
+				} catch (err) {
+					failures.push({
+						sessionId: archivedId,
+						error: `archived: ${String(err instanceof Error ? err.message : err)}`
+					});
+				}
+			}
+			const corpusIds = new Set(records.map((record) => record.header.id));
+			for (const indexed of this.engine.listIndexedSessions()) if (!corpusIds.has(indexed.sessionId) && !archivedSet.has(indexed.sessionId)) this.engine.removeSession(indexed.sessionId);
+			await this.backfillTitles(changedIds);
+			const emptyTitles = this.engine.listIndexedSessions().filter((session) => session.title.trim() === "").map((session) => session.sessionId).slice(0, 100);
+			if (emptyTitles.length > 0) {
+				await this.backfillTitles(emptyTitles);
+				let filled = 0;
+				for (const id of emptyTitles) {
+					const row = this.engine.getSession(id);
+					if (row !== void 0 && row.title.trim() !== "") continue;
+					const fromProjection = this.readProjectionTitle?.(id) ?? "";
+					if (fromProjection.trim() !== "") {
+						this.engine.updateSessionHeader({
+							sessionId: id,
+							title: fromProjection
+						});
+						filled += 1;
+					}
+				}
+				if (filled > 0) this.log?.(`title sweep: ${filled}/${emptyTitles.length} filled from projection cache`);
+			}
+			this.state.updated = updated;
+			this.state.failures = failures;
+			this.state.indexed = this.engine.countSessions();
+			this.state.lastSyncAt = Date.now();
+			this.state.state = "idle";
+			this.state.error = void 0;
+			this.log?.(`sync pass: scanned=${this.state.total} updated=${updated} archived=${archivedSet.size} failures=${failures.length} indexed=${this.state.indexed} duration=${Date.now() - passStart}ms driver=${this.engine.driverLabel}`);
+		} catch (err) {
+			this.state.state = "error";
+			this.state.error = String(err instanceof Error ? err.message : err);
+			this.log?.(`sync pass FAILED: ${this.state.error}`);
+		}
+		return this.snapshot();
+	}
+	/**
+	* Fold latest titles for changed sessions into the index header rows.
+	*
+	* beta.4 教训:整批一次调用,任何一个坏 id（典型:归档 id）让整个 promise
+	* reject,catch 一吞就是**全部**标题丢失。改为分块 + 块失败时逐 id 重试 ——
+	* 单点坏 id 最多损失它自己的精修标题（入索引时的 extractTitleFromEvents
+	* 基础层仍然在）。
+	*/
+	async backfillTitles(sessionIds) {
+		const readTitles = this.sessionQuery.readTitleSnapshots;
+		if (readTitles === void 0 || sessionIds.length === 0) return;
+		const ids = [...new Set(sessionIds)];
+		const foldOne = (observation) => {
+			if (observation.status !== "fulfilled" || observation.value === void 0) return;
+			const title = observation.value.title?.title;
+			if (typeof title === "string" && title.trim().length > 0) this.engine.updateSessionHeader({
+				sessionId: observation.value.session.id,
+				title
+			});
+		};
+		for (let start = 0; start < ids.length; start += TITLE_CHUNK) {
+			const chunk = ids.slice(start, start + TITLE_CHUNK);
+			try {
+				(await readTitles(chunk)).forEach(foldOne);
+			} catch {
+				for (const id of chunk) try {
+					(await readTitles([id])).forEach(foldOne);
+				} catch {}
+			}
+		}
+	}
+};
+//#endregion
+//#region src/host/index/archive-source.ts
+/**
+* Official archive-set source resolution.
+*
+* Primary: the in-process `workspaceRegistry` service (the same fact the UI
+* filters by). Fallback: read the canonical storage hub file directly — the
+* workspace domain persists `archivedSessionIds` under the `global` segment
+* (storage-json: `~/.dsh/storages/workspace.json`; storage-sqlite variant
+* exists but the JSON fallback file is what stock web profiles ship).
+* Resolution order is decided per read; failures degrade to "no archive set"
+* and are reported through the diagnostics face.
+*
+* READ-ONLY by contract. The archive set is WRITTEN by dsh-manage-session
+* (会话管家 → 病案室); this package only consumes it to keep archived sessions
+* out of the index. Format contract: `dsh-归档文件格式契约-20260914.md`.
+*/
+/** DSH storage hub candidates for the workspace domain (json backend). */
+function storageFileCandidates() {
+	return [join(homedir(), ".dsh", "storages", "workspace.json")];
+}
+/** Parse the storage hub file's global.archivedSessionIds; throw on malformed content. */
+function readStorageFile(path) {
+	const ids = JSON.parse(readFileSync(path, "utf8")).global?.archivedSessionIds;
+	if (!Array.isArray(ids)) throw new Error(`storage hub "${path}" holds no global.archivedSessionIds array`);
+	return ids.filter((id) => typeof id === "string");
+}
+/**
+* Resolve the official archive set once.
+* @param registry - lazy workspaceRegistry face (may be absent or throw).
+* @returns the archive ids plus which source served them.
+*/
+function readArchiveSet$1(registry) {
+	if (registry !== void 0) try {
+		const ids = registry.archivedSessionIds;
+		if (Array.isArray(ids)) return {
+			ids,
+			source: "registry"
+		};
+	} catch {}
+	for (const path of storageFileCandidates()) {
+		if (!existsSync(path)) continue;
+		try {
+			return {
+				ids: readStorageFile(path),
+				source: "storage-file"
+			};
+		} catch {}
+	}
+	return {
+		ids: [],
+		source: "none"
+	};
+}
+/** Build the lazy source face the syncer expects, with diagnostics capture. */
+function createArchiveSource(getRegistry) {
+	let last = {
+		source: "none",
+		ids: 0
+	};
+	return {
+		read: () => {
+			const read = readArchiveSet$1(getRegistry());
+			last = {
+				source: read.source,
+				ids: read.ids.length
+			};
+			return read;
+		},
+		diagnostics: () => ({ ...last })
+	};
+}
+//#endregion
+//#region src/host/index/peers.ts
+/**
+* Presence probe for the peer plugin that owns the archived-session domain.
+*
+* Why this exists
+* ---------------
+* This package *reads* the official archive set — archived sessions are
+* excluded from the index — but it no longer *owns* archiving: browsing and
+* disposing of archived sessions moved to `dsh-manage-session`. The settings
+* card went on reporting a bare archived count, with no pointer to the plugin
+* that can act on it. A number the user cannot act on, next to a capability
+* that lives somewhere else, reads as a broken feature.
+*
+* The pointer has to say different things depending on whether the owner is
+* actually installed, and only the host half can answer that: the client
+* bundle cannot resolve another package, and the slot registry exposes no
+* "is anything registered under this id" query.
+*
+* Three states, never two. A probe that cannot run must not be reported as
+* "missing" — that would tell the user to install something they already have.
+*/
+/** The package that owns the archived-session domain. */
+const STEWARD_PACKAGE = "dsh-manage-session";
+/**
+* Probe whether a package resolves from this plugin's own module graph.
+*
+* The bundle lives at `<profile>/node_modules/dsh-search-index/lib/index.mjs`,
+* so resolution runs against `<profile>/node_modules` — exactly where a
+* profile dependency lands, and therefore the same place the host would load
+* the peer from.
+*
+* @param name - the package name to resolve.
+* @param base - resolution base; defaults to this module's own URL, i.e. the
+*   plugin's install directory. Injectable so the classification can be tested
+*   against a fixture that fails in a way this checkout cannot produce.
+* @returns `installed` when it resolves; `missing` only for a genuine
+*   module-not-found; `unknown` for every other failure, because an
+*   unanswerable probe is not evidence of absence.
+*/
+function probePeer(name, base = import.meta.url) {
+	try {
+		createRequire(base).resolve(name);
+		return "installed";
+	} catch (err) {
+		const code = err?.code;
+		return code === "MODULE_NOT_FOUND" || code === "ERR_MODULE_NOT_FOUND" ? "missing" : "unknown";
+	}
+}
+/**
+* Probe whether {@link STEWARD_PACKAGE} is installed alongside this plugin.
+*
+* @returns the resolution state, never a throw.
+*/
+function detectSteward() {
+	return probePeer(STEWARD_PACKAGE);
+}
+//#endregion
+//#region src/host/index/rebuild.ts
+/**
+* Non-destructive index rebuild ("整理索引") for the independent index.
+*
+* A shadow index file is built from scratch beside the active one; the active
+* engine keeps serving queries the whole time. When the shadow is complete the
+* swap is three synchronous renames (active → archive, shadow → active), then
+* the engine reopens. Old archives are kept (bounded) and stay readable.
+*/
+/** Default layout names. */
+const DEFAULT_INDEX_LAYOUT = {
+	dir: ".",
+	active: "index.sqlite",
+	building: "index.building.sqlite",
+	archivePrefix: "index.archive-"
+};
+/**
+* Inspect the index directory for half-built leftovers from an abnormally
+* terminated rebuild and recover:
+* - shadow present + active present: the build never finished — the shadow
+*   is garbage (the active index kept serving) and is discarded.
+* - shadow present + active missing: the crash hit the rename window — the
+*   newest archive is restored as the active index, the shadow discarded.
+* Runs at host activation, before the engine opens (opening would create a
+* fresh empty active file and mask the swap-window case).
+*/
+async function recoverIndex(layout, log) {
+	const actions = [];
+	await mkdir(layout.dir, { recursive: true });
+	const activePath = join(layout.dir, layout.active);
+	const buildingPath = join(layout.dir, layout.building);
+	const activeExists = existsSync(activePath);
+	if (!existsSync(buildingPath)) return actions;
+	const discardShadow = async () => {
+		for (const suffix of [
+			"",
+			"-wal",
+			"-shm"
+		]) await rm(`${buildingPath}${suffix}`, { force: true });
+	};
+	if (activeExists) {
+		await discardShadow();
+		actions.push(`discarded stale shadow index (a previous rebuild did not finish; the active index was never at risk)`);
+	} else {
+		const archives = await listArchives(layout);
+		if (archives.length > 0) {
+			const newest = archives[archives.length - 1];
+			await rename(join(layout.dir, newest), activePath);
+			actions.push(`active index was missing (crash during the swap window); restored "${newest}" as the active index`);
+		} else actions.push("no active index and no archive: the first build crashed mid-way; starting from a fresh index");
+		await discardShadow();
+	}
+	for (const action of actions) log?.(`index recovery: ${action}`);
+	return actions;
+}
+/** List existing archive files, oldest first. */
+async function listArchives(layout) {
+	if (!existsSync(layout.dir)) return [];
+	return (await readdir(layout.dir)).filter((name) => name.startsWith(layout.archivePrefix) && name.endsWith(".sqlite")).sort();
+}
+/** Sessions per batched transaction (one fsync checkpoint per chunk). */
+const REBUILD_CHUNK = 50;
+async function rebuildIndex(activeEngine, layout, sessionQuery, keepArchives, onProgress, archiveSource, hooks) {
+	const startedMs = Date.now();
+	let docsWritten = 0;
+	const emit = () => {
+		hooks?.onState?.({ ...state });
+	};
+	const rate = () => {
+		const secs = Math.max(.001, (Date.now() - startedMs) / 1e3);
+		return `${(state.done / secs).toFixed(1)} sess/s`;
+	};
+	const eta = () => {
+		if (state.total <= 0 || state.done === 0) return "?";
+		const secs = (Date.now() - startedMs) / 1e3;
+		return `${Math.max(0, Math.round((state.total - state.done) / (state.done / secs)))}s`;
+	};
+	const state = {
+		state: "building",
+		done: 0,
+		total: 0,
+		startedAt: Date.now(),
+		finishedAt: 0,
+		failures: []
+	};
+	try {
+		hooks?.log?.(`rebuild started: dir=${layout.dir} keep=${keepArchives}`);
+		emit();
+		await mkdir(layout.dir, { recursive: true });
+		const buildingPath = join(layout.dir, layout.building);
+		if (existsSync(buildingPath)) await unlink(buildingPath);
+		const shadow = new SwitchIndexEngine({ path: buildingPath });
+		await shadow.open();
+		try {
+			const records = await sessionQuery.listSessions();
+			state.total = records.length;
+			hooks?.log?.(`rebuild corpus listed: ${state.total} sessions (archived included, full content)`);
+			emit();
+			const archivedSet = new Set(archiveSource?.()?.archivedSessionIds ?? []);
+			const readLog = async (header) => {
+				let log;
+				try {
+					log = await sessionQuery.readSession(header.id);
+				} catch (serviceError) {
+					if (hooks?.readSessionFromFile === void 0) throw serviceError;
+					const fromFile = await hooks.readSessionFromFile(header.id);
+					if (fromFile === void 0) throw serviceError;
+					log = fromFile;
+				}
+				return {
+					sessionId: header.id,
+					version: log.session.version,
+					title: extractTitleFromEvents(log.events),
+					cwd: log.session.cwd ?? "",
+					updatedAt: log.session.createdAt ?? 0,
+					archived: archivedSet.has(header.id),
+					events: log.events
+				};
+			};
+			for (let i = 0; i < records.length; i += REBUILD_CHUNK) {
+				const chunk = records.slice(i, i + REBUILD_CHUNK);
+				const chunkStart = Date.now();
+				const reads = [];
+				for (const record of chunk) try {
+					reads.push(await readLog(record.header));
+				} catch (err) {
+					state.failures.push({
+						sessionId: record.header.id,
+						error: String(err instanceof Error ? err.message : err)
+					});
+				}
+				try {
+					shadow.runBatched(() => {
+						for (const item of reads) {
+							shadow.upsertSession(item);
+							docsWritten += item.events.length;
+						}
+					});
+				} catch (err) {
+					hooks?.log?.(`rebuild chunk txn failed, replaying individually: ${String(err instanceof Error ? err.message : err)}`);
+					for (const item of reads) try {
+						shadow.upsertSession(item);
+						docsWritten += item.events.length;
+					} catch (e2) {
+						state.failures.push({
+							sessionId: item.sessionId,
+							error: String(e2 instanceof Error ? e2.message : e2)
+						});
+					}
+				}
+				state.done = Math.min(state.total, i + chunk.length);
+				onProgress?.(state.done, state.total);
+				emit();
+				hooks?.log?.(`rebuild ${state.done}/${state.total} (${Math.round(state.done / Math.max(1, state.total) * 100)}%) ${rate()} elapsed ${Math.round((Date.now() - startedMs) / 1e3)}s eta ${eta()} chunk ${Date.now() - chunkStart}ms`);
+			}
+			shadow.setArchived(archivedSet);
+			shadow.close();
+		} catch (error) {
+			shadow.close();
+			await unlink(buildingPath).catch(() => {});
+			throw error;
+		}
+		state.state = "swapping";
+		emit();
+		hooks?.log?.(`rebuild shadow complete: ${state.done} sessions, ~${docsWritten} docs, ${state.failures.length} failures; swapping`);
+		const activePath = join(layout.dir, layout.active);
+		if (existsSync(activePath)) {
+			activeEngine.close();
+			await rename(activePath, join(layout.dir, `${layout.archivePrefix}${Date.now()}.sqlite`));
+		}
+		await rename(buildingPath, activePath);
+		await activeEngine.open();
+		await pruneArchives(layout, keepArchives);
+		state.finishedAt = Date.now();
+		state.state = "idle";
+		emit();
+		hooks?.log?.(`rebuild done: total ${((state.finishedAt - startedMs) / 1e3).toFixed(1)}s, archives pruned to ${keepArchives}`);
+	} catch (err) {
+		state.state = "error";
+		state.error = String(err instanceof Error ? err.message : err);
+		hooks?.log?.(`rebuild FAILED at done=${state.done}: ${state.error}`);
+		emit();
+		if (!activeEngine.isOpen) await activeEngine.open().catch(() => {});
+	}
+	return state;
+}
+/** Import doc-level records into the shadow file and swap it in (same swap path). */
+async function importIntoIndex(activeEngine, layout, records, keepArchives) {
+	const state = {
+		state: "building",
+		done: 0,
+		total: records.length,
+		startedAt: Date.now(),
+		finishedAt: 0,
+		failures: []
+	};
+	try {
+		await mkdir(layout.dir, { recursive: true });
+		const buildingPath = join(layout.dir, layout.building);
+		if (existsSync(buildingPath)) await unlink(buildingPath);
+		const shadow = new SwitchIndexEngine({ path: buildingPath });
+		await shadow.open();
+		try {
+			for (const record of records) {
+				try {
+					shadow.importSessionDocs({
+						sessionId: record.sessionId,
+						version: record.version,
+						title: record.title ?? "",
+						archived: record.archived === true,
+						docs: record.docs
+					});
+				} catch (err) {
+					state.failures.push({
+						sessionId: record.sessionId,
+						error: String(err instanceof Error ? err.message : err)
+					});
+				}
+				state.done += 1;
+			}
+			shadow.close();
+		} catch (error) {
+			shadow.close();
+			await unlink(buildingPath).catch(() => {});
+			throw error;
+		}
+		state.state = "swapping";
+		const activePath = join(layout.dir, layout.active);
+		if (existsSync(activePath)) {
+			activeEngine.close();
+			await rename(activePath, join(layout.dir, `${layout.archivePrefix}${Date.now()}.sqlite`));
+		}
+		await rename(buildingPath, activePath);
+		await activeEngine.open();
+		await pruneArchives(layout, keepArchives);
+		state.finishedAt = Date.now();
+		state.state = "idle";
+	} catch (err) {
+		state.state = "error";
+		state.error = String(err instanceof Error ? err.message : err);
+		if (!activeEngine.isOpen) await activeEngine.open().catch(() => {});
+	}
+	return state;
+}
+/** Remove the oldest archives beyond the retention bound. */
+async function pruneArchives(layout, keep) {
+	const archives = await listArchives(layout);
+	const excess = archives.length - Math.max(0, keep);
+	for (let i = 0; i < excess; i += 1) await unlink(join(layout.dir, archives[i])).catch(() => {});
+}
+/**
+* Resolve the index directory that hosts the independent index files:
+* an explicit override wins, otherwise a plugin-owned directory under the
+* user's home (never the official index path).
+*/
+function resolveIndexDir(preferred) {
+	if (preferred !== void 0 && preferred.trim() !== "") return preferred;
+	return join(homedir(), ".dsh-switch-search");
+}
+//#endregion
+//#region src/host/index/snapshot.ts
+/** Render the snapshot header line. */
+function snapshotHeader() {
+	return JSON.stringify({
+		v: 1,
+		kind: "dsh-switch-search-snapshot",
+		exportedAt: Date.now()
+	});
+}
+/**
+* Export the whole index (active AND archived) as a JSON Lines string.
+* 归档行带 archived 标记一起导出——快照是完整备份,不是活跃子集。
+* @param engine - the open active engine.
+* @returns the complete snapshot text (header line first).
+*/
+function exportSnapshot(engine) {
+	const lines = [snapshotHeader()];
+	for (const session of engine.listIndexedSessions()) lines.push(JSON.stringify({
+		v: 1,
+		sessionId: session.sessionId,
+		version: session.version,
+		title: session.title,
+		...session.archived ? { archived: true } : {},
+		docs: engine.exportSessionDocs(session.sessionId)
+	}));
+	return `${lines.join("\n")}\n`;
+}
+/**
+* Parse a snapshot's JSON Lines text into importable records.
+* The header line and any malformed line are skipped, not fatal.
+* @param text - raw snapshot text.
+* @returns importable records and how many lines were skipped.
+*/
+function parseSnapshot(text) {
+	const records = [];
+	let skipped = 0;
+	for (const line of text.split(/\r?\n/)) {
+		if (line.trim() === "") continue;
+		let value;
+		try {
+			value = JSON.parse(line);
+		} catch {
+			skipped += 1;
+			continue;
+		}
+		if (typeof value !== "object" || value === null || Array.isArray(value)) {
+			skipped += 1;
+			continue;
+		}
+		const record = value;
+		if (record["kind"] === "dsh-switch-search-snapshot") continue;
+		const sessionId = record["sessionId"];
+		const rawDocs = record["docs"];
+		if (typeof sessionId !== "string" || sessionId === "" || !Array.isArray(rawDocs)) {
+			skipped += 1;
+			continue;
+		}
+		const docs = [];
+		let docsValid = true;
+		for (const rawDoc of rawDocs) {
+			if (typeof rawDoc !== "object" || rawDoc === null || typeof rawDoc.seq !== "number" || typeof rawDoc.type !== "string" || typeof rawDoc.text !== "string") {
+				docsValid = false;
+				break;
+			}
+			const doc = rawDoc;
+			docs.push({
+				seq: doc.seq,
+				type: doc.type,
+				surface: typeof doc.surface === "string" ? doc.surface : "current",
+				time: typeof doc.time === "number" ? doc.time : 0,
+				text: doc.text
+			});
+		}
+		if (!docsValid) {
+			skipped += 1;
+			continue;
+		}
+		records.push({
+			sessionId,
+			version: typeof record["version"] === "number" ? record["version"] : 0,
+			title: typeof record["title"] === "string" ? record["title"] : void 0,
+			archived: record["archived"] === true,
+			docs
+		});
+	}
+	return {
+		records,
+		skipped
+	};
+}
+//#endregion
+//#region src/index.ts
+/** 本插件声明的宿主服务（与 toggle 相同的注入面）。0.2.1-a.2 起 webRuntime 更名 webStartup，读取面走双名回退链。 */
+const inject = ["webServer", "webStartup"];
+/** Resolve one possibly-volatile field: a live ref on 0.1.7+, a plain value otherwise. */
+function readVolatileValue(value) {
+	if (value !== null && typeof value === "object" && typeof value.get === "function") return value.get();
+	return value;
+}
+/**
+* `.volatile()` 探针回退（preset-manager 的 volatile breakpoint 同款）：宿主
+* schemastery 只在 0.1.7+ 线提供 `.volatile()`，老线上该方法是 undefined ——
+* 在模块加载期链式调用直接 TypeError，插件整包起不来。这里探测到才链，探测
+* 不到就返回普通字段（老线的配置只来自组合入口，无设置表单，行为正确）。
+*/
+function withVolatile(field) {
+	if (field !== null && typeof field === "object" && typeof field.volatile === "function") return field.volatile();
+	return field;
+}
+/** 运行时配置 schema（与 src/config.ts 的形状保持一致）。0.1.7+：volatile 字段即设置表单。 */
+const Config = z.object({
+	enabled: withVolatile(z.boolean().default(true)),
+	historyFiles: withVolatile(z.boolean().default(true)),
+	healthCheck: withVolatile(z.boolean().default(true)),
+	search: withVolatile(z.boolean().default(true)),
+	defaultMode: withVolatile(z.union(["title", "content"]).default("title")),
+	autoSync: withVolatile(z.boolean().default(true)),
+	syncIntervalMs: withVolatile(z.number().default(3e4)),
+	archiveKeep: withVolatile(z.number().default(2)),
+	indexDir: withVolatile(z.string().default(""))
+});
+/** 单次请求体的上限（防御无界读取）。 */
+const MAX_BODY_BYTES = 16 << 20;
+/** content-search 单次返回的默认会话数上限。 */
+const DEFAULT_LIMIT = 20;
+/** 独立索引目录的环境变量覆盖。 */
+const INDEX_DIR_ENV = "DSH_SWITCH_SEARCH_DIR";
+/** 改名/自动标题落盘的 log-only 事件（追加进日志，会推 version，水位轮询本可迟到一轮兜住）。 */
+const TITLE_EVENT_TYPE = "session/title";
+/** 改名风暴合并为一次标题折叠（自动标题一轮会连发多条）。 */
+const TITLE_FLUSH_MS = 250;
+/** 归一化 Host authority，无法解析时为 undefined。 */
+function parseAuthority(authority) {
+	try {
+		return new URL(`http://${authority}`);
+	} catch {
+		return;
+	}
+}
+/** 主机名是否本机回环。 */
+function isLoopbackHostname(hostname) {
+	if (hostname === "localhost" || hostname === "[::1]") return true;
+	const parts = hostname.split(".");
+	return parts.length === 4 && parts[0] === "127" && parts.every((part) => /^\d{1,3}$/.test(part) && Number(part) <= 255);
+}
+/** Host 是否命中 trustedHosts（精确或省略端口）。 */
+function isTrustedAuthority(hostUrl, trustedHosts) {
+	return trustedHosts.some((entry) => {
+		const entryUrl = parseAuthority(entry);
+		if (entryUrl === void 0) return false;
+		return (entryUrl.port === "" ? entryUrl.hostname : entryUrl.host) === hostUrl.host;
+	});
+}
+/** 浏览器可信围栏（与 /api 网关行为一致）：DNS 重绑定/跨站防御，不是鉴权。 */
+function isTrustedApiRequest(req, trustedHosts) {
+	const host = req.headers.host;
+	if (host === void 0) return false;
+	const hostUrl = parseAuthority(host);
+	if (hostUrl === void 0) return false;
+	if (!isLoopbackHostname(hostUrl.hostname) && !isTrustedAuthority(hostUrl, trustedHosts)) return false;
+	const fetchSite = req.headers["sec-fetch-site"];
+	if (typeof fetchSite === "string" && fetchSite === "cross-site") return false;
+	const origin = req.headers.origin;
+	if (origin === void 0) return true;
+	try {
+		return new URL(origin).host === hostUrl.host;
+	} catch {
+		return false;
+	}
+}
+/** 读原始请求体（有界）。 */
+async function readRawBody(req) {
+	const chunks = [];
+	let total = 0;
+	for await (const chunk of req) {
+		const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+		total += buffer.length;
+		if (total > MAX_BODY_BYTES) throw new Error("request body too large");
+		chunks.push(buffer);
+	}
+	return Buffer.concat(chunks).toString("utf8");
+}
+/** 读 JSON 请求体（空体视为 {}）。 */
+async function readJsonBody(req) {
+	const text = await readRawBody(req);
+	if (text.trim() === "") return {};
+	try {
+		return JSON.parse(text);
+	} catch {
+		throw new Error("request body is not JSON");
 	}
 }
 /** 写 JSON 响应。 */
@@ -2418,6 +4227,14 @@ function writeJson(res, status, body) {
 	res.writeHead(status, { "content-type": "application/json; charset=utf-8" });
 	res.end(text);
 }
+/** 写原始文本响应。 */
+function writeRaw(res, status, contentType, body) {
+	res.writeHead(status, {
+		"content-type": contentType,
+		"cache-control": "no-cache"
+	});
+	res.end(body);
+}
 /** 会话 id 形状校验（拒绝任意字符串进入路径拼接）。 */
 function asSessionId(value) {
 	if (typeof value !== "string") return void 0;
@@ -2436,8 +4253,11 @@ const MAX_SCAN_LIMIT = 200;
 */
 const HISTORY_METHODS = [
 	"session-history-list",
+	"session-history-archive",
 	"session-history-prune",
-	"session-history-purge"
+	"session-history-purge",
+	"session-history-favorites-list",
+	"session-history-favorite-set"
 ];
 const HEALTH_METHODS = [
 	"session-health-status",
@@ -2446,34 +4266,508 @@ const HEALTH_METHODS = [
 	"session-health-repair",
 	"session-health-source-migrate"
 ];
+/** 搜索索引子域方法（`/switch-search/api`；index-export/import 走原始体，其余 JSON）。 */
+const INDEX_METHODS = [
+	"list-sessions",
+	"content-search",
+	"search-status",
+	"index-status",
+	"index-rebuild",
+	"index-export",
+	"index-import"
+];
 /** 依据开关判定某方法是否启用。 */
 function methodEnabled(method, config) {
 	if (HISTORY_METHODS.includes(method)) return config.historyFiles !== false;
 	if (HEALTH_METHODS.includes(method)) return config.healthCheck !== false;
+	if (INDEX_METHODS.includes(method)) return config.search !== false;
 	return false;
 }
+/** Fold titles for a set of sessions into a sessionId → title map. */
+async function titleMap(sessionQuery, sessionIds) {
+	if (sessionIds.length === 0) return /* @__PURE__ */ new Map();
+	const observations = await sessionQuery.readTitleSnapshots([...new Set(sessionIds)]);
+	const map = /* @__PURE__ */ new Map();
+	for (const observation of observations) {
+		if (observation.status !== "fulfilled" || observation.value === void 0) continue;
+		const title = observation.value.title?.title;
+		if (typeof title === "string" && title.trim().length > 0) map.set(observation.value.session.id, title);
+	}
+	return map;
+}
+/** list-sessions: the title-search corpus (index-served, live fallback). */
+async function listSessions(srt) {
+	const index = srt.index;
+	const sessionQuery = srt.sessionQuery;
+	if (index.engine.isOpen && index.engine.countSessions() > 0) {
+		if (sessionQuery !== void 0 && index.sync.snapshot().state !== "syncing") index.sync.poll().catch(() => {});
+		return {
+			ok: true,
+			items: index.engine.listIndexedSessions().map((session) => ({
+				sessionId: session.sessionId,
+				title: session.title,
+				cwd: session.cwd,
+				updatedAt: session.updatedAt,
+				archived: session.archived
+			}))
+		};
+	}
+	if (sessionQuery === void 0) return {
+		ok: false,
+		error: "sessionQuery 服务不可用，且独立索引尚未建立"
+	};
+	try {
+		const records = await sessionQuery.listSessions();
+		const titles = await titleMap(sessionQuery, records.map((record) => record.header.id));
+		return {
+			ok: true,
+			items: records.map((record) => ({
+				sessionId: record.header.id,
+				title: titles.get(record.header.id) ?? "",
+				cwd: record.header.cwd ?? "",
+				updatedAt: record.header.createdAt,
+				archived: false
+			}))
+		};
+	} catch (err) {
+		return {
+			ok: false,
+			error: String(err instanceof Error ? err.message : err)
+		};
+	}
+}
+/**
+* content-search: session-grouped hits from the independent index.
+* `sortBy: 'time'` orders by session recency (`updatedAt`), anything else by
+* relevance; the host orders before truncating so the page is honest.
+*/
+async function contentSearch(srt, payload) {
+	const record = payload;
+	const query = typeof record?.query === "string" ? record.query.trim() : "";
+	if (query === "") return {
+		ok: false,
+		error: "缺少 query"
+	};
+	const archived = record?.archived === "active" ? "active" : record?.archived === "archived" ? "archived" : "all";
+	const fromMs = dayBoundaryMs(record?.from);
+	const toMs = record?.to === void 0 ? void 0 : dayBoundaryMs(record?.to, true);
+	const requestedLimit = typeof record?.limit === "number" && Number.isSafeInteger(record.limit) ? record.limit : DEFAULT_LIMIT;
+	const limit = Math.min(Math.max(1, requestedLimit), 100);
+	const sortBy = record?.sortBy === "time" ? "time" : "relevance";
+	let types;
+	if (Array.isArray(record?.types) && record.types.length > 0) types = record.types.filter((entry) => entry === "all" || entry === "user" || entry === "reply" || entry === "tool");
+	else types = ["user", "reply"];
+	const index = srt.index;
+	if (index.engine.isOpen === false) return {
+		ok: false,
+		error: "独立索引未就绪：请在面板或设置中先建立索引（整理索引）"
+	};
+	try {
+		return {
+			ok: true,
+			items: index.engine.search({
+				query,
+				types,
+				limit,
+				sortBy,
+				archived,
+				from: fromMs,
+				to: toMs
+			})
+		};
+	} catch (err) {
+		return {
+			ok: false,
+			error: String(err instanceof Error ? err.message : err)
+		};
+	}
+}
+/** search-status: probe the independent index readiness and progress. */
+async function searchStatus(srt) {
+	const index = srt.index;
+	const sync = index.sync.snapshot();
+	return {
+		ok: true,
+		available: index.engine.isOpen && index.engine.countSessions() > 0,
+		reason: index.engine.isOpen ? void 0 : "not-open",
+		indexing: sync.state === "syncing",
+		archivedSessions: index.engine.countArchived(),
+		archive: index.archiveReader.diagnostics(),
+		sync,
+		rebuild: index.rebuild
+	};
+}
+/** index-status: full lifecycle surface for the settings row. */
+async function indexStatus(srt) {
+	const index = srt.index;
+	const sync = index.sync.snapshot();
+	let indexed = sync.indexed;
+	if (index.engine.isOpen) indexed = index.engine.countSessions();
+	return {
+		ok: true,
+		available: index.engine.isOpen && indexed > 0,
+		archivedSessions: index.engine.isOpen ? index.engine.countArchived() : 0,
+		steward: detectSteward(),
+		driver: index.engine.driverLabel,
+		archive: index.archiveReader.diagnostics(),
+		dir: index.layout.dir,
+		archives: await listArchives(index.layout).catch(() => []),
+		sync: {
+			...sync,
+			indexed
+		},
+		rebuild: index.rebuild
+	};
+}
+/**
+* index-rebuild: start the non-destructive 整理 (shadow build → atomic swap →
+* archives). Responds immediately; progress rides index-status.
+*/
+async function indexRebuild(srt) {
+	const index = srt.index;
+	if (index.rebuild.state === "building" || index.rebuild.state === "swapping") return {
+		ok: false,
+		error: "整理已在进行中"
+	};
+	const sessionQuery = srt.sessionQuery;
+	if (sessionQuery === void 0 || sessionQuery.readSession === void 0) return {
+		ok: false,
+		error: "sessionQuery 服务不可用，无法读取会话日志"
+	};
+	const config = srt.config();
+	const keepArchives = Math.max(0, config.archiveKeep ?? SWITCH_DEFAULT_CONFIG.archiveKeep);
+	rebuildIndex(index.engine, index.layout, {
+		listSessions: () => sessionQuery.listSessions(),
+		readSession: async (sessionId) => {
+			const snapshot = await sessionQuery.readSession(sessionId);
+			return {
+				session: snapshot.session,
+				events: snapshot.events
+			};
+		}
+	}, keepArchives, void 0, srt.registry, {
+		log: srt.log,
+		onState: (live) => {
+			index.rebuild = live;
+		},
+		readSessionFromFile: srt.readSessionFromFile
+	}).then((state) => {
+		index.rebuild = state;
+	}).catch((err) => {
+		index.rebuild = {
+			state: "error",
+			done: 0,
+			total: 0,
+			startedAt: Date.now(),
+			finishedAt: 0,
+			failures: [],
+			error: String(err instanceof Error ? err.message : err)
+		};
+	});
+	index.rebuild = {
+		state: "building",
+		done: 0,
+		total: 0,
+		startedAt: Date.now(),
+		finishedAt: 0,
+		failures: []
+	};
+	return {
+		ok: true,
+		started: true
+	};
+}
+/**
+* Tombs for the two methods the search package used to own before the
+* steward merge. A stale client bundle (browser refresh does not reload the
+* host half) must fail LOUDLY and be told where the feature went — a silent
+* 404 would read as "archiving is broken".
+*/
+const MOVED_TO_HISTORY = {
+	"list-archived": "session-history-list",
+	"archive-prune": "session-history-prune"
+};
+/** Build the explicit "moved" error body for a tombstoned method. */
+function movedToHistory(method) {
+	const replacement = MOVED_TO_HISTORY[method];
+	return {
+		ok: false,
+		error: `"${method}" 已并入会话管家 history 子域：请改用 POST ${STEWARD_API_PREFIX}/${replacement}`
+	};
+}
+/** index-export: dump the active index as JSON Lines. */
+async function indexExport(srt, res) {
+	const index = srt.index;
+	if (index.engine.isOpen === false) {
+		writeJson(res, 200, {
+			ok: false,
+			error: "独立索引未就绪"
+		});
+		return;
+	}
+	writeRaw(res, 200, "application/x-ndjson; charset=utf-8", exportSnapshot(index.engine));
+}
+/** index-import: parse a JSON Lines snapshot and swap it in as the active index. */
+async function indexImport(srt, text) {
+	const index = srt.index;
+	if (index.rebuild.state === "building" || index.rebuild.state === "swapping") return {
+		ok: false,
+		error: "整理/导入已在进行中"
+	};
+	if (text.includes("\"snapshot\"")) try {
+		const envelope = JSON.parse(text);
+		if (typeof envelope.snapshot === "string") text = envelope.snapshot;
+	} catch {}
+	const parsed = parseSnapshot(text);
+	if (parsed.records.length === 0) return {
+		ok: false,
+		error: `快照无可导入会话（跳过 ${parsed.skipped} 行）`
+	};
+	const config = srt.config();
+	const keepArchives = Math.max(0, config.archiveKeep ?? SWITCH_DEFAULT_CONFIG.archiveKeep);
+	importIntoIndex(index.engine, index.layout, parsed.records, keepArchives).then((state) => {
+		index.rebuild = state;
+	}).catch((err) => {
+		index.rebuild = {
+			state: "error",
+			done: 0,
+			total: parsed.records.length,
+			startedAt: Date.now(),
+			finishedAt: 0,
+			failures: [],
+			error: String(err instanceof Error ? err.message : err)
+		};
+	});
+	index.rebuild = {
+		state: "building",
+		done: 0,
+		total: parsed.records.length,
+		startedAt: Date.now(),
+		finishedAt: 0,
+		failures: []
+	};
+	return {
+		ok: true,
+		started: true,
+		sessions: parsed.records.length,
+		skipped: parsed.skipped
+	};
+}
+/** JSON 面的搜索子域方法分发（index-export/import 走原始体，在路由层特判）。 */
+async function handleIndexMethod(method, payload, srt) {
+	if (method === "list-sessions") return await listSessions(srt);
+	if (method === "content-search") return await contentSearch(srt, payload);
+	if (method === "search-status") return await searchStatus(srt);
+	if (method === "index-status") return await indexStatus(srt);
+	if (method === "index-rebuild") return await indexRebuild(srt);
+	return {
+		ok: false,
+		error: `未知的 switch-search API 方法 "${method}"`
+	};
+}
+/** 逐 id 串行调用官方内存方法;失败按会话隔离收集（AM 批量语义）。 */
+async function runMemoryArchiveOps(registry, ids, op) {
+	const fn = op === "archive" ? registry.archiveSession : registry.unarchiveSession;
+	const succeeded = [];
+	const failures = [];
+	for (const id of ids) try {
+		await fn.call(registry, id);
+		succeeded.push(id);
+	} catch (err) {
+		failures.push({
+			sessionId: id,
+			reason: String(err instanceof Error ? err.message : err)
+		});
+	}
+	return {
+		succeeded,
+		failures
+	};
+}
+/** 收藏文件候选（与管家其余域同一 dshHome 纪律）。 */
+function favoritesPathsFor(dshHome) {
+	return [join(dshHome, "storages", "session-steward-favorites.json")];
+}
+/** 本地日界（YYYY-MM-DD → epoch ms;nextDay 为排他上界）。非法返回 undefined。 */
+function dayBoundaryMs(value, nextDay = false) {
+	if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(value)) return void 0;
+	const [year, month, day] = value.split("-").map(Number);
+	const date = new Date(year, month - 1, day);
+	if (date.getFullYear() !== year || date.getMonth() !== month - 1 || date.getDate() !== day) return void 0;
+	if (nextDay) date.setDate(date.getDate() + 1);
+	return date.getTime();
+}
+/** 从 payload 抽合法 sessionIds（与 prune/purge 的入参纪律一致）；不合法返回 undefined。 */
+function validSessionIds(value) {
+	if (!Array.isArray(value) || value.length === 0) return void 0;
+	const ids = [...new Set(value.filter((id) => typeof id === "string" && id !== ""))];
+	return ids.length > 0 ? ids : void 0;
+}
 /**
-* 处理一次 API 调用（导出以便单测直接驱动，不需要起 HTTP）。
+* 处理一次管家子域 API 调用（导出以便单测直接驱动，不需要起 HTTP）。
 * @param method - 路由方法名。
 * @param payload - 已解析的请求体。
 * @param runtime - 运行时依赖。
 */
+/** 现代宿主的只读投影：把运行时配置拆成两命名空间形状（describe 用）。 */
+function configSnapshotProjection(config) {
+	return {
+		[STEWARD_SETTINGS_NAMESPACE]: {
+			enabled: config.enabled,
+			historyFiles: config.historyFiles,
+			healthCheck: config.healthCheck,
+			search: config.search
+		},
+		[SWITCH_SEARCH_SETTINGS_NAMESPACE]: {
+			enabled: config.enabled,
+			defaultMode: config.defaultMode ?? SWITCH_DEFAULT_CONFIG.defaultMode,
+			autoSync: config.autoSync ?? SWITCH_DEFAULT_CONFIG.autoSync,
+			syncIntervalMs: config.syncIntervalMs ?? SWITCH_DEFAULT_CONFIG.syncIntervalMs,
+			archiveKeep: config.archiveKeep ?? SWITCH_DEFAULT_CONFIG.archiveKeep,
+			indexDir: config.indexDir ?? SWITCH_DEFAULT_CONFIG.indexDir
+		}
+	};
+}
 async function handleMethod(method, payload, runtime) {
 	const config = runtime.config();
-	if (![...HISTORY_METHODS, ...HEALTH_METHODS].includes(method)) return {
+	const settingsMethods = method === "settings-describe" || method === "settings-mutate";
+	if (![
+		...HISTORY_METHODS,
+		...HEALTH_METHODS,
+		"settings-describe",
+		"settings-mutate"
+	].includes(method)) return {
 		ok: false,
 		error: `未知的 session-steward API 方法 "${method}"`
 	};
-	if (!methodEnabled(method, config)) return {
+	if (!settingsMethods && !methodEnabled(method, config)) return {
 		ok: false,
 		error: `子域已关闭（${HISTORY_METHODS.includes(method) ? "historyFiles" : "healthCheck"}=false）：${method} 未注册`
 	};
+	if (method === "settings-describe") {
+		const state = runtime.settingsBridge;
+		if (state !== void 0 && state.bridge !== void 0) return settingsDescribe(state);
+		return {
+			ok: true,
+			namespaces: configSnapshotProjection(config),
+			writable: false,
+			revision: state?.revision ?? 0
+		};
+	}
+	if (method === "settings-mutate") return await settingsMutate(runtime.settingsBridge ?? {
+		bridge: void 0,
+		revision: 0
+	}, payload);
 	if (method === "session-history-list") return await listHistory(runtime.registry, void 0, storagePathsFor(runtime.dshHome), runtime.dshHome);
-	if (method === "session-history-prune") return pruneHistory(payload, runtime.log, storagePathsFor(runtime.dshHome));
-	if (method === "session-history-purge") return purgeHistory(payload, runtime.log, {
-		dshHome: runtime.dshHome,
-		searchPaths: storagePathsFor(runtime.dshHome)
-	});
+	if (method === "session-history-archive") {
+		const ids = validSessionIds((payload ?? {}).sessionIds);
+		if (ids === void 0) return {
+			ok: false,
+			error: "缺少 sessionIds 数组"
+		};
+		const mem = runtime.registry();
+		if (mem?.archiveSession !== void 0) {
+			const before = new Set(mem.archivedSessionIds ?? []);
+			const { succeeded, failures } = await runMemoryArchiveOps(mem, ids, "archive");
+			runtime.index?.onArchive(succeeded);
+			const total = (mem.archivedSessionIds ?? []).length;
+			return {
+				ok: true,
+				added: ids.filter((id) => !before.has(id)).length,
+				total,
+				requiresRestart: false,
+				...failures.length === 0 ? {} : { failures }
+			};
+		}
+		const result = archiveHistory(payload, runtime.log, storagePathsFor(runtime.dshHome));
+		if (result.ok) runtime.index?.onArchive(ids);
+		return result;
+	}
+	if (method === "session-history-prune") {
+		const ids = validSessionIds((payload ?? {}).sessionIds);
+		const mem = runtime.registry();
+		if (mem?.unarchiveSession !== void 0 && ids !== void 0) {
+			const { succeeded, failures } = await runMemoryArchiveOps(mem, ids, "unarchive");
+			runtime.index?.onUnarchive(succeeded);
+			const remaining = (mem.archivedSessionIds ?? []).length;
+			return {
+				ok: true,
+				removed: succeeded.length,
+				remaining,
+				requiresRestart: false,
+				...failures.length === 0 ? {} : { failures }
+			};
+		}
+		const result = pruneHistory(payload, runtime.log, storagePathsFor(runtime.dshHome));
+		if (result.ok && ids !== void 0) runtime.index?.onUnarchive(ids);
+		return result;
+	}
+	if (method === "session-history-purge") {
+		const ids = validSessionIds((payload ?? {}).sessionIds);
+		if (ids === void 0) return {
+			ok: false,
+			error: "缺少 sessionIds 数组"
+		};
+		const mem = runtime.registry();
+		if (typeof mem?.deleteSession === "function") {
+			mem.dshHome = runtime.dshHome;
+			const succeeded = [];
+			const failures = [];
+			const usage = locateSessionUsage(ids, runtime.dshHome);
+			let freedBytes = 0;
+			for (const id of ids) {
+				freedBytes += usage.get(id)?.bytes ?? 0;
+				freedBytes += usage.get(id)?.cacheBytes ?? 0;
+			}
+			for (const id of ids) try {
+				const outcome = await mem.deleteSession(id);
+				if (outcome.ok) succeeded.push(id);
+				else failures.push({
+					sessionId: id,
+					reason: outcome.error ?? "删除失败"
+				});
+			} catch (err) {
+				failures.push({
+					sessionId: id,
+					reason: String(err instanceof Error ? err.message : err)
+				});
+			}
+			runtime.index?.onPurged(succeeded);
+			return {
+				ok: true,
+				purged: succeeded.length,
+				freedBytes,
+				requiresRestart: false,
+				...failures.length === 0 ? {} : { failures }
+			};
+		}
+		const result = purgeHistory(payload, runtime.log, {
+			dshHome: runtime.dshHome,
+			searchPaths: storagePathsFor(runtime.dshHome)
+		});
+		if (result.ok && ids !== void 0) {
+			const failed = new Set((result.failures ?? []).map((f) => f.sessionId));
+			runtime.index?.onPurged(ids.filter((id) => !failed.has(id)));
+		}
+		return result;
+	}
+	if (method === "session-history-favorites-list") return {
+		ok: true,
+		favorites: listFavorites(favoritesPathsFor(runtime.dshHome))
+	};
+	if (method === "session-history-favorite-set") {
+		const request = payload ?? {};
+		const sessionId = asSessionId(request.sessionId);
+		if (sessionId === void 0) return {
+			ok: false,
+			error: "缺少合法的 sessionId"
+		};
+		if (typeof request.favorite !== "boolean") return {
+			ok: false,
+			error: "缺少 favorite 布尔值"
+		};
+		return setFavoriteState(sessionId, request.favorite, favoritesPathsFor(runtime.dshHome));
+	}
 	if (method === "session-health-status") return {
 		ok: true,
 		namespace: STEWARD_SETTINGS_NAMESPACE,
@@ -2627,15 +4921,21 @@ async function handleMethod(method, payload, runtime) {
 	};
 }
 /**
-* 插件主体：装配运行时、挂载 fenced 路由。
-* @param ctx - host 插件上下文（webServer / webRuntime / 可选 sessionQuery、sessions、sessionProjections）。
+* 插件主体：装配运行时、挂载两条 fenced 路由与索引生命周期。
+* @param ctx - host 插件上下文（webServer / webStartup（旧名 webRuntime）/ 可选 sessionQuery、workspaceRegistry）。
 * @param config - 组合条目（0.1.7：`.volatile()` 字段为 live ref）。
 */
 function apply(ctx, config = {}) {
 	const current = () => ({
 		enabled: readVolatileValue(config.enabled) ?? DEFAULT_CONFIG.enabled,
 		historyFiles: readVolatileValue(config.historyFiles) ?? DEFAULT_CONFIG.historyFiles,
-		healthCheck: readVolatileValue(config.healthCheck) ?? DEFAULT_CONFIG.healthCheck
+		healthCheck: readVolatileValue(config.healthCheck) ?? DEFAULT_CONFIG.healthCheck,
+		search: readVolatileValue(config.search) ?? DEFAULT_CONFIG.search,
+		defaultMode: readVolatileValue(config.defaultMode) ?? SWITCH_DEFAULT_CONFIG.defaultMode,
+		autoSync: readVolatileValue(config.autoSync) ?? SWITCH_DEFAULT_CONFIG.autoSync,
+		syncIntervalMs: readVolatileValue(config.syncIntervalMs) ?? SWITCH_DEFAULT_CONFIG.syncIntervalMs,
+		archiveKeep: readVolatileValue(config.archiveKeep) ?? SWITCH_DEFAULT_CONFIG.archiveKeep,
+		indexDir: readVolatileValue(config.indexDir) ?? SWITCH_DEFAULT_CONFIG.indexDir
 	});
 	const log = (message) => {
 		try {
@@ -2645,9 +4945,9 @@ function apply(ctx, config = {}) {
 	const homeEnv = process.env["DSH_HOME"];
 	const resolvedHome = homeEnv !== void 0 && homeEnv !== "" ? homeEnv : join(homedir(), ".dsh");
 	const webServer = ctx.webServer;
-	const webRuntime = ctx.webRuntime;
+	const webRuntime = ctx.webStartup ?? ctx.get?.("webRuntime");
 	if (webServer === void 0 || webRuntime === void 0) {
-		log("webServer / webRuntime 不可用：不注册路由");
+		log("webServer / webStartup(webRuntime) 不可用：不注册路由");
 		return;
 	}
 	let ownerIndex;
@@ -2676,17 +4976,170 @@ function apply(ctx, config = {}) {
 	const registry = () => ctx.get("workspaceRegistry");
 	const runtime = {
 		config: () => current(),
+		settingsBridge: installLegacySettingsBridge(ctx),
 		dshHome: resolvedHome,
 		registry,
 		projectionStateFor,
 		attribute: attributor,
 		log,
-		cache: new HealthCache()
+		cache: new HealthCache(),
+		index: {
+			onArchive: (ids) => {
+				if (!engine.isOpen) return;
+				try {
+					for (const id of ids) engine.setArchivedOne(id, true);
+				} catch (err) {
+					log(`index onArchive failed: ${String(err instanceof Error ? err.message : err)}`);
+				}
+			},
+			onUnarchive: (ids) => {
+				if (!engine.isOpen) return;
+				try {
+					for (const id of ids) engine.setArchivedOne(id, false);
+				} catch (err) {
+					log(`index onUnarchive failed: ${String(err instanceof Error ? err.message : err)}`);
+				}
+			},
+			onPurged: (ids) => {
+				if (!engine.isOpen) return;
+				try {
+					for (const id of ids) engine.removeSession(id);
+				} catch (err) {
+					log(`index onPurged failed: ${String(err instanceof Error ? err.message : err)}`);
+				}
+			}
+		}
+	};
+	const initial = current();
+	const sessionQuery = ctx.get("sessionQuery");
+	const archiveReader = createArchiveSource(() => ctx.get("workspaceRegistry"));
+	const indexLayout = {
+		...DEFAULT_INDEX_LAYOUT,
+		dir: resolveIndexDir(initial.indexDir || process.env[INDEX_DIR_ENV])
+	};
+	const engine = new SwitchIndexEngine({ path: `${indexLayout.dir}/${indexLayout.active}` });
+	const readSessionFromFile = async (sessionId) => {
+		try {
+			const logPath = findSessionLog(sessionId, resolvedHome);
+			if (logPath === void 0) return void 0;
+			const decoded = decodeSessionLogFile(logPath);
+			return {
+				session: {
+					id: sessionId,
+					version: 0
+				},
+				events: decoded.events.map((event) => ({
+					seq: event.seq,
+					type: event.type,
+					time: event.time,
+					surfaceOp: event.surfaceOp,
+					data: event.data
+				}))
+			};
+		} catch (err) {
+			log(`file fallback read failed for ${sessionId}: ${String(err instanceof Error ? err.message : err)}`);
+			return;
+		}
+	};
+	const readProjectionTitle = (sessionId) => {
+		try {
+			const path = join(resolvedHome, "storages", "session_projcache", "sessions", `${sessionId}.json`);
+			if (!existsSync(path)) return "";
+			const value = JSON.parse(readFileSync(path, "utf8")).record?.rows?.title?.val;
+			return typeof value === "string" ? value : "";
+		} catch {
+			return "";
+		}
+	};
+	const indexState = {
+		engine,
+		archiveReader,
+		sync: new SwitchWatermarkSync(engine, {
+			listSessions: () => sessionQuery?.listSessions() ?? Promise.resolve([]),
+			readSession: async (sessionId) => {
+				if (sessionQuery?.readSession === void 0) throw new Error("sessionQuery.readSession 不可用");
+				return sessionQuery.readSession(sessionId);
+			},
+			readTitleSnapshots: sessionQuery === void 0 ? void 0 : (ids) => sessionQuery.readTitleSnapshots(ids)
+		}, () => ({ archivedSessionIds: archiveReader.read().ids }), log, readSessionFromFile, readProjectionTitle),
+		layout: indexLayout,
+		rebuild: {
+			state: "idle",
+			done: 0,
+			total: 0,
+			startedAt: 0,
+			finishedAt: 0,
+			failures: []
+		}
+	};
+	const srt = {
+		sessionQuery,
+		index: indexState,
+		config: () => current(),
+		registry: () => ({ archivedSessionIds: archiveReader.read().ids }),
+		log,
+		readSessionFromFile
 	};
-	if (current().enabled === false) {
+	const initialConfig = current();
+	if (initialConfig.enabled === false) {
 		log("enabled=false：不注册任何路由");
 		return;
 	}
+	let syncTimer;
+	const scheduleSync = (intervalMs) => {
+		if (syncTimer !== void 0) clearInterval(syncTimer);
+		if (intervalMs <= 0) return;
+		syncTimer = setInterval(() => {
+			const latest = current();
+			if (latest.enabled === false || latest.search === false || latest.autoSync === false) return;
+			indexState.sync.poll().catch(() => {});
+		}, Math.max(5e3, intervalMs));
+	};
+	let pendingTitleIds = /* @__PURE__ */ new Set();
+	let titleTimer;
+	const flushPendingTitles = () => {
+		titleTimer = void 0;
+		const ids = [...pendingTitleIds];
+		pendingTitleIds = /* @__PURE__ */ new Set();
+		if (ids.length === 0) return;
+		indexState.sync.refreshTitles(ids).catch(() => {});
+	};
+	ctx.effect(() => {
+		const bus = ctx;
+		if (typeof bus.on !== "function") return () => {};
+		try {
+			return bus.on("session/event", (session, event) => {
+				if (event?.type !== TITLE_EVENT_TYPE) return;
+				const latest = current();
+				if (latest.enabled === false || latest.search === false || latest.autoSync === false) return;
+				const id = session?.id;
+				if (typeof id !== "string" || id === "") return;
+				pendingTitleIds.add(id);
+				if (titleTimer !== void 0) return;
+				titleTimer = setTimeout(flushPendingTitles, TITLE_FLUSH_MS);
+			});
+		} catch {
+			return () => {};
+		}
+	}, "dsh-manage-session: realtime titles");
+	if (initialConfig.search !== false) (async () => {
+		try {
+			const recovered = await recoverIndex(indexLayout, log);
+			if (recovered.length > 0) log(`index recovery applied ${recovered.length} fix(es)`);
+		} catch (err) {
+			log(`index recovery failed: ${String(err instanceof Error ? err.message : err)}`);
+		}
+		await engine.open().catch(() => {});
+		log(`index open: driver=${engine.driverLabel} dir=${indexLayout.dir}`);
+		if (engine.driverLabel === "node:sqlite") log("tip: optional speedup not active — approve the better-sqlite3 build (add \"better-sqlite3@*: true\" under allowBuilds in the profile pnpm-workspace.yaml, then reinstall) to speed up index rebuilds; everything works without it");
+		if (initialConfig.autoSync !== false) await indexState.sync.poll().catch(() => {});
+		scheduleSync(initialConfig.syncIntervalMs ?? SWITCH_DEFAULT_CONFIG.syncIntervalMs);
+	})();
+	ctx.effect(() => () => {
+		if (syncTimer !== void 0) clearInterval(syncTimer);
+		if (titleTimer !== void 0) clearTimeout(titleTimer);
+		engine.close();
+	}, "dsh-manage-session: index lifecycle");
 	ctx.effect(() => webServer.register({
 		kind: "prefix",
 		path: STEWARD_API_PREFIX,
@@ -2725,6 +5178,64 @@ function apply(ctx, config = {}) {
 			}
 		}
 	}), "dsh-manage-session: /session-steward/api route");
+	ctx.effect(() => webServer.register({
+		kind: "prefix",
+		path: SWITCH_API_PREFIX,
+		handler: async (req, res) => {
+			if (!isTrustedApiRequest(req, webRuntime.trustedHosts)) {
+				writeJson(res, 403, {
+					ok: false,
+					error: "forbidden"
+				});
+				return;
+			}
+			if (req.method !== "POST") {
+				writeJson(res, 405, {
+					ok: false,
+					error: "method not allowed"
+				});
+				return;
+			}
+			const pathname = new URL(req.url ?? "/", "http://dsh.internal").pathname;
+			const prefix = `${SWITCH_API_PREFIX}/`;
+			const method = pathname.startsWith(prefix) ? pathname.slice(prefix.length) : void 0;
+			if (method === void 0 || method === "" || method.includes("/")) {
+				writeJson(res, 404, {
+					ok: false,
+					error: "unknown switch-search API method"
+				});
+				return;
+			}
+			if (method in MOVED_TO_HISTORY) {
+				writeJson(res, 410, movedToHistory(method));
+				return;
+			}
+			try {
+				if (methodEnabled(method, current()) === false) {
+					writeJson(res, 200, {
+						ok: false,
+						error: `子域已关闭（search=false）：${method} 未注册`
+					});
+					return;
+				}
+				if (method === "index-export") {
+					await indexExport(srt, res);
+					return;
+				}
+				if (method === "index-import") {
+					const text = await readRawBody(req);
+					writeJson(res, 200, await indexImport(srt, text));
+					return;
+				}
+				writeJson(res, 200, await handleIndexMethod(method, await readJsonBody(req), srt));
+			} catch (err) {
+				writeJson(res, 400, {
+					ok: false,
+					error: err instanceof Error ? err.message : String(err)
+				});
+			}
+		}
+	}), "dsh-manage-session: /switch-search/api route");
 }
 //#endregion
-export { Config, DEFAULT_CONFIG, HEALTH_METHODS, HISTORY_METHODS, HealthCache, SOURCE_MIGRATE_BACKUP_SUFFIX, STEWARD_API_PREFIX, STEWARD_SETTINGS_NAMESPACE, V4_HOST_MIN, apply, assessRepair, backupFilesIn, buildProjectionOwnerIndex, buildSessionReport, classifyGenerationFilename, countCorpus, createAttributor, decodeSessionLogBytes, decodeSessionLogFile, dirSize, discoverSessions, editWorkspaceDocument, findSession, findSessionLog, firstLosslessViolation, gateColdRead, gateGeneration, gateLogIntegrity, gateLosslessJson, gateProjectionCache, gateSourceKind, generationLogFilename, handleMethod, indexSessionDirs, inject, isLossless, isMigrationStagingFilename, isSafeChild, isSourceMigrateBackupName, latestArtifactMtime, listHistory, locateSessionUsage, methodEnabled, migrateLegacySource, migrateSessionSourceKind, parseGenerationLogFilename, prescribe, projCacheRootFor, pruneArchiveFile, pruneHistory, purgeHistory, quarantineProjectionCache, readArchiveSet, readProjectionCache, readSessionGenerations, readSourceKindFacts, readTailFacts, scanSessions, scanZstdFrames, sessionPriority, sessionsRootFor };
+export { Config, DEFAULT_CONFIG, DEFAULT_INDEX_LAYOUT, HEALTH_METHODS, HISTORY_METHODS, HealthCache, INDEX_METHODS, SOURCE_MIGRATE_BACKUP_SUFFIX, STEWARD_API_PREFIX, STEWARD_SETTINGS_NAMESPACE, SWITCH_API_PREFIX, SWITCH_DEFAULT_CONFIG, SwitchIndexEngine, SwitchWatermarkSync, V4_HOST_MIN, apply, archiveArchiveFile, archiveHistory, assessRepair, backupFilesIn, buildProjectionOwnerIndex, buildSessionReport, classifyGenerationFilename, countCorpus, createArchiveSource, createAttributor, decodeSessionLogBytes, decodeSessionLogFile, detectSteward, dirSize, discoverSessions, editWorkspaceDocument, exportSnapshot, extractTitleFromEvents, findSession, findSessionLog, firstLosslessViolation, gateColdRead, gateGeneration, gateLogIntegrity, gateLosslessJson, gateProjectionCache, gateSourceKind, generationLogFilename, handleIndexMethod, handleMethod, importIntoIndex, indexSessionDirs, inject, isLossless, isMigrationStagingFilename, isSafeChild, isSourceMigrateBackupName, latestArtifactMtime, listHistory, locateSessionUsage, methodEnabled, migrateLegacySource, migrateSessionSourceKind, parseGenerationLogFilename, parseSnapshot, prescribe, probePeer, projCacheRootFor, pruneArchiveFile, pruneHistory, purgeHistory, quarantineProjectionCache, readArchiveSet, readProjectionCache, readSessionGenerations, readSourceKindFacts, readTailFacts, rebuildIndex, recoverIndex, scanSessions, scanZstdFrames, sessionPriority, sessionsRootFor };