@deepseek-ai/dsh-session-snapshot 0.1.2-rc.1 → 0.1.3-alpha.2

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/test-support/session-snapshot/README.md
-README.md: 0e099dba28f45031bdaa3c187f3e3ffce5b3b2b9
-README.zh.md: f81b3038b14b94716f4f045aee2d70daa27930dc
+README.md: 12acb8d426a2966a852f98d85843d3c246ffeb5f
+README.zh.md: 0b30cbf205f6055ef7b11b791d47adb38f6f704d

package/README.md

@@ -68,17 +68,19 @@ defineAcpSnapshotSuite({
 })
 ```
 
-Each recorded-session directory carries a closed `snapshot.yml` manifest plus its `session.jsonl` and contiguous `session.<n>.jsonl` child logs. The manifest names the scenario, shipped profile, composition/header class, recording source, and only the replay, platform, permission, environment, workspace, or input facts the completed session cannot reconstruct. The adapter registers expected-output, session-log, and optional `workspace.expected/` comparisons; guards reject orphan directories, missing files, absolute paths, malformed manifests, and platform-specific separators.
+Each recorded-session directory carries a closed `snapshot.yml` manifest plus canonical parent and contiguous child roles. Parent filenames are `session[.vN].jsonl`; children are `session.<ordinal>[.vN].jsonl`; v0 omits `.v0`, positive versions use lowercase `.vN`, and every filename agrees with its header. A role may retain older generations, but the harness selects the numerically highest one. An owning manifest may declare `sessionFormat.version` plus one or more closed `coverage` names to keep that historical generation as an explicit migration fixture; absence tracks the current writer. The manifest also names the scenario, shipped profile, composition/header class, recording source, and only the replay, platform, permission, environment, workspace, or input facts the completed Session cannot reconstruct. The adapter registers expected-output, Session-log, and optional `workspace.expected/` comparisons; guards reject orphan directories, missing roles, noncanonical names, absolute paths, malformed manifests, and platform-specific separators.
 
-`normalizeSessionSnapshot` retains the complete session header and event payloads but omits ordinary `seq`/`time` and packed-row `seq0`/`time0` envelopes from committed fixtures after normalizing paths and scrubbing request headers. Replay synthesizes the envelopes in memory, while runtime persistence continues to write complete logs. Fixtures use canonical packed rows; the [temporary repository migrator](../../../scripts/migrate-packed-session-fixtures.ts) (`pnpm run migrate:packed-session-fixtures`) rewrites older layouts, and its [removal proposal](../../../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md) owns its deletion.
+`normalizeSessionSnapshot` retains the complete Session header and event payloads but omits top-level `seq`/`time` envelopes from committed fixtures after normalizing paths and scrubbing request headers; it also normalizes embedded stream clocks and historical packed-row `seq0`/`time0` envelopes. Replay synthesizes the top-level envelopes in memory, while runtime persistence continues to write complete logs. Multi-session comparison restores every selected persisted or projected fixture through the current build-static Session format catalog before identity redaction and normalization, so retained v0/v1 replay input and fresh `session.v2.jsonl` writer output compare as one v2 logical Session without rewriting or renaming historical files. Expected and harvested logs use the same strict restoration path; source filenames cannot alter format validation. Versionless protocol-adapter unit fixtures remain outside the released Session format corpus. Current v2 fixtures use one row per event; retained v0/v1 fixtures may use canonical packed rows. The [temporary repository migrator](../../../scripts/migrate-packed-session-fixtures.ts) (`pnpm run migrate:packed-session-fixtures`) rewrites older historical layouts, and its [removal proposal](../../../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md) owns its deletion.
+
+Known snapshot spill paths normalize to stable locator tokens, including paths quoted inside JSON omission notices with JSON-escaped Windows separators. Refresh extraction preserves the matched serialized path spelling for literal replacement. Normalization changes only the locator: saved byte lengths and omission counts remain comparison evidence.
 
 ### Record, replay, and refresh
 
-`pnpm run test:snapshot:record` calls the live LLM and rewrites recorded model fixtures; `pnpm run test:snapshot:refresh` stays keyless, runs the replay overlay, and rewrites stdout, comparable session-log expected outputs, and owned prompt and tool-schema sidecars from committed model scripts. Each composition owner keeps its replay patch beside its live patch; top-level `snapshots/` owns session-driven scenarios, while other expected outputs stay beside their owning package. [`dsh-llm-replay`](../llm-replay/README.md) serves the recorded streams selected through `DSH_SNAPSHOT_*` environment values.
+`pnpm run test:snapshot:record` calls the live LLM and writes the harvested current generation under its canonical versioned filename. Record and refresh never rename or delete a completed generation, including generations of a child role absent from a later run; reviewed source-tree curation removes a predecessor only after the same role has a verified current replacement. Scenarios with an explicit `sessionFormat` remain read-only in record mode. `pnpm run test:snapshot:refresh` stays keyless, runs the selected highest replay input, and writes stdout, owned prompt and tool-schema sidecars, and a fresh current-generation comparable Session output unless the manifest retains a historical generation. Each composition owner keeps its replay patch beside its live patch; top-level `snapshots/` owns Session-driven scenarios, while other expected outputs stay beside their owning package. [`dsh-llm-replay`](../llm-replay/README.md) serves the recorded streams selected through `DSH_SNAPSHOT_*` environment values.
 
 ### Pinning request headers
 
-A pin owns its generated `system-prompt.expected.md` or `tool-schemas.expected.json` sidecar by default; `systemPromptSource` and `toolSchemasSource` name another pin when the complete corresponding sequence is identical, so each distinct version is committed once. The pin's `session.jsonl` stores `"system":"{{system}}","tools":"{{tools}}"` while retaining config, reason, and any model-visible prefix. A child session whose own scope composes a different request declares it per fixture index with `pinsChildToolSchemas` and `pinsChildSystemPrompts`. A scenario that changes the request header mid-run declares `expectedHeaderChanges`.
+A pin owns its generated `system-prompt.expected.md` or `tool-schemas.expected.json` sidecar by default; `systemPromptSource` and `toolSchemasSource` name another pin when the complete corresponding sequence is identical, so each distinct version is committed once. The selected highest parent fixture stores `"system":"{{system}}","tools":"{{tools}}"` while retaining config, reason, and any model-visible prefix. A child Session whose own scope composes a different request declares it per fixture index with `pinsChildToolSchemas` and `pinsChildSystemPrompts`. A scenario that changes the request header mid-run declares `expectedHeaderChanges`.
 
 ### Platform and composition variants
 
@@ -102,7 +104,7 @@ This section explains the design of the kit; the observable behavior is fully co
 
 ### Design
 
-The shared core owns manifests, workspace setup/comparison, typed identity mapping, normalizers, and fixture invariants. The ACP adapter adds four composable layers: launcher, scenario harness, normalizers, and suite factory. `launchAcpTestAgent` boots a source profile under tsx or a built `lib` profile under plain Node, connects the SDK client over a raw-byte stdout tee, collects session updates and stderr, fails closed on unhandled permission requests, and owns shutdown. `runScenario` drives ACP JSON-RPC stdio and harvests every persisted raw JSONL session log. The pure normalizers replace cwd paths and typed identities with stable tokens, zero times, expand physical provenance ranges, and scrub request-header bulk. `defineAcpSnapshotSuite` registers comparisons, fixture write-back, and the live uniformity guard.
+The shared core owns manifests, generation-qualified role selection, workspace setup/comparison, typed identity mapping, normalizers, and fixture invariants. The ACP adapter adds four composable layers: launcher, scenario harness, normalizers, and suite factory. `launchAcpTestAgent` boots a source profile under tsx or a built `lib` profile under plain Node, connects the SDK client over a raw-byte stdout tee, collects Session updates and stderr, fails closed on unhandled permission requests, and owns shutdown. `runScenario` drives ACP JSON-RPC stdio and harvests the numerically highest persisted raw JSONL generation for every Session directory. The pure normalizers replace cwd paths and typed identities with stable tokens, zero times, expand physical provenance ranges, and scrub request-header bulk. `defineAcpSnapshotSuite` registers comparisons, generation-qualified fixture write-back, and the live uniformity guard.
 
 ### Source map
 
@@ -111,6 +113,7 @@ The shared core owns manifests, workspace setup/comparison, typed identity mappi
 | [`src/launcher.ts`](src/launcher.ts) | Subprocess/client launcher and shutdown ownership |
 | [`src/harness.ts`](src/harness.ts) | Scripted scenario driver and session-log harvest |
 | [`src/manifest.ts`](src/manifest.ts) | Closed `snapshot.yml` schema, collection, and ownership rules |
+| [`src/session-files.ts`](src/session-files.ts) | Canonical parent/child generation grammar, header agreement, and highest-role selection |
 | [`src/identity.ts`](src/identity.ts) | Typed first-seen identity tokenization across parent and child logs |
 | [`src/normalize.ts`](src/normalize.ts) | Pure normalizers and scrubbing helpers |
 | [`src/workspace.ts`](src/workspace.ts) | Scenario workspace setup and complete expected-state comparison |

package/README.zh.md

@@ -68,17 +68,19 @@ defineAcpSnapshotSuite({
 })
 ```
 
