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

package/lib/index.js

@@ -14,7 +14,7 @@ import { entryListSchema } from "@deepseek-ai/cordis-plugin-include";
 import { resolveExampleLaunch } from "@deepseek-ai/dsh-loader-smoke";
 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 { SESSION_FORMAT_VERSION, 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
@@ -423,6 +423,16 @@ function sessionFixtureName(index, version) {
 	return `session${index === 0 ? "" : `.${index}`}${version === 0 ? "" : `.v${version}`}.jsonl`;
 }
 /**
+* Name the native-writer oracle for a retained historical replay role.
+* This expected output never participates in replay generation selection.
+* @param index - Parent `0` or a positive child/ordinal slot.
+* @returns The expected-output JSONL basename.
+*/
+function writerSnapshotName(index) {
+	nonNegativeSafeInteger(index, "writer snapshot index");
+	return `writer${index === 0 ? "" : `.${index}`}.expected.jsonl`;
+}
+/**
 * Parse one canonical recorded-session fixture filename.
 *
 * @param name - Basename from a scenario directory.
@@ -668,7 +678,7 @@ function captureExpectedWorkspaceSnapshot(root) {
 const DEFAULT_WAIT_TIMEOUT_MS = 1e4;
 const WAIT_POLL_INTERVAL_MS = 10;
 /**
-* Derive one stable, fixed-length spill root owned by this scenario.
+* Derive the stable, fixed-length logical spill prefix; never allocate files here.
 * Windows uses a two-character-shorter root because drive resolution adds its drive prefix.
 * @param fixtureFile - The scenario fixture whose parent directory provides the stable identity.
 * @param platform - the host platform, injectable for unit coverage.
@@ -692,11 +702,12 @@ async function runScenario(input, opts) {
 	const cwd = await mkdtemp(join(opts.workspaceParent ?? tmpdir(), "acp-snap-cwd-"));
 	const cwdAliases = [...new Set([realpathSync(cwd), realpathSync.native(cwd)])];
 	const sessionsRoot = await mkdtemp(join(tmpdir(), "acp-snap-sessions-"));
-	const spillRoot = snapshotSpillRoot(opts.fixtureFile);
+	let spillRoot;
 	let launched;
 	let sessionId;
 	let sessionLogs = [];
 	const outcome = await (async () => {
+		spillRoot = await mkdtemp(join(tmpdir(), "acp-snap-spill-"));
 		if (opts.workspaceDir !== void 0 && existsSync(opts.workspaceDir)) await cp(opts.workspaceDir, cwd, { recursive: true });
 		await opts.prepareWorkspace?.(cwd);
 		const initialWorkspace = await captureWorkspaceSnapshot(cwd, { ignoredRootEntries: [
@@ -712,6 +723,7 @@ async function runScenario(input, opts) {
 			DSH_SNAPSHOT_FILE: opts.fixtureFile,
 			DSH_SNAPSHOT_SESSIONS_ROOT: sessionsRoot,
 			DSH_SNAPSHOT_SPILL_ROOT: spillRoot,
+			DSH_SNAPSHOT_SPILL_LOCATOR_ROOT: snapshotSpillRoot(opts.fixtureFile),
 			DSH_HOME: join(cwd, ".dsh"),
 			DSH_AGENTS_HOME: join(cwd, ".agents"),
 			...opts.overrideFile !== void 0 ? { DSH_SNAPSHOT_OVERRIDE: opts.overrideFile } : {},
@@ -789,7 +801,8 @@ async function runScenario(input, opts) {
 		recursive: true,
 		force: true
 	}));
-	await cleanup(() => rm(spillRoot, {
+	const allocatedSpillRoot = spillRoot;
+	if (allocatedSpillRoot !== void 0) await cleanup(() => rm(allocatedSpillRoot, {
 		recursive: true,
 		force: true
 	}));
@@ -987,13 +1000,18 @@ async function waitForPersistedTurnEnd(root, sessionId, timeoutMs = DEFAULT_WAIT
 * own model work reached a closed turn.
 */
 async function waitForPersistedChildTurnEnd(root, child, timeoutMs = DEFAULT_WAIT_TIMEOUT_MS, minimumTurn = 1) {
-	await vi.waitFor(async () => {
-		const log = (await harvestSessionLogs(root))[child];
-		if (log === void 0 || !latestTurnIsClosed(log.content) || !hasRequestHeaderAfterDescriptor(log.content) || !hasClosedTurn(log.content, minimumTurn)) throw new Error(`snapshot-harness: subagent child #${child} did not persist closed turn ${minimumTurn} within ${timeoutMs}ms`);
-	}, {
-		interval: WAIT_POLL_INTERVAL_MS,
-		timeout: timeoutMs
-	});
+	const message = `snapshot-harness: subagent child #${child} did not persist closed turn ${minimumTurn} within ${timeoutMs}ms`;
+	try {
+		await vi.waitFor(async () => {
+			const log = (await harvestSessionLogs(root))[child];
+			if (log === void 0 || !latestTurnIsClosed(log.content) || !hasRequestHeaderAfterDescriptor(log.content) || !hasClosedTurn(log.content, minimumTurn)) throw new Error(message);
+		}, {
+			interval: WAIT_POLL_INTERVAL_MS,
+			timeout: timeoutMs
+		});
+	} catch (cause) {
+		throw new Error(message, { cause });
+	}
 }
 /** Whether a raw session log contains the requested closed turn. */
 function hasClosedTurn(content, turn) {
@@ -1132,8 +1150,8 @@ async function harvestSessionLogs(root) {
 /**
 * Pure ACP transcript and session-log normalizers. They scrub session ids, run cwd, RPC ids,
 * timestamps, goal lifecycle clocks, and hook duration while preserving semantic payload values.
-* Request-header scrubbers stay composable so one scenario per header class can pin prompt and
-* tool-schema sidecars.
+* The prompt-text and tool-schema scrubbers stay composable so one scenario per header class can
+* pin prompt and tool-schema sidecars.
 * @module @deepseek-ai/dsh-session-snapshot/normalize
 */
 const SESSION_ID = "{{sessionId}}";
@@ -1392,7 +1410,7 @@ function normalizeSessionLog(rawLog, ctx, options = {}) {
 	}).map((r) => JSON.stringify(r)).join("\n") + "\n";
 }
 /**
-* Canonicalize projected v2 body records. Compact streams are nested event data,
+* Canonicalize projected v3 body records. Compact streams are nested event data,
 * so persistence flush boundaries cannot change the row layout.
 */
 function projectSessionSnapshot(rawLog) {
@@ -1410,7 +1428,7 @@ function projectSessionSnapshot(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 writes the v2 logical event stream as
+* persistence-envelope projection, then writes the v3 logical event stream as
 * one record per event, independent of persistence flush boundaries.
 *
 * @param rawLog - persisted or already-projected session JSONL.
@@ -1438,51 +1456,20 @@ function normalizeSessionSnapshots(rawLogs, ctx, options = {}) {
 	}))));
 }
 /**
-* Omit only generation-qualified operational provenance from expected-output comparison.
+* Omit the artifact header generation after official migration for comparison.
+* Delivery and captured-source generations retain their opaque recorded values.
 * @param rawLog - Session records or events as compact JSON lines.
-* @returns the same records without delivery or captured-source generation qualifiers.
+* @returns the same records with only the Session header version omitted.
 */
 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;
