dsh-manage-session 0.2.3 → 0.4.8

package/lib/index.js

@@ -183,6 +183,557 @@ function pruneArchiveFile(ids, log, searchPaths) {
 	throw new Error(lastReason);
 }
 //#endregion
+//#region src/host/health/decode.ts
+/**
+* 会话日志读取链路（`log-integrity` gate 与 `lossless-json` gate 的共同底座）。
+*
+* 链路与 `_tools/dsh-session-invariant-repro.mjs` 的 `decodeSessionLog` 一致：
+*   zstd 多帧扫描（撕裂尾帧用 ZSTD_e_flush 抢救）→ 逐行 JSON.parse
+*   → provenance 展开（storage 形态的 seq ranges）→ `decodeStorageRecord` 解包
+*   （`text-chunks` / `reasoning-chunks` / `tool-call-chunks` 展开回 `assistant/chunk`）
+*   → seq 连续性校验（提交区出现缺口即停止并按 prefix 语义处理）。
+*
+* 解码器优先使用宿主真实的 `@deepseek-ai/dsh-session`（运行时按需软加载，零硬依赖）；
+* 不可用时使用本文件内的等价实现（同格式：dt 为**时间**增量、成员数 = dt.length + 1；
+* provenance 存储形态为 `[[start,end],…]` 区间编码）。二者的差异会被显式记入
+* `decoder` 字段，禁止静默回退。
+*/
+/** zstd 帧魔数（0xFD2FB528 的小端读取值）。 */
+const ZSTD_MAGIC = 4247762216;
+/** 打包行类型（读路径必须解包）。 */
+const PACKED_ROWS = /* @__PURE__ */ new Set([
+	"text-chunks",
+	"reasoning-chunks",
+	"tool-call-chunks"
+]);
+/** 扫描拼接的 zstd 多帧；返回完整帧范围与撕裂尾帧起点。 */
+function scanZstdFrames(buffer) {
+	const frames = [];
+	let offset = 0;
+	while (offset < buffer.length) {
+		const start = offset;
+		if (buffer.length - offset < 4) return {
+			frames,
+			tornStart: start
+		};
+		if (buffer.readUInt32LE(offset) !== ZSTD_MAGIC) return {
+			frames,
+			tornStart: start
+		};
+		offset += 4;
+		if (offset === buffer.length) return {
+			frames,
+			tornStart: start
+		};
+		const descriptor = buffer.readUInt8(offset);
+		offset += 1;
+		if ((descriptor & 24) !== 0) return {
+			frames,
+			tornStart: start
+		};
+		const contentSizeFlag = descriptor >>> 6;
+		const singleSegment = (descriptor & 32) !== 0;
+		const checksum = (descriptor & 4) !== 0;
+		const dictionaryFlag = descriptor & 3;
+		const dictionaryBytes = dictionaryFlag === 3 ? 4 : dictionaryFlag;
+		const contentSizeBytes = contentSizeFlag === 0 ? singleSegment ? 1 : 0 : 1 << contentSizeFlag;
+		const remainingHeaderBytes = (singleSegment ? 0 : 1) + dictionaryBytes + contentSizeBytes;
+		if (buffer.length - offset < remainingHeaderBytes) return {
+			frames,
+			tornStart: start
+		};
+		offset += remainingHeaderBytes;
+		for (;;) {
+			if (buffer.length - offset < 3) return {
+				frames,
+				tornStart: start
+			};
+			const blockHeader = buffer.readUIntLE(offset, 3);
+			offset += 3;
+			const lastBlock = (blockHeader & 1) !== 0;
+			const blockType = blockHeader >>> 1 & 3;
+			const blockSize = blockHeader >>> 3;
+			if (blockType === 3) return {
+				frames,
+				tornStart: start
+			};
+			const payloadBytes = blockType === 1 ? 1 : blockSize;
+			if (buffer.length - offset < payloadBytes) return {
+				frames,
+				tornStart: start
+			};
+			offset += payloadBytes;
+			if (lastBlock) break;
+		}
+		if (checksum) {
+			if (buffer.length - offset < 4) return {
+				frames,
+				tornStart: start
+			};
+			offset += 4;
+		}
+		frames.push({
+			start,
+			end: offset
+		});
+	}
+	return { frames };
+}
+/** 存储形态的 provenance（`[[start,end],…]` 区间编码或直接 seq 数组）展开为递增 seq 列表。 */
+function decodeSeqRangesStorage(value, currentSeq) {
+	if (!Array.isArray(value)) throw new Error("sourceEventSeqs must be an array when present");
+	const out = [];
+	for (const entry of value) {
+		if (typeof entry === "number") {
+			out.push(entry);
+			continue;
+		}
+		if (Array.isArray(entry) && entry.length === 2) {
+			const [start, end] = entry;
+			if (typeof start !== "number" || typeof end !== "number" || end < start) throw new Error("sourceEventSeqs range is malformed");
+			for (let seq = start; seq <= end; seq += 1) out.push(seq);
+			continue;
+		}
+		throw new Error("sourceEventSeqs entry is neither a seq nor a [start,end] range");
+	}
+	for (const seq of out) if (!Number.isSafeInteger(seq) || seq < 0 || seq >= currentSeq) throw new Error(`sourceEventSeqs must reference earlier events: ${seq} >= ${currentSeq}`);
+	return out;
+}
+/** 本地等价实现：把一行存储记录解包为事件（打包行展开为 assistant/chunk）。 */
+function decodeRecordLocal(value) {
+	if (typeof value !== "object" || value === null) return [value];
+	const record = value;
+	const type = record["type"];
+	if (typeof type !== "string" || !PACKED_ROWS.has(type)) {
+		const seq = record["seq"];
+		if (typeof seq === "number" && (!Number.isSafeInteger(seq) || seq < 0)) throw new Error(`session event seq ${String(seq)} is not a non-negative safe integer`);
+		return [record];
+	}
+	const data = record["data"];
+	if (data === void 0) throw new Error(`malformed ${type} storage row: data must be an object`);
+	const members = type === "tool-call-chunks" ? data["args"] : data["texts"];
+	if (!Array.isArray(members) || members.length === 0 || members.some((entry) => typeof entry !== "string")) throw new Error(`malformed ${type} storage row: payload must be a non-empty string array`);
+	const dt = data["dt"];
+	if (!Array.isArray(dt) || dt.some((gap) => !Number.isSafeInteger(gap))) throw new Error(`malformed ${type} storage row: dt must be an array of safe integers`);
+	if (dt.length !== members.length - 1) throw new Error(`malformed ${type} storage row: dt length ${dt.length} does not match ${members.length} members`);
+	const seq0 = record["seq0"];
+	const time0 = record["time0"];
+	if (typeof seq0 !== "number" || typeof time0 !== "number") throw new Error(`malformed ${type} storage row: seq0/time0 must be numbers`);
+	const turn = data["turn"];
+	const step = data["step"];
+	const index = data["index"];
+	const out = [];
+	let time = time0;
+	for (let k = 0; k < members.length; k += 1) {
+		if (k > 0) time += dt[k - 1];
+		let chunk;
+		if (type === "text-chunks") chunk = {
+			type: "text-delta",
+			index,
+			text: members[k]
+		};
+		else if (type === "reasoning-chunks") chunk = {
+			type: "reasoning-delta",
+			index,
+			text: members[k]
+		};
+		else chunk = {
+			type: "tool-call-delta",
+			index,
+			id: typeof data["id"] === "string" ? data["id"] : "",
+			...typeof data["name"] === "string" ? { name: data["name"] } : {},
+			argumentsDelta: members[k]
+		};
+		out.push({
+			type: "assistant/chunk",
+			seq: seq0 + k,
+			time,
+			data: {
+				turn,
+				step,
+				chunk
+			}
+		});
+	}
+	return out;
+}
+/**
+* 读取一个会话日志文件（zip 帧扫描 + 解包 + seq 连续性）。
+* @param file - 当前代日志的绝对路径（由代次解析得出，不假定具体文件名）。
+* @param bytes - 文件内容（调用方读取，便于测试注入）。
+* @param decoders - 可选官方解码器（缺省用本地等价实现）。
+* @returns 事件、统计与问题清单。
+*/
+function decodeSessionLogBytes(file, bytes, decoders) {
+	const { frames, tornStart } = scanZstdFrames(bytes);
+	const parts = [];
+	const frameIssues = [];
+	for (const frame of frames) try {
+		parts.push(zlib.zstdDecompressSync(bytes.subarray(frame.start, frame.end)));
+	} catch (err) {
+		frameIssues.push(`frame@${frame.start}: ${String(err instanceof Error ? err.message : err)}`);
+	}
+	let recoveredFromTorn = 0;
+	if (tornStart !== void 0) try {
+		const recovered = zlib.zstdDecompressSync(bytes.subarray(tornStart), { finishFlush: zlib.constants.ZSTD_e_flush });
+		recoveredFromTorn = recovered.length;
+		parts.push(recovered);
+	} catch {}
+	const lines = Buffer.concat(parts).toString("utf8").split("\n").filter((line) => line.trim() !== "");
+	const issues = frameIssues.map((why, index) => ({
+		line: index + 1,
+		why
+	}));
+	const decodeRecord = decoders?.decodeStorageRecord ?? decodeRecordLocal;
+	const events = [];
+	for (let index = 1; index < lines.length; index += 1) {
+		const line = lines[index];
+		let decoded;
+		try {
+			const parsed = JSON.parse(line);
+			decoded = decodeRecord(parsed["sourceEventSeqs"] === void 0 ? parsed : {
+				...parsed,
+				sourceEventSeqs: decoders?.decodeSeqRanges !== void 0 && typeof parsed["seq"] === "number" ? decoders.decodeSeqRanges(parsed["sourceEventSeqs"], parsed["seq"]) : decodeSeqRangesStorage(parsed["sourceEventSeqs"], Number(parsed["seq"] ?? 0))
+			});
+		} catch (err) {
+			issues.push({
+				line: index + 1,
+				why: `decode failed: ${String(err instanceof Error ? err.message : err)}`
+			});
+			break;
+		}
+		const rowStart = events.length;
+		let gapped = false;
+		for (const event of decoded) {
+			if (event.seq !== events.length) {
+				issues.push({
+					line: index + 1,
+					why: `seq gap (expected ${events.length}, got ${event.seq})`
+				});
+				events.length = rowStart;
+				gapped = true;
+				break;
+			}
+			events.push(event);
+		}
+		if (gapped) break;
+	}
+	const openStep = findOpenStep(events);
+	let header;
+	const headerLine = lines[0];
+	if (headerLine !== void 0) try {
+		const parsed = JSON.parse(headerLine);
+		if (typeof parsed === "object" && parsed !== null) header = parsed;
+	} catch {}
+	return {
+		events,
+		frames: frames.length,
+		...tornStart === void 0 ? {} : { tornStart },
+		recoveredFromTorn,
+		issues,
+		decoder: decoders === void 0 ? "local" : "official",
+		...openStep === void 0 ? {} : { openStep },
+		...header === void 0 ? {} : { header }
+	};
+}
+/** 从文件读取并解码。 */
+function decodeSessionLogFile(file, decoders) {
+	return decodeSessionLogBytes(file, readFileSync(file), decoders);
+}
+/** 尾部未收尾的 open step（有 step/start 无对应 step/end）。 */
+function findOpenStep(events) {
+	let open;
+	for (const event of events) {
+		const data = event.data;
+		if (event.type === "step/start" && typeof data?.turn === "number" && typeof data?.step === "number") {
+			open = {
+				turn: data.turn,
+				step: data.step
+			};
+			continue;
+		}
+		if (event.type === "step/end") open = void 0;
+	}
+	return open;
+}
+//#endregion
+//#region src/host/health/source-kind.ts
+/**
+* 插件署名格式（source kind）体检门与转换。
+*
+* ## 背景：会话格式 v4 的署名要求
+*
+* 宿主 0.1.7-rc.1 起（会话格式 v4）废弃裸 `source: { kind: 'plugin', plugin: '<name>' }`
+* 的署名方式，要求每条插件写入的消息使用生产者自有 kind（`plugin:<name>`）。
+* 校验失败时**整轮失败**（SessionFormatError），不是丢一条消息。
+* 修复模式（与已适配的 aegis、dsh-better-sidebar 一致）：
+*   `{ kind: 'plugin', plugin: '<name>' }` → `{ kind: 'plugin:<name>' }`（删除 plugin 字段）。
+*
+* ## 版本依赖表（各格式代次依赖的宿主固定版本与处置策略）
+*
+* | 格式代次 | 宿主版本线          | 旧署名行是否合法 | 处置策略                                   |
+* |---|---|---|---|
+* | v1       | 未考证（早期线）     | 合法             | 不动（leave-asis）                          |
+* | v2       | 未考证               | 合法             | 不动                                        |
+* | v3       | 0.1.6 时代（待考证） | 合法             | 不动：宿主 v3→v4 迁移负责，插件越权改写属过度操作 |
+* | v4       | ≥ 0.1.7-rc.1（已实锤）| **拒绝**（SessionFormatError） | 检测 + 可选转换（本模块） |
+*
+* 判定依据是**日志 header 的 version 字段**（`decode.ts` 已解析为 `SessionLogRead.header`），
+* 不猜文件名、不猜宿主安装版本：同一份磁盘语料可能混有多条版本线的产物，
+* 每份日志按它自己的 header 代次走对应的策略线。
+*
+* ## 红线（与 repair.ts 的红线关系）
+*
+* repair.ts 的红线是「禁止改写会话日志」。本模块的转换是**经用户显式触发的唯一例外**：
+* 只改 `source.kind` / `source.plugin` 两个署名字段，其余字节原样保留；改前整文件备份；
+* 日志完整性不合格（撕裂尾帧 / 解码失败 / seq 缺口）或代次不在 v4 线时**拒绝执行**。
+* 这三道闸缺一不可，否则就退化成「静默改历史数据」。
+*/
+/** v4 线起点的宿主版本（会话格式 v4 引入 producer-owned source kind）。 */
+const V4_HOST_MIN = "0.1.7-rc.1";
+/** 从解码后的日志提取旧署名事实（只读）。 */
+function readSourceKindFacts(log) {
+	const byPlugin = {};
+	const examples = [];
+	for (const event of log.events) {
+		const source = event.data?.source;
+		if (source === void 0 || typeof source !== "object" || source.kind !== "plugin" || typeof source.plugin !== "string" || source.plugin === "") continue;
+		byPlugin[source.plugin] = (byPlugin[source.plugin] ?? 0) + 1;
+		if (examples.length < 5) examples.push({
+			seq: event.seq,
+			plugin: source.plugin
+		});
+	}
+	const headerVersion = typeof log.header?.["version"] === "number" ? log.header["version"] : void 0;
+	return {
+		legacyCount: Object.values(byPlugin).reduce((sum, n) => sum + n, 0),
+		byPlugin,
+		examples,
+		...headerVersion === void 0 ? {} : { headerVersion }
+	};
+}
+/**
+* gate 5：插件署名格式（v4 线要求 producer-owned kind）。
+*
+* 档位判据（有据才抬档）：
+* - header.version ≥ 4 且观测到旧署名行 → `warn`：v4 校验拒绝这种署名；存量行让
+*   未适配插件的读回判断（`kind === 'plugin' && plugin === name`）失配，转换可消除；
+* - header.version < 4 → `ok`：v3 及更早线旧行合法，宿主迁移负责，**不动**（防过度操作）；
+* - header.version 无从读取 → `skipped`：无从判定该走哪条版本线。
+* @param facts - 旧署名事实；undefined 表示未提供（无日志）。
+*/
+function gateSourceKind(facts) {
+	if (facts === void 0) return {
+		id: "source-kind",
+		level: "skipped",
+		evidence: "未提供日志读取结果，本门无从判定"
+	};
+	const version = facts.headerVersion;
+	const plugins = Object.entries(facts.byPlugin);
+	const detail = {
+		headerVersion: version,
+		legacyCount: facts.legacyCount,
+		byPlugin: facts.byPlugin,
+		examples: facts.examples,
+		v4HostMin: V4_HOST_MIN
+	};
+	if (version === void 0) return {
+		id: "source-kind",
+		level: "skipped",
+		evidence: "日志 header 无 version 字段，无从判定格式代次线",
+		detail
+	};
+	if (version < 4) return {
+		id: "source-kind",
+		level: "ok",
+		evidence: `格式代次 v${version}（v4 之前的版本线）：旧署名行合法，宿主 v3→v4 迁移负责，不做转换` + (plugins.length > 0 ? `（观测到 ${plugins.reduce((s, [, n]) => s + n, 0)} 行旧署名，按策略不动）` : ""),
+		detail
+	};
+	if (plugins.length === 0) return {
+		id: "source-kind",
+		level: "ok",
+		evidence: `格式代次 v${version}：全部插件署名均为 producer-owned kind（plugin:<name>）`,
+		detail
+	};
+	const summary = plugins.map(([name, count]) => `${name}×${count}`).join("、");
+	return {
+		id: "source-kind",
+		level: "warn",
+		evidence: `格式代次 v${version} 但存在 ${facts.legacyCount} 行旧署名（${summary}）：宿主 v4 拒绝该形态，未适配插件读回判断也会失配；可执行署名转换`,
+		detail
+	};
+}
+/**
+* 从旧署名对象构造新署名：`{ kind: 'plugin', plugin: name, …rest }` → `{ kind: 'plugin:name', …rest }`。
+* 非 legacy（缺 plugin 字段 / kind 不符）返回 undefined，调用方跳过该行。
+*
+* ⚠️ 只对**第三方**生产者名成立（第四轮审计 ST1）：宿主 `producerKind`
+* （dsh-session-format-v3-to-v4@0.1.7-rc.2 lib/index.js:88-96）对第一方名走改名表
+* 或同名裸 kind，本函数无条件加前缀会对那 30 个名字写出宿主永不产出的 kind。
+* 第一方名由 `FIRST_PARTY_RENAMED_PRODUCERS` / `FIRST_PARTY_SAME_NAME_PRODUCERS`
+* 判定，`migrateSessionSourceKind` 命中即跳过并如实上报（宿主迁移职权，不代转换）。
+*/
+function migrateLegacySource(source) {
+	if (typeof source !== "object" || source === null) return void 0;
+	const record = source;
+	if (record["kind"] !== "plugin" || typeof record["plugin"] !== "string" || record["plugin"] === "") return void 0;
+	const { plugin, ...rest } = record;
+	return {
+		...rest,
+		kind: `plugin:${plugin}`
+	};
+}
+/**
+* 宿主 v3→v4 迁移会**改名**的第一方生产者（出处：dsh-session-format-v3-to-v4@
+* 0.1.7-rc.2 lib/index.js:51-57 `RENAMED_PRODUCERS`，逐字照录）。
+*/
+const FIRST_PARTY_RENAMED_PRODUCERS = Object.freeze({
+	"compact": "compact-checkpoint",
+	"tools-code-mode": "ptc-mode",
+	"tools-ptc": "ptc-mode",
+	"dsh-compaction-basic": "compact-basic",
+	"@deepseek-ai/dsh-system-prompt": "runtime-context"
+});
+/**
+* 宿主迁移后**保留同名裸 kind** 的第一方生产者（出处：同上 lib/index.js:59-84
+* `RELEASED_SAME_NAME_PRODUCERS`，逐字照录；注释明言限第一方）。
+* 注：`@deepseek-ai/dsh-system-prompt` 还有 role 敏感分支（role=system →
+* `system-prompt`），steward 无 role 上下文、结构性不可复刻——这正是第一方名
+* 一律跳过、交还宿主迁移的核心理由之一。
+*/
+const FIRST_PARTY_SAME_NAME_PRODUCERS = /* @__PURE__ */ new Set([
+	"agent-instructions",
+	"session-reference",
+	"team-message",
+	"goal",
+	"skill-invocation",
+	"skill-catalog",
+	"coordinator",
+	"subagent-report",
+	"subagent-settled",
+	"webhook",
+	"agent-message",
+	"model-selection",
+	"plan-mode",
+	"time-context",
+	"tmux-context",
+	"user-approval",
+	"repeat-tool-reminder",
+	"tool-cordis",
+	"cordis-host-runner",
+	"tool-goal",
+	"tool-jobs",
+	"hooks-codex",
+	"hooks-claude-code",
+	"schedule",
+	"dsh-session-title-llm"
+]);
+/** 是否第一方生产者名（宿主迁移职权，steward 不代转换——防归因静默损坏）。 */
+function isFirstPartyLegacyProducer(plugin) {
+	return Object.hasOwn(FIRST_PARTY_RENAMED_PRODUCERS, plugin) || FIRST_PARTY_SAME_NAME_PRODUCERS.has(plugin);
+}
+/**
+* 转换一个会话日志里的旧署名行（v4 线专用；先备份，只动署名字段）。
+*
+* 执行闸（任一不满足即拒绝，不写盘）：
+* 1. 日志可整体解码且无完整性问题（撕裂尾帧 / 解码失败 / seq 缺口）；
+* 2. header.version ≥ 4（v3 及更早的旧行按契约由宿主迁移，不动）；
+* 3. 确有旧署名行（没有则空手而归，不做无谓重压缩）。
+* @param sessionId - 会话 id（用于结果标注）。
+* @param logPath - 当前代日志路径（必须 .zstd 结尾）。
+* @param log - 已解码的日志（复用体检结果，闸 1/2 在其上判定）。
+* @param dshHome - DSH home（备份不依赖它，参数保留与其它处置一致的面）。
+* @param now - 时间源（备份后缀，测试可控）。
+*/
+function migrateSessionSourceKind(sessionId, logPath, log, dshHome, now = Date.now) {
+	const failure = (error) => ({
+		ok: false,
+		sessionId,
+		path: logPath,
+		error
+	});
+	if (!logPath.endsWith(".zstd")) return failure(`非 zstd 产物，拒绝处理：${logPath}`);
+	if (log.issues.length > 0) return failure(`日志存在 ${log.issues.length} 条完整性问题，拒绝改写（先解决 log-integrity 门）`);
+	if (log.tornStart !== void 0) return failure("存在撕裂尾帧，拒绝改写（先让宿主完成提交或处置 log-integrity 门）");
+	const headerVersion = typeof log.header?.["version"] === "number" ? log.header["version"] : void 0;
+	if (headerVersion === void 0) return failure("日志 header 无 version 字段，无法确认格式代次线，拒绝改写");
+	if (headerVersion < 4) return failure(`格式代次 v${headerVersion}：旧署名在该版本线合法，宿主迁移负责，不做转换（防过度操作）`);
+	let original;
+	try {
+		original = readPlaintext(logPath);
+	} catch (err) {
+		return failure(`读取日志失败：${String(err instanceof Error ? err.message : err)}`);
+	}
+	const lines = original.split("\n");
+	let changedRows = 0;
+	const byPlugin = {};
+	const skippedFirstParty = {};
+	const rewritten = lines.map((line, index) => {
+		if (index === 0 || line.trim() === "") return line;
+		let parsed;
+		try {
+			parsed = JSON.parse(line);
+		} catch {
+			return line;
+		}
+		if (typeof parsed !== "object" || parsed === null) return line;
+		const record = parsed;
+		const data = record["data"];
+		if (data === void 0 || typeof data !== "object") return line;
+		const legacy = data["source"];
+		if (legacy === void 0 || typeof legacy !== "object" || legacy["kind"] !== "plugin" || typeof legacy["plugin"] !== "string" || legacy["plugin"] === "") return line;
+		const plugin = legacy["plugin"];
+		if (isFirstPartyLegacyProducer(plugin)) {
+			skippedFirstParty[plugin] = (skippedFirstParty[plugin] ?? 0) + 1;
+			return line;
+		}
+		const migrated = migrateLegacySource(legacy);
+		if (migrated === void 0) return line;
+		data["source"] = migrated;
+		changedRows += 1;
+		byPlugin[plugin] = (byPlugin[plugin] ?? 0) + 1;
+		return JSON.stringify(record);
+	});
+	if (changedRows === 0) return {
+		ok: true,
+		sessionId,
+		path: logPath,
+		changedRows: 0,
+		byPlugin: {},
+		...Object.values(skippedFirstParty).reduce((sum, n) => sum + n, 0) > 0 ? { skippedFirstParty } : {}
+	};
+	const backup = `${logPath}.pre-sourcemigrate-${now()}`;
+	try {
+		copyFileSync(logPath, backup);
+		const compressed = zlib.zstdCompressSync(Buffer.from(rewritten.join("\n"), "utf8"));
+		const tmp = `${logPath}.sourcemigrate-tmp`;
+		writeFileSync(tmp, compressed);
+		renameSync(tmp, logPath);
+		return {
+			ok: true,
+			sessionId,
+			path: logPath,
+			backup,
+			changedRows,
+			byPlugin,
+			...Object.keys(skippedFirstParty).length > 0 ? { skippedFirstParty } : {}
+		};
+	} catch (err) {
+		return failure(`转换落盘失败（原文件未动，备份${existsSync(backup) ? "已生成" : "未生成"}）：${String(err instanceof Error ? err.message : err)}`);
+	}
+}
+/** 读出整份 zstd 日志的明文；失败时抛出（调用方拒绝改写并如实上报）。 */
+function readPlaintext(logPath) {
+	const bytes = readFileSync(logPath);
+	const { frames, tornStart } = scanZstdFrames(bytes);
+	if (tornStart !== void 0) throw new Error("存在撕裂尾帧，拒绝改写");
+	const parts = [];
+	for (const frame of frames) parts.push(zlib.zstdDecompressSync(bytes.subarray(frame.start, frame.end)));
+	return Buffer.concat(parts).toString("utf8");
+}
+/** 备份文件的后缀约定（purge/清理工具可据此识别并一并处置）。 */
+const SOURCE_MIGRATE_BACKUP_SUFFIX = ".pre-sourcemigrate-";
+//#endregion
 //#region src/host/history/purge.ts
 /**
 * 归档文件清理（**真删除**）—— 会话管家唯一的破坏性操作。
@@ -208,6 +759,39 @@ function pruneArchiveFile(ids, log, searchPaths) {
 * 执行顺序是**先改文件、后删实体**：改文件是原子的且可整体中止（失败则一个字节都没删）；
 * 反过来先删实体再改文件，中途失败会留下僵尸 id。
 */