-每个已记录会话目录携带封闭的 `snapshot.yml` manifest，以及自身的 `session.jsonl` 与连续的 `session.<n>.jsonl` 子会话日志。manifest 指名场景、随附 profile、组合／header 类别、录制来源，以及已完成会话无法重建的 replay、平台、权限、环境、workspace 或输入事实。适配器注册预期输出、会话日志与可选 `workspace.expected/` 比较；保护会拒绝遗留目录、缺失文件、绝对路径、畸形 manifest 与平台专用分隔符。
+每个已记录 Session 目录携带封闭的 `snapshot.yml` manifest，以及规范 parent 与连续 child 角色。parent 文件名是 `session[.vN].jsonl`；child 是 `session.<ordinal>[.vN].jsonl`；v0 省略 `.v0`，正版本使用小写 `.vN`，且每个文件名与其 header 一致。一个角色可以保留旧 generation，但 harness 会选择数值最高的一项。拥有 fixture 的 manifest 可以声明 `sessionFormat.version` 与一个或多个封闭 `coverage` 名称，把该历史 generation 保留为显式迁移 fixture；省略此字段时跟随当前 writer。manifest 还会指名场景、随附 profile、组合／header 类别、录制来源，以及已完成 Session 无法重建的 replay、平台、权限、环境、workspace 或输入事实。适配器注册预期输出、Session 日志与可选 `workspace.expected/` 比较；保护会拒绝遗留目录、缺失角色、非规范名称、绝对路径、malformed manifest 与平台专用分隔符。
 
-`normalizeSessionSnapshot` 在规范化路径并清理 request header 后，会保留完整会话 header 与事件 payload，但从已提交 fixture 中省略普通行的 `seq`/`time` 和打包行的 `seq0`/`time0` envelope。回放只在内存中合成这些 envelope，而运行时持久化仍写入完整日志。fixture 使用规范打包行；[临时仓库迁移器](../../../scripts/migrate-packed-session-fixtures.ts)（`pnpm run migrate:packed-session-fixtures`）会改写较旧的布局，由其[移除提案](../../../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.zh.md)负责删除该迁移器。
+`normalizeSessionSnapshot` 在规范化路径并清理 request header 后，会保留完整 Session header 与事件 payload，但从已提交 fixture 中省略顶层 `seq`/`time` envelope；它还会规范化嵌入式 stream clock 与历史 packed-row 的 `seq0`/`time0` envelope。Replay 只在内存中合成顶层 envelope，而运行时持久化仍写入完整日志。多 Session 比较会先通过当前构建期静态 Session 格式目录恢复每个选定的持久化或投影 fixture，再进行身份脱敏与规范化，因此保留的 v0/v1 replay 输入与新生成的 `session.v2.jsonl` writer 输出会作为同一个 v2 logical Session 比较，且不会重写或重命名历史文件。预期日志与收集日志使用同一条严格恢复路径；来源文件名不能改变格式校验。无版本的协议适配器单元测试 fixture 不属于已发布 Session 格式语料。当前 v2 fixture 每个事件占一行；保留的 v0/v1 fixture 可以使用规范 packed row。[临时仓库迁移器](../../../scripts/migrate-packed-session-fixtures.ts)（`pnpm run migrate:packed-session-fixtures`）会改写更旧的历史布局，由其[移除提案](../../../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.zh.md)负责删除该迁移器。
+
+已知的快照 spill 路径会规范化为稳定的定位信息 token，包括 JSON 省略通知中带引号、使用 JSON 转义 Windows 分隔符的路径。刷新提取会保留匹配路径的序列化写法，以便进行字面替换。规范化只改变定位信息：保存字节数与省略计数仍作为比较证据。
 
 ### 录制、回放与刷新
 
-`pnpm run test:snapshot:record` 调用在线 LLM（大语言模型），并重写已录制的模型 fixture；`pnpm run test:snapshot:refresh` 保持无密钥，运行回放 overlay，并从已提交模型脚本重写 stdout、可比较会话日志预期输出，以及各 pin 自有的提示词与工具 schema 伴随文件。每个组合 owner 把 replay patch 放在 live patch 旁；顶层 `snapshots/` 拥有会话驱动场景，其他预期输出留在其包 owner 旁。[`dsh-llm-replay`](../llm-replay/README.zh.md) 提供通过 `DSH_SNAPSHOT_*` 环境值选择的已记录流。
+`pnpm run test:snapshot:record` 调用在线 LLM（大语言模型），并在规范具名版本文件下写入收集到的当前 generation。record 与 refresh 绝不重命名或删除已完成的 generation，即使后续运行不再产生某个 child 角色也一样；受审阅的源树整理只有在同角色存在已验证的当前替代文件后才移除前代。显式声明 `sessionFormat` 的场景在录制模式下保持只读。`pnpm run test:snapshot:refresh` 保持无密钥，运行选定的最高 replay 输入，并写入 stdout、各 pin 自有的 prompt 与工具 schema sidecar；只有 manifest 未保留历史 generation 时，才写入新鲜当前 generation 的可比较 Session 输出。每个组合 owner 把 replay patch 放在 live patch 旁；顶层 `snapshots/` 拥有 Session 驱动场景，其他预期输出留在其 package owner 旁。[`dsh-llm-replay`](../llm-replay/README.zh.md) 提供通过 `DSH_SNAPSHOT_*` 环境值选择的已记录流。
 
 ### 固定请求 header
 
-每个 pin 默认拥有其生成的 `system-prompt.expected.md` 或 `tool-schemas.expected.json` 伴随文件；当完整的对应序列相同时，`systemPromptSource` 与 `toolSchemasSource` 指定另一个 pin 作为来源，因此每个不同版本只提交一次。该 pin 的 `session.jsonl` 存储 `"system":"{{system}}","tools":"{{tools}}"`，同时保留配置、原因与任何模型可见前缀。自身作用域组合出不同请求的子会话按 fixture 索引以 `pinsChildToolSchemas` 与 `pinsChildSystemPrompts` 单独声明。运行中改变请求 header 的场景声明 `expectedHeaderChanges`。
+每个 pin 默认拥有其生成的 `system-prompt.expected.md` 或 `tool-schemas.expected.json` sidecar；当完整的对应序列相同时，`systemPromptSource` 与 `toolSchemasSource` 指定另一个 pin 作为来源，因此每个不同版本只提交一次。选定的最高 parent fixture 存储 `"system":"{{system}}","tools":"{{tools}}"`，同时保留配置、原因与任何模型可见前缀。自身 scope 组合出不同请求的 child Session 按 fixture index 以 `pinsChildToolSchemas` 与 `pinsChildSystemPrompts` 单独声明。运行中改变请求 header 的场景声明 `expectedHeaderChanges`。
 
 ### 平台与组合变体
 
