dsh-manage-session 0.2.3 → 0.3.3

package/lib/index.js

@@ -965,7 +965,7 @@ function decodeRecordLocal(value) {
 }
 /**
 * 读取一个会话日志文件（zip 帧扫描 + 解包 + seq 连续性）。
-* @param file - `session.jsonl.zstd` 绝对路径。
+* @param file - 当前代日志的绝对路径（由代次解析得出，不假定具体文件名）。
 * @param bytes - 文件内容（调用方读取，便于测试注入）。
 * @param decoders - 可选官方解码器（缺省用本地等价实现）。
 * @returns 事件、统计与问题清单。
@@ -1025,6 +1025,12 @@ function decodeSessionLogBytes(file, bytes, decoders) {
 		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,
@@ -1032,7 +1038,8 @@ function decodeSessionLogBytes(file, bytes, decoders) {
 		recoveredFromTorn,
 		issues,
 		decoder: decoders === void 0 ? "local" : "official",
-		...openStep === void 0 ? {} : { openStep }
+		...openStep === void 0 ? {} : { openStep },
+		...header === void 0 ? {} : { header }
 	};
 }
 /** 从文件读取并解码。 */
@@ -1056,6 +1063,186 @@ function findOpenStep(events) {
 	return open;
 }
 //#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" : "";