+/** 是否署名转换备份文件（`*.pre-sourcemigrate-<ts>`）。 */
+function isSourceMigrateBackupName(name) {
+	return name.includes(SOURCE_MIGRATE_BACKUP_SUFFIX);
+}
+/**
+* 列出一个转录目录里的署名转换备份（只扫顶层：备份与日志同目录落盘）。
+* @returns 备份绝对路径与合计字节数；目录不存在时为空。
+*/
+function backupFilesIn(dir) {
+	const files = [];
+	let bytes = 0;
+	let entries;
+	try {
+		entries = readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return {
+			files,
+			bytes
+		};
+	}
+	for (const entry of entries) {
+		if (!entry.isFile() || !isSourceMigrateBackupName(entry.name)) continue;
+		const path = join(dir, entry.name);
+		files.push(path);
+		try {
+			bytes += statSync(path).size;
+		} catch {}
+	}
+	return {
+		files,
+		bytes
+	};
+}
 /** 转录根目录（`<dshHome>/sessions`）。 */
 function sessionsRootFor(dshHome) {
 	return join(dshHome, "sessions");
@@ -299,12 +883,17 @@ function locateSessionUsage(ids, dshHome) {
 		const usage = {
 			sessionId,
 			bytes: 0,
+			backupBytes: 0,
+			backupCount: 0,
 			cacheBytes: 0
 		};
 		const dir = dirs.get(key);
 		if (dir !== void 0) {
 			usage.dir = dir;
 			usage.bytes = dirSize(dir);
+			const backups = backupFilesIn(dir);
+			usage.backupBytes = backups.bytes;
+			usage.backupCount = backups.files.length;
 		}
 		for (const name of [`${sessionId}.json`, `${key}.json`]) {
 			const candidate = join(cacheRoot, name);
@@ -412,6 +1001,7 @@ function purgeHistory(payload, log, options) {
 	const failures = [];
 	let purged = 0;
 	let freedBytes = 0;
+	let backupsRemoved = 0;
 	for (const sessionId of ids) {
 		const entry = usage.get(sessionId);
 		let missing = 0;
@@ -424,6 +1014,7 @@ function purgeHistory(payload, log, options) {
 				});
 				continue;
 			}
+			backupsRemoved += entry.backupCount;
 			try {
 				rmSync(entry.dir, {
 					recursive: true,
@@ -461,11 +1052,12 @@ function purgeHistory(payload, log, options) {
 		purged++;
 		freedBytes += entryFreed;
 	}
-	log?.(`archive purge: cleared ${purged} of ${ids.length}; freed ${(freedBytes / 1048576).toFixed(1)}MB; failures ${failures.length}`);
+	log?.(`archive purge: cleared ${purged} of ${ids.length}; freed ${(freedBytes / 1048576).toFixed(1)}MB; backups ${backupsRemoved}; failures ${failures.length}`);
 	return {
 		ok: true,
 		purged,
 		freedBytes,
+		backupsRemoved,
 		requiresRestart: true,
 		...failures.length === 0 ? {} : { failures }
 	};
@@ -529,7 +1121,8 @@ async function listHistory(getRegistry, query, searchPaths, dshHome) {
 			cwd: "",
 			updatedAt: 0,
 			bytes: 0,
-			cacheBytes: 0
+			cacheBytes: 0,
+			backupBytes: 0
 		};
 	});
 	if (dshHome !== void 0 && dshHome !== "" && items.length > 0) try {
@@ -539,6 +1132,7 @@ async function listHistory(getRegistry, query, searchPaths, dshHome) {
 			if (entry === void 0) continue;
 			item.bytes = entry.bytes;
 			item.cacheBytes = entry.cacheBytes;
+			item.backupBytes = entry.backupBytes;
 		}
 	} catch {}
 	const fileIds = new Set(ids);
@@ -732,328 +1326,241 @@ var HealthCache = class {
 	/** 开始一轮分批扫描（客户端以 `offset: 0` 发起时调用）。 */
 	begin(total) {
 		this.pending = {
-			total: Math.max(0, Math.floor(total)),
-			findings: [],
-			visited: 0
-		};
-	}
-	/**
-	* 追加一批扫描结果。
-	*
-	* 只有累积的已访问数走满语料总数才成型；语言中途断掉（关面板、报错）不会留下
-	* 半份缓存冒充完整结果。
-	* @param findings - 本批的非 ok 报告。
-	* @param scanned - 本批**已访问**的会话数（不是命中数）。
-	* @param now - 时间源（测试可控）。
-	* @returns 本批追加后缓存是否刚好成型。
-	*/
-	append(findings, scanned, now = Date.now) {
-		const pending = this.pending;
-		if (pending === void 0) return false;
-		pending.findings.push(...findings);
-		pending.visited += Math.max(0, Math.floor(scanned));
-		if (pending.visited < pending.total) return false;
-		this.ready = {
-			findings: pending.findings,
-			total: pending.total,
-			generatedAt: now()
-		};
-		this.pending = void 0;
-		return true;
-	}
-	/**
-	* 单条就地回写（单会话体检 / 可逆处置后调用）。
-	*
-	* 这是缓存的**关键收益**：处置本就重算了 `after` 报告，把它写回即可，
-	* 不必为了刷新一行而重扫整个语料。
-	* @param report - 重算出的单会话报告。
-	* @returns 是否真的改动了缓存（无缓存时为 false）。
-	*/
-	patch(report) {
-		const ready = this.ready;
-		if (ready === void 0) return false;
-		const index = ready.findings.findIndex((entry) => entry.sessionId === report.sessionId);
-		if (report.level === "ok") {
-			if (index < 0) return false;
-			ready.findings.splice(index, 1);
-			return true;
-		}
-		if (index >= 0) ready.findings[index] = report;
-		else ready.findings.push(report);
-		return true;
-	}
-	/** 丢弃缓存与未完成的累积。 */
-	clear() {
-		this.ready = void 0;
-		this.pending = void 0;
-	}
-};
-//#endregion
-//#region src/host/health/decode.ts
-/**
-* 会话日志读取链路（`log-integrity` gate 与 `lossless-json` gate 的共同底座）。
-*
-* 链路与 `_tools/dsh-session-invariant-repro.mjs` 的 `decodeSessionLog` 一致：
-*   zstd 多帧扫描（撕裂尾帧用 ZSTD_e_flush 抢救）→ 逐行 JSON.parse
-*   → provenance 展开（storage 形态的 seq ranges）→ `decodeStorageRecord` 解包
-*   （`text-chunks` / `reasoning-chunks` / `tool-call-chunks` 展开回 `assistant/chunk`）
-*   → seq 连续性校验（提交区出现缺口即停止并按 prefix 语义处理）。
-*
-* 解码器优先使用宿主真实的 `@deepseek-ai/dsh-session`（运行时按需软加载，零硬依赖）；
-* 不可用时使用本文件内的等价实现（同格式：dt 为**时间**增量、成员数 = dt.length + 1；
-* provenance 存储形态为 `[[start,end],…]` 区间编码）。二者的差异会被显式记入
-* `decoder` 字段，禁止静默回退。
-*/
-/** zstd 帧魔数（0xFD2FB528 的小端读取值）。 */
-const ZSTD_MAGIC = 4247762216;
-/** 打包行类型（读路径必须解包）。 */
-const PACKED_ROWS = /* @__PURE__ */ new Set([
-	"text-chunks",
-	"reasoning-chunks",
-	"tool-call-chunks"
-]);
-/** 扫描拼接的 zstd 多帧；返回完整帧范围与撕裂尾帧起点。 */
-function scanZstdFrames(buffer) {
-	const frames = [];
-	let offset = 0;
-	while (offset < buffer.length) {
-		const start = offset;
-		if (buffer.length - offset < 4) return {
-			frames,
-			tornStart: start
-		};
-		if (buffer.readUInt32LE(offset) !== ZSTD_MAGIC) return {
-			frames,
-			tornStart: start
-		};
-		offset += 4;
-		if (offset === buffer.length) return {
-			frames,
-			tornStart: start
-		};
-		const descriptor = buffer.readUInt8(offset);
-		offset += 1;
-		if ((descriptor & 24) !== 0) return {
-			frames,
-			tornStart: start
-		};
-		const contentSizeFlag = descriptor >>> 6;
-		const singleSegment = (descriptor & 32) !== 0;
-		const checksum = (descriptor & 4) !== 0;
-		const dictionaryFlag = descriptor & 3;
-		const dictionaryBytes = dictionaryFlag === 3 ? 4 : dictionaryFlag;
-		const contentSizeBytes = contentSizeFlag === 0 ? singleSegment ? 1 : 0 : 1 << contentSizeFlag;
-		const remainingHeaderBytes = (singleSegment ? 0 : 1) + dictionaryBytes + contentSizeBytes;
-		if (buffer.length - offset < remainingHeaderBytes) return {
-			frames,
-			tornStart: start
-		};
-		offset += remainingHeaderBytes;
-		for (;;) {
-			if (buffer.length - offset < 3) return {
-				frames,
-				tornStart: start
-			};
-			const blockHeader = buffer.readUIntLE(offset, 3);
-			offset += 3;
-			const lastBlock = (blockHeader & 1) !== 0;
-			const blockType = blockHeader >>> 1 & 3;
-			const blockSize = blockHeader >>> 3;
-			if (blockType === 3) return {
-				frames,
-				tornStart: start
-			};
-			const payloadBytes = blockType === 1 ? 1 : blockSize;
-			if (buffer.length - offset < payloadBytes) return {
-				frames,
-				tornStart: start
-			};
-			offset += payloadBytes;
-			if (lastBlock) break;
-		}
-		if (checksum) {
-			if (buffer.length - offset < 4) return {
-				frames,
-				tornStart: start
-			};
-			offset += 4;
-		}
-		frames.push({
-			start,
-			end: offset
-		});
-	}
-	return { frames };
-}
-/** 存储形态的 provenance（`[[start,end],…]` 区间编码或直接 seq 数组）展开为递增 seq 列表。 */
-function decodeSeqRangesStorage(value, currentSeq) {
-	if (!Array.isArray(value)) throw new Error("sourceEventSeqs must be an array when present");
-	const out = [];
-	for (const entry of value) {
-		if (typeof entry === "number") {
-			out.push(entry);
-			continue;
-		}
-		if (Array.isArray(entry) && entry.length === 2) {
-			const [start, end] = entry;
-			if (typeof start !== "number" || typeof end !== "number" || end < start) throw new Error("sourceEventSeqs range is malformed");
-			for (let seq = start; seq <= end; seq += 1) out.push(seq);
-			continue;
-		}
-		throw new Error("sourceEventSeqs entry is neither a seq nor a [start,end] range");
-	}
-	for (const seq of out) if (!Number.isSafeInteger(seq) || seq < 0 || seq >= currentSeq) throw new Error(`sourceEventSeqs must reference earlier events: ${seq} >= ${currentSeq}`);
-	return out;
-}
-/** 本地等价实现：把一行存储记录解包为事件（打包行展开为 assistant/chunk）。 */
-function decodeRecordLocal(value) {
-	if (typeof value !== "object" || value === null) return [value];
-	const record = value;
-	const type = record["type"];
-	if (typeof type !== "string" || !PACKED_ROWS.has(type)) {
-		const seq = record["seq"];
-		if (typeof seq === "number" && (!Number.isSafeInteger(seq) || seq < 0)) throw new Error(`session event seq ${String(seq)} is not a non-negative safe integer`);
-		return [record];
-	}
-	const data = record["data"];
-	if (data === void 0) throw new Error(`malformed ${type} storage row: data must be an object`);
-	const members = type === "tool-call-chunks" ? data["args"] : data["texts"];
-	if (!Array.isArray(members) || members.length === 0 || members.some((entry) => typeof entry !== "string")) throw new Error(`malformed ${type} storage row: payload must be a non-empty string array`);
-	const dt = data["dt"];
-	if (!Array.isArray(dt) || dt.some((gap) => !Number.isSafeInteger(gap))) throw new Error(`malformed ${type} storage row: dt must be an array of safe integers`);
-	if (dt.length !== members.length - 1) throw new Error(`malformed ${type} storage row: dt length ${dt.length} does not match ${members.length} members`);
-	const seq0 = record["seq0"];
-	const time0 = record["time0"];
-	if (typeof seq0 !== "number" || typeof time0 !== "number") throw new Error(`malformed ${type} storage row: seq0/time0 must be numbers`);
-	const turn = data["turn"];
-	const step = data["step"];
-	const index = data["index"];
-	const out = [];
-	let time = time0;
-	for (let k = 0; k < members.length; k += 1) {
-		if (k > 0) time += dt[k - 1];
-		let chunk;
-		if (type === "text-chunks") chunk = {
-			type: "text-delta",
-			index,
-			text: members[k]
-		};
-		else if (type === "reasoning-chunks") chunk = {
-			type: "reasoning-delta",
-			index,
-			text: members[k]
+			total: Math.max(0, Math.floor(total)),
+			findings: [],
+			visited: 0
 		};
-		else chunk = {
-			type: "tool-call-delta",
-			index,
-			id: typeof data["id"] === "string" ? data["id"] : "",
-			...typeof data["name"] === "string" ? { name: data["name"] } : {},
-			argumentsDelta: members[k]
+	}
+	/**
+	* 追加一批扫描结果。
+	*
+	* 只有累积的已访问数走满语料总数才成型；语言中途断掉（关面板、报错）不会留下
+	* 半份缓存冒充完整结果。
+	* @param findings - 本批的非 ok 报告。
+	* @param scanned - 本批**已访问**的会话数（不是命中数）。
+	* @param now - 时间源（测试可控）。
+	* @returns 本批追加后缓存是否刚好成型。
+	*/
+	append(findings, scanned, now = Date.now) {
+		const pending = this.pending;
+		if (pending === void 0) return false;
+		pending.findings.push(...findings);
+		pending.visited += Math.max(0, Math.floor(scanned));
+		if (pending.visited < pending.total) return false;
+		this.ready = {
+			findings: pending.findings,
+			total: pending.total,
+			generatedAt: now()
 		};
-		out.push({
-			type: "assistant/chunk",
-			seq: seq0 + k,
-			time,
-			data: {
-				turn,
-				step,
-				chunk
-			}
-		});
+		this.pending = void 0;
+		return true;
 	}
-	return out;
+	/**
+	* 单条就地回写（单会话体检 / 可逆处置后调用）。
+	*
+	* 这是缓存的**关键收益**：处置本就重算了 `after` 报告，把它写回即可，
+	* 不必为了刷新一行而重扫整个语料。
+	* @param report - 重算出的单会话报告。
+	* @returns 是否真的改动了缓存（无缓存时为 false）。
+	*/
+	patch(report) {
+		const ready = this.ready;
+		if (ready === void 0) return false;
+		const index = ready.findings.findIndex((entry) => entry.sessionId === report.sessionId);
+		if (report.level === "ok") {
+			if (index < 0) return false;
+			ready.findings.splice(index, 1);
+			return true;
+		}
+		if (index >= 0) ready.findings[index] = report;
+		else ready.findings.push(report);
+		return true;
+	}
+	/** 丢弃缓存与未完成的累积。 */
+	clear() {
+		this.ready = void 0;
+		this.pending = void 0;
+	}
+};
+//#endregion
+//#region src/host/health/generation.ts
+/**
+* 会话日志的「代次」文件名契约（对齐宿主 session 操作核心）。
+*
+* 一个会话目录里可以同时存在多份日志产物：
+*
+*     session.jsonl.zstd                          历史代 0（无版本号）
+*     session.v<N>.jsonl.zstd                     当前代 N（N ≥ 1）
+*     session.migration.<token>.jsonl.zstd.tmp    迁移暂存（当前代的发布源）
+*
+* **当前代由目录实测的最高代次决定，不硬编码 `v3`；日志名由代次推导，不硬编码
+* `session.jsonl.zstd`。** 硬编码 v0 正是本插件此前「看不见任何已发布当前代的
+* 会话」的病根：实测 449 个会话目录中有 61 个只留当前代，旧发现逻辑对它们一条
+* 都发现不了，因而既扫不到也修不了。
+*
+* 宿主侧的代次发布顺序是「写暂存 → fsync → 校验 → 原子发布成当前代」，所以
+* **当前代次非 0 等价于「这份日志是从 TMP 里移出来的」**；目录内仍有暂存残留
+* 则是发布源仍在原地的物证。本模块据此给出处置优先级。
+*
+* 语法逐条对齐宿主包，改动它们必须同步这里（`tests/generation.spec.ts` 复刻了
+* 宿主的全部拒绝用例，宿主放宽/收紧时该组测试会失败）：
+*   - `@deepseek-ai/dsh-session-format/src/filename.ts`
+*     `CANONICAL_LOG_FILENAME = /^session(?:\.v([1-9][0-9]*))?\.jsonl$/u`
+*   - `@deepseek-ai/dsh-session-persistence-jsonl/src/format.ts` 的压缩后缀
+*   - `@deepseek-ai/dsh-session-persistence-jsonl/src/generation.ts:725`
+*     暂存名 `session.migration.${randomToken()}${suffix}.tmp`（token 为 16 位小写十六进制）
+*/
+/**
+* 规范日志名的语法（不含压缩后缀）。
+*
+* 与宿主 `session-format/src/filename.ts` 逐字一致：版本 0 不带版本号，
+* 后续代次必须是小写数字且无前导零；`.v0`、`.v01`、`.V1`、`session.v1.backup.jsonl`
+* 都不识别为规范代次。
+*/
+const CANONICAL_LOG_BASENAME = /^session(?:\.v([1-9][0-9]*))?\.jsonl$/u;
+/**
+* 迁移暂存名的语法（对齐 `generation.ts:725` 的写入名）。
+*
+* token 的位数与字符集是宿主内部细节，这里只固定**形状**
+* `session.migration.<hex>.jsonl[.zstd].tmp`，宿主换 token 长度时本插件不会失明。
+*/
+const MIGRATION_STAGING_NAME = /^session\.migration\.[0-9a-f]+\.jsonl(?:\.zstd)?\.tmp$/u;
+function compressionSuffix(compression) {
+	return compression === "zstd" ? ".zstd" : "";
 }
 /**
-* 读取一个会话日志文件（zip 帧扫描 + 解包 + seq 连续性）。
-* @param file - `session.jsonl.zstd` 绝对路径。
-* @param bytes - 文件内容（调用方读取，便于测试注入）。
-* @param decoders - 可选官方解码器（缺省用本地等价实现）。
-* @returns 事件、统计与问题清单。
+* 某代次的规范日志文件名。
+* @param version - 非负安全整数的格式代次。
+* @param compression - 物理编码（缺省 zstd）。
+* @returns 该代次在会话目录内的文件名。
 */
-function decodeSessionLogBytes(file, bytes, decoders) {
-	const { frames, tornStart } = scanZstdFrames(bytes);
-	const parts = [];
-	const frameIssues = [];
-	for (const frame of frames) try {
-		parts.push(zlib.zstdDecompressSync(bytes.subarray(frame.start, frame.end)));
-	} catch (err) {
-		frameIssues.push(`frame@${frame.start}: ${String(err instanceof Error ? err.message : err)}`);
+function generationLogFilename(version, compression = "zstd") {
+	if (!Number.isSafeInteger(version) || version < 0) throw new Error(`session log generation must be a non-negative safe integer, got ${String(version)}`);
+	return `${version === 0 ? "session.jsonl" : `session.v${version}.jsonl`}${compressionSuffix(compression)}`;
+}
+/**
+* 把一个规范日志名解析回代次。
+*
+* 与宿主 `parseGenerationLogFilename` 同语义：非规范名（临时、大写、前导零、
+* `.v0`、别的压缩后缀）一律返回 undefined，**不猜**。
+* @param filename - 会话目录里的一个文件名。
+* @param compression - 该目录使用的物理编码（缺省 zstd）。
+* @returns 其格式代次，或名字不构成规范代次时的 undefined。
+*/
+function parseGenerationLogFilename(filename, compression = "zstd") {
+	const suffix = compressionSuffix(compression);
+	if (!filename.endsWith(suffix)) return void 0;
+	const match = CANONICAL_LOG_BASENAME.exec(filename.slice(0, filename.length - suffix.length));
+	if (match === null) return void 0;
+	if (match[1] === void 0) return 0;
+	const version = Number(match[1]);
+	return Number.isSafeInteger(version) ? version : void 0;
+}
+/**
+* 两种压缩编码都试一遍，判定该名字是不是某代的规范产物。
+*
+* 发现路径不能假设部署里的 `compression` 配置：配置在 profile 侧，插件读不到，
+* 而日志就在磁盘上。因此按名字本身分类，编码作为结果一并带回。
+* @param filename - 会话目录里的一个文件名。
+* @returns 代次与编码，或该名字不是规范代次时的 undefined。
+*/
+function classifyGenerationFilename(filename) {
+	const zstd = parseGenerationLogFilename(filename, "zstd");
+	if (zstd !== void 0) return {
+		version: zstd,
+		compression: "zstd"
+	};
+	const none = parseGenerationLogFilename(filename, "none");
+	if (none !== void 0) return {
+		version: none,
+		compression: "none"
+	};
+}
+/**
+* 该文件名是否是迁移暂存（当前代的发布源）。
+* @param filename - 会话目录里的一个文件名。
+* @returns 是否形如 `session.migration.<token>.jsonl[.zstd].tmp`。
+*/
+function isMigrationStagingFilename(filename) {
+	return MIGRATION_STAGING_NAME.test(filename);
+}
+/**
+* 读取一个会话目录的代次事实（只读，不碰任何文件内容）。
+* @param dir - 会话目录的绝对路径。
+* @returns 规范产物（按代次升序）、当前代、历史代与暂存残留。
+*/
+function readSessionGenerations(dir) {
+	const canonical = [];
+	const staging = [];
+	let entries;
+	try {
+		entries = readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return {
+			canonical: [],
+			staging: [],
+			legacyOnly: false
+		};
 	}
-	let recoveredFromTorn = 0;
-	if (tornStart !== void 0) try {
-		const recovered = zlib.zstdDecompressSync(bytes.subarray(tornStart), { finishFlush: zlib.constants.ZSTD_e_flush });
-		recoveredFromTorn = recovered.length;
-		parts.push(recovered);
-	} catch {}
-	const lines = Buffer.concat(parts).toString("utf8").split("\n").filter((line) => line.trim() !== "");
-	const issues = frameIssues.map((why, index) => ({
-		line: index + 1,
-		why
-	}));
-	const decodeRecord = decoders?.decodeStorageRecord ?? decodeRecordLocal;
-	const events = [];
-	for (let index = 1; index < lines.length; index += 1) {
-		const line = lines[index];
-		let decoded;
+	for (const entry of entries) {
+		if (!entry.isFile()) continue;
+		const path = join(dir, entry.name);
+		let bytes;
+		let mtimeMs;
 		try {
-			const parsed = JSON.parse(line);
-			decoded = decodeRecord(parsed["sourceEventSeqs"] === void 0 ? parsed : {
-				...parsed,
-				sourceEventSeqs: decoders?.decodeSeqRanges !== void 0 && typeof parsed["seq"] === "number" ? decoders.decodeSeqRanges(parsed["sourceEventSeqs"], parsed["seq"]) : decodeSeqRangesStorage(parsed["sourceEventSeqs"], Number(parsed["seq"] ?? 0))
-			});
-		} catch (err) {
-			issues.push({
-				line: index + 1,
-				why: `decode failed: ${String(err instanceof Error ? err.message : err)}`
-			});
-			break;
+			const stat = statSync(path);
+			bytes = stat.size;
+			mtimeMs = stat.mtimeMs;
+		} catch {
+			continue;
 		}
-		const rowStart = events.length;
-		let gapped = false;
-		for (const event of decoded) {
-			if (event.seq !== events.length) {
-				issues.push({
-					line: index + 1,
-					why: `seq gap (expected ${events.length}, got ${event.seq})`
-				});
-				events.length = rowStart;
-				gapped = true;
-				break;
-			}
-			events.push(event);
+		const artifact = {
+			name: entry.name,
+			path,
+			bytes,
+			mtimeMs
+		};
+		const generation = classifyGenerationFilename(entry.name);
+		if (generation !== void 0) {
+			canonical.push({
+				...artifact,
+				version: generation.version,
+				compression: generation.compression
+			});
+			continue;
 		}
-		if (gapped) break;
+		if (isMigrationStagingFilename(entry.name)) staging.push(artifact);
 	}
-	const openStep = findOpenStep(events);
+	canonical.sort((left, right) => left.version - right.version || left.mtimeMs - right.mtimeMs);
+	staging.sort((left, right) => left.mtimeMs - right.mtimeMs);
+	const current = canonical.at(-1);
+	const legacy = canonical.find((artifact) => artifact.version === 0);
 	return {
-		events,
-		frames: frames.length,
-		...tornStart === void 0 ? {} : { tornStart },
-		recoveredFromTorn,
-		issues,
-		decoder: decoders === void 0 ? "local" : "official",
-		...openStep === void 0 ? {} : { openStep }
+		canonical,
+		staging,
+		...current === void 0 ? {} : { current },
+		...legacy === void 0 ? {} : { legacy },
+		legacyOnly: canonical.length > 0 && current?.version === 0
 	};
 }
-/** 从文件读取并解码。 */
-function decodeSessionLogFile(file, decoders) {
-	return decodeSessionLogBytes(file, readFileSync(file), decoders);
+/** 目录内全部已识别产物的最新 mtime。 */
+function latestArtifactMtime(facts) {
+	const times = [...facts.canonical, ...facts.staging].map((artifact) => artifact.mtimeMs);
+	return times.length === 0 ? void 0 : Math.max(...times);
 }
-/** 尾部未收尾的 open step（有 step/start 无对应 step/end）。 */
-function findOpenStep(events) {
-	let open;
-	for (const event of events) {
-		const data = event.data;
-		if (event.type === "step/start" && typeof data?.turn === "number" && typeof data?.step === "number") {
-			open = {
-				turn: data.turn,
-				step: data.step
-			};
-			continue;
-		}
-		if (event.type === "step/end") open = void 0;
-	}
-	return open;
+/**
+* 该会话的处置优先级。
+*
+* `high` 的判据就是「从 TMP 移出来」本身：当前代次非 0（当前代是经
+* `session.migration.*.tmp` 暂存发布出来的），或目录内仍有暂存残留。
+* 代次 0 的历史代是宿主按契约保留的未发布会话，旧发现逻辑读的就是它 —— 这类
+* 会话既没有发布痕迹、也没有被读错，故为 `normal`。
+* @param facts - 会话目录的代次事实。
+* @returns 处置优先级。
+*/
+function sessionPriority(facts) {
+	if (facts.staging.length > 0) return "high";
+	return (facts.current?.version ?? 0) > 0 ? "high" : "normal";
 }
 //#endregion
 //#region src/host/health/lossless.ts
@@ -1207,7 +1714,7 @@ function isPlainArray(value) {
 //#endregion
 //#region src/host/health/gates.ts
 /**
-* 四个体检 gate（每个可独立测试）与报告聚合。
+* 五个体检 gate（每个可独立测试）与报告聚合。
 *
 * 统一输出形状：`{ id, level, evidence, attribution, detail }`；
 * 聚合结果 `SessionHealthReport` 供「体检 → 处方 → 出院」三步流程使用。
@@ -1246,6 +1753,65 @@ function readTailFacts(log) {
 		assistantAfterLastUser
 	};
 }
+/**
+* gate 0：代次事实（当前代是历史代还是已发布代、有没有暂存残留）。
+*
+* 存在的理由：一个会话目录里可以有多份日志产物，而**读哪一份**决定了后面所有
+* 门的结论。早期版本固定读 `session.jsonl.zstd`，于是对已发布当前代的会话要么
+* 读错（读历史代那份，12MB 全量回放）、要么完全发现不了。本门把这个前提显式化成
+* 可判定的证据，档位判据只取「有据可依」的三条：
+*   - 没有任何规范产物（只剩暂存）→ `fail`：当前代尚未发布；
+*   - 有暂存残留 → `warn`：发布源仍在原地（发布完成未清，或尚未发布）；
+*   - 文件名代次与 header 代次不一致 → `warn`：发布不变量被破坏。
+* 历史代与当前代并存是宿主**契约要求**（已提交代次不删不改），故记 `ok` 并写进
+* 证据，不抬档 —— 抬档会把 34 个完全正常的会话变成噪声。
+* @param facts - 会话目录的代次事实；缺省表示无从判定。
+* @param log - 已解码的日志（用于取 header.version 交叉核对）。
+*/
+function gateGeneration(facts, log) {
+	if (facts === void 0) return {
+		id: "generation",
+		level: "skipped",
+		evidence: "未提供代次事实，本门无从判定"
+	};
+	const current = facts.current;
+	const headerVersion = typeof log?.header?.["version"] === "number" ? log.header["version"] : void 0;
+	const detail = {
+		currentVersion: current?.version,
+		currentName: current?.name,
+		currentCompression: current?.compression,
+		canonicalVersions: facts.canonical.map((artifact) => artifact.version),
+		staging: facts.staging.map((artifact) => artifact.name),
+		legacyOnly: facts.legacyOnly,
+		priority: sessionPriority(facts),
+		...headerVersion === void 0 ? {} : { headerVersion }
+	};
+	if (current === void 0) return {
+		id: "generation",
+		level: "fail",
+		evidence: `目录内没有任何规范代次产物，仅剩 ${facts.staging.length} 份迁移暂存：当前代尚未从暂存发布`,
+		detail
+	};
+	if (facts.staging.length > 0) return {
+		id: "generation",
+		level: "warn",
+		evidence: `当前代 v${current.version}（${current.name}）旁留有 ${facts.staging.length} 份迁移暂存残留：` + facts.staging.map((artifact) => artifact.name).join("、"),
+		detail
+	};
+	if (headerVersion !== void 0 && headerVersion !== current.version) return {
+		id: "generation",
+		level: "warn",
+		evidence: `文件名代次与日志头代次不一致：${current.name} 名为 v${current.version}，header.version=${headerVersion}`,
+		detail
+	};
+	const note = facts.legacyOnly ? "；目录内只有历史代，宿主首次写访问时才发布当前代" : facts.legacy === void 0 ? "" : "；历史代 v0 按契约保留未删";
+	return {
+		id: "generation",
+		level: "ok",
+		evidence: `当前代 v${current.version}（${current.name}）${note}`,
+		detail
+	};
+}
 /** gate 1：日志完整性（可解码、seq 连续、无撕裂尾帧）。 */
 function gateLogIntegrity(log) {
 	if (log.issues.length > 0) {
@@ -1438,10 +2004,11 @@ function gateColdRead(facts) {
 		detail
 	};
 }
-/** 聚合四门结果为一份报告。 */
+/** 聚合全部 gate 结果为一份报告。 */
 function buildSessionReport(context) {
 	const log = context.log ?? (context.logPath === void 0 ? void 0 : decodeSessionLogFile(context.logPath));
 	const gates = [];
+	gates.push(gateGeneration(context.generations, log));
 	if (log === void 0) gates.push({
 		id: "log-integrity",
 		level: "fail",
@@ -1453,11 +2020,13 @@ function buildSessionReport(context) {
 		gates.push(gateProjectionCache(readProjectionCache(context.sessionId, tail.lastSeq, context.dshHome)));
 		gates.push(gateLosslessJson(context.projectionState, context.attribute));
 		gates.push(gateColdRead(tail));
+		gates.push(gateSourceKind(readSourceKindFacts(log)));
 	}
 	const level = gates.some((gate) => gate.level === "fail") ? "fail" : gates.some((gate) => gate.level === "warn") ? "warn" : "ok";
 	return {
 		sessionId: context.sessionId,
 		level,
+		priority: context.generations === void 0 ? "normal" : sessionPriority(context.generations),
 		gates,
 		generatedAt: (context.now ?? Date.now)()
 	};
@@ -1537,6 +2106,13 @@ function quarantineProjectionCache(sessionId, dshHome, now = Date.now) {
 function prescribe(report, dshHome) {
 	const lines = [];
 	const gate = (id) => report.gates.find((entry) => entry.id === id);
+	const generation = gate("generation");
+	if (generation?.level === "fail" || generation?.level === "warn") {
+		lines.push(`# 代次异常：${generation.evidence}`);
+		const currentVersion = generation.detail?.["currentVersion"];
+		lines.push(typeof currentVersion === "number" ? `# 当前代 v${currentVersion}：本插件不改会话日志，暂存残留的发布/隔离需用会话代次工具处理` : "# 目录内只有迁移暂存、还没有规范产物：需先用会话代次工具发布当前代，或重启宿主触发发布");
+		if (report.priority === "high") lines.push("# 该会话优先级为 high（当前代由暂存发布而来），建议先处置它");
+	}
 	const lossless = gate("lossless-json");
 	if (lossless?.level === "fail") {
 		const pkg = lossless.attribution?.package ?? "unknown";
@@ -1562,10 +2138,15 @@ function prescribe(report, dshHome) {
 	if (gate("cold-read")?.level === "fail") lines.push("# 会话仍处于 open step：请等待宿主结算（不要硬改日志），必要时重启宿主后重新体检");
 	if (lines.length === 0) {
 		const unjudged = report.gates.filter((entry) => entry.level === "skipped");
-		lines.push(unjudged.length === 0 ? "# 四门全绿：无需处置" : `# 无可处置项（${unjudged.length} 门无从判定，非异常）：${unjudged.map((entry) => entry.id).join(" / ")}`);
+		lines.push(unjudged.length === 0 ? "# 全部检查通过：无需处置" : `# 无可处置项（${unjudged.length} 门无从判定，非异常）：${unjudged.map((entry) => entry.id).join(" / ")}`);
 	}
 	return lines;
 }
+/** 残留门的可读归因：区分「本插件有能力处置」与「按红线只能等 / 交给别的工具」。 */
+function residualNote(residual) {
+	if (residual.some((entry) => entry.id === "generation")) return "其中 generation 来自会话目录的代次产物（暂存残留或当前代尚未发布），本插件不改会话日志，需用会话代次工具处置。";
+	return "这类异常来自会话日志或宿主运行态，本插件不改会话日志，请等待宿主结算后重新体检。";
+}
 /**
 * 判定一次处置的结果，并给出人读说明。
 *
@@ -1585,7 +2166,7 @@ function assessRepair(input) {
 	const residualIds = residual.map((entry) => entry.id).join(" / ");
 	if (before.level === "ok") return {
 		verdict: "nothing-to-do",
-		explanation: "四门全绿，无需处置",
+		explanation: "全部检查通过，无需处置",
 		residual: []
 	};
 	if (repair.ok) return residual.length === 0 ? {
@@ -1594,12 +2175,12 @@ function assessRepair(input) {
 		residual: []
 	} : {
 		verdict: "repaired-with-residual",
-		explanation: `已隔离投影缓存记录；但仍有与该缓存无关的异常：${residualIds}。这类异常来自会话日志或宿主运行态，本插件不改会话日志，请等待宿主结算后重新体检。`,
+		explanation: `已隔离投影缓存记录；但仍有与该缓存无关的异常：${residualIds}。${residualNote(residual)}`,
 		residual
 	};
 	if (!isActionable(before.gates.find((entry) => entry.id === "projection-cache")?.level)) return {
 		verdict: "not-applicable",
-		explanation: residualIds === "" ? "当前异常无可逆处置项" : `当前异常无可逆处置项（投影缓存无可隔离记录）；异常来自 ${residualIds}，本插件不改会话日志，请等待宿主结算后重新体检。`,
+		explanation: residualIds === "" ? "当前异常无可逆处置项" : `当前异常无可逆处置项（投影缓存无可隔离记录）；异常来自 ${residualIds}，${residualNote(residual)}`,
 		residual
 	};
 	return {
@@ -1611,17 +2192,36 @@ function assessRepair(input) {
 //#endregion
 //#region src/host/health/scan.ts
 /**
-* 批量体检：枚举会话日志、跑四门、给出汇总（供 `session-health-scan` 使用）。
+* 批量体检：枚举会话日志、跑门、给出汇总（供 `session-health-scan` 使用）。
 *
 * 只读；不激活任何 Agent，也不写任何会话数据。为控制成本，默认限制单次扫描的
 * 会话数与并发度，并支持 `limit` / `since` 过滤。
+*
+* **发现按代次而不是按固定文件名。** 一个会话目录的当前日志名由目录实测的最高
+* 代次决定（见 `generation.ts`）：历史代是 `session.jsonl.zstd`，已发布的当前代
+* 是 `session.v<N>.jsonl.zstd`。早期版本在这里写死 `session.jsonl.zstd`，于是
+* 61 个只留当前代的会话**一条都发现不了** —— 既扫不到，`findSessionLog` 也返回
+* undefined，连 `session-health-repair` 都会先报「未找到会话日志」。
 */
-/** 会话根目录（`<dshHome>/sessions/<project>/<sessionId>/session.jsonl.zstd`）。 */
+/** 会话根目录（`<dshHome>/sessions/<project>/<sessionId>/`）。 */
 function sessionsRoot(dshHome) {
 	return join(dshHome ?? join(homedir(), ".dsh"), "sessions");
 }
-/** 枚举全部会话日志（按 mtime 倒序），带可选上限。 */
-function discoverSessions(dshHome, limit = 200) {
+/**
+* 语料枚举上限。
+*
+* 这是防御无界遍历的**边界**，不是策略：早期版本写 200，实测语料 449 个会话时
+* 它静默截掉了一半（体检进度分母恒为 200，末 249 个会话永远扫不到）。
+*/
+const DISCOVERY_LIMIT = 1e5;
+/**
+* 枚举全部会话（按 mtime 倒序），带可选上限。
+*
+* 「是会话目录」的判据是**目录里有规范代次产物或迁移暂存**，不要求任何具体文件名。
+* @param dshHome - DSH home（缺省 ~/.dsh）。
+* @param limit - 返回上限（缺省 `DISCOVERY_LIMIT`）。
+*/
+function discoverSessions(dshHome, limit = DISCOVERY_LIMIT) {
 	const root = sessionsRoot(dshHome);
 	const out = [];
 	if (!existsSync(root)) return out;
@@ -1636,30 +2236,23 @@ function discoverSessions(dshHome, limit = 200) {
 			continue;
 		}
 		for (const entry of entries) {
+			if (!entry.isDirectory()) continue;
 			const path = join(dir, entry.name);
-			if (entry.isDirectory()) {
-				const candidate = join(path, "session.jsonl.zstd");
-				if (existsSync(candidate)) {
-					let stats;
-					try {
-						const stat = statSync(candidate);
-						stats = {
-							mtimeMs: stat.mtimeMs,
-							size: stat.size
-						};
-					} catch {
-						continue;
-					}
-					out.push({
-						sessionId: entry.name,
-						logPath: candidate,
-						updatedAt: stats.mtimeMs,
-						bytes: stats.size
-					});
-					continue;
-				}
+			const generations = readSessionGenerations(path);
+			if (generations.canonical.length === 0 && generations.staging.length === 0) {
 				stack.push(path);
+				continue;
 			}
+			const current = generations.current;
+			out.push({
+				sessionId: entry.name,
+				dir: path,
+				...current === void 0 ? {} : { logPath: current.path },
+				generations,
+				priority: sessionPriority(generations),
+				updatedAt: latestArtifactMtime(generations) ?? 0,
+				bytes: current?.bytes ?? 0
+			});
 		}
 	}
 	out.sort((left, right) => right.updatedAt - left.updatedAt);
@@ -1668,19 +2261,28 @@ function discoverSessions(dshHome, limit = 200) {
 /**
 * 语料总数：只做目录枚举，**不跑体检**。
 *
-* 用于判断缓存是否已过期——枚举很便宜，而重扫要解 zstd、跑四门。
+* 用于判断缓存是否已过期——枚举很便宜，而重扫要解 zstd、跑门。
 * 正因为两者代价差着量级，「对账」才不构成缓存失效策略本身。
 * @param dshHome - DSH home（缺省 ~/.dsh）。
 */
 function countCorpus(dshHome) {
 	return discoverSessions(dshHome, DISCOVERY_LIMIT).length;
 }
-/** 定位一个会话的日志路径（跨工程目录查找）。 */
+/** 按 id 定位一个会话（跨工程目录查找）。 */
+function findSession(sessionId, dshHome) {
+	return discoverSessions(dshHome, DISCOVERY_LIMIT).find((session) => session.sessionId === sessionId);
+}
+/**
+* 定位一个会话的**当前代**日志路径（跨工程目录查找）。
+*
+* 返回 undefined 有两种含义，调用方必须区分：会话不存在，或会话存在但尚未发布
+* 当前代（只有迁移暂存）。需要区分时用 `findSession`。
+* @param sessionId - 会话 id。
+* @param dshHome - DSH home（缺省 ~/.dsh）。
+*/
 function findSessionLog(sessionId, dshHome) {
-	return discoverSessions(dshHome, 1e5).find((session) => session.sessionId === sessionId)?.logPath;
+	return findSession(sessionId, dshHome)?.logPath;
 }
-/** 语料枚举上限（进度分母的来源；与 route 侧 MAX_SCAN_LIMIT 同量级）。 */
-const DISCOVERY_LIMIT = 200;
 /** 未显式传 limit 时的单批会话数。 */
 const DEFAULT_BATCH_LIMIT = 50;
 /**
@@ -1689,6 +2291,9 @@ const DEFAULT_BATCH_LIMIT = 50;
 * 语料先整体列出（按 mtime 倒序，≤ DISCOVERY_LIMIT），再按 `[offset, offset+limit)`
 * 切片扫描。这样客户端可以用小批次连续调用、自己累计真实进度，而宿主保持无状态
 * ——不必把同步循环改成异步，也不必新增进度轮询端点。
+*
+* 批内**命中顺序**按处置优先级排（`high` 在前，稳定排序）。分批切片仍按 mtime，
+* 所以 offset/total 的算术不受影响：只有同一批里的呈现顺序变了。
 * @param options - dshHome / 批大小 / 批起点 / 是否只返回非 ok / 归属查询 / 热态状态提供者。
 */
 function scanSessions(options) {
@@ -1710,7 +2315,8 @@ function scanSessions(options) {
 		const report = buildSessionReport({
 			sessionId: session.sessionId,
 			...options.dshHome === void 0 ? {} : { dshHome: options.dshHome },
-			logPath: session.logPath,
+			...session.logPath === void 0 ? {} : { logPath: session.logPath },
+			generations: session.generations,
 			...projectionState === void 0 ? {} : { projectionState },
 			...options.attribute === void 0 ? {} : { attribute: options.attribute },
 			...options.now === void 0 ? {} : { now: options.now }
@@ -1718,6 +2324,7 @@ function scanSessions(options) {
 		if (options.onlyProblems === true && report.level === "ok") continue;
 		findings.push(report);
 	}
+	findings.sort((left, right) => left.priority === right.priority ? 0 : left.priority === "high" ? -1 : 1);
 	return {
 		ok: true,
 		scanned: batch.length,
@@ -1731,28 +2338,17 @@ function scanSessions(options) {
 //#region src/index.ts
 /** 本插件声明的宿主服务（与 toggle 相同的注入面）。 */
 const inject = ["webServer", "webRuntime"];
-/** 运行时配置 schema（与 src/config.ts 的形状保持一致）。 */
+/** 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),
-	historyFiles: z.boolean().default(true),
-	healthCheck: z.boolean().default(true)
+	enabled: z.boolean().default(true).volatile(),
+	historyFiles: z.boolean().default(true).volatile(),
+	healthCheck: z.boolean().default(true).volatile()
 });
-/**
-* 官方 `installSettingsSection` 的内联等价：通过 settings 服务注册命名空间、
-* 以组合入口作为 `base` 层、并保持运行时来源实时（与 toggle / thinking-levels 同范式）。
-*/
-function installSettingsSection(ctx, ns, schema, entry, hooks) {
-	ctx.inject(["settings"], (sctx) => {
-		const scope = sctx.settings.register(ns, schema, { base: entry });
-		hooks.setSource(() => scope.get());
-		hooks.onChange();
-		sctx.effect(() => () => {
-			hooks.setSource(() => entry);
-			hooks.onChange();
-		});
-		scope.watch(() => hooks.onChange());
-	});
-}
 /** 单次请求体的上限（防御无界读取）。 */
 const MAX_BODY_BYTES = 16 << 20;
 /** 归一化 Host authority，无法解析时为 undefined。 */
@@ -1847,7 +2443,8 @@ const HEALTH_METHODS = [
 	"session-health-status",
 	"session-health-scan",
 	"session-health-session",
-	"session-health-repair"
+	"session-health-repair",
+	"session-health-source-migrate"
 ];
 /** 依据开关判定某方法是否启用。 */
 function methodEnabled(method, config) {
@@ -1935,8 +2532,8 @@ async function handleMethod(method, payload, runtime) {
 		ok: false,
 		error: "缺少合法的 sessionId"
 	};
-	const logPath = findSessionLog(sessionId, runtime.dshHome);
-	if (logPath === void 0) return {
+	const session = findSession(sessionId, runtime.dshHome);
+	if (session === void 0) return {
 		ok: false,
 		error: `未找到会话日志：${sessionId}`
 	};
@@ -1944,7 +2541,8 @@ async function handleMethod(method, payload, runtime) {
 	const reportFor = () => buildSessionReport({
 		sessionId,
 		dshHome: runtime.dshHome,
-		logPath,
+		...session.logPath === void 0 ? {} : { logPath: session.logPath },
+		generations: session.generations,
 		...projectionState === void 0 ? {} : { projectionState },
 		attribute: runtime.attribute
 	});
@@ -1957,6 +2555,31 @@ async function handleMethod(method, payload, runtime) {
 			prescriptions: prescribe(report, runtime.dshHome)
 		};
 	}
+	if (method === "session-health-source-migrate") {
+		if (session.logPath === void 0) return {
+			ok: false,
+			error: "会话尚未发布当前代日志，无从转换（先用会话代次工具发布）"
+		};
+		const log = decodeSessionLogFile(session.logPath);
+		const outcome = migrateSessionSourceKind(sessionId, session.logPath, log, runtime.dshHome);
+		const after = buildSessionReport({
+			sessionId,
+			dshHome: runtime.dshHome,
+			logPath: session.logPath,
+			generations: session.generations,
+			...projectionState === void 0 ? {} : { projectionState },
+			attribute: runtime.attribute
+		});
+		runtime.cache?.patch(after);
+		runtime.log(`source-kind migrate ${sessionId}: ok=${outcome.ok} changed=${outcome.changedRows ?? 0}` + (outcome.error === void 0 ? "" : ` error=${outcome.error}`));
+		return {
+			ok: outcome.ok,
+			outcome,
+			after,
+			report: after,
+			error: outcome.error
+		};
+	}
 	const before = reportFor();
 	if (before.level === "ok") {
 		runtime.cache?.patch(before);
@@ -1979,7 +2602,7 @@ async function handleMethod(method, payload, runtime) {
 			verdict: clean.verdict,
 			explanation: clean.explanation,
 			residual: clean.residual,
-			prescriptions: ["# 四门全绿：无需处置"]
+			prescriptions: ["# 全部检查通过：无需处置"]
 		};
 	}
 	const repair = quarantineProjectionCache(sessionId, runtime.dshHome);
@@ -2004,19 +2627,15 @@ async function handleMethod(method, payload, runtime) {
 	};
 }
 /**
-* 插件主体：注册设置命名空间、装配运行时、挂载 fenced 路由。
-* @param ctx - host 插件上下文（webServer / webRuntime / 可选 settings、sessionQuery、sessions、sessionProjections）。
+* 插件主体：装配运行时、挂载 fenced 路由。
+* @param ctx - host 插件上下文（webServer / webRuntime / 可选 sessionQuery、sessions、sessionProjections）。
+* @param config - 组合条目（0.1.7：`.volatile()` 字段为 live ref）。
 */
-function apply(ctx) {
-	let current = () => DEFAULT_CONFIG;
-	installSettingsSection(ctx, STEWARD_SETTINGS_NAMESPACE, Config, DEFAULT_CONFIG, {
-		setSource: (source) => {
-			current = () => ({
-				...DEFAULT_CONFIG,
-				...source()
-			});
-		},
-		onChange: () => {}
+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
 	});
 	const log = (message) => {
 		try {
@@ -2108,4 +2727,4 @@ function apply(ctx) {
 	}), "dsh-manage-session: /session-steward/api route");
 }
 //#endregion
-export { DEFAULT_CONFIG, HEALTH_METHODS, HISTORY_METHODS, HealthCache, STEWARD_API_PREFIX, STEWARD_SETTINGS_NAMESPACE, apply, assessRepair, buildProjectionOwnerIndex, buildSessionReport, countCorpus, createAttributor, decodeSessionLogBytes, decodeSessionLogFile, dirSize, discoverSessions, editWorkspaceDocument, findSessionLog, firstLosslessViolation, gateColdRead, gateLogIntegrity, gateLosslessJson, gateProjectionCache, handleMethod, indexSessionDirs, inject, isLossless, isSafeChild, listHistory, locateSessionUsage, methodEnabled, prescribe, projCacheRootFor, pruneArchiveFile, pruneHistory, purgeHistory, quarantineProjectionCache, readArchiveSet, readProjectionCache, readTailFacts, scanSessions, scanZstdFrames, sessionsRootFor };
+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 };