@@ -102,7 +104,7 @@ defineAcpSnapshotSuite({
 
 ### 设计
 
-共享核心拥有 manifest、workspace 设置／比较、类型化身份映射、规范化器与 fixture 不变式。ACP 适配器增加四个可组合层：启动器、场景 harness、规范化器与套件工厂。`launchAcpTestAgent` 在 tsx 下启动源码 profile，或在普通 Node 下启动已构建 `lib` profile，通过原始字节 stdout tee 连接 SDK 客户端，收集会话更新与 stderr，默认拒绝未处理的权限请求，并负责关闭。`runScenario` 驱动 ACP JSON-RPC stdio，并收集每个持久化原始 JSONL 会话日志。纯规范化器把 cwd 路径与类型化身份变为稳定 token，将时间归零、展开物理来源区间，并擦除请求 header bulk。`defineAcpSnapshotSuite` 注册比较、fixture 回写与实时一致性保护。
+共享核心拥有 manifest、generation 限定角色选择、workspace 设置／比较、类型化身份映射、normalizer 与 fixture 不变式。ACP 适配器增加四个可组合层：launcher、场景 harness、normalizer 与 suite factory。`launchAcpTestAgent` 在 tsx 下启动源码 profile，或在普通 Node 下启动已构建 `lib` profile，通过原始字节 stdout tee 连接 SDK client，收集 Session update 与 stderr，默认拒绝未处理的权限请求，并负责关闭。`runScenario` 驱动 ACP JSON-RPC stdio，并收集每个 Session 目录中数值最高的持久原始 JSONL generation。纯 normalizer 把 cwd 路径与类型化身份变为稳定 token，将时间归零、展开物理来源区间，并清理 request header bulk。`defineAcpSnapshotSuite` 注册比较、generation 限定 fixture 回写与实时一致性保护。
 
 ### 源码地图
 
@@ -111,6 +113,7 @@ defineAcpSnapshotSuite({
 | [`src/launcher.ts`](src/launcher.ts) | 子进程/客户端启动器与关闭所有权 |
 | [`src/harness.ts`](src/harness.ts) | 脚本化场景驱动与会话日志收集 |
 | [`src/manifest.ts`](src/manifest.ts) | 封闭 `snapshot.yml` schema、收集与归属规则 |
+| [`src/session-files.ts`](src/session-files.ts) | 规范 parent/child generation grammar、header 一致性与最高角色选择 |
 | [`src/identity.ts`](src/identity.ts) | 跨父子日志的类型化首次出现身份 token 化 |
 | [`src/normalize.ts`](src/normalize.ts) | 纯规范化器与擦除辅助 |
 | [`src/workspace.ts`](src/workspace.ts) | 场景 workspace 设置与完整预期状态比较 |

package/lib/index.js

@@ -12,7 +12,10 @@ import { pathToFileURL } from "node:url";
 import * as yaml from "js-yaml";
 import { entryListSchema } from "@deepseek-ai/cordis-plugin-include";
 import { resolveExampleLaunch } from "@deepseek-ai/dsh-loader-smoke";
-import { SessionLogOffset, SessionSeq, decodeSeqRanges, decodeStorageRecord, packChunkRuns } from "@deepseek-ai/dsh-session";
+import { clearedProxyEnv } from "@deepseek-ai/dsh-http-proxy";
+import { parseSessionFormatLogFilename, sessionFormatLogFilename } from "@deepseek-ai/dsh-session-format";
+import { decodeSeqRanges } from "@deepseek-ai/dsh-session";
+import { prepareSessionSnapshotFixtureForComparison } from "@deepseek-ai/dsh-llm-replay";
 import { isSurfaceEligibleType } from "@deepseek-ai/dsh-session/surface";
 //#region lib/types/identity.js
 /** Relationship-preserving identity redaction for committed session snapshots. */
@@ -88,7 +91,10 @@ function redactSessionSnapshotIds(logs) {
 			collect(item, recordType);
 		}
 	};
-	for (const log of parsed) for (const record of log.records) collect(record, record.type);
+	for (const log of parsed) for (const record of log.records) {
+		if (record.type === "feedback/message-put" && isRecord$1(record.data) && isRecord$1(record.data.item)) claim(record.data.item.version, "id");
+		collect(record, record.type);
+	}
 	const replacements = [...tokenByValue].sort(([left], [right]) => right.length - left.length);
 	const replace = (value) => {
 		if (typeof value === "string") {
@@ -398,6 +404,188 @@ function isRunning(child) {
 	return child.exitCode === null && child.signalCode === null;
 }
 //#endregion
+//#region lib/types/session-files.js
+/** Immutable Session-generation filenames used by recorded-session fixtures. */
+const FIXTURE_FILE = /^session(?:\.([1-9]\d*))?(?:\.v([1-9]\d*))?\.jsonl$/u;
+function nonNegativeSafeInteger(value, label) {
+	if (!Number.isSafeInteger(value) || value < 0 || Object.is(value, -0)) throw new Error(`${label} must be a non-negative safe integer`);
+}
+/**
+* Return the canonical fixture filename for one parent/ordinal and generation.
+*
+* @param index - Parent `0` or a positive child/ordinal slot.
+* @param version - Physical format generation; `0` is omitted.
+* @returns The lowercase canonical JSONL filename.
+*/
+function sessionFixtureName(index, version) {
+	nonNegativeSafeInteger(index, "session fixture index");
+	nonNegativeSafeInteger(version, "Session format version");
+	return `session${index === 0 ? "" : `.${index}`}${version === 0 ? "" : `.v${version}`}.jsonl`;
+}
+/**
+* Parse one canonical recorded-session fixture filename.
+*
+* @param name - Basename from a scenario directory.
+* @returns Parsed role and generation, or `undefined` for an unrelated file.
+*/
+function parseSessionFixtureName(name) {
+	const match = FIXTURE_FILE.exec(name);
+	if (match === null) {
+		if (name.startsWith("session") && name.endsWith(".jsonl")) throw new Error(`invalid session fixture name: ${name}`);
+		return;
+	}
+	const index = match[1] === void 0 ? 0 : Number(match[1]);
+	const version = match[2] === void 0 ? 0 : Number(match[2]);
+	if (!Number.isSafeInteger(index) || !Number.isSafeInteger(version)) throw new Error(`invalid session fixture name: ${name}`);
+	return {
+		index,
+		version,
+		name
+	};
+}
+/**
+* Select the highest generation for every parent/ordinal fixture role.
+* Older generations remain in the directory but do not count as extra Sessions.
+*
+* @param names - File basenames in one scenario directory.
+* @returns Parent first, followed by contiguous child/ordinal roles.
+*/
+function sessionFixtureFiles(names) {
+	const selected = /* @__PURE__ */ new Map();
+	const identities = /* @__PURE__ */ new Set();
+	for (const name of names) {
+		const fixture = parseSessionFixtureName(name);
+		if (fixture === void 0) continue;
+		const identity = `${fixture.index}/${fixture.version}`;
+		if (identities.has(identity)) throw new Error(`duplicate session fixture generation: ${name}`);
+		identities.add(identity);
+		const previous = selected.get(fixture.index);
+		if (previous === void 0 || fixture.version > previous.version) selected.set(fixture.index, fixture);
+	}
+	if (selected.get(0) === void 0) throw new Error("missing parent session fixture");
+	const ordered = [...selected.values()].sort((left, right) => left.index - right.index);
+	for (const [offset, fixture] of ordered.entries()) if (fixture.index !== offset) throw new Error(`session fixture roles must be contiguous: expected index ${offset}, found ${fixture.name}`);
+	return ordered;
+}
+/**
+* Validate and order a scenario directory's selected Session fixture filenames.
+*
+* @param names - File basenames in one scenario directory.
+* @returns Highest-generation parent and child/ordinal filenames.
+*/
+function sessionFixtureNames(names) {
+	return sessionFixtureFiles(names).map((file) => file.name);
+}
+/**
+* Read the declared physical generation from one Session JSONL header.
+*
+* @param content - Complete UTF-8 JSONL content.
+* @param label - Diagnostic filename or path.
+* @returns The declared non-negative format generation.
+*/
+function sessionHeaderVersion(content, label) {
+	const line = content.split(/\r?\n/u).find((candidate) => candidate.trim().length > 0);
+	if (line === void 0) throw new Error(`${label}: session fixture is empty`);
+	let value;
+	try {
+		value = JSON.parse(line);
+	} catch (error) {
+		throw new Error(`${label}: session header contains invalid JSON`, { cause: error });
+	}
+	if (value === null || typeof value !== "object" || Array.isArray(value) || value.type !== "session") throw new Error(`${label}: first record must be a Session header`);
+	const version = value.version;
+	if (!Number.isSafeInteger(version) || version < 0 || Object.is(version, -0)) throw new Error(`${label}: Session header version must be a non-negative safe integer`);
+	return version;
+}
+/**
+* Require one fixture's canonical filename generation to equal its header.
+*
+* @param name - Canonical fixture basename.
+* @param content - Complete UTF-8 JSONL content.
+* @returns The validated format generation.
+*/
+function assertSessionFixtureVersion(name, content) {
+	const fixture = parseSessionFixtureName(name);
+	if (fixture === void 0) throw new Error(`not a session fixture name: ${name}`);
+	const first = content.split(/\r?\n/u).find((candidate) => candidate.trim().length > 0);
+	if (first !== void 0) {
+		let projected;
+		try {
+			projected = JSON.parse(first);
+		} catch {
+			projected = void 0;
+		}
+		if (projected !== null && typeof projected === "object" && !Array.isArray(projected) && projected.type === "session" && !Object.hasOwn(projected, "version")) {
+			if (fixture.version !== 0) throw new Error(`${name}: a versionless projected Session header is format v0`);
+			return 0;
+		}
+	}
+	const headerVersion = sessionHeaderVersion(content, name);
+	if (headerVersion !== fixture.version) throw new Error(`${name}: filename declares Session format v${fixture.version}, header declares v${headerVersion}`);
+	return headerVersion;
+}
+/**
+* Return the canonical persistence basename for one generation and compression.
+*
+* @param version - Physical format generation; `0` is omitted.
+* @param compression - Backend compression mode.
+* @returns The canonical persistence basename.
+*/
+function persistedSessionFilename(version, compression = "raw") {
+	return `${sessionFormatLogFilename(version)}${compression === "zstd" ? ".zstd" : ""}`;
+}
+/**
+* Parse a canonical persistence basename from a Session's own directory.
+*
+* @param name - Candidate basename.
+* @returns Its generation and compression, or `undefined` for noise and noncanonical names.
+*/
+function parsePersistedSessionFilename(name) {
+	const compression = name.endsWith(".zstd") ? "zstd" : "raw";
+	const version = parseSessionFormatLogFilename(compression === "zstd" ? name.slice(0, -5) : name);
+	if (version === void 0) return void 0;
+	return {
+		version,
+		compression,
+		name
+	};
+}
+/**
+* Select one highest-generation persistence path per physical Session directory.
+*
+* @param paths - Relative or absolute paths beneath a sessions root.
+* @param compression - Compression selected by the snapshot composition.
+* @returns Stable path order with older generations and filesystem noise omitted.
+*/
+function latestPersistedSessionPaths(paths, compression = "raw") {
+	const selected = /* @__PURE__ */ new Map();
+	for (const path of paths) {
+		const parsed = parsePersistedSessionFilename(basename(path));
+		if (parsed === void 0 || parsed.compression !== compression) continue;
+		const directory = dirname(path);
+		const previous = selected.get(directory);
+		if (previous === void 0 || parsed.version > previous.version) selected.set(directory, {
+			path,
+			version: parsed.version
+		});
+	}
+	return [...selected.values()].map((entry) => entry.path).sort();
+}
+/**
+* Require one persistence basename's generation to equal its Session header.
+*
+* @param name - Canonical persistence basename.
+* @param content - Complete uncompressed UTF-8 JSONL content.
+* @returns The validated generation.
+*/
+function assertPersistedSessionVersion(name, content) {
+	const persisted = parsePersistedSessionFilename(name);
+	if (persisted === void 0) throw new Error(`not a canonical Session persistence filename: ${name}`);
+	const headerVersion = sessionHeaderVersion(content, name);
+	if (headerVersion !== persisted.version) throw new Error(`${name}: filename declares Session format v${persisted.version}, header declares v${headerVersion}`);
+	return headerVersion;
+}
+//#endregion
 //#region lib/types/workspace.js
 /** Capture readable, path-stable workspace state for recorded-session tests. */
 /** Marker that lets Git retain an expected empty directory without becoming expected workspace state. */
@@ -519,6 +707,7 @@ async function runScenario(input, opts) {
 		] });
 		const env = {
 			...opts.env,
+			...clearedProxyEnv(),
 			DSH_SNAPSHOT: opts.mode,
 			DSH_SNAPSHOT_FILE: opts.fixtureFile,
 			DSH_SNAPSHOT_SESSIONS_ROOT: sessionsRoot,
@@ -902,13 +1091,14 @@ function latestOpenTurn(content) {
 	return turn;
 }
 /**
-* Harvest EVERY persisted `.jsonl` session log under a sessions root, parse each
+* Harvest every latest-generation raw JSONL Session under a sessions root, parse each
 * header line, and return them ordered primary-first: the top-level session (no
 * `parentSession`) leads, then each subagent child by ascending `createdAt`.
 *
-* Snapshot configs select the JSONL backend's raw mode, which lays sessions
-* out as `<root>/<project>/<session-id>/session.jsonl`. Recursive collection
-* catches the primary and every child session. Returns `[]` if no log was
+* Snapshot configs select the JSONL backend's raw mode, which lays each immutable
+* generation beneath `<root>/<project>/<session-id>/`. Recursive collection
+* chooses the numerically highest generation for the primary and every child.
+* Returns `[]` if no log was
 * produced (a no-session scenario).
 */
 async function harvestSessionLogs(root) {
@@ -919,9 +1109,10 @@ async function harvestSessionLogs(root) {
 		return [];
 	}
 	const logs = [];
-	for (const file of files) {
-		if (basename(file) !== "session.jsonl") continue;
+	for (const file of latestPersistedSessionPaths(files)) {
 		const content = await readFile(join(root, file), "utf8");
+		assertPersistedSessionVersion(basename(file), content);
+		/* v8 ignore next -- the generation validator above rejects header-less content. */
 		const firstLine = content.split("\n").find((line) => line.trim().length > 0) ?? "{}";
 		const header = JSON.parse(firstLine);
 		logs.push({
@@ -978,8 +1169,8 @@ const PATH_TEXT_BOUNDARY_RE = /[\s<>'"`()\[\]{},;:!?=]/;
 const FILE_URI_PATH_PREFIX_RE = /(?:^|[^a-z0-9+.-])file:\/\/\/?$/i;
 /** A UUID v4 string, the shape `randomUUID()` produces for session ids. */
 const UUID_RE$1 = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi;
-const LOCAL_SPILL_PATH_RE = new RegExp(String.raw`\{\{cwd\}\}[\\/]\.spill[\\/]session-[0-9a-f]{12}[\\/][0-9a-f]{12}-([A-Za-z0-9._~-]+?)` + String.raw`(?=\. Use read with offset/limit|[\s)]|$)`, "g");
-const SNAPSHOT_SPILL_PATH_RE = new RegExp(String.raw`(?:[A-Za-z]:)?[\\/](?:tmp|t)[\\/](?:dsh-acp-snap-[0-9a-f]{9}|dsh-acp-snapshot-spill)[\\/]session-[0-9a-f]{12}[\\/][0-9a-f]{12}-([A-Za-z0-9._~-]+?)` + String.raw`(?=\. Use read with offset/limit|[\s)]|$)`, "g");
+const LOCAL_SPILL_PATH_RE = new RegExp(String.raw`\{\{cwd\}\}[\\/]+\.spill[\\/]+session-[0-9a-f]{12}[\\/]+[0-9a-f]{12}-([A-Za-z0-9._~-]+?)` + String.raw`(?=\. Use read with offset/limit|[\s)"]|\\+"|$)`, "g");
+const SNAPSHOT_SPILL_PATH_RE = new RegExp(String.raw`(?:[A-Za-z]:)?[\\/]+(?:tmp|t)[\\/]+(?:dsh-acp-snap-[0-9a-f]{9}|dsh-acp-snapshot-spill)[\\/]+session-[0-9a-f]{12}[\\/]+[0-9a-f]{12}-([A-Za-z0-9._~-]+?)` + String.raw`(?=\. Use read with offset/limit|[\s)"]|\\+"|$)`, "g");
 /**
 * Extract every snapshot-mode spill path from a session log, keyed by spill
 * filename. Used by refresh write-back to keep spill paths stable across runs.
@@ -1151,9 +1342,9 @@ function normalizeStdout(rawStdout, ctx, options = {}) {
 }
 /**
 * Normalize a session JSONL log into a stable expected output: the header line's
-* volatile fields (`createdAt`, `id`, `cwd`) are zeroed/scrubbed, ordinary
-* event `time`, packed-row `time0`, and goal-change lifecycle clock values are
-* zeroed, and all volatile strings are scrubbed. Projected inputs remain
+* volatile fields (`createdAt`, `id`, `cwd`) are zeroed/scrubbed; event,
+* historical packed-row, embedded Assistant-stream, and goal lifecycle clocks
+* are zeroed; and all volatile strings are scrubbed. Projected inputs remain
 * projected. Packed `data.dt` gaps are normalized even when the projected row
 * omits its `time0` anchor.
 * Output is JSONL in the same shape as the input — one compact record per
@@ -1176,10 +1367,21 @@ function normalizeSessionLog(rawLog, ctx, options = {}) {
 			const data = record.data;
 			if (data !== null && typeof data === "object" && Array.isArray(data.dt)) data.dt = data.dt.map(() => 0);
 		} else if ("time" in record) record.time = 0;
+		if ((record.type === "assistant/message" || record.type === "assistant/attempt") && record.data !== null && typeof record.data === "object") {
+			const stream = record.data.stream;
+			if (Array.isArray(stream)) for (const member of stream) {
+				if (member === null || typeof member !== "object") continue;
+				const timed = member;
+				if (typeof timed.time === "number") timed.time = 0;
+				if (typeof timed.time0 === "number") timed.time0 = 0;
+				if (Array.isArray(timed.dt)) timed.dt = timed.dt.map(() => 0);
+			}
+		}
 		if (record.type === "hook/result" && record.data !== null && typeof record.data === "object") {
 			const data = record.data;
 			if ("durationMs" in data) data.durationMs = 0;
 		}
+		normalizeFeedbackClocks(record);
 		if (record.type === "goal/change" && record.data !== null && typeof record.data === "object") {
 			const data = record.data;
 			if ("createdAt" in data) data.createdAt = 0;
@@ -1190,36 +1392,15 @@ function normalizeSessionLog(rawLog, ctx, options = {}) {
 	}).map((r) => JSON.stringify(r)).join("\n") + "\n";
 }
 /**
-* Repack projected body records so persistence flush boundaries do not affect
-* committed snapshots. Synthetic envelopes exist only while the storage codec
-* reconstructs and packs the logical event stream; returned rows stay projected.
+* Canonicalize projected v2 body records. Compact streams are nested event data,
+* so persistence flush boundaries cannot change the row layout.
 */
-function repackSessionSnapshot(rawLog) {
+function projectSessionSnapshot(rawLog) {
 	const lines = rawLog.split("\n").filter((line) => line.trim().length > 0);
-	const header = lines.shift();
-	let nextSeq = SessionLogOffset(0);
 	return [
-		header,
-		...packChunkRuns(lines.flatMap((line) => {
-			const record = JSON.parse(line);
-			if (isPackedFixtureRow(record)) {
-				const decoded = decodeStorageRecord({
-					...record,
-					seq0: nextSeq,
-					time0: 0
-				});
-				nextSeq = SessionLogOffset(nextSeq + decoded.length);
-				return decoded;
-			}
-			const event = {
-				...record,
-				seq: SessionSeq(nextSeq),
-				time: 0
-			};
-			nextSeq = SessionLogOffset(nextSeq + 1);
-			return [event];
-		})).map((stored) => {
-			const projected = { ...stored };
+		lines.shift(),
+		...lines.map((line) => {
+			const projected = { ...JSON.parse(line) };
 			omitFixtureEnvelope(projected);
 			return JSON.stringify(projected);
 		}),
@@ -1229,8 +1410,8 @@ function repackSessionSnapshot(rawLog) {
 /**
 * Normalize and project persisted session JSONL for a committed fixture.
 * This composes ordinary log normalization with request-header scrubbing and
-* persistence-envelope projection, then packs the logical event stream into a
-* canonical layout independent of persistence flush boundaries.
+* persistence-envelope projection, then writes the v2 logical event stream as
+* one record per event, independent of persistence flush boundaries.
 *
 * @param rawLog - persisted or already-projected session JSONL.
 * @param ctx - the run's volatile values to scrub.
@@ -1238,7 +1419,7 @@ function repackSessionSnapshot(rawLog) {
 * @returns normalized committed session snapshot JSONL.
 */
 function normalizeSessionSnapshot(rawLog, ctx, options = {}) {
-	return repackSessionSnapshot(scrubSessionSnapshot(normalizeSessionLog(rawLog, ctx, options)));
+	return projectSessionSnapshot(scrubSessionSnapshot(normalizeSessionLog(rawLog, ctx, options)));
 }
 /**
 * Normalize one scenario's primary and child logs with shared typed identity redaction.
@@ -1248,7 +1429,7 @@ function normalizeSessionSnapshot(rawLog, ctx, options = {}) {
 * @returns normalized session fixtures in input order.
 */
 function normalizeSessionSnapshots(rawLogs, ctx, options = {}) {
-	return redactSessionSnapshotIds(rawLogs).map((log) => repackSessionSnapshot(scrubSessionSnapshot(normalizeSessionLog(log, {
+	return redactSessionSnapshotIds(rawLogs.map((log) => hasSessionFormatVersion(log) ? prepareSessionSnapshotFixtureForComparison(log) : log).map(normalizeSessionFormatProvenance)).map((log) => projectSessionSnapshot(scrubSessionSnapshot(normalizeSessionLog(log, {
 		...ctx,
 		sessionIds: []
 	}, {
@@ -1257,6 +1438,60 @@ function normalizeSessionSnapshots(rawLogs, ctx, options = {}) {
 	}))));
 }
 /**
+* Omit only generation-qualified operational provenance from expected-output comparison.
+* @param rawLog - Session records or events as compact JSON lines.
+* @returns the same records without delivery or captured-source generation qualifiers.
+*/
+function normalizeSessionFormatProvenance(rawLog) {
+	return rawLog.split("\n").map((line) => {
+		if (line.trim().length === 0) return line;
+		const record = JSON.parse(line);
+		let changed = normalizeCapturedFormatProvenance(record);
+		if (record.type === "session" && Object.hasOwn(record, "version")) {
+			delete record.version;
+			changed = true;
+		}
+		if (record.type === "session-log-deepseek/delivery-accepted" && record.data !== null && typeof record.data === "object" && !Array.isArray(record.data)) {
+			const data = { ...record.data };
+			if (Object.hasOwn(data, "sessionFormatVersion")) {
+				delete data.sessionFormatVersion;
+				record.data = data;
+				changed = true;
+			}
+		}
+		return changed ? JSON.stringify(record) : line;
+	}).join("\n");
+}
+/** Omit captured generations only from an actual current Message source position. */
+function normalizeCapturedFormatProvenance(event) {
+	if (event.data === null || typeof event.data !== "object" || Array.isArray(event.data)) return false;
+	const data = event.data;
+	const message = event.type === "user/message" ? data : event.type === "assistant/message" || event.type === "tool/result" ? data.message : void 0;
+	if (message === null || typeof message !== "object" || Array.isArray(message)) return false;
+	const source = message.source;
+	if (source === null || typeof source !== "object" || Array.isArray(source)) return false;
+	const record = source;
+	if (record.kind !== "session-reference" || record.form !== "recall" || record.version !== 1 || !Array.isArray(record.references)) return false;
+	let changed = false;
+	for (const reference of record.references) {
+		if (reference === null || typeof reference !== "object" || Array.isArray(reference)) continue;
+		const captured = reference;
+		if (Object.hasOwn(captured, "capturedFormatVersion")) {
+			delete captured.capturedFormatVersion;
+			changed = true;
+		}
+	}
+	return changed;
+}
+/** Whether a fixture declares a released Session format and therefore participates in migration burn-in. */
+function hasSessionFormatVersion(rawLog) {
+	const firstLine = rawLog.split(/\r?\n/).find((line) => line.trim().length > 0);
+	if (firstLine === void 0) throw new Error("session snapshot must start with a session header");
+	const header = JSON.parse(firstLine);
+	if (header === null || typeof header !== "object" || Array.isArray(header) || header["type"] !== "session") throw new Error("session snapshot must start with a session header");
+	return Object.hasOwn(header, "version");
+}
+/**
 * Replace system-prompt content in request headers with `{{system}}` tokens
 * while retaining field presence.
 * Other header content stays verbatim, so a header-pinning fixture can keep
@@ -1320,9 +1555,19 @@ function scrubSessionSnapshot(rawLog) {
 			return line;
 		}
 		omitFixtureEnvelope(record);
+		normalizeFeedbackClocks(record);
 		return JSON.stringify(record);
 	}).join("\n");
 }
+/** Normalize service-owned feedback clocks without touching user-authored payloads. */
+function normalizeFeedbackClocks(record) {
+	if (record.type !== "feedback/message-put" || record.data === null || typeof record.data !== "object") return;
+	const item = record.data.item;
+	if (item === null || typeof item !== "object") return;
+	const clocks = item;
+	if ("createdAt" in clocks) clocks.createdAt = 0;
+	if ("updatedAt" in clocks) clocks.updatedAt = 0;
+}
 /** Transform the selected request-header payloads. */
 function scrubHeaderContent(rawLog, options) {
 	return rawLog.split("\n").map((line) => {
@@ -1350,6 +1595,18 @@ function scrubHeaderContent(rawLog, options) {
 //#endregion
 //#region lib/types/manifest.js
 /** Parse and validate one recorded-session snapshot manifest. */
+/**
+* Whether one run writes current-writer Session fixtures for this scenario.
+* Explicit historical generations remain immutable replay inputs; record and
+* refresh may still update their non-Session expected outputs.
+*
+* @param manifest - Parsed scenario ownership and retained-generation metadata.
+* @param mode - Snapshot execution mode.
+* @returns True only when a write-capable mode tracks the current writer.
+*/
+function writesCurrentSessionFixtures(manifest, mode) {
+	return mode !== "replay" && manifest.session === void 0 && manifest.sessionFormat === void 0;
+}
 const PROFILES = new Set([
 	"headless",
 	"sdk",
@@ -1363,6 +1620,13 @@ const PERMISSIONS = new Set([
 	"workspace-write",
 	"danger-full-access"
 ]);
+const SESSION_FORMAT_COVERAGE = new Set([
+	"multi-hop",
+	"packed-row",
+	"retry-failure",
+	"shipped-profile",
+	"adjacent-migration"
+]);
 const NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 function record(value, label) {
 	if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be a mapping`);
@@ -1412,7 +1676,8 @@ function parseSnapshotManifest(source, path = "snapshot.yml") {
 			"environment",
 			"workspace",
 			"input",
-			"session"
+			"session",
+			"sessionFormat"
 		], "manifest");
 		if (root.version !== 1) throw new Error("manifest.version must equal 1");
 		const scenario = root.scenario === void 0 ? void 0 : name(root.scenario, "manifest.scenario");
@@ -1527,6 +1792,18 @@ function parseSnapshotManifest(source, path = "snapshot.yml") {
 			if (isAbsolute(value.source) || value.source.includes("\\") || value.source.includes("\0")) throw new Error("manifest.session.source must be a relative POSIX path");
 			session = { source: value.source };
 		}
+		let sessionFormat;
+		if (root.sessionFormat !== void 0) {
+			const value = record(root.sessionFormat, "manifest.sessionFormat");
+			exactKeys(value, ["version", "coverage"], "manifest.sessionFormat");
+			if (!Number.isSafeInteger(value.version) || Number(value.version) < 0 || Object.is(value.version, -0)) throw new Error("manifest.sessionFormat.version must be a non-negative safe integer");
+			if (!Array.isArray(value.coverage) || value.coverage.length === 0 || value.coverage.some((item) => typeof item !== "string" || !SESSION_FORMAT_COVERAGE.has(item)) || new Set(value.coverage).size !== value.coverage.length) throw new Error("manifest.sessionFormat.coverage must be a non-empty array of unique supported coverage names");
+			if (session !== void 0) throw new Error("manifest.sessionFormat is only valid when the scenario owns its Session fixtures");
+			sessionFormat = {
+				version: Number(value.version),
+				coverage: [...value.coverage]
+			};
+		}
 		return {
 			version: 1,
 			...scenario === void 0 ? {} : { scenario },
@@ -1540,7 +1817,8 @@ function parseSnapshotManifest(source, path = "snapshot.yml") {
 			...environment === void 0 ? {} : { environment },
 			...workspace === void 0 ? {} : { workspace },
 			...input === void 0 ? {} : { input },
-			...session === void 0 ? {} : { session }
+			...session === void 0 ? {} : { session },
+			...sessionFormat === void 0 ? {} : { sessionFormat }
 		};
 	} catch (error) {
 		/* v8 ignore next -- every parser and validator above throws Error instances. */
@@ -1592,9 +1870,10 @@ const PACKED_CHUNK_ROW_TYPES = new Set([
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 /**
 * Whether a scenario's run test is skipped for this mode and host: record mode
-* skips authored (non-`recorded`) scenarios, {@link Scenario.posixOnly}
-* scenarios skip on Windows, and {@link Scenario.pwshOnly} scenarios skip
-* when the caller's `hasPwsh` probe is false.
+* skips authored (non-`recorded`) scenarios and explicit historical Session
+* generations, {@link Scenario.posixOnly} scenarios skip on Windows, and
+* {@link Scenario.pwshOnly} scenarios skip when the caller's `hasPwsh` probe
+* is false.
 *
 * @param scenario The scenario whose run test is being registered.
 * @param recording Whether the suite runs in record mode.
@@ -1604,7 +1883,7 @@ const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
 * @returns True when the scenario's run test must not execute.
 */
 function scenarioSkipped(scenario, recording, platform = process.platform, hasPwsh) {
-	if (recording && !scenario.recorded) return true;
+	if (recording && (!scenario.recorded || scenario.sessionFormat !== void 0)) return true;
 	if (scenario.posixOnly === true && platform === "win32") return true;
 	return scenario.pwshOnly === true && hasPwsh !== true;
 }
@@ -1660,47 +1939,20 @@ function assertUniqueSnapshotContents(kind, snapshots) {
 		firstPathByContent.set(snapshot.content, snapshot.path);
 	}
 }
-/**
-* Validate and order a scenario directory's session-fixture filenames.
-*
-* The primary fixture is always `session.jsonl`; child sessions are discovered
-* from contiguous `session.1.jsonl` … filenames. The directory is the source of
-* truth, so scenario tables do not duplicate a child count that can drift from
-* the files. A session-like JSONL with any other suffix fails loud.
-*
-* @param names File names in one scenario directory.
-* @returns The primary and child fixture names in replay/harvest order.
-*/
-function sessionFixtureNames(names) {
-	if (!names.includes("session.jsonl")) throw new Error("missing session.jsonl");
-	const children = [];
-	for (const name of names) {
-		if (name === "session.jsonl") continue;
-		if (!name.startsWith("session.") || !name.endsWith(".jsonl")) continue;
-		const match = /^session\.([1-9]\d*)\.jsonl$/.exec(name);
-		if (match === null) throw new Error(`invalid child session fixture name: ${name}`);
-		children.push({
-			name,
-			index: Number(match[1])
-		});
-	}
-	children.sort((a, b) => a.index - b.index);
-	for (const [offset, child] of children.entries()) {
-		const expected = offset + 1;
-		if (child.index !== expected) throw new Error(`child session fixtures must be contiguous: expected session.${expected}.jsonl, found ${child.name}`);
-	}
-	return ["session.jsonl", ...children.map((child) => child.name)];
-}
 /** Read one scenario directory's validated session-fixture inventory. */
 async function sessionFixtures(dir) {
-	return sessionFixtureNames((await readdir(dir, { withFileTypes: true })).filter((entry) => entry.isFile()).map((entry) => entry.name));
+	const names = sessionFixtureNames((await readdir(dir, { withFileTypes: true })).filter((entry) => entry.isFile()).map((entry) => entry.name));
+	await Promise.all(names.map(async (name) => {
+		assertSessionFixtureVersion(name, await readFile(join(dir, name), "utf8"));
+	}));
+	return names;
 }
 /**
 * Derive normalization values from a fixture's own session header. Recorded ids and cwd differ
 * from the live replay run; the non-empty sentinel for missing cwd avoids accidental empty-
 * string replacement.
 *
-* @param fixture The committed `session.jsonl` content.
+* @param fixture The selected committed parent Session fixture content.
 * @returns The fixture's own volatile values, ready for {@link normalizeSessionLog}.
 */
 function fixtureContext(fixture) {
@@ -2271,11 +2523,12 @@ function defineAcpSnapshotSuite(options) {
 			const workspaceDir = join(dir, "workspace");
 			let fixtureFiles = RECORDING ? [] : await sessionFixtures(dir);
 			const childFixtureFiles = fixtureFiles.slice(1);
+			const primaryFixtureFile = fixtureFiles[0] ?? sessionFixtureName(0, 0);
 			const comparesLog = scenario.comparesLog ?? scenario.hasModelTurn;
 			const result = await runScenario(input, {
 				agent,
 				mode: childMode,
-				fixtureFile: join(dir, "session.jsonl"),
+				fixtureFile: join(dir, primaryFixtureFile),
 				...scenario.env !== void 0 ? { env: scenario.env } : {},
 				...existsSync(overrideFile) ? { overrideFile } : {},
 				...!RECORDING && childFixtureFiles.length > 0 ? { childFiles: childFixtureFiles.map((file) => join(dir, file)) } : {},
@@ -2293,23 +2546,19 @@ function defineAcpSnapshotSuite(options) {
 			const childSchemaPins = new Set(scenario.pinsChildToolSchemas ?? []);
 			const childPromptPins = new Set(scenario.pinsChildSystemPrompts ?? []);
 			const portableFixture = scenario.workspaceParent === void 0 ? tokenizeSessionFixtureCwd : (log) => log;
-			if (RECORDING && scenario.recorded && scenario.hasModelTurn || REFRESHING && comparesLog) {
+			if (writesCurrentSessionFixtures(manifest, mode) && (RECORDING && scenario.recorded && scenario.hasModelTurn || REFRESHING && comparesLog)) {
 				expect(result.sessionLogs.length, `${mode} produced no session log to harvest`).toBeGreaterThan(0);
 				if (REFRESHING) expect(result.sessionLogs.length, `expected ${fixtureFiles.length} session logs (parent + children)`).toBe(fixtureFiles.length);
-				const outputFixtureFiles = ["session.jsonl", ...Array.from({ length: result.sessionLogs.length - 1 }, (_, i) => `session.${i + 1}.jsonl`)];
-				const existingFixtures = await Promise.all(outputFixtureFiles.map(async (file) => {
-					const path = join(dir, file);
-					return existsSync(path) ? readFile(path, "utf8") : "";
+				const outputFixtureFiles = result.sessionLogs.map((log, index) => sessionFixtureName(index, sessionHeaderVersion(log.content, `harvested Session ${index}`)));
+				const existingFixtures = await Promise.all(outputFixtureFiles.map(async (_file, index) => {
+					const file = fixtureFiles[index];
+					if (file === void 0) return "";
+					return readFile(join(dir, file), "utf8");
 				}));
 				const refreshReplacements = REFRESHING ? refreshFixtureReplacements(result.sessionLogs, existingFixtures) : [];
 				const outputFixtures = redactSessionSnapshotIds(stabilizeFixtureMessageIds(REFRESHING ? result.sessionLogs.map((log, index) => scrubSessionSnapshot(portableFixture(stabilizeRefreshLog(log.content, existingFixtures[index], refreshReplacements, ctx)))) : result.sessionLogs.map((log) => scrubSessionSnapshot(portableFixture(log.content))), existingFixtures));
 				await Promise.all(outputFixtures.map((fixture, index) => writeFile(join(dir, outputFixtureFiles[index]), fixture)));
-				if (RECORDING) {
-					const outputNames = new Set(outputFixtureFiles);
-					const entries = await readdir(dir, { withFileTypes: true });
-					await Promise.all(entries.filter((entry) => entry.isFile() && /^session\.[1-9]\d*\.jsonl$/.test(entry.name) && !outputNames.has(entry.name)).map((entry) => rm(join(dir, entry.name))));
-					fixtureFiles = outputFixtureFiles;
-				}
+				fixtureFiles = outputFixtureFiles;
 				if (scenario.pinsHeader === true) {
 					const primary = result.sessionLogs[0];
 					const pinningHeaders = pinningHeaderPayloads(primary.content, ctx);
@@ -2366,7 +2615,9 @@ function defineAcpSnapshotSuite(options) {
 			const promptSource = promptSourceByClass.get(classOf(scenario)) ?? pinningScenario;
 			/* v8 ignore next -- registration guarantees every scenario class has resolved sources. */
 			const schemaSource = schemaSourceByClass.get(classOf(scenario)) ?? pinningScenario;
-			const pinnedFixture = await readFile(join(join(snapshotsDir, pinningScenario.name), "session.jsonl"), "utf8");
+			const pinningDir = join(snapshotsDir, pinningScenario.name);
+			const [pinningFixtureFile] = await sessionFixtures(pinningDir);
+			const pinnedFixture = await readFile(join(pinningDir, pinningFixtureFile), "utf8");
 			const pinned = pinningHeaderPayloads(pinnedFixture, fixtureContext(pinnedFixture));
 			const promptSnapshot = await readFile(join(snapshotsDir, promptSource.name, SYSTEM_PROMPT_SNAPSHOT), "utf8");
 			const initialPromptSnapshot = initialSystemPromptSnapshot(promptSnapshot);
@@ -2444,7 +2695,6 @@ function defineAcpSnapshotSuite(options) {
 				expect(existsSync(join(dir, "input.json")), `${name}/input.json`).toBe(true);
 				expect(existsSync(join(dir, "stdout.expected.jsonl")), `${name}/stdout.expected.jsonl`).toBe(true);
 				expect(existsSync(join(dir, WINDOWS_STDOUT_SNAPSHOT)), `${name}/${WINDOWS_STDOUT_SNAPSHOT} presence must match \`pinsNativeWindowsStdout\``).toBe(pinsNativeWindowsStdout === true);
-				expect(existsSync(join(dir, "session.jsonl")), `${name}/session.jsonl`).toBe(true);
 				expect(existsSync(join(dir, "replay.override.json")), `${name}/replay.override.json presence must match \`overridden\``).toBe(overridden === true);
 				expect(existsSync(join(dir, SYSTEM_PROMPT_SNAPSHOT)), `${name}/${SYSTEM_PROMPT_SNAPSHOT} presence must match snapshot-source ownership`).toBe(promptOwners.has(name));
 				expect(existsSync(join(dir, TOOL_SCHEMAS_SNAPSHOT)), `${name}/${TOOL_SCHEMAS_SNAPSHOT} presence must match snapshot-source ownership`).toBe(schemaOwners.has(name));
@@ -2466,7 +2716,9 @@ function defineAcpSnapshotSuite(options) {
 				const promptSource = promptSourceByClass.get(classOf(scenario)) ?? scenario;
 				/* v8 ignore next -- registration guarantees every pin has resolved sources. */
 				const schemaSource = schemaSourceByClass.get(classOf(scenario)) ?? scenario;
-				const fixture = await readFile(join(snapshotsDir, scenario.name, "session.jsonl"), "utf8");
+				const fixtureDir = join(snapshotsDir, scenario.name);
+				const [fixtureFile] = await sessionFixtures(fixtureDir);
+				const fixture = await readFile(join(fixtureDir, fixtureFile), "utf8");
 				const headers = pinningHeaderPayloads(fixture, fixtureContext(fixture));
 				const promptSnapshot = await readFile(join(snapshotsDir, promptSource.name, SYSTEM_PROMPT_SNAPSHOT), "utf8");
 				expect(headers.length, `${scenario.name}: unexpected request/header count`).toBe(1 + (scenario.expectedHeaderChanges ?? 0));
@@ -2531,4 +2783,4 @@ function defineAcpSnapshotSuite(options) {
 	});
 }
 //#endregion
-export { EMPTY_WORKSPACE_MARKER, captureExpectedWorkspaceSnapshot, captureWorkspaceSnapshot, defineAcpSnapshotSuite, extractSnapshotSpillPaths, fixtureContext, formatSystemPromptSnapshot, formatToolSchemasSnapshot, headerChangeCount, launchAcpTestAgent, materializeProfilePatch, normalizeSessionLog, normalizeSessionSnapshot, normalizeSessionSnapshots, normalizeStdout, normalizedHeaders, normalizedSystemPrompts, normalizedToolSchemas, parseSnapshotManifest, parseToolSchemasSnapshot, redactSessionSnapshotIds, refreshFixtureReplacements, restorePinnedToolSchemas, runScenario, scrubRequestHeaders, scrubSessionSnapshot, scrubSystemPrompts, scrubToolSchemas, sessionFixtureNames, snapshotSpillRoot, stabilizeFixtureMessageIds, stabilizeRefreshLog, tokenizeSessionFixtureCwd };
+export { EMPTY_WORKSPACE_MARKER, assertPersistedSessionVersion, assertSessionFixtureVersion, captureExpectedWorkspaceSnapshot, captureWorkspaceSnapshot, defineAcpSnapshotSuite, extractSnapshotSpillPaths, fixtureContext, formatSystemPromptSnapshot, formatToolSchemasSnapshot, headerChangeCount, latestPersistedSessionPaths, launchAcpTestAgent, materializeProfilePatch, normalizeSessionFormatProvenance, normalizeSessionLog, normalizeSessionSnapshot, normalizeSessionSnapshots, normalizeStdout, normalizedHeaders, normalizedSystemPrompts, normalizedToolSchemas, parsePersistedSessionFilename, parseSessionFixtureName, parseSnapshotManifest, parseToolSchemasSnapshot, persistedSessionFilename, redactSessionSnapshotIds, refreshFixtureReplacements, restorePinnedToolSchemas, runScenario, scrubRequestHeaders, scrubSessionSnapshot, scrubSystemPrompts, scrubToolSchemas, sessionFixtureFiles, sessionFixtureName, sessionFixtureNames, sessionHeaderVersion, snapshotSpillRoot, stabilizeFixtureMessageIds, stabilizeRefreshLog, tokenizeSessionFixtureCwd, writesCurrentSessionFixtures };

package/lib/types/index.d.ts

@@ -19,8 +19,9 @@
 export { redactSessionSnapshotIds, } from './identity.ts';
 export { runScenario, snapshotSpillRoot, type HarvestedLog, type InputScript, type InputStep, type PermissionAnswer, type RunOptions, type RunResult, } from './harness.ts';
 export { launchAcpTestAgent, materializeProfilePatch, type AcpTestLaunchOptions, type AgentUnderTest, type LaunchedAcpTestAgent, } from './launcher.ts';
-export { extractSnapshotSpillPaths, normalizeSessionLog, normalizeSessionSnapshot, normalizeSessionSnapshots, normalizeStdout, scrubRequestHeaders, scrubSessionSnapshot, scrubSystemPrompts, scrubToolSchemas, tokenizeSessionFixtureCwd, type CwdPathMode, type NormalizeContext, type NormalizeOptions, } from './normalize.ts';
-export { parseSnapshotManifest, type SnapshotHeaderManifest, type SnapshotInputAttachment, type SnapshotInputManifest, type SnapshotManifest, type SnapshotPermission, type SnapshotPlatform, type SnapshotProfile, type SnapshotRecording, type SnapshotReplayManifest, type SnapshotSessionReference, type SnapshotWorkspaceManifest, } from './manifest.ts';
-export { formatSystemPromptSnapshot, formatToolSchemasSnapshot, fixtureContext, headerChangeCount, defineAcpSnapshotSuite, normalizedHeaders, normalizedSystemPrompts, normalizedToolSchemas, parseToolSchemasSnapshot, refreshFixtureReplacements, restorePinnedToolSchemas, sessionFixtureNames, stabilizeFixtureMessageIds, stabilizeRefreshLog, type Scenario, type SnapshotSuiteOptions, } from './suite.ts';
+export { extractSnapshotSpillPaths, normalizeSessionFormatProvenance, normalizeSessionLog, normalizeSessionSnapshot, normalizeSessionSnapshots, normalizeStdout, scrubRequestHeaders, scrubSessionSnapshot, scrubSystemPrompts, scrubToolSchemas, tokenizeSessionFixtureCwd, type CwdPathMode, type NormalizeContext, type NormalizeOptions, } from './normalize.ts';
+export { parseSnapshotManifest, writesCurrentSessionFixtures, type SnapshotHeaderManifest, type SnapshotInputAttachment, type SnapshotInputManifest, type SnapshotManifest, type SnapshotPermission, type SnapshotPlatform, type SnapshotProfile, type SnapshotRecording, type SnapshotReplayManifest, type SnapshotSessionReference, type SnapshotSessionFormatCoverage, type SnapshotSessionFormatManifest, type SnapshotSessionWriteMode, type SnapshotWorkspaceManifest, } from './manifest.ts';
+export { assertPersistedSessionVersion, assertSessionFixtureVersion, latestPersistedSessionPaths, parsePersistedSessionFilename, parseSessionFixtureName, persistedSessionFilename, sessionFixtureFiles, sessionFixtureName, sessionFixtureNames, sessionHeaderVersion, type PersistedSessionFile, type SessionFixtureFile, } from './session-files.ts';
+export { formatSystemPromptSnapshot, formatToolSchemasSnapshot, fixtureContext, headerChangeCount, defineAcpSnapshotSuite, normalizedHeaders, normalizedSystemPrompts, normalizedToolSchemas, parseToolSchemasSnapshot, refreshFixtureReplacements, restorePinnedToolSchemas, stabilizeFixtureMessageIds, stabilizeRefreshLog, type Scenario, type SnapshotSuiteOptions, } from './suite.ts';
 export { captureExpectedWorkspaceSnapshot, captureWorkspaceSnapshot, EMPTY_WORKSPACE_MARKER, type CaptureWorkspaceSnapshotOptions, type WorkspaceBinaryFileSnapshot, type WorkspaceEmptyDirectorySnapshot, type WorkspaceSnapshotEntry, type WorkspaceSymlinkSnapshot, type WorkspaceTextFileSnapshot, } from './workspace.ts';
 //# sourceMappingURL=index.d.ts.map

package/lib/types/manifest.d.ts

@@ -56,9 +56,18 @@ export interface SnapshotInputManifest {
 }
 /** Optional reference to another scenario's canonical session. */
 export interface SnapshotSessionReference {
-    /** Repository-relative POSIX path from this scenario directory to the owning `session.jsonl`. */
+    /** Repository-relative POSIX path to the owning scenario's selected parent Session fixture. */
     source: string;
 }
+/** Historical-format behavior one retained scenario permanently exercises. */
+export type SnapshotSessionFormatCoverage = 'multi-hop' | 'packed-row' | 'retry-failure' | 'shipped-profile' | 'adjacent-migration';
+/** Explicit historical generation retained by an owning scenario. */
+export interface SnapshotSessionFormatManifest {
+    /** Selected fixture generation; absent manifest metadata tracks the current writer. */
+    readonly version: number;
+    /** Migration behaviors that require this historical fixture. */
+    readonly coverage: readonly SnapshotSessionFormatCoverage[];
+}
 /** Declarative ownership metadata stored beside a recorded session. */
 export interface SnapshotManifest {
     /** Manifest format version. */
@@ -85,9 +94,23 @@ export interface SnapshotManifest {
     workspace?: SnapshotWorkspaceManifest;
     /** Exceptional controller input absent for ordinary log-driven scenarios. */
     input?: SnapshotInputManifest;
-    /** Absent when this directory owns `session.jsonl`; present for a read-only borrower. */
+    /** Absent when this directory owns its selected parent fixture; present for a read-only borrower. */
     session?: SnapshotSessionReference;
+    /** Historical generation retained by an owner instead of tracking the current writer. */
+    sessionFormat?: SnapshotSessionFormatManifest;
 }
+/** Snapshot execution modes that may read or replace committed fixture generations. */
+export type SnapshotSessionWriteMode = 'replay' | 'record' | 'refresh';
+/**
+ * Whether one run writes current-writer Session fixtures for this scenario.
+ * Explicit historical generations remain immutable replay inputs; record and
+ * refresh may still update their non-Session expected outputs.
+ *
+ * @param manifest - Parsed scenario ownership and retained-generation metadata.
+ * @param mode - Snapshot execution mode.
+ * @returns True only when a write-capable mode tracks the current writer.
+ */
+export declare function writesCurrentSessionFixtures(manifest: SnapshotManifest, mode: SnapshotSessionWriteMode): boolean;
 /**
  * Parse one `snapshot.yml` without admitting JavaScript YAML tags or unknown fields.
  * @param source - complete manifest text.

package/lib/types/normalize.d.ts

@@ -55,9 +55,9 @@ export declare function tokenizeSessionFixtureCwd(rawLog: string): string;
 export declare function normalizeStdout(rawStdout: string, ctx: NormalizeContext, options?: NormalizeOptions): string;
 /**
  * Normalize a session JSONL log into a stable expected output: the header line's
- * volatile fields (`createdAt`, `id`, `cwd`) are zeroed/scrubbed, ordinary
- * event `time`, packed-row `time0`, and goal-change lifecycle clock values are
- * zeroed, and all volatile strings are scrubbed. Projected inputs remain
+ * volatile fields (`createdAt`, `id`, `cwd`) are zeroed/scrubbed; event,
+ * historical packed-row, embedded Assistant-stream, and goal lifecycle clocks
+ * are zeroed; and all volatile strings are scrubbed. Projected inputs remain
  * projected. Packed `data.dt` gaps are normalized even when the projected row
  * omits its `time0` anchor.
  * Output is JSONL in the same shape as the input — one compact record per
@@ -72,8 +72,8 @@ export declare function normalizeSessionLog(rawLog: string, ctx: NormalizeContex
 /**
  * Normalize and project persisted session JSONL for a committed fixture.
  * This composes ordinary log normalization with request-header scrubbing and
- * persistence-envelope projection, then packs the logical event stream into a
- * canonical layout independent of persistence flush boundaries.
+ * persistence-envelope projection, then writes the v2 logical event stream as
+ * one record per event, independent of persistence flush boundaries.
  *
  * @param rawLog - persisted or already-projected session JSONL.
  * @param ctx - the run's volatile values to scrub.
@@ -89,6 +89,12 @@ export declare function normalizeSessionSnapshot(rawLog: string, ctx: NormalizeC
  * @returns normalized session fixtures in input order.
  */
 export declare function normalizeSessionSnapshots(rawLogs: readonly string[], ctx: NormalizeContext, options?: Omit<NormalizeOptions, 'identityMode'>): string[];
+/**
+ * Omit only generation-qualified operational provenance from expected-output comparison.
+ * @param rawLog - Session records or events as compact JSON lines.
+ * @returns the same records without delivery or captured-source generation qualifiers.
+ */
+export declare function normalizeSessionFormatProvenance(rawLog: string): string;
 /**
  * Replace system-prompt content in request headers with `{{system}}` tokens
  * while retaining field presence.

package/lib/types/session-files.d.ts

@@ -0,0 +1,97 @@
+/** Immutable Session-generation filenames used by recorded-session fixtures. */
+/** One canonical recorded-session fixture filename. */
+export interface SessionFixtureFile {
+    /** Parent is `0`; positive values are child/ordinal slots. */
+    readonly index: number;
+    /** Physical Session format generation; zero is encoded by omission. */
+    readonly version: number;
+    /** Canonical filename. */
+    readonly name: string;
+}
+/** One canonical persistence filename in a Session's own storage directory. */
+export interface PersistedSessionFile {
+    /** Physical Session format generation; zero is encoded by omission. */
+    readonly version: number;
+    /** Physical compression selected by the backend. */
+    readonly compression: 'raw' | 'zstd';
+    /** Canonical basename. */
+    readonly name: string;
+}
+/**
+ * Return the canonical fixture filename for one parent/ordinal and generation.
+ *
+ * @param index - Parent `0` or a positive child/ordinal slot.
+ * @param version - Physical format generation; `0` is omitted.
+ * @returns The lowercase canonical JSONL filename.
+ */
+export declare function sessionFixtureName(index: number, version: number): string;
+/**
+ * Parse one canonical recorded-session fixture filename.
+ *
+ * @param name - Basename from a scenario directory.
+ * @returns Parsed role and generation, or `undefined` for an unrelated file.
+ */
+export declare function parseSessionFixtureName(name: string): SessionFixtureFile | undefined;
+/**
+ * Select the highest generation for every parent/ordinal fixture role.
+ * Older generations remain in the directory but do not count as extra Sessions.
+ *
+ * @param names - File basenames in one scenario directory.
+ * @returns Parent first, followed by contiguous child/ordinal roles.
+ */
+export declare function sessionFixtureFiles(names: readonly string[]): SessionFixtureFile[];
+/**
+ * Validate and order a scenario directory's selected Session fixture filenames.
+ *
+ * @param names - File basenames in one scenario directory.
+ * @returns Highest-generation parent and child/ordinal filenames.
+ */
+export declare function sessionFixtureNames(names: readonly string[]): string[];
+/**
+ * Read the declared physical generation from one Session JSONL header.
+ *
+ * @param content - Complete UTF-8 JSONL content.
+ * @param label - Diagnostic filename or path.
+ * @returns The declared non-negative format generation.
+ */
+export declare function sessionHeaderVersion(content: string, label: string): number;
+/**
+ * Require one fixture's canonical filename generation to equal its header.
+ *
+ * @param name - Canonical fixture basename.
+ * @param content - Complete UTF-8 JSONL content.
+ * @returns The validated format generation.
+ */
+export declare function assertSessionFixtureVersion(name: string, content: string): number;
+/**
+ * Return the canonical persistence basename for one generation and compression.
+ *
+ * @param version - Physical format generation; `0` is omitted.
+ * @param compression - Backend compression mode.
+ * @returns The canonical persistence basename.
+ */
+export declare function persistedSessionFilename(version: number, compression?: 'raw' | 'zstd'): string;
+/**
+ * Parse a canonical persistence basename from a Session's own directory.
+ *
+ * @param name - Candidate basename.
+ * @returns Its generation and compression, or `undefined` for noise and noncanonical names.
+ */
+export declare function parsePersistedSessionFilename(name: string): PersistedSessionFile | undefined;
+/**
+ * Select one highest-generation persistence path per physical Session directory.
+ *
+ * @param paths - Relative or absolute paths beneath a sessions root.
+ * @param compression - Compression selected by the snapshot composition.
+ * @returns Stable path order with older generations and filesystem noise omitted.
+ */
+export declare function latestPersistedSessionPaths(paths: readonly string[], compression?: 'raw' | 'zstd'): string[];
+/**
+ * Require one persistence basename's generation to equal its Session header.
+ *
+ * @param name - Canonical persistence basename.
+ * @param content - Complete uncompressed UTF-8 JSONL content.
+ * @returns The validated generation.
+ */
+export declare function assertPersistedSessionVersion(name: string, content: string): number;
+//# sourceMappingURL=session-files.d.ts.map

package/lib/types/suite.d.ts

@@ -17,6 +17,7 @@
  * @module @deepseek-ai/dsh-session-snapshot/suite
  */
 import { type AgentUnderTest, type HarvestedLog } from './harness.ts';
+import { type SnapshotSessionFormatManifest } from './manifest.ts';
 import { type CwdPathMode, type NormalizeContext } from './normalize.ts';
 /** A snapshot scenario and how its fixtures are produced. */
 export interface Scenario {
@@ -27,24 +28,26 @@ export interface Scenario {
     hasModelTurn: boolean;
     /**
      * Whether the run persists a comparable session log to diff against the
-     * `session.jsonl` fixture. Defaults to {@link hasModelTurn} (a model turn
+     * selected parent Session fixture. Defaults to {@link hasModelTurn} (a model turn
      * always produces a log worth comparing). Set it independently for a scenario
      * that produces a non-trivial durable log without calling the model.
      */
     comparesLog?: boolean;
     /**
-     * Whether `test:snapshot:record` regenerates this scenario's `session.jsonl`
-     * from the LIVE API. `recorded` scenarios are model-driven and reproducible;
+     * Whether `test:snapshot:record` regenerates this scenario's current-version
+     * Session fixtures from the LIVE API. `recorded` scenarios are model-driven and reproducible;
      * `authored` scenarios (fixtures hand-written or hand-harvested — e.g. a
      * provider error or a cancel the live API can't be coaxed into
      * deterministically, a deterministic hook scenario, or a scripted repetition
      * a live model won't reproduce) are NEVER re-recorded.
      */
     recorded: boolean;
+    /** Historical generation retained as a read-only migration fixture. */
+    sessionFormat?: SnapshotSessionFormatManifest;
     /**
      * Whether replay is driven by a hand-written `replay.override.json` sidecar
      * (a `ReplayOverrideDoc` that replaces or patches the script derived from
-     * `session.jsonl`) — the throw/hang cases chunks cannot express. The fixture
+     * selected parent Session fixture) — the throw/hang cases chunks cannot express. The fixture
      * guard requires the sidecar exactly when this is set: the harness forwards
      * the file purely on existence, so an unregistered stray sidecar would
      * silently alter the derived script. The guard fails loud on either
@@ -142,9 +145,10 @@ export interface Scenario {
 }
 /**
  * Whether a scenario's run test is skipped for this mode and host: record mode
- * skips authored (non-`recorded`) scenarios, {@link Scenario.posixOnly}
- * scenarios skip on Windows, and {@link Scenario.pwshOnly} scenarios skip
- * when the caller's `hasPwsh` probe is false.
+ * skips authored (non-`recorded`) scenarios and explicit historical Session
+ * generations, {@link Scenario.posixOnly} scenarios skip on Windows, and
+ * {@link Scenario.pwshOnly} scenarios skip when the caller's `hasPwsh` probe
+ * is false.
  *
  * @param scenario The scenario whose run test is being registered.
  * @param recording Whether the suite runs in record mode.
@@ -223,24 +227,12 @@ export declare function claimSharedSnapshot(claims: Map<string, SharedSnapshotCl
  * @returns Nothing.
  */
 export declare function assertUniqueSnapshotContents(kind: string, snapshots: readonly NamedSnapshotContent[]): void;
-/**
- * Validate and order a scenario directory's session-fixture filenames.
- *
- * The primary fixture is always `session.jsonl`; child sessions are discovered
- * from contiguous `session.1.jsonl` … filenames. The directory is the source of
- * truth, so scenario tables do not duplicate a child count that can drift from
- * the files. A session-like JSONL with any other suffix fails loud.
- *
- * @param names File names in one scenario directory.
- * @returns The primary and child fixture names in replay/harvest order.
- */
-export declare function sessionFixtureNames(names: readonly string[]): string[];
 /**
  * Derive normalization values from a fixture's own session header. Recorded ids and cwd differ
  * from the live replay run; the non-empty sentinel for missing cwd avoids accidental empty-
  * string replacement.
  *
- * @param fixture The committed `session.jsonl` content.
+ * @param fixture The selected committed parent Session fixture content.
  * @returns The fixture's own volatile values, ready for {@link normalizeSessionLog}.
  */
 export declare function fixtureContext(fixture: string): NormalizeContext;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session-snapshot",
   "description": "Session-log snapshot core with an ACP protocol adapter, expected-output normalization, and fixture invariants",
-  "version": "0.1.2-rc.1",
+  "version": "0.1.3-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -30,25 +30,29 @@
     "@agentclientprotocol/sdk": "1.4.0",
     "js-yaml": "^4.2.0",
     "vitest": "^4.1.8",
-    "@deepseek-ai/dsh-loader-smoke": "0.1.2-rc.1",
-    "@deepseek-ai/cordis-plugin-include": "1.0.7"
+    "@deepseek-ai/cordis-plugin-include": "1.0.7",
+    "@deepseek-ai/dsh-llm-replay": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-loader-smoke": "0.1.3-alpha.2",
+    "@deepseek-ai/dsh-session-format": "^0.1.3-alpha.2"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-session": "^0.1.2-rc.1"
+    "@deepseek-ai/dsh-session": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-http-proxy": "^0.1.3-alpha.2"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-agent": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-agent-loop": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-compaction": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-llm": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-sandbox": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-sandbox-policy": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-session": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-subagent": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-tools": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-user-questions": "^0.1.2-rc.1"
+    "@deepseek-ai/dsh-agent": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-agent-loop": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-compaction": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-llm": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-sandbox": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-subagent": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-tools": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-user-questions": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-http-proxy": "^0.1.3-alpha.2"
   }
 }