+		if (record.type !== "session" || !Object.hasOwn(record, "version")) return line;
+		delete record.version;
+		return JSON.stringify(record);
 	}).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);
@@ -1492,60 +1479,58 @@ function hasSessionFormatVersion(rawLog) {
 	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
-* its complete tool schemas while every JSONL fixture omits the prompt text.
-* Lines without a system payload pass through byte-for-byte; the transform is
-* idempotent.
+* Replace the rendered prompt text of every `system/message` event with the
+* `{{system}}` token. The text block keeps its position and type, so the
+* fixture still shows one system node per prompt version; an empty `content`
+* (no system prompt) stays empty. Request headers and every other line pass
+* through byte-for-byte; the transform is idempotent.
 *
 * @param rawLog The raw session `.jsonl` content.
-* @returns The JSONL with system-prompt content tokenized.
+* @returns The JSONL with system-prompt text tokenized.
 */
 function scrubSystemPrompts(rawLog) {
-	return scrubHeaderContent(rawLog, { system: true });
+	return scrubModelRequestContent(rawLog, { system: true });
 }
 /**
 * Replace tool schemas in full request-header snapshots with `{{tools}}`
-* tokens while retaining field presence. System prompts and session-prefix
-* messages stay verbatim so pinning fixtures can move only schema bulk into
-* their dedicated JSON sidecar. Lines without a tool payload pass through
-* byte-for-byte; the transform is idempotent.
+* tokens while retaining field presence. System-prompt text stays verbatim so
+* pinning fixtures can move only schema bulk into their dedicated JSON
+* sidecar. Lines without a tool payload pass through byte-for-byte; the
+* transform is idempotent.
 *
 * @param rawLog The raw session `.jsonl` content.
 * @returns The JSONL with tool-schema content tokenized.
 */
 function scrubToolSchemas(rawLog) {
-	return scrubHeaderContent(rawLog, { tools: true });
+	return scrubModelRequestContent(rawLog, { tools: true });
 }
 /**
-* Replace all bulky request-header content in a session JSONL with stable
-* tokens. This includes the system-prompt fields handled by
-* {@link scrubSystemPrompts}, tool schemas, and session-prefix messages. It
-* keeps prefix message counts, field presence, config, and reason. Lines
-* without content to scrub pass through byte-for-byte, and the transform is
-* idempotent.
+* Replace all bulky model-request content in a session JSONL with stable
+* tokens: the `system/message` prompt text handled by
+* {@link scrubSystemPrompts} and the request-header tool schemas handled by
+* {@link scrubToolSchemas}. Field presence, config, and reason are kept.
+* Lines without content to scrub pass through byte-for-byte, and the
+* transform is idempotent.
 *
 * @param rawLog The raw session `.jsonl` content.
-* @returns The JSONL with all header bulk tokenized, other lines byte-identical.
+* @returns The JSONL with prompt text and schema bulk tokenized, other lines byte-identical.
 */
-function scrubRequestHeaders(rawLog) {
-	return scrubHeaderContent(rawLog, {
+function scrubModelRequestBulk(rawLog) {
+	return scrubModelRequestContent(rawLog, {
 		system: true,
 		tools: true
 	});
 }
 /**
-* Project a persisted session log while tokenizing all request-header bulk.
-* Each non-empty line is parsed at most once; the session header stays
-* byte-identical. Body records omit their persistence-only envelopes, and
-* request-header payloads are tokenized.
+* Project a persisted session log while tokenizing prompt text and schema
+* bulk. Each non-empty line is parsed at most once; the session header stays
+* byte-identical. Body records omit their persistence-only envelopes.
 *
 * @param rawLog - persisted or already-projected session JSONL.
-* @returns committed snapshot JSONL with request headers tokenized.
+* @returns committed snapshot JSONL with prompt text and tool schemas tokenized.
 */
 function scrubSessionSnapshot(rawLog) {
-	const scrubbed = scrubRequestHeaders(rawLog);
+	const scrubbed = scrubModelRequestBulk(rawLog);
 	let recordIndex = 0;
 	return scrubbed.split("\n").map((line) => {
 		if (line.trim().length === 0) return line;
@@ -1568,26 +1553,31 @@ function normalizeFeedbackClocks(record) {
 	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 the first text block of a `system/message` payload, or `undefined` when it carries none. */
+function systemPromptBlock(data) {
+	const message = data.message;
+	if (message === null || typeof message !== "object" || !Array.isArray(message.content)) return void 0;
+	const block = message.content[0];
+	return block !== null && typeof block === "object" && typeof block.text === "string" ? block : void 0;
+}
+/** Transform the selected model-request payloads. */
+function scrubModelRequestContent(rawLog, options) {
 	return rawLog.split("\n").map((line) => {
 		if (line.trim().length === 0) return line;
 		const record = JSON.parse(line);
 		const data = record.data;
 		if (data === null || typeof data !== "object") return line;
-		if (record.type === "request/header") {
+		if (options.system === true && record.type === "system/message") {
+			const block = systemPromptBlock(data);
+			if (block === void 0) return line;
+			block.text = SYSTEM;
+			return JSON.stringify(record);
+		}
+		if (options.tools === true && record.type === "request/header") {
 			const header = data.header;
-			if (header === null || typeof header !== "object") return line;
-			let touched = false;
-			if (options.system === true && "system" in header) {
-				header.system = SYSTEM;
-				touched = true;
-			}
-			if (options.tools === true && "tools" in header) {
-				header.tools = TOOLS;
-				touched = true;
-			}
-			return touched ? JSON.stringify(record) : line;
+			if (header === null || typeof header !== "object" || !("tools" in header)) return line;
+			header.tools = TOOLS;
+			return JSON.stringify(record);
 		}
 		return line;
 	}).join("\n");
@@ -1698,10 +1688,11 @@ function parseSnapshotManifest(source, path = "snapshot.yml") {
 				"toolSchemasSource",
 				"childSystemPrompts",
 				"childToolSchemas",
-				"changes"
+				"changes",
+				"promptChanges"
 			], "manifest.header");
 			if (value.pin !== void 0 && value.pin !== true) throw new Error("manifest.header.pin must equal true when present");
-			if (value.changes !== void 0 && (!Number.isInteger(value.changes) || Number(value.changes) < 0)) throw new Error("manifest.header.changes must be a non-negative integer");
+			for (const field of ["changes", "promptChanges"]) if (value[field] !== void 0 && (!Number.isInteger(value[field]) || Number(value[field]) < 0)) throw new Error(`manifest.header.${field} must be a non-negative integer`);
 			header = {
 				class: name(value.class, "manifest.header.class"),
 				...value.pin === true ? { pin: true } : {},
@@ -1709,7 +1700,8 @@ function parseSnapshotManifest(source, path = "snapshot.yml") {
 				...value.toolSchemasSource === void 0 ? {} : { toolSchemasSource: scenarioSource(value.toolSchemasSource, "manifest.header.toolSchemasSource") },
 				...value.childSystemPrompts === void 0 ? {} : { childSystemPrompts: positiveIndexes(value.childSystemPrompts, "manifest.header.childSystemPrompts") },
 				...value.childToolSchemas === void 0 ? {} : { childToolSchemas: positiveIndexes(value.childToolSchemas, "manifest.header.childToolSchemas") },
-				...value.changes === void 0 ? {} : { changes: Number(value.changes) }
+				...value.changes === void 0 ? {} : { changes: Number(value.changes) },
+				...value.promptChanges === void 0 ? {} : { promptChanges: Number(value.promptChanges) }
 			};
 		}
 		let replay;
@@ -1744,11 +1736,11 @@ function parseSnapshotManifest(source, path = "snapshot.yml") {
 				"parent"
 			], "manifest.workspace");
 			if (value.final !== void 0 && value.final !== true) throw new Error("manifest.workspace.final must equal true when present");
-			if (value.parent !== void 0 && value.parent !== "home") throw new Error("manifest.workspace.parent must equal home");
+			if (value.parent !== void 0 && value.parent !== "outside-temp") throw new Error("manifest.workspace.parent must equal outside-temp");
 			workspace = {
 				...value.setup === void 0 ? {} : { setup: name(value.setup, "manifest.workspace.setup") },
 				...value.final === true ? { final: true } : {},
-				...value.parent === "home" ? { parent: "home" } : {}
+				...value.parent === "outside-temp" ? { parent: "outside-temp" } : {}
 			};
 			if (Object.keys(workspace).length === 0) throw new Error("manifest.workspace must not be empty");
 		}
@@ -1838,9 +1830,10 @@ function parseSnapshotManifest(source, path = "snapshot.yml") {
 * refresh stay serial while writing.
 *
 * Exactly one scenario per header-composition class pins the tokenized header
-* sequence. Its prompt and tool-schema sequences live in independent
-* sidecars, each of which may be shared with another class pin when the bytes
-* are identical. Every live header is checked against the composed pin, so
+* sequence and the tokenized `system/message` sequence. Its prompt and
+* tool-schema sequences live in independent sidecars, each of which may be
+* shared with another class pin when the bytes are identical. Every live
+* header and system prompt is checked against the composed pin, so
 * session-dependent composition must declare a separate class instead of
 * escaping coverage.
 * @module @deepseek-ai/dsh-session-snapshot/suite
@@ -1965,10 +1958,13 @@ function fixtureContext(fixture) {
 }
 /** Normalize request-header payloads while retaining the reason that selects a pin revision. */
 function normalizedHeaderEvents(rawLog, ctx) {
-	return normalizeSessionLog(rawLog, ctx).split("\n").filter((line) => line.trim().length > 0).map((line) => JSON.parse(line)).filter((record) => record.type === "request/header").map((record) => ({
-		header: record.data?.header,
-		reason: record.data?.reason
-	}));
+	return parseJsonlRecords(normalizeSessionLog(rawLog, ctx)).filter((record) => record.type === "request/header").map((record) => {
+		const data = record.data;
+		return {
+			header: data?.header,
+			reason: data?.reason
+		};
+	});
 }
 /**
 * Header revisions that own sidecar content. `series` reuses the current revision, while
@@ -1979,13 +1975,17 @@ function normalizedHeaderEvents(rawLog, ctx) {
 function pinningHeaderPayloads(rawLog, ctx) {
 	return normalizedHeaderEvents(rawLog, ctx).filter((event) => event.reason !== "series").map((event) => event.header);
 }
-/** Extract every string system prompt from a normalized header sequence. */
-function systemPromptsFrom(headers) {
-	return headers.flatMap((header) => {
-		if (header === null || typeof header !== "object") return [];
-		const system = header.system;
-		return typeof system === "string" ? [system] : [];
-	});
+/**
+* The rendered prompt text of one parsed `system/message` record: its single
+* text block, or `''` when the empty `content` records "no system prompt".
+* Any other record yields `undefined`.
+*/
+function systemPromptOf(record) {
+	if (record.type !== "system/message") return void 0;
+	const content = record.data?.message?.content;
+	if (!Array.isArray(content)) return void 0;
+	const block = content[0];
+	return content.length === 0 ? "" : typeof block?.text === "string" ? block.text : void 0;
 }
 /** Extract every array-valued tool catalog from a normalized header sequence. */
 function toolSchemasFrom(headers) {
@@ -1999,8 +1999,7 @@ function toolSchemasFrom(headers) {
 * The `data.header` payload of every `request/header` event in a session
 * JSONL, in log order, with the log's volatile values scrubbed first
 * ({@link normalizeSessionLog}) so headers harvested from different runs —
-* each embedding its own generated cwd in the composed prompt — compare on equal
-* footing.
+* each embedding its own generated cwd — compare on equal footing.
 *
 * @param rawLog The session `.jsonl` content to extract headers from.
 * @param ctx The volatile values of the run that produced it.
@@ -2010,16 +2009,35 @@ function normalizedHeaders(rawLog, ctx) {
 	return normalizedHeaderEvents(rawLog, ctx).map((event) => event.header);
 }
 /**
-* The normalized string-valued system prompts carried by request headers in a
-* session JSONL, in log order. Headers without a string prompt are omitted so
-* callers can assert one prompt per header explicitly.
+* The normalized prompt text of every `system/message` event in a session
+* JSONL, in log order: the first is the initial system prompt (surface node 0)
+* and each later one replaced it or, on an in-history route, appended the
+* changed prompt after the cached history. An empty `content` yields `''`; a
+* `system/message` without a text block is omitted.
 *
 * @param rawLog The session `.jsonl` content to inspect.
 * @param ctx The volatile values of the run that produced it.
-* @returns The normalized system prompts, in header order.
+* @returns The normalized system prompts, in log order.
 */
 function normalizedSystemPrompts(rawLog, ctx) {
-	return systemPromptsFrom(normalizedHeaders(rawLog, ctx));
+	return parseJsonlRecords(normalizeSessionLog(rawLog, ctx)).flatMap((record) => {
+		const prompt = systemPromptOf(record);
+		return prompt === void 0 ? [] : [prompt];
+	});
+}
+/**
+* Whether every model request in a session JSONL is preceded by its system
+* prompt: the log has no `request/header`, or a `system/message` event comes
+* before its first `request/header`.
+*
+* @param rawLog The session `.jsonl` content to inspect.
+* @returns True when the first `request/header` (if any) follows a `system/message`.
+*/
+function systemPromptPrecedesRequests(rawLog) {
+	const types = parseJsonlRecords(rawLog).map((record) => record.type);
+	const firstHeader = types.indexOf("request/header");
+	const firstPrompt = types.indexOf("system/message");
+	return firstHeader < 0 || firstPrompt >= 0 && firstPrompt < firstHeader;
 }
 /**
 * The normalized tool-schema arrays carried by request headers in a session
@@ -2077,24 +2095,40 @@ function restorePinnedToolSchemas(header, schemas) {
 		tools: schemas
 	};
 }
+/** Marker line separating one replaced prompt from the previous one in a prompt sidecar. */
+const SYSTEM_PROMPT_CHANGE_MARKER = "\n<!-- system/message change ";
 /**
 * Render a normalized prompt as a repository-friendly Markdown snapshot.
 * Prompt text is unchanged except that a missing terminal newline is added so
 * the committed file follows the repository newline contract.
 *
-* @param prompt The normalized system prompt.
-* @param changes Full normalized prompts from later changed-header snapshots.
+* @param prompt The normalized initial system prompt (surface node 0).
+* @param changes Full normalized prompts from later `system/message` events, replacements or in-history appends.
 * @returns Markdown snapshot text ending in a newline.
 */
 function formatSystemPromptSnapshot(prompt, changes = []) {
 	let snapshot = prompt.endsWith("\n") ? prompt : `${prompt}\n`;
 	for (const [index, change] of changes.entries()) {
-		snapshot += `\n<!-- request/header change ${index + 1} -->\n\n`;
+		snapshot += `${SYSTEM_PROMPT_CHANGE_MARKER}${index + 1} -->\n\n`;
 		snapshot += change.endsWith("\n") ? change : `${change}\n`;
 	}
 	return snapshot;
 }
 /**
+* Split a prompt sidecar into its initial prompt and each later change, the
+* inverse of {@link formatSystemPromptSnapshot}.
+*
+* @param snapshot The Markdown sidecar text.
+* @returns The initial prompt snapshot plus one entry per later `system/message`.
+*/
+function parseSystemPromptSnapshot(snapshot) {
+	const parts = snapshot.split(/\n<!-- system\/message change [1-9]\d* -->\n\n/);
+	return {
+		initial: parts[0],
+		changes: parts.slice(1)
+	};
+}
+/**
 * Reject a child prompt sidecar that cannot own distinct, canonical prompt text.
 * @param sidecar - committed child prompt snapshot.
 * @param classPin - initial prompt snapshot owned by the scenario's header class.
@@ -2105,10 +2139,9 @@ function assertChildSystemPromptSnapshot(sidecar, classPin, label) {
 	if (!sidecar.endsWith("\n")) throw new Error(`${label} must end in a newline`);
 	if (sidecar === classPin) throw new Error(`${label} must differ from its class pin`);
 }
-/** Return the initial-prompt portion of a possibly multi-header snapshot. */
+/** Return the initial-prompt portion of a possibly multi-prompt snapshot. */
 function initialSystemPromptSnapshot(snapshot) {
-	const marker = snapshot.indexOf("\n<!-- request/header change ");
-	return marker < 0 ? snapshot : snapshot.slice(0, marker);
+	return parseSystemPromptSnapshot(snapshot).initial;
 }
 /**
 * Count changed `request/header` snapshots in a session JSONL.
@@ -2141,6 +2174,7 @@ function surfaceEventMessage(record) {
 		case "user/message":
 			message = data;
 			break;
+		case "system/message":
 		case "assistant/message":
 		case "tool/result":
 			message = data.message;
@@ -2458,11 +2492,34 @@ function stabilizeRefreshLog(fresh, existing, replacements, freshContext) {
 	return records.map((record) => JSON.stringify(record)).join("\n") + "\n";
 }
 /**
+* Check every selected role for tool/path defects and current generations for canonical prompt/identity storage.
+* Historical roles retain their released bytes, including roles retired by the current writer.
+* @param dir Scenario directory containing canonical Session fixtures.
+* @param scenarioName Scenario name used in failure diagnostics.
+* @returns Resolves when all selected fixtures satisfy the storage checks.
+*/
+async function assertSessionFixtureStorage(dir, scenarioName) {
+	const files = await sessionFixtures(dir);
+	const currentFixtures = [];
+	for (const file of files) {
+		const fixture = await readFile(join(dir, file), "utf8");
+		const version = assertSessionFixtureVersion(file, fixture);
+		expect(unknownToolCallIds(fixture), `${scenarioName}/${file} contains UNKNOWN_TOOL`).toEqual([]);
+		expect(fixture, `${scenarioName}/${file} carries a non-canonical macOS cwd token`).not.toContain("/private{{cwd}}");
+		if (version !== SESSION_FORMAT_VERSION) continue;
+		currentFixtures.push(fixture);
+		expect(scrubSystemPrompts(fixture), `${scenarioName}/${file} carries an unscrubbed system prompt`).toEqual(fixture);
+		expect(scrubToolSchemas(fixture), `${scenarioName}/${file} carries unscrubbed tool schemas`).toEqual(fixture);
+		expect(systemPromptPrecedesRequests(fixture), `${scenarioName}/${file} has a request/header with no preceding system/message`).toBe(true);
+	}
+	expect(redactSessionSnapshotIds(currentFixtures), `${scenarioName}: identity redaction fixed point`).toEqual(currentFixtures);
+}
+/**
 * Register the suite: one test per scenario (the expected-output and log comparisons and
-* the header-uniformity guard) plus the fixture guard block (no orphan
+* the header and prompt uniformity guard) plus the fixture guard block (no orphan
 * scenario dirs, required files present, exactly one pin per header class,
-* shared sidecars unique and well-formed, every JSONL prompt-scrubbed,
-* non-pinning fixtures fully header-scrubbed). Must
+* shared sidecars unique and well-formed, every JSONL prompt- and
+* schema-scrubbed with a `system/message` before its first request). Must
 * run at vitest collection time — it calls `describe`/`it`. Throws
 * immediately if any header class lacks a pinning scenario or carries two
 * (the uniformity guard needs exactly one comparison anchor per class).
@@ -2481,7 +2538,12 @@ function defineAcpSnapshotSuite(options) {
 	for (const scenario of scenarios) {
 		if (scenariosByName.has(scenario.name)) throw new Error(`acp-snapshot: duplicate scenario name "${scenario.name}"`);
 		scenariosByName.set(scenario.name, scenario);
-		for (const field of ["systemPromptSource", "toolSchemasSource"]) if (scenario[field] !== void 0 && scenario.pinsHeader !== true) throw new Error(`acp-snapshot: ${scenario.name}.${field} is only valid on a header-pinning scenario`);
+		for (const field of [
+			"systemPromptSource",
+			"toolSchemasSource",
+			"expectedHeaderChanges",
+			"expectedPromptChanges"
+		]) if (scenario[field] !== void 0 && scenario.pinsHeader !== true) throw new Error(`acp-snapshot: ${scenario.name}.${field} is only valid on a header-pinning scenario`);
 	}
 	/** Each header class's single pinning scenario. Guarded here (and by meta-tests) so a pin cannot silently vanish or split. */
 	const pinningByClass = /* @__PURE__ */ new Map();
@@ -2493,14 +2555,19 @@ function defineAcpSnapshotSuite(options) {
 		pinningByClass.set(cls, scenario);
 	}
 	for (const scenario of scenarios) if (!pinningByClass.has(classOf(scenario))) throw new Error(`acp-snapshot: no scenario pins the request-header content of class "${classOf(scenario)}" (needed by ${scenario.name})`);
+	/**
+	* Resolve one pin's sidecar source. A prompt sidecar spans `1 + expectedPromptChanges`
+	* prompts and a schema sidecar spans `1 + expectedHeaderChanges` schema sets, so a shared
+	* source must declare the count that sizes the sidecar it lends.
+	*/
 	const sourceFor = (pinningScenario, field, label) => {
 		const sourceName = pinningScenario[field] ?? pinningScenario.name;
 		const source = scenariosByName.get(sourceName);
 		if (source === void 0) throw new Error(`acp-snapshot: ${pinningScenario.name} names unknown ${label} source "${sourceName}"`);
 		if (source.pinsHeader !== true) throw new Error(`acp-snapshot: ${pinningScenario.name} names non-pinning ${label} source "${sourceName}"`);
 		if (source[field] !== void 0 && source[field] !== source.name) throw new Error(`acp-snapshot: ${pinningScenario.name} names ${label} source "${sourceName}", which does not own its sidecar`);
-		const expectedChanges = pinningScenario.expectedHeaderChanges ?? 0;
-		if ((source.expectedHeaderChanges ?? 0) !== expectedChanges) throw new Error(`acp-snapshot: ${pinningScenario.name} and ${sourceName} declare different header-change counts for shared ${label}`);
+		const countField = field === "systemPromptSource" ? "expectedPromptChanges" : "expectedHeaderChanges";
+		if ((source[countField] ?? 0) !== (pinningScenario[countField] ?? 0)) throw new Error(`acp-snapshot: ${pinningScenario.name} and ${sourceName} declare different ${countField} counts for shared ${label}`);
 		return source;
 	};
 	const promptSourceByClass = /* @__PURE__ */ new Map();
@@ -2524,7 +2591,7 @@ function defineAcpSnapshotSuite(options) {
 			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 comparesLog = scenario.comparesLog ?? (scenario.hasModelTurn && manifest.sessionFormat === void 0);
 			const result = await runScenario(input, {
 				agent,
 				mode: childMode,
@@ -2561,16 +2628,14 @@ function defineAcpSnapshotSuite(options) {
 				fixtureFiles = outputFixtureFiles;
 				if (scenario.pinsHeader === true) {
 					const primary = result.sessionLogs[0];
-					const pinningHeaders = pinningHeaderPayloads(primary.content, ctx);
-					const prompts = systemPromptsFrom(pinningHeaders);
-					expect(prompts.length, `${mode} produced no system prompt to snapshot`).toBeGreaterThan(0);
+					const prompts = normalizedSystemPrompts(primary.content, ctx);
+					expect(prompts.length, `${mode} produced a system prompt count that differs from 1 + expectedPromptChanges`).toBe(1 + (scenario.expectedPromptChanges ?? 0));
 					const promptSnapshot = formatSystemPromptSnapshot(prompts[0], prompts.slice(1));
 					const promptPath = join(snapshotsDir, (promptSourceByClass.get(classOf(scenario)) ?? scenario).name, SYSTEM_PROMPT_SNAPSHOT);
 					claimSharedSnapshot(promptClaims, promptPath, scenario.name, promptSnapshot);
 					await writeFile(promptPath, promptSnapshot);
-					const schemaSets = toolSchemasFrom(pinningHeaders);
-					expect(schemaSets.length, `${mode} produced no tool schemas to snapshot`).toBeGreaterThan(0);
-					expect(schemaSets.length, `${mode} produced a tool-schema sequence that differs from its prompt sequence`).toBe(prompts.length);
+					const schemaSets = toolSchemasFrom(pinningHeaderPayloads(primary.content, ctx));
+					expect(schemaSets.length, `${mode} produced a tool-schema count that differs from 1 + expectedHeaderChanges`).toBe(1 + (scenario.expectedHeaderChanges ?? 0));
 					const toolSchemasSnapshot = formatToolSchemasSnapshot(schemaSets[0], schemaSets.slice(1));
 					const schemaPath = join(snapshotsDir, (schemaSourceByClass.get(classOf(scenario)) ?? scenario).name, TOOL_SCHEMAS_SNAPSHOT);
 					claimSharedSnapshot(schemaClaims, schemaPath, scenario.name, toolSchemasSnapshot);
@@ -2586,7 +2651,7 @@ function defineAcpSnapshotSuite(options) {
 				for (const index of childPromptPins) {
 					const log = result.sessionLogs[index];
 					expect(log, `${mode}: no child session log at index ${index} to snapshot a prompt from`).toBeDefined();
-					const prompts = systemPromptsFrom(pinningHeaderPayloads(log.content, ctx));
+					const prompts = normalizedSystemPrompts(log.content, ctx);
 					expect(prompts.length, `${mode}: child ${index} produced no system prompt to snapshot`).toBeGreaterThan(0);
 					await writeFile(join(dir, childSystemPromptSnapshot(index)), formatSystemPromptSnapshot(prompts[0]));
 				}
@@ -2622,6 +2687,7 @@ function defineAcpSnapshotSuite(options) {
 			const promptSnapshot = await readFile(join(snapshotsDir, promptSource.name, SYSTEM_PROMPT_SNAPSHOT), "utf8");
 			const initialPromptSnapshot = initialSystemPromptSnapshot(promptSnapshot);
 			expect(pinned.length, `the pinning fixture (${pinningScenario.name}) has an unexpected request/header count`).toBe(1 + (pinningScenario.expectedHeaderChanges ?? 0));
+			expect(parseSystemPromptSnapshot(promptSnapshot).changes.length, `the prompt source (${promptSource.name}) has an unexpected system prompt change count`).toBe(pinningScenario.expectedPromptChanges ?? 0);
 			const toolSchemasSnapshot = await readFile(join(snapshotsDir, schemaSource.name, TOOL_SCHEMAS_SNAPSHOT), "utf8");
 			const toolSchemas = parseToolSchemasSnapshot(toolSchemasSnapshot);
 			const pinnedSchemaSets = [toolSchemas.initial, ...toolSchemas.changes];
@@ -2636,14 +2702,18 @@ function defineAcpSnapshotSuite(options) {
 			for (const index of childPromptPins) childPinnedPrompts.set(index, await readFile(join(dir, childSystemPromptSnapshot(index)), "utf8"));
 			for (const [logIndex, log] of result.sessionLogs.entries()) {
 				const childSchemas = childPinnedSchemas.get(logIndex);
-				const expectedChanges = scenario.pinsHeader === true && logIndex === 0 ? scenario.expectedHeaderChanges ?? 0 : 0;
+				const pinsPrimary = scenario.pinsHeader === true && logIndex === 0;
+				const expectedChanges = pinsPrimary ? scenario.expectedHeaderChanges ?? 0 : 0;
+				const expectedPromptChanges = pinsPrimary ? scenario.expectedPromptChanges ?? 0 : 0;
 				expect(headerChangeCount(log.content), `session ${log.id}: changed request/header count`).toBe(expectedChanges);
-				const headerEvents = normalizedHeaderEvents(scrubSystemPrompts(log.content), ctx);
+				const headerEvents = normalizedHeaderEvents(log.content, ctx);
 				const headers = headerEvents.map((event) => event.header);
 				const prompts = normalizedSystemPrompts(log.content, ctx);
-				const schemaSets = normalizedToolSchemas(log.content, ctx);
-				expect(prompts.length, `session ${log.id}: every request/header must carry a string system prompt`).toBe(headers.length);
-				expect(schemaSets.length, `session ${log.id}: every request/header must carry an array-valued tools field`).toBe(headers.length);
+				expect(normalizedToolSchemas(log.content, ctx).length, `session ${log.id}: every request/header must carry an array-valued tools field`).toBe(headers.length);
+				if (headers.length > 0) {
+					expect(systemPromptPrecedesRequests(log.content), `session ${log.id}: a system/message must precede the first request/header`).toBe(true);
+					expect(prompts.length, `session ${log.id}: system/message count`).toBe(1 + expectedPromptChanges);
+				}
 				if (childSchemas !== void 0) expect(childSchemas.length, `session ${log.id}: ${childToolSchemasSnapshot(logIndex)} has an unexpected tool-schema count`).toBe(1 + headerChangeCount(log.content));
 				let revision = 0;
 				for (const [k, header] of headers.entries()) {
@@ -2654,17 +2724,15 @@ function defineAcpSnapshotSuite(options) {
 						tools: childSchemas[revision]
 					};
 					expect(header, `session ${log.id}: request/header #${k + 1} diverged from the pinned (${pinningScenario.name}) header`).toEqual(expected);
-					if (expectedChanges === 0) {
-						const childPrompt = childPinnedPrompts.get(logIndex);
-						const promptOrigin = childPrompt === void 0 ? `${promptSource.name}/${SYSTEM_PROMPT_SNAPSHOT}` : childSystemPromptSnapshot(logIndex);
-						expect(formatSystemPromptSnapshot(prompts[k]), `session ${log.id}: initial system prompt #${k + 1} diverged from ${promptOrigin}`).toEqual(childPrompt ?? initialPromptSnapshot);
-					}
 				}
-				if (scenario.pinsHeader === true && logIndex === 0) {
-					const pinningHeaders = pinningHeaderPayloads(log.content, ctx);
-					const pinningPrompts = systemPromptsFrom(pinningHeaders);
-					const pinningSchemas = toolSchemasFrom(pinningHeaders);
-					expect(formatSystemPromptSnapshot(pinningPrompts[0], pinningPrompts.slice(1)), `session ${log.id}: changed system prompts diverged from ${promptSource.name}/${SYSTEM_PROMPT_SNAPSHOT}`).toEqual(promptSnapshot);
+				if (expectedPromptChanges === 0) {
+					const childPrompt = childPinnedPrompts.get(logIndex);
+					const promptOrigin = childPrompt === void 0 ? `${promptSource.name}/${SYSTEM_PROMPT_SNAPSHOT}` : childSystemPromptSnapshot(logIndex);
+					for (const [k, prompt] of prompts.entries()) expect(formatSystemPromptSnapshot(prompt), `session ${log.id}: system prompt #${k + 1} diverged from ${promptOrigin}`).toEqual(childPrompt ?? initialPromptSnapshot);
+				}
+				if (pinsPrimary) {
+					const pinningSchemas = toolSchemasFrom(pinningHeaderPayloads(log.content, ctx));
+					expect(formatSystemPromptSnapshot(prompts[0], prompts.slice(1)), `session ${log.id}: changed system prompts diverged from ${promptSource.name}/${SYSTEM_PROMPT_SNAPSHOT}`).toEqual(promptSnapshot);
 					expect(formatToolSchemasSnapshot(pinningSchemas[0], pinningSchemas.slice(1)), `session ${log.id}: changed tool schemas diverged from ${schemaSource.name}/${TOOL_SCHEMAS_SNAPSHOT}`).toEqual(toolSchemasSnapshot);
 				}
 			}
@@ -2729,6 +2797,8 @@ function defineAcpSnapshotSuite(options) {
 				for (const [index, header] of headers.entries()) expect(() => restorePinnedToolSchemas(header, schemaSets[index]), `${scenario.name}: tools must use the sidecar token`).not.toThrow();
 				expect(promptSnapshot.length, `${promptSource.name}/${SYSTEM_PROMPT_SNAPSHOT} must not be empty`).toBeGreaterThan(0);
 				expect(promptSnapshot.endsWith("\n"), `${promptSource.name}/${SYSTEM_PROMPT_SNAPSHOT} must end in a newline`).toBe(true);
+				expect(parseSystemPromptSnapshot(promptSnapshot).changes.length, `${promptSource.name}: prompt change count must match ${scenario.name}'s expectedPromptChanges`).toBe(scenario.expectedPromptChanges ?? 0);
+				expect(normalizedSystemPrompts(fixture, fixtureContext(fixture)).length, `${scenario.name}: a pinning fixture must carry exactly its declared system/message count`).toBe(1 + (scenario.expectedPromptChanges ?? 0));
 				expect(toolSchemasSnapshot, `${schemaSource.name}/${TOOL_SCHEMAS_SNAPSHOT} must use canonical JSON formatting`).toBe(formatToolSchemasSnapshot(toolSchemas.initial, toolSchemas.changes));
 				expect(headerChangeCount(fixture), `${scenario.name}: a pinning fixture must carry exactly its declared changed headers`).toBe(scenario.expectedHeaderChanges ?? 0);
 			}
@@ -2765,22 +2835,9 @@ function defineAcpSnapshotSuite(options) {
 			}
 		});
 		it("every committed JSONL has valid tool results and canonical fixture storage", async () => {
-			for (const scenario of scenarios) {
-				const dir = join(snapshotsDir, scenario.name);
-				const files = await sessionFixtures(dir);
-				for (const file of files) {
-					const fixture = await readFile(join(dir, file), "utf8");
-					expect(unknownToolCallIds(fixture), `${scenario.name}/${file} contains UNKNOWN_TOOL`).toEqual([]);
-					expect(fixture, `${scenario.name}/${file} carries a non-canonical macOS cwd token`).not.toContain("/private{{cwd}}");
-					expect(scrubSystemPrompts(fixture), `${scenario.name}/${file} carries an unscrubbed system prompt`).toEqual(fixture);
-					expect(scrubToolSchemas(fixture), `${scenario.name}/${file} carries unscrubbed tool schemas`).toEqual(fixture);
-					if (scenario.pinsHeader !== true) expect(scrubRequestHeaders(fixture), `${scenario.name}/${file} carries unscrubbed header content`).toEqual(fixture);
-				}
-				const fixtures = await Promise.all(files.map((file) => readFile(join(dir, file), "utf8")));
-				expect(redactSessionSnapshotIds(fixtures), `${scenario.name}: identity redaction fixed point`).toEqual(fixtures);
-			}
+			for (const scenario of scenarios) await assertSessionFixtureStorage(join(snapshotsDir, scenario.name), scenario.name);
 		});
 	});
 }
 //#endregion
-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 };
+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, parseSystemPromptSnapshot, parseToolSchemasSnapshot, persistedSessionFilename, redactSessionSnapshotIds, refreshFixtureReplacements, restorePinnedToolSchemas, runScenario, scrubModelRequestBulk, scrubSessionSnapshot, scrubSystemPrompts, scrubToolSchemas, sessionFixtureFiles, sessionFixtureName, sessionFixtureNames, sessionHeaderVersion, snapshotSpillRoot, stabilizeFixtureMessageIds, stabilizeRefreshLog, systemPromptPrecedesRequests, tokenizeSessionFixtureCwd, writerSnapshotName, writesCurrentSessionFixtures };