@deepseek-ai/dsh-session 0.1.2-rc.1 → 0.1.5-alpha.1

package/lib/index.js

@@ -1,7 +1,7 @@
 import { Service } from "@deepseek-ai/cordis";
 import { isAbsolute } from "node:path";
 import { brandNumber, brandString } from "@deepseek-ai/dsh-brand";
-import { deepFreeze, snapshotJsonValue } from "@deepseek-ai/dsh-util-values";
+import { assertNever, deepFreeze, snapshotJsonValue } from "@deepseek-ai/dsh-util-values";
 import { scopeOf, scopeTarget } from "@deepseek-ai/dsh-scope";
 import { callConfigEquals } from "@deepseek-ai/dsh-llm";
 //#region lib/types/types.js
@@ -32,11 +32,11 @@ function SessionLogOffset(value) {
 	return brandNumber(value);
 }
 /**
-* The on-disk session format version, stamped into every newly-written {@link SessionHeader}
-* and enforced by every persistence backend on load. The single source of truth for the
-* version — write sites and the load-time check all read it.
-* While the harness is unreleased it is pinned at `0`: no compatibility is
-* implied, incompatible logs are rejected, and no migration is provided.
+* Current logical Session format version, stamped into every newly written
+* {@link SessionHeader}. Current Session and persistence code accept only this
+* value; header-only readers classify supported historical formats, while an
+* event-body read composes the build-static adjacent chain and publishes only
+* this final generation before constructing a Session.
 *
 * The version is a single monotonic integer with no major/minor split. Whether
 * a bump is needed is decided by what the WRITER emits, never by what a newer
@@ -49,12 +49,89 @@ function SessionLogOffset(value) {
 * Adding an ordinary event type does not bump — the per-event
 * {@link SessionEvent.ignorable} guard covers vocabulary growth instead. When
 * in doubt, bump: a near-identity upgrade step is almost free, a missed bump
-* makes older runtimes read new logs wrong silently. The full mechanism
-* (upgrade-step chain, in-memory view conversion, migrate-on-continue) is
-* recorded in the session-log-version-mechanism Agent Note
-* (`.agents/notes/implemented/architecture/2026-08-10-session-log-version-mechanism.md`).
+* makes older runtimes read new logs wrong silently. The released migration,
+* immutable prior-generation, and current fast-path rules are recorded in
+* `.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md`.
 */