+}
+/**
+* 某代次的规范日志文件名。
+* @param version - 非负安全整数的格式代次。
+* @param compression - 物理编码（缺省 zstd）。
+* @returns 该代次在会话目录内的文件名。
+*/
+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
+		};
+	}
+	for (const entry of entries) {
+		if (!entry.isFile()) continue;
+		const path = join(dir, entry.name);
+		let bytes;
+		let mtimeMs;
+		try {
+			const stat = statSync(path);
+			bytes = stat.size;
+			mtimeMs = stat.mtimeMs;
+		} catch {
+			continue;
+		}
+		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 (isMigrationStagingFilename(entry.name)) staging.push(artifact);
+	}
+	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 {
+		canonical,
+		staging,
+		...current === void 0 ? {} : { current },
+		...legacy === void 0 ? {} : { legacy },
+		legacyOnly: canonical.length > 0 && current?.version === 0
+	};
+}
+/** 目录内全部已识别产物的最新 mtime。 */
+function latestArtifactMtime(facts) {
+	const times = [...facts.canonical, ...facts.staging].map((artifact) => artifact.mtimeMs);
+	return times.length === 0 ? void 0 : Math.max(...times);
+}
+/**
+* 该会话的处置优先级。
+*
+* `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
 /** 单个值是否可无损 JSON 序列化。 */
 function isLossless(value) {
@@ -1207,7 +1394,7 @@ function isPlainArray(value) {
 //#endregion
 //#region src/host/health/gates.ts
 /**
-* 四个体检 gate（每个可独立测试）与报告聚合。
+* 五个体检 gate（每个可独立测试）与报告聚合。
 *
 * 统一输出形状：`{ id, level, evidence, attribution, detail }`；
 * 聚合结果 `SessionHealthReport` 供「体检 → 处方 → 出院」三步流程使用。
@@ -1246,6 +1433,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 +1684,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",
@@ -1458,6 +1705,7 @@ function buildSessionReport(context) {
 	return {
 		sessionId: context.sessionId,
 		level,
+		priority: context.generations === void 0 ? "normal" : sessionPriority(context.generations),
 		gates,
 		generatedAt: (context.now ?? Date.now)()
 	};
@@ -1537,6 +1785,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 +1817,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 +1845,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 +1854,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 +1871,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 +1915,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 +1940,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 +1970,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 +1994,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 +2003,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,
@@ -1935,8 +2221,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 +2230,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
 	});
@@ -1979,7 +2266,7 @@ async function handleMethod(method, payload, runtime) {
 			verdict: clean.verdict,
 			explanation: clean.explanation,
 			residual: clean.residual,
-			prescriptions: ["# 四门全绿：无需处置"]
+			prescriptions: ["# 全部检查通过：无需处置"]
 		};
 	}
 	const repair = quarantineProjectionCache(sessionId, runtime.dshHome);
@@ -2108,4 +2395,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 { DEFAULT_CONFIG, HEALTH_METHODS, HISTORY_METHODS, HealthCache, STEWARD_API_PREFIX, STEWARD_SETTINGS_NAMESPACE, apply, assessRepair, buildProjectionOwnerIndex, buildSessionReport, classifyGenerationFilename, countCorpus, createAttributor, decodeSessionLogBytes, decodeSessionLogFile, dirSize, discoverSessions, editWorkspaceDocument, findSession, findSessionLog, firstLosslessViolation, gateColdRead, gateGeneration, gateLogIntegrity, gateLosslessJson, gateProjectionCache, generationLogFilename, handleMethod, indexSessionDirs, inject, isLossless, isMigrationStagingFilename, isSafeChild, latestArtifactMtime, listHistory, locateSessionUsage, methodEnabled, parseGenerationLogFilename, prescribe, projCacheRootFor, pruneArchiveFile, pruneHistory, purgeHistory, quarantineProjectionCache, readArchiveSet, readProjectionCache, readSessionGenerations, readTailFacts, scanSessions, scanZstdFrames, sessionPriority, sessionsRootFor };

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "dsh-manage-session",
-  "version": "0.2.3",
+  "version": "0.3.3",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public",
-    "tag": "dsh-0.1.2"
+    "tag": "dsh-0.1.5"
   },
-  "description": "DSH Web 插件：会话管家 —— 会话历史文件（归档浏览与清理）与会话健康检查（体检 → 处方 → 出院），不碰会话日志、只做可逆处置",
+  "description": "DSH Web 插件（DSH 0.1.5 专线）：会话管家 —— 会话历史文件（归档浏览与清理）与会话健康检查（体检 → 处方 → 出院），不碰会话日志、只做可逆处置",
   "keywords": [
     "deepseek-harness",
     "dsh",
@@ -51,7 +51,8 @@
     "build": "node -e \"require('fs').rmSync('lib',{recursive:true,force:true})\" && tsc -b && tsdown",
     "prepublishOnly": "npm run build",
     "typecheck": "tsc -b --pretty false",
-    "test": "vitest run"
+    "test": "vitest run",
+    "release:015": "npm publish --tag dsh-0.1.5"
   },
   "files": [
     "lib/index.js",
@@ -76,15 +77,15 @@
   ],
   "engines": {
     "node": ">=20",
-    "dsh": ">=0.1.2-rc.1 <0.1.3-0"
+    "dsh": ">=0.1.5-rc.1 <0.1.6-0"
   },
   "license": "MIT",
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-client-locale": ">=0.1.2-rc.1 <0.1.3-0",
-    "@deepseek-ai/dsh-client-ui-settings": ">=0.1.2-rc.1 <0.1.3-0",
-    "@deepseek-ai/dsh-client-ui-settings-general": ">=0.1.2-rc.1 <0.1.3-0",
-    "@deepseek-ai/dsh-client-ui-slots": ">=0.0.1-rc.1 <0.1.0 || >=0.1.0-rc.1 <0.1.3-0",
+    "@deepseek-ai/dsh-client-locale": ">=0.1.5-rc.1 <0.1.6-0",
+    "@deepseek-ai/dsh-client-ui-settings": ">=0.1.5-rc.1 <0.1.6-0",
+    "@deepseek-ai/dsh-client-ui-settings-general": ">=0.1.5-rc.1 <0.1.6-0",
+    "@deepseek-ai/dsh-client-ui-slots": ">=0.0.1-rc.1 <0.1.0 || >=0.1.0-rc.1 <0.1.6-0",
     "@deepseek-ai/schemastery": "^3.18.1",
     "react": "^18.2.0"
   },

package/screenshots.json

@@ -1,3 +1,7 @@
 {
-  "screenshots": []
+  "screenshots": [
+    "assets/left-sidebar.png",
+    "assets/archive.png",
+    "assets/doctor.png"
+  ]
 }

package/src/client/health-panel.tsx

@@ -1,5 +1,5 @@
 /**
- * 体检面板：体检（四门）→ 处方（命令清单）→ 出院（可逆处置 + before/after 对照）。
+ * 体检面板：体检（五门）→ 处方（命令清单）→ 出院（可逆处置 + before/after 对照）。
  *
  * 三态流转完全由 host 侧报告驱动，客户端只做展示与触发；重型动作都在 host，
  * 渲染周期内不发同步重活。
@@ -19,6 +19,7 @@ import { translate, type LocaleKey } from './locales.ts'
 export type PanelTranslate = (key: LocaleKey, params?: Record<string, unknown>) => string
 
 const GATE_LABEL: Record<HealthGate['id'], LocaleKey> = {
+  'generation': 'health.gate.generation',
   'log-integrity': 'health.gate.log-integrity',
   'projection-cache': 'health.gate.projection-cache',
   'lossless-json': 'health.gate.lossless-json',
@@ -315,6 +316,9 @@ export function HealthPanel({ t, onClose }: { t?: PanelTranslate; onClose: () =>
           .join(' · ')
         return createElement('li', { key: item.sessionId, className: 'dss_row' }, [
           createElement('span', { key: 'lv', className: `dss_levelPill dss_level_${item.level}` }, translate(t, LEVEL_LABEL[item.level])),
+          // 优先级徽标：这些会话的当前代是从迁移暂存（TMP）发布出来的，即本插件
+          // 此前读错产物或完全发现不了的那批。列表按优先级排，再标一次让排序可解释。
+          item.priority === 'high' && createElement('span', { key: 'p', className: 'dss_meta' }, translate(t, 'health.priority.high')),
           createElement('span', { key: 'id', className: 'dss_meta dss_uuid' }, item.sessionId),
           reasons !== '' && createElement('span', { key: 'why', className: 'dss_why' }, reasons),
           createElement('button', {

package/src/client/host-api.ts

@@ -98,7 +98,7 @@ export interface HistoryPurgeResponse {
 
 /** 一个 gate 的结果（与 host 侧 GateResult 对齐）。 */
 export interface HealthGate {
-  id: 'log-integrity' | 'projection-cache' | 'lossless-json' | 'cold-read'
+  id: 'generation' | 'log-integrity' | 'projection-cache' | 'lossless-json' | 'cold-read'
   level: 'ok' | 'warn' | 'fail' | 'skipped'
   evidence: string
   attribution?: { projection?: string; package?: string; field?: string }
@@ -110,6 +110,11 @@ export interface HealthReport {
   sessionId: string
   /** 总判：聚合时 `skipped` 不抬升（见 host 侧 buildSessionReport）。 */
   level: 'ok' | 'warn' | 'fail'
+  /**
+   * 处置优先级（见 host 侧 generation.ts）：`high` = 当前代是从迁移暂存（TMP）发布出来的。
+   * 与 `level` 正交：优先级答「先看谁」，档位答「要不要处置」。
+   */
+  priority?: 'high' | 'normal'
   gates: HealthGate[]
   generatedAt: number
 }