@deepseek-ai/dsh-session 0.2.1-rc.5 → 0.2.2-alpha.3

package/README.i18n.yaml

@@ -18,11 +18,11 @@
   en: 0882d4056c45aa75
   zh: fcee78e9845b78b3
 /deepseek-ai-dsh-session/use-this-package/create-and-inspect-sessions:
-  en: f80dab583fa3939d
-  zh: 5a9a79ebcef86119
+  en: 971e583b3d6c1af8
+  zh: c7da934ecb8f1e87
 /deepseek-ai-dsh-session/use-this-package/append-and-derive:
-  en: aa5f1951ecf3ac0c
-  zh: 62a599ace8f2bf15
+  en: c9ad40c8a8f2cd0b
+  zh: 0b76ae73f39bbb18
 /deepseek-ai-dsh-session/use-this-package/read-the-log:
   en: c4bf3103b9762b6c
   zh: 369c734bb20de2ea

package/README.md

@@ -29,7 +29,9 @@ Mount `dsh-session` wherever a session must exist. It creates and holds event-so
 
 ### Create and inspect sessions
 
-`ctx.sessions.create()` builds a live session bound to the calling fiber; `get(id)` and `list()` find sessions, and `fork()` creates a child session from a stable prefix of a live one.
+`ctx.sessions.create()` builds a live session bound to the calling fiber; `get(id)` and `list()` find sessions, and `fork()` creates an independent session from a stable prefix of a live one. It copies history, `cwd`, `isSeeded`, and the inherited event count without recording a source relationship. `parentSession` records a subagent’s direct creator; historical ordinary forks may retain their source there, so classification uses `origin`.
+
+Independent `Session.create()` and `Session.fromRestore()` instances accept events and plugin records without sending `session/event`. A `SessionStore` takes ownership through `prepare()` or `enter()`; writes then require store membership and a completed synchronous `session/created` announcement. Creation listeners are read-only and see all existing history; entering an independent instance does not replay that history as `session/event`. Failed announcement or removal leaves writes disabled. Removal emits `session/disposed` only if `session/created` began, including a failed announcement; an entered but never announced instance emits neither notification.
 
 ```text
 const session = ctx.sessions.create(sessionId, { meta: { cwd: '/workspace' } })
@@ -39,7 +41,7 @@ ctx.sessions.list()              // every live session, in creation order
 
 ### Append and derive
 
-`session.append(type, data, opts?)` commits one typed event — it snapshots and freezes the payload, validates it as lossless JSON, and notifies observers. `session.deriveMessages()` projects the log into the `Message[]` the model sees, incrementally and cached:
+`session.append(type, data, opts?)` commits one typed event. It rejects read-only instances before reading payload fields, snapshots and freezes valid JSON, then rechecks write permission before committing and notifying observers. `session.deriveMessages()` projects the log into the `Message[]` the model sees, incrementally and cached:
 
 ```text
 session.append('user/message', { role: 'user', content: [{ type: 'text', text: 'hello' }], source: { kind: 'user' } },

package/README.zh.md

@@ -29,7 +29,9 @@ kind: "package-reference"
 
 ### 创建与检查会话
 
-`ctx.sessions.create()` 构建绑定到调用方 fiber 的实时会话；`get(id)` 与 `list()` 查找会话，`fork()` 从实时会话的精确前缀创建子会话。
+`ctx.sessions.create()` 构建绑定到调用方 fiber 的实时会话；`get(id)` 与 `list()` 查找会话，`fork()` 从实时会话的精确前缀创建独立会话。它复制历史、`cwd`、`isSeeded` 和继承事件数，不记录来源关系。`parentSession` 记录子代理的直接创建者；历史普通 fork 可能仍在此字段保留来源，因此分类使用 `origin`。
+
+独立的 `Session.create()` 和 `Session.fromRestore()` 实例接受事件和插件记录，但不发送 `session/event`。`SessionStore` 通过 `prepare()` 或 `enter()` 接管实例；此后只有实例仍在 Store 中且同步 `session/created` 宣告已完成时才能写入。创建监听器只能读取，并能看到全部已有历史；独立实例进入 Store 时不会把已有历史重放为 `session/event`。宣告失败或移除后仍禁止写入。只有开始过 `session/created` 宣告的实例在移除时发出 `session/disposed`，宣告失败也不例外；进入 Store 但从未宣告的实例不发出这两个通知。
 
 ```text
 const session = ctx.sessions.create(sessionId, { meta: { cwd: '/workspace' } })
@@ -39,7 +41,7 @@ ctx.sessions.list()              // every live session, in creation order
 
 ### 追加与派生
 
-`session.append(type, data, opts?)` 提交一个类型化事件——它先快照并冻结载荷、校验其为无损 JSON，再通知观察者。`session.deriveMessages()` 把日志投影为模型看到的 `Message[]`，采用增量且有缓存的方式：
+`session.append(type, data, opts?)` 提交一个类型化事件。它在读取载荷字段前拒绝只读实例，为有效 JSON 创建快照并冻结，再次检查写入权限后提交并通知观察者。`session.deriveMessages()` 把日志投影为模型看到的 `Message[]`，采用增量且有缓存的方式：
 
 ```text
 session.append('user/message', { role: 'user', content: [{ type: 'text', text: 'hello' }], source: { kind: 'user' } },

package/lib/index.js

@@ -1238,7 +1238,7 @@ function invokeContainedSessionObservers(ctx, name, id, args, callbacks) {
 		ctx.logger.warn(`session "${id}": ${name} listener threw: ${String(error)}`);
 	}
 }
-/** Store attachment for the append path; module-private to keep Session store-agnostic publicly. */
+/** Store-owned Sessions retain a null entry while unentered; absent keys are independent. */
 const attachments = /* @__PURE__ */ new WeakMap();
 /**
 * Grammar of a {@link PluginRecordType}: `plugin:` followed by
@@ -1288,7 +1288,9 @@ let commitPluginRecord;
 *   with a letter or digit.
 * @param data - JSON payload, snapshotted before it enters the log.
 * @returns the sequence number of the committed record.
-* @throws when `type` is outside that grammar, when `data` is not losslessly
+* @throws when a store-owned Session is unentered or its creation announcement
+*   has not completed, when `type` is outside
+*   that grammar, when `data` is not losslessly
 *   JSON-serializable, or when the call reenters another append's publication;
 *   a rejected record does not change the log.
 */
@@ -1484,6 +1486,9 @@ var Session = class Session {
 	* the log, the append is committed: observer failures are logged and
 	* contained per listener, so they do not change the return value or prevent
 	* later listeners from observing the same accepted event.
+	* Independent Sessions append without notifying store observers. Once a store
+	* prepares or enters the instance, writes require a completed creation
+	* announcement and remain disabled after removal.
 	*
 	* @param type - The event type (key of {@link SessionEventMap}).
 	* @param data - The event payload; must be JSON-serializable.
@@ -1499,7 +1504,9 @@ var Session = class Session {
 	* @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.
-	* @throws if `data` or surface metadata is not losslessly JSON-serializable
+	* @throws if a store-owned Session is unentered or its creation announcement
+	*   has not completed, or if `data` or surface
+	*   metadata is not losslessly JSON-serializable
 	*   (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
@@ -1515,6 +1522,7 @@ var Session = class Session {
 	*   rejects before the log changes.
 	*/
 	append(type, data, ...opts) {
+		this.publicationEntry();
 		const surfaceOpts = opts[0];
 		const surfaceMetadata = {
 			...surfaceOpts?.sourceEventSeqs === void 0 ? {} : { sourceEventSeqs: surfaceOpts.sourceEventSeqs },
@@ -1546,6 +1554,7 @@ var Session = class Session {
 	* @returns the record's sequence number.
 	*/
 	#appendRecord(type, data) {
+		this.publicationEntry();
 		const dataSnapshot = snapshotJsonValue(data);
 		if (dataSnapshot === void 0) throw new Error(`plugin record "${type}" carries non-JSON-serializable data`);
 		const entry = this.publicationEntry();
@@ -1561,12 +1570,13 @@ var Session = class Session {
 		return record.seq;
 	}
 	/**
-	* Read the store attachment for one append, refusing an append that
-	* reenters while another append is being published.
-	* @returns the attachment, or undefined for a detached Session.
+	* Require announced membership for store-owned Sessions and refuse reentrant publication.
+	* @returns the current store attachment, or undefined for an independent Session.
 	*/
 	publicationEntry() {
 		const entry = attachments.get(this);
+		if (entry === null) throw new Error(`session "${this.id}" cannot append outside a SessionStore`);
+		if (entry !== void 0 && entry.announcement !== "complete") throw new Error(`session "${this.id}" cannot append before session/created completes`);
 		if (entry?.appending) throw new Error("session append cannot reenter while another append is being published");
 		return entry;
 	}
@@ -1580,20 +1590,19 @@ var Session = class Session {
 		this.surfaceManager.validateNext(event);
 		if (entry !== void 0) entry.appending = true;
 		try {
-			let callbacks;
 			const callbackArgs = [this, event];
-			if (entry !== void 0) callbacks = collectSessionCallbacks(entry.emitCtx, [
+			const callbacks = entry === void 0 ? void 0 : collectSessionCallbacks(entry.emitCtx, [
 				entry.carrier,
 				"session/event",
 				...callbackArgs
 			]);
 			this.log.push(event);
 			this.eventsSnapshot = void 0;
-			if (callbacks !== void 0 && entry !== void 0) invokeContainedSessionObservers(entry.emitCtx, "session/event", entry.id, callbackArgs, callbacks);
+			if (entry !== void 0 && callbacks !== void 0) invokeContainedSessionObservers(entry.emitCtx, "session/event", entry.id, callbackArgs, callbacks);
 		} finally {
 			if (entry !== void 0) {
 				entry.appending = false;
-				if (entry.detachRequested && !entry.announcing) entry.detach();
+				if (entry.detachRequested && entry.announcement !== "dispatching") entry.detach();
 			}
 		}
 	}
@@ -1791,7 +1800,7 @@ var SessionStore = class extends Service {
 	*   `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.
+	* @returns the store-owned session, not yet entered and read-only until announced.
 	* @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
 	*   non-absolute path.
@@ -1807,7 +1816,11 @@ var SessionStore = class extends Service {
 			const { eventState } = options;
 			switch (eventState) {
 				case "detached":
-				case "shared-frozen": return Session.fromRestore(sessionId, options.seed, options.meta, options.inheritedEventCount, eventState, this.projections);
+				case "shared-frozen": {
+					const session = Session.fromRestore(sessionId, options.seed, options.meta, options.inheritedEventCount, eventState, this.projections);
+					attachments.set(session, null);
+					return session;
+				}
 				case void 0: break;
 				/* v8 ignore next -- closed-union exhaustiveness guard */
 				default: assertNever(eventState, "SessionStore.prepare event state");
@@ -1826,11 +1839,14 @@ var SessionStore = class extends Service {
 			...meta?.delegationDepth === void 0 ? {} : { delegationDepth: meta.delegationDepth },
 			...meta?.agentPreset === void 0 ? {} : { agentPreset: meta.agentPreset }
 		};
-		return Session.create(sessionId, seed, header, options?.inheritedEventCount, this.projections);
+		const session = Session.create(sessionId, seed, header, options?.inheritedEventCount, this.projections);
+		attachments.set(session, null);
+		return session;
 	}
 	/**
-	* Enter a {@link prepare}d session into the store: install the module-private
-	* append publication hooks and add it to the store. Returns the DETACH
+	* Enter a session into the store: install the module-private
+	* append publication hooks and add it to the store. Writes remain disabled
+	* until {@link announce} completes successfully. Returns the DETACH
 	* disposer (hooks + store removal). Does NOT emit `session/created` —
 	* the caller yields this disposer inside its effect and THEN calls
 	* {@link announce}, so a throwing `session/created` listener rolls the attach
@@ -1844,7 +1860,7 @@ var SessionStore = class extends Service {
 	* the two back-to-back so they never trip this, but the public API cannot
 	* assume that.
 	*
-	* @param session - a {@link prepare}d session not yet in the store.
+	* @param session - an unentered session; independent instances become store-owned.
 	* @returns the detach disposer (publication hooks + store removal). When called from
 	*   a synchronous `session/created` listener, removal and disposal wait until
 	*   that creation dispatch unwinds.
@@ -1854,14 +1870,13 @@ var SessionStore = class extends Service {
 		const id = session.id;
 		const carrier = scopeTarget(session, scopeOf(this.ctx));
 		if (this.store.has(id)) throw new Error(`session "${id}" already exists`);
-		if (attachments.has(session)) throw new Error(`session "${id}" is already attached to a store`);
+		if (attachments.get(session) != null) throw new Error(`session "${id}" is already attached to a store`);
 		const entry = {
 			id,
 			session,
 			carrier,
 			emitCtx: this.ctx,
-			announced: false,
-			announcing: false,
+			announcement: "pending",
 			appending: false,
 			detachRequested: false,
 			detach: () => {
@@ -1874,7 +1889,7 @@ var SessionStore = class extends Service {
 		const detach = () => {
 			if (!entered) return;
 			entered = false;
-			if (entry.announcing || entry.appending) {
+			if (entry.announcement === "dispatching" || entry.appending) {
 				entry.detachRequested = true;
 				return;
 			}
@@ -1888,22 +1903,23 @@ var SessionStore = class extends Service {
 		/* v8 ignore next -- enter() rejects replacement while this single-shot detach capability is live. */
 		if (this.store.get(entry.id) !== entry) return;
 		this.store.delete(entry.id);
-		attachments.delete(entry.session);
-		if (entry.announced) this.emitDisposed(entry);
+		attachments.set(entry.session, null);
+		if (entry.announcement !== "pending") this.emitDisposed(entry);
 	}
 	/** Emit `session/created` exactly once for an {@link enter}ed session (with
 	* the carrier {@link enter} captured). Separate from {@link enter} so the
 	* caller can yield the detach disposer first (rollback safety — see
-	* {@link enter}).
+	* {@link enter}). The Session remains read-only throughout synchronous
+	* dispatch; successful completion enables appends. A failed announcement
+	* leaves it read-only and cannot be retried.
 	* @param session - the entered session to announce to listeners.
 	* @throws if the session is not live or its announcement already began,
 	*   including a reentrant call from a creation listener. */
 	announce(session) {
 		const entry = this.liveEntryFor(session);
-		if (entry.announced || entry.announcing) throw new Error(`session "${entry.id}" was already announced`);
-		entry.announced = true;
+		if (entry.announcement !== "pending") throw new Error(`session "${entry.id}" was already announced`);
 		const callbackArgs = [session];
-		entry.announcing = true;
+		entry.announcement = "dispatching";
 		try {
 			const callbacks = collectSessionCallbacks(this.ctx, [
 				entry.carrier,
@@ -1916,9 +1932,12 @@ var SessionStore = class extends Service {
 					this.ctx.logger.warn(`session "${entry.id}": session/created listener rejected: ${String(error)}`);
 				});
 			}
+			entry.announcement = "complete";
+		} catch (error) {
+			entry.announcement = "failed";
+			throw error;
 		} finally {
-			entry.announcing = false;
-			if (entry.detachRequested && !entry.appending) entry.detach();
+			if (entry.detachRequested) entry.detach();
 		}
 	}
 	/** Emit the paired teardown notification with per-listener containment. */
@@ -1969,7 +1988,7 @@ var SessionStore = class extends Service {
 	/** Return the exact live entry; detached/prepared objects reject. */
 	liveEntryFor(session) {
 		const entry = attachments.get(session);
-		if (entry === void 0 || this.store.get(entry.id) !== entry) throw new Error(`session "${session.id}" is not live in this store`);
+		if (entry == null || this.store.get(entry.id) !== entry) throw new Error(`session "${session.id}" is not live in this store`);
 		return entry;
 	}
 	/**
@@ -1988,7 +2007,7 @@ var SessionStore = class extends Service {
 		return [...this.store.values()].map((entry) => entry.session);
 	}
 	/**
-	* Create a live child session from an exact prefix of a live source.
+	* Create an independent live session from an exact prefix of a live source.
 	* `boundary` is an inclusive source event seq; omitted means the source's
 	* current last event. An open tail receives synthetic tool results and
 	* step/turn closers with the forked cause. Closed steps and turns remain
@@ -2014,7 +2033,6 @@ var SessionStore = class extends Service {
 			inheritedEventCount: SessionLogOffset(resolved === void 0 ? 0 : resolved + 1),
 			meta: {
 				...liveSource.header.cwd !== void 0 ? { cwd: liveSource.header.cwd } : {},
-				parentSession: liveSource.id,
 				isSeeded: true
 			}
 		});

package/lib/types/index.d.ts

@@ -29,8 +29,10 @@ declare module '@deepseek-ai/cordis' {
     }
     interface Events {
         /**
-         * Creation announcement during session publication. A synchronous throw vetoes and rolls
-         * back with a paired disposal; detach requested during dispatch is deferred.
+         * Read-only creation announcement after store entry.
+         * New events reject until every synchronous listener has returned successfully.
+         * A synchronous throw vetoes creation and rolls back with a paired disposal;
+         * detach requested during dispatch is deferred.
          * A returned-promise rejection is logged but cannot retroactively veto this
          * synchronous boundary.
          * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners
@@ -110,7 +112,9 @@ export declare function snapshotSessionEvent<T extends SessionEvent>(event: T):
  *   with a letter or digit.
  * @param data - JSON payload, snapshotted before it enters the log.
  * @returns the sequence number of the committed record.
- * @throws when `type` is outside that grammar, when `data` is not losslessly
+ * @throws when a store-owned Session is unentered or its creation announcement
+ *   has not completed, when `type` is outside
+ *   that grammar, when `data` is not losslessly
  *   JSON-serializable, or when the call reenters another append's publication;
  *   a rejected record does not change the log.
  */
@@ -244,6 +248,9 @@ export declare class Session {
      * the log, the append is committed: observer failures are logged and
      * contained per listener, so they do not change the return value or prevent
      * later listeners from observing the same accepted event.
+     * Independent Sessions append without notifying store observers. Once a store
+     * prepares or enters the instance, writes require a completed creation
+     * announcement and remain disabled after removal.
      *
      * @param type - The event type (key of {@link SessionEventMap}).
      * @param data - The event payload; must be JSON-serializable.
@@ -259,7 +266,9 @@ export declare class Session {
      * @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.
-     * @throws if `data` or surface metadata is not losslessly JSON-serializable
+     * @throws if a store-owned Session is unentered or its creation announcement
+     *   has not completed, or if `data` or surface
+     *   metadata is not losslessly JSON-serializable
      *   (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
@@ -276,9 +285,8 @@ export declare class Session {
      */
     append<T extends SessionEventType>(type: T, data: SessionEventMap[T], ...opts: T extends SurfaceEventType ? [opts: SurfaceIntent<T>] : []): SessionEvent<T>;
     /**
-     * Read the store attachment for one append, refusing an append that
-     * reenters while another append is being published.
-     * @returns the attachment, or undefined for a detached Session.
+     * Require announced membership for store-owned Sessions and refuse reentrant publication.
+     * @returns the current store attachment, or undefined for an independent Session.
      */
     private publicationEntry;
     /**
@@ -426,15 +434,16 @@ export declare class SessionStore extends Service {
      *   `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.
+     * @returns the store-owned session, not yet entered and read-only until announced.
      * @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
      *   non-absolute path.
      */
     prepare(id?: SessionId, options?: PrepareSessionOptions): Session;
     /**
-     * Enter a {@link prepare}d session into the store: install the module-private
-     * append publication hooks and add it to the store. Returns the DETACH
+     * Enter a session into the store: install the module-private
+     * append publication hooks and add it to the store. Writes remain disabled
+     * until {@link announce} completes successfully. Returns the DETACH
      * disposer (hooks + store removal). Does NOT emit `session/created` —
      * the caller yields this disposer inside its effect and THEN calls
      * {@link announce}, so a throwing `session/created` listener rolls the attach
@@ -448,7 +457,7 @@ export declare class SessionStore extends Service {
      * the two back-to-back so they never trip this, but the public API cannot
      * assume that.
      *
-     * @param session - a {@link prepare}d session not yet in the store.
+     * @param session - an unentered session; independent instances become store-owned.
      * @returns the detach disposer (publication hooks + store removal). When called from
      *   a synchronous `session/created` listener, removal and disposal wait until
      *   that creation dispatch unwinds.
@@ -460,7 +469,9 @@ export declare class SessionStore extends Service {
     /** Emit `session/created` exactly once for an {@link enter}ed session (with
      * the carrier {@link enter} captured). Separate from {@link enter} so the
      * caller can yield the detach disposer first (rollback safety — see
-     * {@link enter}).
+     * {@link enter}). The Session remains read-only throughout synchronous
+     * dispatch; successful completion enables appends. A failed announcement
+     * leaves it read-only and cannot be retried.
      * @param session - the entered session to announce to listeners.
      * @throws if the session is not live or its announcement already began,
      *   including a reentrant call from a creation listener. */
@@ -495,7 +506,7 @@ export declare class SessionStore extends Service {
      */
     list(): Session[];
     /**
-     * Create a live child session from an exact prefix of a live source.
+     * Create an independent live session from an exact prefix of a live source.
      * `boundary` is an inclusive source event seq; omitted means the source's
      * current last event. An open tail receives synthetic tool results and
      * step/turn closers with the forked cause. Closed steps and turns remain

package/lib/types/index.js

@@ -322,7 +322,7 @@ function invokeContainedSessionObservers(ctx, name, id, args, callbacks) {
         }
     }
 }
-/** Store attachment for the append path; module-private to keep Session store-agnostic publicly. */
+/** Store-owned Sessions retain a null entry while unentered; absent keys are independent. */
 const attachments = new WeakMap();
 /**
  * Grammar of a {@link PluginRecordType}: `plugin:` followed by
@@ -374,7 +374,9 @@ let commitPluginRecord;
  *   with a letter or digit.
  * @param data - JSON payload, snapshotted before it enters the log.
  * @returns the sequence number of the committed record.
- * @throws when `type` is outside that grammar, when `data` is not losslessly
+ * @throws when a store-owned Session is unentered or its creation announcement
+ *   has not completed, when `type` is outside
+ *   that grammar, when `data` is not losslessly
  *   JSON-serializable, or when the call reenters another append's publication;
  *   a rejected record does not change the log.
  */
@@ -605,6 +607,9 @@ export class Session {
      * the log, the append is committed: observer failures are logged and
      * contained per listener, so they do not change the return value or prevent
      * later listeners from observing the same accepted event.
+     * Independent Sessions append without notifying store observers. Once a store
+     * prepares or enters the instance, writes require a completed creation
+     * announcement and remain disabled after removal.
      *
      * @param type - The event type (key of {@link SessionEventMap}).
      * @param data - The event payload; must be JSON-serializable.
@@ -620,7 +625,9 @@ export class Session {
      * @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.
-     * @throws if `data` or surface metadata is not losslessly JSON-serializable
+     * @throws if a store-owned Session is unentered or its creation announcement
+     *   has not completed, or if `data` or surface
+     *   metadata is not losslessly JSON-serializable
      *   (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
@@ -636,6 +643,7 @@ export class Session {
      *   rejects before the log changes.
      */
     append(type, data, ...opts) {
+        this.publicationEntry();
         const surfaceOpts = opts[0];
         const surfaceMetadata = {
             ...surfaceOpts?.sourceEventSeqs === undefined ? {} : { sourceEventSeqs: surfaceOpts.sourceEventSeqs },
@@ -649,6 +657,7 @@ export class Session {
         if (surfaceMetadataSnapshot === undefined) {
             throw new Error(`session event "${type}" carries non-JSON-serializable surface metadata`);
         }
+        // Payload getters can detach the Session while the snapshots are read.
         const entry = this.publicationEntry();
         const event = deepFreeze({
             type,
@@ -671,6 +680,7 @@ export class Session {
      * @returns the record's sequence number.
      */
     #appendRecord(type, data) {
+        this.publicationEntry();
         const dataSnapshot = snapshotJsonValue(data);
         if (dataSnapshot === undefined) {
             throw new Error(`plugin record "${type}" carries non-JSON-serializable data`);
@@ -688,12 +698,17 @@ export class Session {
         return record.seq;
     }
     /**
-     * Read the store attachment for one append, refusing an append that
-     * reenters while another append is being published.
-     * @returns the attachment, or undefined for a detached Session.
+     * Require announced membership for store-owned Sessions and refuse reentrant publication.
+     * @returns the current store attachment, or undefined for an independent Session.
      */
     publicationEntry() {
         const entry = attachments.get(this);
+        if (entry === null) {
+            throw new Error(`session "${this.id}" cannot append outside a SessionStore`);
+        }
+        if (entry !== undefined && entry.announcement !== 'complete') {
+            throw new Error(`session "${this.id}" cannot append before session/created completes`);
+        }
         if (entry?.appending) {
             throw new Error('session append cannot reenter while another append is being published');
         }
@@ -710,21 +725,20 @@ export class Session {
         if (entry !== undefined)
             entry.appending = true;
         try {
-            let callbacks;
             const callbackArgs = [this, event];
-            if (entry !== undefined) {
-                callbacks = collectSessionCallbacks(entry.emitCtx, [entry.carrier, 'session/event', ...callbackArgs]);
-            }
+            const callbacks = entry === undefined
+                ? undefined
+                : collectSessionCallbacks(entry.emitCtx, [entry.carrier, 'session/event', ...callbackArgs]);
             this.log.push(event);
             this.eventsSnapshot = undefined;
-            if (callbacks !== undefined && entry !== undefined) {
+            if (entry !== undefined && callbacks !== undefined) {
                 invokeContainedSessionObservers(entry.emitCtx, 'session/event', entry.id, callbackArgs, callbacks);
             }
         }
         finally {
             if (entry !== undefined) {
                 entry.appending = false;
-                if (entry.detachRequested && !entry.announcing)
+                if (entry.detachRequested && entry.announcement !== 'dispatching')
                     entry.detach();
             }
         }
@@ -942,7 +956,7 @@ export class SessionStore extends Service {
      *   `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.
+     * @returns the store-owned session, not yet entered and read-only until announced.
      * @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
      *   non-absolute path.
@@ -963,8 +977,11 @@ export class SessionStore extends Service {
             const { eventState } = options;
             switch (eventState) {
                 case 'detached':
-                case 'shared-frozen':
-                    return Session.fromRestore(sessionId, options.seed, options.meta, options.inheritedEventCount, eventState, this.projections);
+                case 'shared-frozen': {
+                    const session = Session.fromRestore(sessionId, options.seed, options.meta, options.inheritedEventCount, eventState, this.projections);
+                    attachments.set(session, null);
+                    return session;
+                }
                 case undefined:
                     break;
                 /* v8 ignore next -- closed-union exhaustiveness guard */
@@ -985,11 +1002,14 @@ export class SessionStore extends Service {
             ...meta?.delegationDepth === undefined ? {} : { delegationDepth: meta.delegationDepth },
             ...meta?.agentPreset === undefined ? {} : { agentPreset: meta.agentPreset },
         };
-        return Session.create(sessionId, seed, header, options?.inheritedEventCount, this.projections);
+        const session = Session.create(sessionId, seed, header, options?.inheritedEventCount, this.projections);
+        attachments.set(session, null);
+        return session;
     }
     /**
-     * Enter a {@link prepare}d session into the store: install the module-private
-     * append publication hooks and add it to the store. Returns the DETACH
+     * Enter a session into the store: install the module-private
+     * append publication hooks and add it to the store. Writes remain disabled
+     * until {@link announce} completes successfully. Returns the DETACH
      * disposer (hooks + store removal). Does NOT emit `session/created` —
      * the caller yields this disposer inside its effect and THEN calls
      * {@link announce}, so a throwing `session/created` listener rolls the attach
@@ -1003,7 +1023,7 @@ export class SessionStore extends Service {
      * the two back-to-back so they never trip this, but the public API cannot
      * assume that.
      *
-     * @param session - a {@link prepare}d session not yet in the store.
+     * @param session - an unentered session; independent instances become store-owned.
      * @returns the detach disposer (publication hooks + store removal). When called from
      *   a synchronous `session/created` listener, removal and disposal wait until
      *   that creation dispatch unwinds.
@@ -1016,15 +1036,14 @@ export class SessionStore extends Service {
         // preparation. Only one exact same-id transaction can publish.
         if (this.store.has(id))
             throw new Error(`session "${id}" already exists`);
-        if (attachments.has(session))
+        if (attachments.get(session) != null)
             throw new Error(`session "${id}" is already attached to a store`);
         const entry = {
             id,
             session,
             carrier,
             emitCtx: this.ctx,
-            announced: false,
-            announcing: false,
+            announcement: 'pending',
             appending: false,
             detachRequested: false,
             detach: () => { this.detachEntered(entry); },
@@ -1039,7 +1058,7 @@ export class SessionStore extends Service {
             // A lifecycle listener may own the advanced detach capability. Keep the
             // entry and its publication hooks live until synchronous creation or append
             // publication unwinds, then publish the paired disposal edge.
-            if (entry.announcing || entry.appending) {
+            if (entry.announcement === 'dispatching' || entry.appending) {
                 entry.detachRequested = true;
                 return;
             }
@@ -1056,28 +1075,28 @@ export class SessionStore extends Service {
         if (this.store.get(entry.id) !== entry)
             return;
         this.store.delete(entry.id);
-        attachments.delete(entry.session);
-        if (entry.announced)
+        attachments.set(entry.session, null);
+        if (entry.announcement !== 'pending')
             this.emitDisposed(entry);
     }
     /** Emit `session/created` exactly once for an {@link enter}ed session (with
      * the carrier {@link enter} captured). Separate from {@link enter} so the
      * caller can yield the detach disposer first (rollback safety — see
-     * {@link enter}).
+     * {@link enter}). The Session remains read-only throughout synchronous
+     * dispatch; successful completion enables appends. A failed announcement
+     * leaves it read-only and cannot be retried.
      * @param session - the entered session to announce to listeners.
      * @throws if the session is not live or its announcement already began,
      *   including a reentrant call from a creation listener. */
     announce(session) {
         const entry = this.liveEntryFor(session);
-        if (entry.announced || entry.announcing) {
+        if (entry.announcement !== 'pending') {
             throw new Error(`session "${entry.id}" was already announced`);
         }
-        // Mark before emit: Cordis emit may deliver to earlier listeners and then
-        // throw. Rollback must still pair that partial creation with disposal, and
-        // a listener cannot recursively create a second lifecycle edge.
-        entry.announced = true;
+        // Partial creation dispatch still requires disposal on rollback; listeners
+        // cannot recursively begin another announcement.
         const callbackArgs = [session];
-        entry.announcing = true;
+        entry.announcement = 'dispatching';
         try {
             const callbacks = collectSessionCallbacks(this.ctx, [entry.carrier, 'session/created', session]);
             for (const callback of callbacks) {
@@ -1091,10 +1110,14 @@ export class SessionStore extends Service {
                     this.ctx.logger.warn(`session "${entry.id}": session/created listener rejected: ${String(error)}`);
                 });
             }
+            entry.announcement = 'complete';
+        }
+        catch (error) {
+            entry.announcement = 'failed';
+            throw error;
         }
         finally {
-            entry.announcing = false;
-            if (entry.detachRequested && !entry.appending)
+            if (entry.detachRequested)
                 entry.detach();
         }
     }
@@ -1145,7 +1168,7 @@ export class SessionStore extends Service {
     /** Return the exact live entry; detached/prepared objects reject. */
     liveEntryFor(session) {
         const entry = attachments.get(session);
-        if (entry === undefined || this.store.get(entry.id) !== entry) {
+        if (entry == null || this.store.get(entry.id) !== entry) {
             throw new Error(`session "${session.id}" is not live in this store`);
         }
         return entry;
@@ -1166,7 +1189,7 @@ export class SessionStore extends Service {
         return [...this.store.values()].map(entry => entry.session);
     }
     /**
-     * Create a live child session from an exact prefix of a live source.
+     * Create an independent live session from an exact prefix of a live source.
      * `boundary` is an inclusive source event seq; omitted means the source's
      * current last event. An open tail receives synthetic tool results and
      * step/turn closers with the forked cause. Closed steps and turns remain
@@ -1195,7 +1218,6 @@ export class SessionStore extends Service {
             inheritedEventCount: SessionLogOffset(resolved === undefined ? 0 : resolved + 1),
             meta: {
                 ...liveSource.header.cwd !== undefined ? { cwd: liveSource.header.cwd } : {},
-                parentSession: liveSource.id,
                 isSeeded: true,
             },
         });

package/lib/types/types.d.ts

@@ -68,7 +68,11 @@ export interface SessionHeader {
     readonly createdAt: number;
     /** Absolute working directory the session was created in (if any). */
     readonly cwd?: string;
-    /** The session this one was forked from (seed lineage), if any. */
+    /**
+     * Direct creator of a subagent Session. Ordinary forks omit this field;
+     * historical ordinary forks may retain their source id here. Presence alone
+     * does not classify a Session as a subagent; use `origin` for that distinction.
+     */
     readonly parentSession?: SessionId;
     /**
      * Whether this Session contains a fork-inherited event prefix. The exact prefix
@@ -177,8 +181,9 @@ export interface TurnEndReasonMap {
     };
     /**
      * The turn failed. `error` is always a structured failure: the `LlmError`
-     * facts verbatim, or `{ message: errorChain(error), code: 'UNKNOWN' }`
-     * flattened from any other error.
+     * facts verbatim, or `{ message: errorChain(error), code }` flattened from
+     * any other error, where `code` is `TOOL_ACTIVATION_FAILED` for a failed
+     * tool condition and `UNKNOWN` otherwise.
      */
     error: {
         kind: 'error';
@@ -305,8 +310,10 @@ export interface SessionEventMap {
      * The rendered system prompt on the model-visible surface. The loop appends
      * the first one as surface node 0 before the step's first `user/message`.
      * A prepared in-history route can append nonempty changes in a continuing
-     * series. An incapable route or new series normalizes text to the first system
-     * node. Normalization empties nonempty later nodes, then rewrites the head if
+     * series. An incapable route, or a new series whose effective text differs,
+     * normalizes text to the first system node; a series start whose latest
+     * surviving node already holds the rendering leaves it in place.
+     * Normalization empties nonempty later nodes, then rewrites the head if
      * needed, through logged per-node replacements. An empty rendering always
      * clears all active system nodes, leaving no older instructions model-visible.
      * Empty later nodes are dormant and project to no message; an empty head with

package/locale/de.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Sitzung",
+    "description": "Protokollieren Sie Nachrichten, Toolaufrufe und führen Sie Ereignisse in einer Sitzung aus."
+  }
+}

package/locale/es.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "sesión",
+    "description": "Registre mensajes, llamadas de herramientas y ejecute eventos en una sesión."
+  }
+}

package/locale/fr.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "séance",
+    "description": "Enregistrez les messages, les appels d'outils et exécutez des événements dans une session."
+  }
+}

package/locale/ja.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "セッション記録",
+    "description": "セッション内のメッセージ、ツール呼び出し、実行イベントを記録します。"
+  }
+}

package/locale/pt.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "sessão",
+    "description": "Registrar mensagens, chamadas de ferramentas e executar eventos em uma sessão."
+  }
+}

package/locale/ru.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "сессия",
+    "description": "Регистрируйте сообщения, вызовы инструментов и запускайте события в сеансе."
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session",
   "description": "Event-sourced session store for the DeepSeek Harness",
-  "version": "0.2.1-rc.5",
+  "version": "0.2.2-alpha.3",
   "publishConfig": {
     "access": "public"
   },
@@ -42,18 +42,18 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-scope": "0.2.1-rc.5",
-    "@deepseek-ai/cordis": "~4.0.5"
+    "@deepseek-ai/dsh-scope": "0.2.2-alpha.3",
+    "@deepseek-ai/cordis": "~4.0.6-alpha.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-scope": "0.2.1-rc.5",
-    "@deepseek-ai/dsh-typert-protocol": "0.2.1-rc.5",
-    "@deepseek-ai/dsh-typert-registry": "0.2.1-rc.5",
-    "@deepseek-ai/cordis": "~4.0.5"
+    "@deepseek-ai/dsh-scope": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-typert-protocol": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-typert-registry": "0.2.2-alpha.3",
+    "@deepseek-ai/cordis": "~4.0.6-alpha.2"
   },
   "dependencies": {
-    "@deepseek-ai/dsh-llm": "0.2.1-rc.5",
-    "@deepseek-ai/dsh-brand": "0.2.1-rc.5",
-    "@deepseek-ai/dsh-util-values": "0.2.1-rc.5"
+    "@deepseek-ai/dsh-llm": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-brand": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-util-values": "0.2.2-alpha.3"
   }
 }