-const SESSION_FORMAT_VERSION = 0;
+const SESSION_FORMAT_VERSION = 3;
+//#endregion
+//#region lib/types/known-event-types.js
+/**
+* GENERATED by `scripts/gen-persistence-catalog.ts` — do not edit by hand; run
+* `pnpm run gen-persistence-catalog` to regenerate (verified fresh by
+* `pnpm run verify-persistence-catalog`, part of `doc-sync`).
+* @module @deepseek-ai/dsh-session/known-event-types
+*/
+/**
+* Every `SessionEventMap` member declared in this repository — the event
+* vocabulary this build understands. The persistence read path refuses to
+* interpret a log containing a type outside this set unless the event
+* carries the envelope's `ignorable` marker (see `SessionEvent.ignorable`
+* in `./types.ts`): such a log was likely written by a newer harness, and
+* silently skipping a required event would reconstruct a wrong session.
+* Downstream (out-of-repo) plugin events are outside this list by
+* construction. The persisted `SessionEvent.ignorable` marker is the
+* compatibility mechanism; event-name registration was rejected because
+* it does not classify omission safety and would make reads
+* composition-dependent. The rationale is in
+* `.agents/notes/implemented/architecture/2026-08-30-retain-ignorable-external-session-events.md`.
+*/
+const KNOWN_SESSION_EVENT_TYPES = new Set([
+	"agent-preset/selected",
+	"agent/inbox/spliced",
+	"approval/asked",
+	"approval/decided",
+	"approval/policy",
+	"assistant/attempt",
+	"assistant/message",
+	"command/done",
+	"command/run",
+	"compaction/end",
+	"compaction/prune",
+	"compaction/start",
+	"compaction/summary",
+	"feedback/message-delete",
+	"feedback/message-put",
+	"feedback/record",
+	"goal/change",
+	"hook/invoked",
+	"hook/result",
+	"llm/retry",
+	"llm/retry-started",
+	"model/selection",
+	"permission/preset",
+	"plan/mode",
+	"request/context",
+	"request/header",
+	"sandbox/mode",
+	"schedule/change",
+	"session-log-deepseek/delivery-accepted",
+	"session/end-seed",
+	"session/title",
+	"session/title-llm-request",
+	"step/end",
+	"step/start",
+	"subagent/descriptor",
+	"subagent/model-selection-policy",
+	"system/message",
+	"team/member",
+	"team/message/delivered",
+	"team/message/queued",
+	"team/task",
+	"todo/write",
+	"tool-workflow/agent-end",
+	"tool-workflow/agent-start",
+	"tool-workflow/run-end",
+	"tool-workflow/run-start",
+	"tool/call",
+	"tool/ptc-dispatch",
+	"tool/ptc-dispatch-start",
+	"tool/result",
+	"turn/end",
+	"turn/start",
+	"user/message",
+	"web/deepseek-search-llm-request"
+]);
 //#endregion
 //#region lib/types/surface.js
 /**
@@ -68,6 +145,7 @@ const SESSION_FORMAT_VERSION = 0;
 */
 /** Runtime counterpart of the message-producing event union. */
 const SURFACE_EVENT_TYPES = new Set([
+	"system/message",
 	"user/message",
 	"assistant/message",
 	"tool/result"
@@ -75,7 +153,7 @@ const SURFACE_EVENT_TYPES = new Set([
 /**
 * Whether an event type can join the model-visible surface.
 * @param type - event type to test.
-* @returns true for one of the three message-producing event types.
+* @returns true for one of the four message-producing event types.
 */
 function isSurfaceEligibleType(type) {
 	return SURFACE_EVENT_TYPES.has(type);
@@ -115,7 +193,7 @@ function isReplacementSurfaceEvent(event) {
 }
 /**
 * Project a single event into the LLM message it derives to, or null when it
-* produces none — a non-surface event (chunk, boundary, log-only record) or an
+* produces none — a non-surface event (attempt, boundary, log-only record) or an
 * empty-content assistant/message (which exists only to host usage). This is
 * THE per-node projection rule: `Session.deriveMessages` folds it over the
 * live surface, external reconstructors and pure projections fold the same
@@ -129,6 +207,7 @@ function isReplacementSurfaceEvent(event) {
 function deriveEventMessage(event) {
 	switch (event.type) {
 		case "user/message": return event.data;
+		case "system/message":
 		case "assistant/message":
 			if (event.data.message.content.length === 0) return null;
 			return event.data.message;
@@ -136,6 +215,36 @@ function deriveEventMessage(event) {
 		default: return null;
 	}
 }
+/** Whether a payload field is a JSON object rather than an array or scalar. */
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Reject noncanonical request-header fields and contradictory tool failure metadata.
+* This does not validate complete event payloads or embedded provider streams.
+* @param event - event whose locally related payload fields are inspected.
+* @param subject - event location to include in validation errors.
+* @throws when request data/header is not an object, optional header fields are empty, or tool failure metadata contradicts its message.
+*/
+function validateSessionEventData(event, subject) {
+	const data = event.data;
+	if (event.type === "request/header") {
+		if (!isRecord(data)) throw new Error(`${subject} data must be an object`);
+		const header = data["header"];
+		if (!isRecord(header)) throw new Error(`${subject} header must be an object`);
+		if (Object.hasOwn(header, "system")) throw new Error(`${subject} must omit header.system; use system/message`);
+		if (Array.isArray(header["tools"]) && header["tools"].length === 0) throw new Error(`${subject} must omit empty tools`);
+		const defaults = header["adapterDefaults"];
+		if (isRecord(defaults) && Object.keys(defaults).length === 0) throw new Error(`${subject} must omit empty adapterDefaults`);
+	} else if (event.type === "tool/result") {
+		if (!isRecord(data)) throw new Error(`${subject} data must be an object`);
+		if (data["error"] === void 0) return;
+		const message = data["message"];
+		const content = isRecord(message) ? message["content"] : void 0;
+		const block = Array.isArray(content) ? content[0] : void 0;
+		if (!isRecord(block) || block["isError"] !== true) throw new Error(`${subject} error requires message content[0].isError === true`);
+	}
+}
 /** Create an empty surface fold state. */
 function createFoldState() {
 	return {
@@ -150,12 +259,13 @@ function isEventSeq(value) {
 /** Whether a runtime value is the exact positional-replacement shape. */
 function isReplaceOp(value) {
 	const op = value;
-	return Object.keys(op).length === 3 && Object.hasOwn(op, "op") && Object.hasOwn(op, "start") && Object.hasOwn(op, "end") && op["op"] === "replace" && isEventSeq(op["start"]) && isEventSeq(op["end"]);
+	return Object.keys(op).length === 3 && Object.hasOwn(op, "op") && Object.hasOwn(op, "startSeq") && Object.hasOwn(op, "endSeq") && op["op"] === "replace" && isEventSeq(op["startSeq"]) && isEventSeq(op["endSeq"]);
 }
 /** Validate event-local surface eligibility and return its operation. */
 function surfaceOpOf(event) {
 	const raw = event;
 	if (!isSurfaceEligibleType(event.type)) {
+		if (!KNOWN_SESSION_EVENT_TYPES.has(event.type) && event.ignorable === true) return;
 		if (raw.surfaceOp !== void 0) throw new Error(`session event "${event.type}" is not surface-eligible and cannot carry surfaceOp`);
 		if (raw.sourceEventSeqs !== void 0) throw new Error(`session event "${event.type}" is not surface-eligible and cannot carry sourceEventSeqs`);
 		return;
@@ -170,10 +280,11 @@ function surfaceOpOf(event) {
 /** Validate cited source-event seqs against prior log entries and the replacement range. */
 function assertProvenance(event, shadowedSeqs) {
 	const raw = event.sourceEventSeqs;
+	if (event.type === "assistant/message" && raw !== void 0) throw new Error("assistant/message embeds its source stream and cannot carry sourceEventSeqs");
 	const sources = /* @__PURE__ */ new Set();
 	if (raw !== void 0) {
 		if (!Array.isArray(raw)) throw new Error(`sourceEventSeqs on event at seq ${event.seq} must be an array when present`);
-		if (raw.length === 0 && event.type !== "assistant/message") throw new Error("sourceEventSeqs must not be empty except on assistant/message");
+		if (raw.length === 0) throw new Error("sourceEventSeqs must not be empty");
 		let nonEarlierSource;
 		for (const source of raw) {
 			if (!isEventSeq(source)) throw new Error(`session event "${event.type}" sourceEventSeqs must densely contain non-negative safe integers`);
@@ -186,13 +297,26 @@ function assertProvenance(event, shadowedSeqs) {
 	const missing = shadowedSeqs.filter((seq) => !sources.has(seq));
 	if (missing.length > 0) throw new Error(`surface replace: sourceEventSeqs must include every shadowed surface node; missing ${missing.join(", ")}`);
 }
+/**
+* Validate one event's surface metadata without checking membership in a log or surface.
+* @param event - event whose marker and source sequence values are inspected.
+* Unknown ignorable records retain opaque metadata and never change the surface.
+* @returns the validated operation, or undefined for a log-only or unknown ignorable event.
+* @throws when metadata violates event-local eligibility, marker, or source-sequence rules.
+*/
+function validateSurfaceMetadata(event) {
+	const op = surfaceOpOf(event);
+	if (op !== void 0 && op !== "append" && (op.startSeq >= event.seq || op.endSeq >= event.seq)) throw new Error(`surface replace at seq ${event.seq}: startSeq and endSeq must reference earlier events`);
+	if (op !== void 0) assertProvenance(event, []);
+	return op;
+}
 /** Locate one replacement range without mutating the current fold state. */
 function replacementRange(state, op) {
-	const startIdx = state.nodes.indexOf(op.start);
-	if (startIdx === -1) throw new Error(`surface replace: start seq ${op.start} not found in surface`);
-	const endIdx = state.nodes.indexOf(op.end);
-	if (endIdx === -1) throw new Error(`surface replace: end seq ${op.end} not found in surface`);
-	if (startIdx > endIdx) throw new Error(`surface replace: start seq ${op.start} (index ${startIdx}) is after end seq ${op.end} (index ${endIdx})`);
+	const startIdx = state.nodes.indexOf(op.startSeq);
+	if (startIdx === -1) throw new Error(`surface replace: start seq ${op.startSeq} not found in surface`);
+	const endIdx = state.nodes.indexOf(op.endSeq);
+	if (endIdx === -1) throw new Error(`surface replace: end seq ${op.endSeq} not found in surface`);
+	if (startIdx > endIdx) throw new Error(`surface replace: start seq ${op.startSeq} (index ${startIdx}) is after end seq ${op.endSeq} (index ${endIdx})`);
 	return {
 		startIdx,
 		endIdx,
@@ -244,26 +368,35 @@ function assertToolResultRewrite(event, shadowedSeqs, events, baseSeq) {
 		if (!isDeepEqualJson(originalRest, replacementRest)) throw new Error("tool/result surface replacement may change only content");
 	}
 }
+/**
+* Protect the system prompt at surface node 0. A replacement covering node 0
+* while that node is a `system/message` must itself be a `system/message` over
+* exactly that node; later system nodes carry no protection and a compaction
+* range may shadow them.
+*/
+function assertSystemHeadRewrite(event, state, startIdx, shadowedSeqs, events, baseSeq) {
+	if (startIdx !== 0) return;
+	if (events[state.nodes[0] - baseSeq]?.type !== "system/message") return;
+	if (event.type !== "system/message" || shadowedSeqs.length !== 1) throw new Error("surface replace: node 0 holds the system prompt and may be rewritten only by a system/message over exactly that node");
+}
 /** Validate one event at its replay boundary and prepare its atomic fold transition. */
 function planSurfaceEvent(state, event, expectedSeq, events, baseSeq) {
 	if (event.seq !== expectedSeq) throw new Error(`session event seq ${event.seq} is not contiguous; expected ${expectedSeq}`);
-	const surfaceOp = surfaceOpOf(event);
+	const surfaceOp = validateSurfaceMetadata(event);
 	if (surfaceOp === void 0) return;
-	if (surfaceOp === "append") {
-		assertProvenance(event, []);
-		return {
-			kind: "append",
-			seq: event.seq
-		};
-	}
+	if (surfaceOp === "append") return {
+		kind: "append",
+		seq: event.seq
+	};
 	const range = replacementRange(state, surfaceOp);
 	assertProvenance(event, range.shadowedSeqs);
 	assertToolResultRewrite(event, range.shadowedSeqs, events, baseSeq);
+	assertSystemHeadRewrite(event, state, range.startIdx, range.shadowedSeqs, events, baseSeq);
 	return {
 		kind: "replace",
 		seq: event.seq,
-		start: surfaceOp.start,
-		end: surfaceOp.end,
+		start: surfaceOp.startSeq,
+		end: surfaceOp.endSeq,
 		...range
 	};
 }
@@ -371,9 +504,9 @@ var SurfaceManager = class {
 * @module dsh-session/request-header
 */
 /**
-* Normalize a header to canonical form: an empty system prompt and empty tool
-* list become absent fields, matching how requests are built. Logging, folding,
-* and comparison use this one representation.
+* Normalize a header to canonical form: an empty tool list becomes an absent
+* field, matching how requests are built. Logging, folding, and comparison use
+* this one representation.
 * @param header - the header to normalize (not mutated).
 * @returns the canonical header.
 */
@@ -382,7 +515,6 @@ function canonicalHeader(header) {
 	return {
 		config: header.config,
 		...adapterDefaults?.reasoningEffort === true || adapterDefaults?.maxTokens === true ? { adapterDefaults } : {},
-		...header.system !== void 0 && header.system.length > 0 ? { system: header.system } : {},
 		...header.tools !== void 0 && header.tools.length > 0 ? { tools: header.tools } : {}
 	};
 }
@@ -394,10 +526,10 @@ function sameSchema(a, b) {
 * Field-wise equality over canonical headers. Tool schemas compare in order.
 * @param a - one canonical header.
 * @param b - the other.
-* @returns whether config, system, and tools all match.
+* @returns whether config, adapter defaults, and tools all match.
 */
 function headerEquals(a, b) {
-	if (!callConfigEquals(a.config, b.config) || a.adapterDefaults?.reasoningEffort !== b.adapterDefaults?.reasoningEffort || a.adapterDefaults?.maxTokens !== b.adapterDefaults?.maxTokens || a.system !== b.system) return false;
+	if (!callConfigEquals(a.config, b.config) || a.adapterDefaults?.reasoningEffort !== b.adapterDefaults?.reasoningEffort || a.adapterDefaults?.maxTokens !== b.adapterDefaults?.maxTokens) return false;
 	const at = a.tools ?? [];
 	const bt = b.tools ?? [];
 	return at.length === bt.length && at.every((tool, i) => sameSchema(tool, bt[i]));
@@ -575,396 +707,6 @@ function interruptedTurnClosers(events) {
 	return closers;
 }
 //#endregion
-//#region lib/types/chunk-rows.js
-/**
-* Lossless row packing for `assistant/chunk` delta runs. Providers stream
-* token-sized deltas, so a log stores hundreds of near-identical event lines
-* whose JSON envelopes dwarf their payloads (~56× measured on a real DeepSeek
-* session). This module packs each run of consecutive same-block delta chunks
-* into ONE storage row — `text-chunks`, `reasoning-chunks`, or
-* `tool-call-chunks` — and expands rows back to the exact original events.
-*
-* Packed rows are an encoding vocabulary, NOT session events: they never enter
-* `Session.snapshotEvents()`, have no `SessionEventMap` entry, and use bare (slash-less)
-* type tags so a reader cannot confuse them with the event taxonomy
-* (precedent: the JSONL header line's `session` tag). Persistence and bounded
-* history transport both use the codec. The encoder whitelists exact shapes —
-* anything it does not fully recognize stays verbatim, so unknown fields or
-* future chunk variants lose compression, never data. The decoder validates
-* before expanding and fails loud on a malformed row-tagged value instead of
-* silently dropping a whole run.
-*
-* @module @deepseek-ai/dsh-session/chunk-rows
-*/
-/**
-* Minimum members before a run packs. Below it a row's envelope rivals the
-* event lines it replaces. A format constant, not a tunable: both layouts
-* decode identically, so changing it never invalidates stored logs.
-*/
-const MIN_RUN = 3;
-function isRecord(value) {
-	return typeof value === "object" && value !== null;
-}
-/** Exact-key check: `value` has every key in `keys` and nothing else. */
-function hasExactKeys(value, keys) {
-	return Object.keys(value).length === keys.length && keys.every((k) => Object.hasOwn(value, k));
-}
-/**
-* Classify an event for packing: its delta kind when the ENTIRE shape
-* (envelope, data, chunk — exact keys, primitive types, integer seq/time) is
-* whitelisted, else `undefined` (store verbatim). Inputs come from live typed
-* appends AND parsed fixture files, so the checks are structural, not
-* type-trusted. Integer times keep gap encoding exact: a fractional time would
-* reconstruct through float subtraction/addition, which need not round-trip.
-*/
-function classify(event) {
-	if (event.type !== "assistant/chunk") return void 0;
-	if (!hasExactKeys(event, [
-		"type",
-		"seq",
-		"time",
-		"data"
-	])) return void 0;
-	if (!Number.isSafeInteger(event.seq) || event.seq < 0 || Object.is(event.seq, -0) || !Number.isSafeInteger(event.time)) return void 0;
-	const data = event.data;
-	if (!isRecord(data) || !hasExactKeys(data, [
-		"turn",
-		"step",
-		"chunk"
-	])) return void 0;
-	if (typeof data.turn !== "number" || typeof data.step !== "number") return void 0;
-	const chunk = data.chunk;
-	if (!isRecord(chunk) || typeof chunk.index !== "number") return void 0;
-	switch (chunk.type) {
-		case "text-delta":
-		case "reasoning-delta": return hasExactKeys(chunk, [
-			"type",
-			"index",
-			"text"
-		]) && typeof chunk.text === "string" ? chunk.type : void 0;
-		case "tool-call-delta": return (hasExactKeys(chunk, [
-			"type",
-			"index",
-			"id",
-			"argumentsDelta"
-		]) || hasExactKeys(chunk, [
-			"type",
-			"index",
-			"id",
-			"name",
-			"argumentsDelta"
-		]) && typeof chunk.name === "string") && typeof chunk.id === "string" && typeof chunk.argumentsDelta === "string" ? chunk.type : void 0;
-		default: return;
-	}
-}
-/** The tool-call fields of a whitelisted delta chunk (only after {@link classify} returned `'tool-call-delta'`). */
-function toolCallOf(event) {
-	return event.data.chunk;
-}
-/** The block index of a whitelisted delta chunk (not every {@link StreamChunk} variant carries one). */
-function indexOf(event) {
-	return event.data.chunk.index;
-}
-/** Whether `next` extends a run ending in `prev` (same kind already checked by the caller). */
-function continues(prev, next, kind) {
-	if (next.seq !== prev.seq + 1) return false;
-	if (!Number.isSafeInteger(next.time - prev.time)) return false;
-	if (next.data.turn !== prev.data.turn || next.data.step !== prev.data.step) return false;
-	if (indexOf(next) !== indexOf(prev)) return false;
-	if (kind !== "tool-call-delta") return true;
-	const a = toolCallOf(prev);
-	const b = toolCallOf(next);
-	return a.id === b.id && Object.hasOwn(a, "name") === Object.hasOwn(b, "name") && a.name === b.name;
-}
-/** Build the row for a completed run (`run.length >= MIN_RUN`, uniform per {@link continues}). */
-function buildRow(kind, run) {
-	const first = run[0];
-	const base = {
-		turn: first.data.turn,
-		step: first.data.step,
-		index: indexOf(first),
-		dt: run.slice(1).map((event, i) => event.time - run[i].time)
-	};
-	const envelope = {
-		seq0: first.seq,
-		time0: first.time
-	};
-	if (kind === "tool-call-delta") {
-		const call = toolCallOf(first);
-		return {
-			type: "tool-call-chunks",
-			...envelope,
-			data: {
-				...base,
-				id: brandString(call.id),
-				...Object.hasOwn(call, "name") ? { name: call.name } : {},
-				args: run.map((event) => event.data.chunk.argumentsDelta)
-			}
-		};
-	}
-	const data = {
-		...base,
-		texts: run.map((event) => event.data.chunk.text)
-	};
-	return kind === "text-delta" ? {
-		type: "text-chunks",
-		...envelope,
-		data
-	} : {
-		type: "reasoning-chunks",
-		...envelope,
-		data
-	};
-}
-/**
-* Pack an event batch for storage: each run of at least {@link MIN_RUN}
-* consecutive whitelisted same-kind, same-block delta chunk events becomes one
-* {@link ChunkRow}; every other event passes through verbatim, in order.
-* Pure and stateless — safe over any array, including a batch whose runs were
-* split by flush boundaries (the split runs simply pack per batch).
-*
-* @param events - the batch to encode, in log order.
-* @returns the storage records to write, one JSONL line each.
-*/
-function packChunkRuns(events) {
-	const out = [];
-	let kind;
-	let run = [];
-	const flush = () => {
-		if (kind !== void 0 && run.length >= MIN_RUN) out.push(buildRow(kind, run));
-		else out.push(...run);
-		kind = void 0;
-		run = [];
-	};
-	for (const event of events) {
-		const k = classify(event);
-		if (k === void 0) {
-			flush();
-			out.push(event);
-			continue;
-		}
-		const delta = event;
-		const last = run[run.length - 1];
-		if (k === kind && last !== void 0 && continues(last, delta, k)) {
-			run.push(delta);
-			continue;
-		}
-		flush();
-		kind = k;
-		run = [delta];
-	}
-	flush();
-	return out;
-}
-/** Throw the uniform malformed-row diagnostic. */
-function malformed(tag, why) {
-	throw new Error(`malformed ${tag} storage row: ${why}`);
-}
-/** Validate the shared run-data fields and the payload/dt arity; returns the member payload. */
-function validateRunData(tag, data, payloadKey) {
-	if (typeof data.turn !== "number" || typeof data.step !== "number" || typeof data.index !== "number") malformed(tag, "turn/step/index must be numbers");
-	const payload = data[payloadKey];
-	if (!Array.isArray(payload) || payload.length === 0 || payload.some((entry) => typeof entry !== "string")) malformed(tag, `${payloadKey} must be a non-empty string array`);
-	const dt = data.dt;
-	if (!Array.isArray(dt) || dt.some((gap) => !Number.isSafeInteger(gap))) malformed(tag, "dt must be an array of safe integers");
-	if (dt.length !== payload.length - 1) malformed(tag, `dt length ${dt.length} does not match ${payload.length} members`);
-	return payload;
-}
-/** Validate a row-tagged parsed value's envelope and data, throwing on any malformation. */
-function validateRow(value, tag) {
-	if (!hasExactKeys(value, [
-		"type",
-		"seq0",
-		"time0",
-		"data"
-	])) malformed(tag, "envelope must be exactly {type, seq0, time0, data}");
-	if (!Number.isSafeInteger(value.seq0) || value.seq0 < 0 || Object.is(value.seq0, -0)) malformed(tag, "seq0 must be a non-negative safe integer");
-	if (!Number.isSafeInteger(value.time0)) malformed(tag, "time0 must be a safe integer");
-	const data = value.data;
-	if (!isRecord(data)) malformed(tag, "data must be an object");
-	let payload;
-	if (tag === "tool-call-chunks") {
-		const withName = hasExactKeys(data, [
-			"turn",
-			"step",
-			"index",
-			"id",
-			"name",
-			"dt",
-			"args"
-		]);
-		if (!withName && !hasExactKeys(data, [
-			"turn",
-			"step",
-			"index",
-			"id",
-			"dt",
-			"args"
-		])) malformed(tag, "data must be exactly {turn, step, index, id, name?, dt, args}");
-		if (typeof data.id !== "string" || withName && typeof data.name !== "string") malformed(tag, "id (and name when present) must be strings");
-		payload = validateRunData(tag, data, "args");
-	} else {
-		if (!hasExactKeys(data, [
-			"turn",
-			"step",
-			"index",
-			"dt",
-			"texts"
-		])) malformed(tag, "data must be exactly {turn, step, index, dt, texts}");
-		payload = validateRunData(tag, data, "texts");
-	}
-	if (payload.length - 1 > Number.MAX_SAFE_INTEGER - value.seq0) malformed(tag, "member seqs must stay safe integers");
-	let time = value.time0;
-	for (const gap of data.dt) {
-		time += gap;
-		if (!Number.isSafeInteger(time)) malformed(tag, "member times must stay safe integers");
-	}
-	SessionSeq(value.seq0);
-	return value;
-}
-/** Expand a validated row back into its exact original events, in order. */
-function expandRow(row) {
-	const members = row.type === "tool-call-chunks" ? row.data.args : row.data.texts;
-	const events = [];
-	let time = row.time0;
-	for (let k = 0; k < members.length; k++) {
-		if (k > 0) time += row.data.dt[k - 1];
-		let chunk;
-		switch (row.type) {
-			case "text-chunks":
-				chunk = {
-					type: "text-delta",
-					index: row.data.index,
-					text: members[k]
-				};
-				break;
-			case "reasoning-chunks":
-				chunk = {
-					type: "reasoning-delta",
-					index: row.data.index,
-					text: members[k]
-				};
-				break;
-			case "tool-call-chunks":
-				chunk = {
-					type: "tool-call-delta",
-					index: row.data.index,
-					id: row.data.id,
-					...Object.hasOwn(row.data, "name") ? { name: row.data.name } : {},
-					argumentsDelta: members[k]
-				};
-				break;
-			/* v8 ignore next 4 -- validateRow only returns the three row tags */
-			default: throw new Error(`chunk-rows received unsupported row ${String(row)}`);
-		}
-		events.push({
-			type: "assistant/chunk",
-			seq: SessionSeq(row.seq0 + k),
-			time,
-			data: {
-				turn: row.data.turn,
-				step: row.data.step,
-				chunk
-			}
-		});
-	}
-	return events;
-}
-/**
-* Decode one parsed JSONL line value into the session event(s) it stores.
-* Chunk-row-tagged values validate and expand (a malformed row throws — it is
-* corrupt storage, and treating it as an event would silently drop a whole
-* run); every other value passes through as a single event after admitting a
-* numeric `seq` through the Session-sequence constructor.
-*
-* @param value - one line's `JSON.parse` result.
-* @returns the stored events, in log order.
-*/
-function decodeStorageRecord(value) {
-	if (!isRecord(value)) return [value];
-	const tag = value.type;
-	if (tag !== "text-chunks" && tag !== "reasoning-chunks" && tag !== "tool-call-chunks") {
-		if (typeof value.seq === "number") SessionSeq(value.seq);
-		return [value];
-	}
-	return expandRow(validateRow(value, tag));
-}
-//#endregion
-//#region lib/types/known-event-types.js
-/**
-* GENERATED by `scripts/gen-persistence-catalog.ts` — do not edit by hand; run
-* `pnpm run gen-persistence-catalog` to regenerate (verified fresh by
-* `pnpm run verify-persistence-catalog`, part of `doc-sync`).
-* @module @deepseek-ai/dsh-session/known-event-types
-*/
-/**
-* Every `SessionEventMap` member declared in this repository — the event
-* vocabulary this build understands. The persistence read path refuses to
-* interpret a log containing a type outside this set unless the event
-* carries the envelope's `ignorable` marker (see `SessionEvent.ignorable`
-* in `./types.ts`): such a log was likely written by a newer harness, and
-* silently skipping a required event would reconstruct a wrong session.
-* Downstream (out-of-repo) plugin events are outside this list by
-* construction. The persisted `SessionEvent.ignorable` marker is the
-* compatibility mechanism; event-name registration was rejected because
-* it does not classify omission safety and would make reads
-* composition-dependent. The rationale is in
-* `.agents/notes/implemented/architecture/2026-08-30-retain-ignorable-external-session-events.md`.
-*/
-const KNOWN_SESSION_EVENT_TYPES = new Set([
-	"agent-preset/selected",
-	"agent/inbox/spliced",
-	"approval/asked",
-	"approval/decided",
-	"approval/policy",
-	"assistant/chunk",
-	"assistant/message",
-	"command/done",
-	"command/run",
-	"compaction/end",
-	"compaction/prune",
-	"compaction/start",
-	"compaction/summary",
-	"feedback/record",
-	"goal/change",
-	"hook/invoked",
-	"hook/result",
-	"llm/retry",
-	"llm/retry-started",
-	"model/selection",
-	"permission/preset",
-	"plan/mode",
-	"request/context",
-	"request/header",
-	"sandbox/mode",
-	"schedule/change",
-	"session-log-deepseek/delivery-accepted",
-	"session/end-seed",
-	"session/title",
-	"session/title-llm-request",
-	"step/end",
-	"step/start",
-	"subagent/descriptor",
-	"subagent/model-selection-policy",
-	"team/member",
-	"team/message/delivered",
-	"team/message/queued",
-	"team/task",
-	"todo/write",
-	"tool-workflow/agent-end",
-	"tool-workflow/agent-start",
-	"tool-workflow/run-end",
-	"tool-workflow/run-start",
-	"tool/call",
-	"tool/code-dispatch",
-	"tool/code-dispatch-start",
-	"tool/result",
-	"turn/end",
-	"turn/start",
-	"user/message",
-	"web/deepseek-search-llm-request"
-]);
-//#endregion
 //#region lib/types/seq-ranges.js
 /** Lossless range encoding for JSONL `sourceEventSeqs` arrays. */
 function isStrictlyIncreasing(values) {
@@ -1034,7 +776,7 @@ function validateSessionHeader(id, input) {
 	if (input === null || typeof input !== "object" || Array.isArray(input)) throw new Error("session header is not a plain JSON record");
 	const record = input;
 	if (Object.hasOwn(record, "seedLength")) throw new Error("session header has invalid field \"seedLength\"");
-	if (record.version !== 0) throw new Error(`session header version must be 0, got ${String(record.version)}`);
+	if (record.version !== 3) throw new Error(`session header version must be 3, got ${String(record.version)}`);
 	if (record.id !== id) throw new Error(`session header id "${String(record.id)}" does not match session id "${id}"`);
 	if (typeof record.createdAt !== "number" || !Number.isSafeInteger(record.createdAt) || record.createdAt < 0) throw new Error("session header createdAt must be a non-negative safe integer");
 	if (record.cwd !== void 0) {
@@ -1059,7 +801,7 @@ function validateRestoredSessionHeader(id, input) {
 /** Detach, validate, and freeze the creation metadata published by a session. */
 function snapshotSessionHeader(id, source) {
 	const snapshot = snapshotJsonValue(source === void 0 ? {
-		version: 0,
+		version: 3,
 		id,
 		createdAt: Date.now(),
 		isSeeded: false
@@ -1074,13 +816,17 @@ function snapshotSessionHeader(id, source) {
 * Use {@link snapshotSessionEvent} when exclusive ownership is not guaranteed.
 * @param event - exclusively owned event imported across a trusted boundary.
 * @returns the same event object with a validated, deeply frozen message.
+* @throws when event-local surface metadata, request-header fields, or message invariants are invalid; history relations are not checked.
 */
 function adoptSessionEvent(event) {
+	validateSessionEventData(event, `session event at seq ${event.seq}`);
+	validateSurfaceMetadata(event);
 	assertMessageEventShape(event, `session event at seq ${event.seq}`);
 	switch (event.type) {
 		case "user/message":
 			deepFreeze(event.data);
 			break;
+		case "system/message":
 		case "assistant/message":
 		case "tool/result":
 			deepFreeze(event.data.message);
@@ -1097,23 +843,10 @@ function adoptSessionEvent(event) {
 function snapshotSessionEvent(event) {
 	return adoptSessionEvent(structuredClone(event));
 }
-/** Deep-freeze one acyclic JSON tree without consuming the JavaScript call stack. */
-function freezeRestoredObject(value) {
-	const pending = [value];
-	while (pending.length > 0) {
-		const current = pending.pop();
-		Object.freeze(current);
-		for (const key in current) {
-			const child = current[key];
-			if (child !== null && typeof child === "object") pending.push(child);
-		}
-	}
-	return value;
-}
 /** Validate the fixed event envelope after one-pass JSON materialization. */
 function assertSessionEventEnvelope(value, index) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error(`seed event at index ${index} has an invalid event envelope`);
 	const event = value;
-	if (event["type"] === "request/header-delta") throw new Error(`seed event at index ${index} uses unsupported legacy request/header-delta format`);
 	for (const key in event) switch (key) {
 		case "type":
 		case "seq":
@@ -1128,9 +861,12 @@ function assertSessionEventEnvelope(value, index) {
 	const seq = event["seq"];
 	const time = event["time"];
 	if (typeof type !== "string" || typeof seq !== "number" || !Number.isSafeInteger(seq) || seq < 0 || Object.is(seq, -0) || typeof time !== "number" || !Number.isSafeInteger(time) || event["data"] === void 0 || event["ignorable"] !== void 0 && event["ignorable"] !== true) throw new Error(`seed event at index ${index} has an invalid event envelope`);
+	validateSessionEventData(event, `seed ${type} at index ${index}`);
 	switch (type) {
 		case "request/header":
+		case "system/message":
 		case "user/message":
+		case "assistant/attempt":
 		case "assistant/message":
 		case "tool/result":
 			assertCurrentLlmShape(event, index);
@@ -1142,18 +878,31 @@ function assertCurrentLlmShape(event, index) {
 	const data = event["data"];
 	const record = typeof data === "object" && data !== null ? data : void 0;
 	if (event["type"] === "request/header") {
-		const header = record?.["header"];
-		const headerRecord = typeof header === "object" && header !== null && !Array.isArray(header) ? header : void 0;
-		const config = headerRecord?.["config"];
+		const headerRecord = record?.["header"];
+		const config = headerRecord["config"];
 		if (!hasProviderModel(config)) throw new Error(`seed request/header at index ${index} lacks provider/model`);
 		const configRecord = config;
 		const reasoningEffort = configRecord["reasoningEffort"];
 		if (reasoningEffort !== void 0 && (typeof reasoningEffort !== "string" || reasoningEffort.length === 0)) throw new Error(`seed request/header at index ${index} has an invalid reasoningEffort`);
-		assertAdapterDefaults(headerRecord?.["adapterDefaults"], configRecord, index);
+		assertAdapterDefaults(headerRecord["adapterDefaults"], configRecord, index);
+		const reason = record?.["reason"];
+		if (reason !== "initial" && reason !== "resume" && reason !== "change" && reason !== "series") throw new Error(`seed request/header at index ${index} has an invalid reason`);
+		if (record?.["startsSeries"] !== void 0 && record["startsSeries"] !== true) throw new Error(`seed request/header at index ${index} has an invalid startsSeries marker`);
 	}
 	const type = event["type"];
-	if (type !== "user/message" && type !== "assistant/message" && type !== "tool/result") return;
+	if (type === "assistant/attempt") {
+		assertAssistantSettlementShape(record, type, index);
+		return;
+	}
+	if (!isMessageEventType(type)) return;
 	assertMessageEventShape(event, `seed ${type} at index ${index}`);
+	if (type === "assistant/message") assertAssistantSettlementShape(record, type, index);
+}
+/** Validate fields used directly by restored Session lifecycle logic without replaying the embedded stream. */
+function assertAssistantSettlementShape(data, type, index) {
+	const turn = data?.["turn"];
+	const step = data?.["step"];
+	if (typeof turn !== "number" || !Number.isSafeInteger(turn) || turn < 0 || Object.is(turn, -0) || typeof step !== "number" || !Number.isSafeInteger(step) || step < 0 || Object.is(step, -0) || !Array.isArray(data?.["stream"])) throw new Error(`seed ${type} at index ${index} has invalid settlement fields`);
 }
 const allowedAdapterKeys = new Set(["reasoningEffort", "maxTokens"]);
 /** Validate adapter-default markers imported from a durable request header. */
@@ -1163,21 +912,35 @@ function assertAdapterDefaults(value, config, index) {
 	const defaults = value;
 	if (Object.keys(defaults).some((key) => !allowedAdapterKeys.has(key)) || Object.values(defaults).some((marker) => marker !== true) || defaults["reasoningEffort"] === true && config["reasoningEffort"] === void 0 || defaults["maxTokens"] === true && config["maxTokens"] === void 0) throw new Error(`seed request/header at index ${index} has invalid adapterDefaults`);
 }
+/** The four surface event types whose payload carries an identified message. */
+function isMessageEventType(type) {
+	return type === "system/message" || type === "user/message" || type === "assistant/message" || type === "tool/result";
+}
+const MESSAGE_ROLE_BY_TYPE = {
+	"system/message": "system",
+	"user/message": "user",
+	"assistant/message": "assistant",
+	"tool/result": "user"
+};
 /** Validate only the event-specific invariants needed to safely replay a message. */
 function assertMessageEventShape(event, subject) {
 	const type = event["type"];
-	if (type !== "user/message" && type !== "assistant/message" && type !== "tool/result") return;
+	if (!isMessageEventType(type)) return;
 	const data = event["data"];
 	const record = typeof data === "object" && data !== null ? data : void 0;
 	const message = type === "user/message" ? record : record?.["message"];
 	if (typeof message !== "object" || message === null || typeof message["id"] !== "string" || message["id"] === "") throw new Error(`${subject} lacks an identified message`);
 	const messageRecord = message;
-	const expectedRole = type === "assistant/message" ? "assistant" : "user";
+	const expectedRole = MESSAGE_ROLE_BY_TYPE[type];
 	if (messageRecord["role"] !== expectedRole) throw new Error(`${subject} message must have role "${expectedRole}"`);
 	const source = messageRecord["source"];
 	if (typeof source !== "object" || source === null || typeof source["kind"] !== "string" || source["kind"] === "") throw new Error(`${subject} message has invalid source`);
 	if (!Array.isArray(messageRecord["content"])) throw new Error(`${subject} message has invalid content`);
 	const sourceRecord = source;
+	if (type === "system/message") {
+		if (sourceRecord["kind"] !== "plugin" || typeof sourceRecord["plugin"] !== "string" || sourceRecord["plugin"] === "") throw new Error(`${subject} message must have plugin source`);
+		return;
+	}
 	if (type === "assistant/message") {
 		if (sourceRecord["kind"] !== "model" || !hasProviderModel(sourceRecord)) throw new Error(`${subject} message must have model source`);
 		return;
@@ -1195,11 +958,6 @@ function hasProviderModel(value) {
 	const pair = value;
 	return typeof pair["provider"] === "string" && pair["provider"].length > 0 && typeof pair["model"] === "string" && pair["model"].length > 0;
 }
-/** Reject request-header vocabulary removed with the legacy delta codec. */
-function assertSupportedRequestHeader(type, data, location) {
-	if (type === "request/header-delta") throw new Error(`${location} uses unsupported legacy request/header-delta format`);
-	if (type === "request/header" && data !== null && typeof data === "object" && !Array.isArray(data) && data["reason"] === "fallback") throw new Error(`${location} uses unsupported legacy request/header reason "fallback"`);
-}
 /** Resolve one listener snapshot, including Cordis's internal dispatch checks. */
 function collectSessionCallbacks(ctx, args) {
 	return [...ctx.events.dispatch("emit", args)];
@@ -1252,9 +1010,10 @@ var Session = class Session {
 	* The first seq appended IN THIS PROCESS: the length of the constructor
 	* seed (0 without one). Events with smaller seq values entered through
 	* construction — replay, fork, or resume — and were never published on the
-	* `session/event` firehose (constructor seeds do not emit), so consumers
-	* that replay the log as a publication substitute (telemetry adoption)
-	* start here. Distinct from {@link inheritedEventCount}, the DURABLE
+	* `session/event` firehose (constructor seeds do not emit). This offset marks
+	* the constructor-input boundary for lifecycle ownership and persistence
+	* adoption; consumers that need complete canonical history still start at
+	* seq 0. Distinct from {@link inheritedEventCount}, the DURABLE
 	* fork-lineage cut: a resumed session's constructor seed is its full stored
 	* log, while the inherited count keeps the original fork value — this field is the
 	* in-process construction fact.
@@ -1284,32 +1043,34 @@ var Session = class Session {
 		return new Session(id, seed, header, "snapshot", inheritedEventCount);
 	}
 	/**
-	* Restore a detached session by taking ownership of fresh persistence values.
-	* The storage format, event envelopes, sequence continuity, surface transitions,
-	* and header fields are validated before the restored objects are frozen.
+	* Restore a detached session by adopting an independently owned or deeply frozen seed.
+	* Runtime-required event fields, event envelopes, sequence continuity, surface
+	* transitions, and header fields are validated without copying or freezing events.
+	* Embedded Assistant streams remain opaque until a stream consumer or storage
+	* verifier reads them.
 	* @param id - restored session identity.
-	* @param seed - fresh detached events whose ownership is transferred.
-	* @param header - fresh detached metadata whose ownership is transferred.
+	* @param seed - independently owned or deeply frozen events.
+	* @param header - independently owned storage metadata.
 	* @param inheritedEventCount - exact fork-inherited prefix length decoded from storage.
+	* @param eventState - aliasing state carried from the operation that produced the seed.
 	* @returns a restored detached session.
 	*/
-	static fromRestore(id, seed, header, inheritedEventCount) {
-		return new Session(id, seed, header, "restore", inheritedEventCount);
+	static fromRestore(id, seed, header, inheritedEventCount, eventState) {
+		return new Session(id, seed, header, eventState, inheritedEventCount);
 	}
 	constructor(id, seed, header, mode = "snapshot", suppliedInheritedEventCount) {
-		const restoredHeader = mode === "restore" ? validateRestoredSessionHeader(id, header) : void 0;
+		const restoredHeader = mode === "snapshot" ? void 0 : validateRestoredSessionHeader(id, header);
 		if (seed !== void 0) for (const [index, source] of seed.entries()) {
-			const snapshot = mode === "restore" ? source : snapshotJsonValue(source);
+			const snapshot = mode === "snapshot" ? snapshotJsonValue(source) : source;
 			if (snapshot === void 0) throw new Error(`seed event at index ${index} is not losslessly JSON-serializable`);
 			assertSessionEventEnvelope(snapshot, index);
-			assertSupportedRequestHeader(snapshot.type, snapshot.data, `seed event at index ${index}`);
 			if (snapshot.seq !== index) throw new Error(`seed event at index ${index} has seq ${snapshot.seq} (expected ${index}); seed must be contiguous from 0`);
 			try {
 				this.surfaceManager.validateNext(snapshot);
 			} catch (error) {
 				throw new Error(`invalid seed event at index ${index}: ${error instanceof Error ? error.message : "invalid surface metadata"}`);
 			}
-			this.log.push(mode === "restore" ? freezeRestoredObject(snapshot) : deepFreeze(snapshot));
+			this.log.push(mode === "snapshot" ? deepFreeze(snapshot) : snapshot);
 		}
 		this.firstLiveSeq = SessionLogOffset(this.log.length);
 		this.header = restoredHeader ?? snapshotSessionHeader(id, header);
@@ -1318,8 +1079,10 @@ var Session = class Session {
 		const inheritedEventCount = SessionLogOffset(suppliedInheritedEventCount ?? 0);
 		if (!this.header.isSeeded && inheritedEventCount !== 0) throw new Error("unseeded session inherited event count must be 0");
 		if (inheritedEventCount > this.log.length) throw new Error("session inherited event count exceeds its event log");
+		if (mode === "snapshot" && this.header.isSeeded && inheritedEventCount !== this.log.length) throw new Error("seeded session constructor seed must equal its inherited prefix");
 		this.inheritedEventCount = inheritedEventCount;
-		if (seed !== void 0 && this.log.at(-1)?.type !== "session/end-seed") this.append("session/end-seed", {});
+		if (seed !== void 0 && mode === "snapshot" && this.header.isSeeded) this.append("session/end-seed", { inherited: true });
+		else if (seed !== void 0 && this.log.at(-1)?.type !== "session/end-seed") this.append("session/end-seed", {});
 	}
 	/** Cached immutable full snapshot of the private append-only log. */
 	eventsSnapshot;
@@ -1382,7 +1145,8 @@ var Session = class Session {
 	*   declare how it joins the surface, the sole source of derived model
 	*   history) and
 	*   rejected by the compiler for non-surface types like `turn/start` or
-	*   `assistant/chunk`.
+	*   `assistant/attempt`. Assistant messages embed their exact provider
+	*   stream and cannot cite top-level source events.
 	* @returns the logged event — its assigned `seq`/`time` plus the SNAPSHOT of
 	*   `data` that entered the log, so reading `event.data` back sees the logged
 	*   value, never the caller's still-mutable input.
@@ -1390,6 +1154,7 @@ var Session = class Session {
 	*   (BigInt, function, symbol, undefined, negative zero, non-finite number,
 	*   circular reference, sparse array, or an exotic object such as
 	*   Map/Set/Date/class instance), or when the candidate violates the
+	*   request-header empty-field or tool-error consistency rules, or the
 	*   canonical surface contract (marker shape and eligibility, unique
 	*   earlier source-event references, positional replacement validity, and complete
 	*   shadowed-node coverage). One iterative pass reads, validates, and
@@ -1408,7 +1173,6 @@ var Session = class Session {
 		};
 		const dataSnapshot = snapshotJsonValue(data);
 		if (dataSnapshot === void 0) throw new Error(`session event "${type}" carries non-JSON-serializable data`);
-		assertSupportedRequestHeader(type, dataSnapshot, `session event "${type}"`);
 		const surfaceMetadataSnapshot = snapshotJsonValue(surfaceMetadata);
 		if (surfaceMetadataSnapshot === void 0) throw new Error(`session event "${type}" carries non-JSON-serializable surface metadata`);
 		const entry = attachments.get(this);
@@ -1420,6 +1184,7 @@ var Session = class Session {
 			data: dataSnapshot,
 			...surfaceMetadataSnapshot
 		});
+		validateSessionEventData(event, `session event "${type}" at seq ${event.seq}`);
 		this.surfaceManager.validateNext(event);
 		if (entry !== void 0) entry.appending = true;
 		try {
@@ -1537,8 +1302,9 @@ var SessionForkError = class extends Error {
 /**
 * In-memory session store (`ctx.sessions`).
 *
-* Persistence is intentionally not implemented here — persistence plugins
-* subscribe to `session/event` and flush on `session/flush` / dispose.
+* Persistence is intentionally not implemented here — the agent lifecycle
+* attaches a session-log writer to each published session's write handle;
+* a session published outside that lifecycle persists nothing.
 */
 var SessionStore = class extends Service {
 	store = /* @__PURE__ */ new Map();
@@ -1595,10 +1361,9 @@ var SessionStore = class extends Service {
 	*
 	* @param id - the session id; omitted, the store mints `session-<n>`.
 	* @param options - seed events and/or creation metadata for the header. With
-	*   `seedSource: 'persistence'`, metadata and events must be fresh detached
-	*   graphs whose ownership transfers to this call: they are validated and
-	*   frozen in place through {@link Session.fromRestore}, so the caller must
-	*   retain no mutable aliases.
+	*   `eventState`, every seed event is either independently owned or any
+	*   shared value is deeply frozen; {@link Session.fromRestore} validates and
+	*   adopts those values without copying or freezing them.
 	* @returns the constructed session, NOT yet in the store.
 	* @throws if a session with `id` already exists, metadata is not a plain
 	*   lossless-JSON record with valid scalar fields, or `meta.cwd` is a
@@ -1611,11 +1376,20 @@ var SessionStore = class extends Service {
 		while (this.store.has(sessionId));
 		else sessionId = brandString(id);
 		if (this.store.has(sessionId)) throw new Error(`session "${sessionId}" already exists`);
-		if (options?.seedSource === "persistence") return Session.fromRestore(sessionId, options.seed, options.meta, options.inheritedEventCount);
+		if (options !== void 0) {
+			const { eventState } = options;
+			switch (eventState) {
+				case "detached":
+				case "shared-frozen": return Session.fromRestore(sessionId, options.seed, options.meta, options.inheritedEventCount, eventState);
+				case void 0: break;
+				/* v8 ignore next -- closed-union exhaustiveness guard */
+				default: assertNever(eventState, "SessionStore.prepare event state");
+			}
+		}
 		const seed = options?.seed;
 		const meta = options?.meta;
 		const header = {
-			version: 0,
+			version: 3,
 			id: sessionId,
 			createdAt: meta?.createdAt ?? Date.now(),
 			...meta?.cwd === void 0 ? {} : { cwd: meta.cwd },
@@ -1847,4 +1621,4 @@ var SessionStore = class extends Service {
 	}
 };
 //#endregion
-export { KNOWN_SESSION_EVENT_TYPES, SESSION_FORMAT_VERSION, Session, SessionForkError, SessionId, SessionLogOffset, SessionPreparation, SessionSeq, SessionStore, SessionStore as default, TOOL_NOT_STARTED, TOOL_OUTCOME_UNKNOWN, adoptSessionEvent, canonicalHeader, decodeSeqRanges, decodeStorageRecord, deriveEventMessage, encodeSeqRanges, foldRequestHeader, foldSurface, headerEquals, interruptedTurnClosers, isAppendSurfaceEvent, isReplacementSurfaceEvent, isSurfaceEligibleType, isSurfaceEvent, packChunkRuns, snapshotSessionEvent };
+export { KNOWN_SESSION_EVENT_TYPES, SESSION_FORMAT_VERSION, Session, SessionForkError, SessionId, SessionLogOffset, SessionPreparation, SessionSeq, SessionStore, SessionStore as default, TOOL_NOT_STARTED, TOOL_OUTCOME_UNKNOWN, adoptSessionEvent, canonicalHeader, decodeSeqRanges, deriveEventMessage, encodeSeqRanges, foldRequestHeader, foldSurface, headerEquals, interruptedTurnClosers, isAppendSurfaceEvent, isReplacementSurfaceEvent, isSurfaceEligibleType, isSurfaceEvent, snapshotSessionEvent };